| Title: | Implementing Computational Models of Attentional Selectivity |
| Version: | 1.2.0 |
| Description: | A set of methods to simulate from and fit computational models of attentional selectivity. The package implements the dual-stage two-phase (DSTP) model of Hübner et al. (2010) <doi:10.1037/a0019471>, and the shrinking spotlight (SSP) model of White et al. (2011) <doi:10.1016/j.cogpsych.2011.08.001>. |
| Depends: | R (≥ 4.0) |
| Imports: | Rcpp |
| LinkingTo: | Rcpp |
| Suggests: | knitr, rmarkdown |
| License: | GPL-3 |
| LazyData: | true |
| Encoding: | UTF-8 |
| RoxygenNote: | 7.3.2 |
| URL: | https://github.com/JimGrange/flankr |
| BugReports: | https://github.com/JimGrange/flankr/issues |
| NeedsCompilation: | yes |
| Packaged: | 2025-08-21 08:45:07 UTC; jimgrange |
| Author: | Jim Grange  [aut,
cre] |
| Maintainer: | Jim Grange <grange.jim@gmail.com> |
| Repository: | CRAN |
| Date/Publication: | 2025-08-27 11:00:02 UTC |
Find conditional accuracy function (CAF) values for a single condition
Description
caf takes a data frame for a single experimental condition and
returns a vector of requested conditional accuracy function (CAF) values.
Usage
caf(data, quantiles = c(0.25, 0.5, 0.75), multipleSubjects = TRUE)
Arguments
data |
A data frame containing the data to be passed to the function.
At the very least, the data frame must contain columns named "accuracy"
logging the accuracy (1 for correct, 0 for error) and "rt" containing the
response time data. If the user wishes to find the average CAFs across
multiple subjects, then another column must be included ("subject") with
numbers identifying unique subjects. See |
quantiles |
The quantile values to be found by the function. By default, the function finds the accuracy for the .25, .5, and .75 quantiles. |
multipleSubjects |
Inform the function whether the data frame contains data from multiple subjects. If set to TRUE, the function returns the average CAF values across all subjects. If set to FALSE, the function assumes all data being passed is just from one subject. |
Details
The function only deals with one experimental condition. There is another
function (cafAll) which will return CAFs for all experimental
conditions. If there are more than one subject in the data frame being
passed to this function, the function first finds the CAF values for each
subject, and then takes the average for each quantile. This average is then
returned to the user.
Value
Returns a matrix with response time (row 1) and accuracy (row 2) for each quantile of CAF requested.
Examples
### example of multiple subjects and default quantile values
# only select the congruent data from the example data set
data <- subset(exampleData, exampleData$congruency == "congruent")
# get the CDFs
getCAF <- caf(data)
#-- example of single subject and different quantile values
# only select subject 1 from the example data. Also, select only the
# "absent" condition and incongruent trials. This is an example when working
# with multiple conditions (besides target congruency).
data <- subset(exampleData, exampleData$subject == 1 &
exampleData$condition == "absent" &
exampleData$congruency == "incongruent")
# set new quantile values
newQuantiles <- c(.2, .4, .6, .8)
# get the CAFs
getCAF <- caf(data, quantiles = newQuantiles, multipleSubjects = FALSE)
Find cumulative distribution function (CDF) values for a single condition
Description
cdf takes a data frame for a single experimental condition and
returns a vector of requested CDF values.
Usage
cdf(
data,
quantiles = c(0.1, 0.3, 0.5, 0.7, 0.9),
correctTrials = 1,
multipleSubjects = TRUE
)
Arguments
data |
A data frame containing the data to be passed to the function.
At the very least, the data frame must contain columns named "accuracy"
logging the accuracy (1 for correct, 0 for error) and "rt" containing the
response time data. If the user wishes to find the average CDFs across
multiple subjects, then another column must be included ("subject") with
numbers identifying unique subjects. See |
quantiles |
The quantile values to be found by the function. By default, the function finds the .1, .3, .5, .7, and .9 CDF values. |
correctTrials |
If set to 1, the function will find the CDFs of correct trials. Set to 2 to find the CDFs of error trials. Set to 3 to find CDFs of ALL trials. Note, though, that CDFs of error trials may be less accurate due to usually-low number of error trials. |
multipleSubjects |
Inform the function whether the data frame contains data from multiple subjects. If set to TRUE, the function returns the average CDF values across all subjects. If set to FALSE, the function assumes all data being passed is just from one subject. |
Details
The function only deals with one experimental condition. There is another
function (cdfAll) which will return CDFs for all experimental
conditions. If there are more than one subject in the data frame being
passed to this function, the function first finds the CDF values for each
subject, and then takes the average for each quantile. This average is then
returned to the user.
Value
Returns a vector of response times for each quantile of CDF requested.
Examples
### example of multiple subjects and default quantile values
# only select the congruent data from the example data set
data <- subset(exampleData, exampleData$congruency == "congruent")
# get the CDFs
getCDF <- cdf(data)
### example of single subject and different quantile values
# only select subject 1 from the example data. Also, select only the
# "absent" condition and incongruent trials. This is an example when working
# with multiple conditions (besides target congruency).
data <- subset(exampleData, exampleData$subject == 1 &
exampleData$condition == "absent" &
exampleData$congruency == "incongruent")
# set new quantile values
newQuantiles <- c(.1, .2, .3, .4, .5, .6, .7, .8, .9)
# get the CDFs
getCDF <- cdf(data, quantiles = newQuantiles, multipleSubjects = FALSE)
Example response time data set for multiple subjects.
Description
An example data set containing multiple participants' data for a response time study involving two experimental conditions, as well as the congruency manipulation. The data includes response time and accuracy.
Usage
exampleData
Format
A data frame with 12524 rows and 5 variables:
- subject
The subject identification number. Note that some participants were removed due to poor accuracy.
- condition
The experimental condition (2 in this example). It logs the presence/absence of an auditory tone before stimulus onset.
- congruency
The congruency of the flanker stimulus.
- accuracy
Accuracy of the response; 1 = correct, 0 = error
- rt
Response time, coded in seconds.
Details
This data is taken from Grange, J.A. (in preparation). The effect of accessory stimuli on choice response time in the flanker task.
Fit the DSTP model to human data
Description
fitDSTP fits the DSTP model to a single experimental condition of
human data (besides congruency, which it accounts for simutaneously).
Usage
fitDSTP(
data,
conditionName = NULL,
parms = c(0.145, 0.08, 0.1, 0.07, 0.325, 1.3, 0.24),
cdfs = c(0.1, 0.3, 0.5, 0.7, 0.9),
cafs = c(0.25, 0.5, 0.75),
maxParms = c(1, 1, 1, 1, 1, 2, 1),
nTrials = 50000,
multipleSubjects = TRUE,
seed = NULL
)
fit_dstp(
data,
conditionName = NULL,
parms = c(0.145, 0.08, 0.1, 0.07, 0.325, 1.3, 0.24),
cdfs = c(0.1, 0.3, 0.5, 0.7, 0.9),
cafs = c(0.25, 0.5, 0.75),
maxParms = c(1, 1, 1, 1, 1, 2, 1),
nTrials = 50000,
multipleSubjects = TRUE,
seed = NULL
)
Arguments
data |
A data frame containing human data. See |
conditionName |
If there is an additional experimental manipulation (i.e., other than target congruency) the model can only be fit to one at a time. Tell the function which condition is currently being fit by passing a string to the function (e.g., "present"). The function by default assumes no additional condition (e.g., conditionName is set to NULL). |
parms |
A vector of starting parameters to use in the minimisation
routine. Must be in the order: |
cdfs |
A vector of quantile values for cumulative distribution functions to be estimated from the human data. The model will attempt to find the best-fitting parameters that match this distributional data. |
cafs |
A vector of quantiles for conditional accuracy functions to be estimated from the human data. The model will attempt to find the best- fitting parameters that match this distributional data. |
maxParms |
A vector containing upper limits on possible parameter values. |
nTrials |
An integer stating how many trials to simulate per iteration of the fitting cycle for each congruency type. |
multipleSubjects |
A boolean stating whether the fit is to multiple subjects (multipleSubjects = TRUE) or to a single subject (multipleSubjects = FALSE). |
seed |
The value for the |
Details
This function can be employed by the user to find the best-fitting
parameters of the DSTP model to fit the human data of a single experimental
condition. The fitting procedure accounts for congruent and incongruent
trials simultaneously. The fit is obtained by a gradient-descent method
(using the Nelder-Mead method contained in R's optim function) and is
fit to the proportion of data contained in human CDF and CAF distributional
data.
Value
bestParameters A vector of the best-fitting parameters found
by the current fit run.
g2 The value of Wilks likelihood ratio (G2) obtained by the
current fit run.
bBIC The value of the Bayesian Information Criterion (BIC)
obtained by the current fit run. This is calculated using the BIC equation
for binned data, hence bBIC (binned BIC).
Examples
# Load the example data the comes with the \code{flankr} package
data(exampleData)
# Fit the model to the condition "present" in the example data set using
# the default settings in the model.
# (Note this is a toy example with very low trial numbers to speed up the
# example. For proper use, increase nTrials.)
fit <- fitDSTP(data = exampleData, conditionName = "present", nTrials = 100)
Fit the DSTP model to human data with some fixed parameters
Description
fitDSTP_fixed fits the DSTP model to a single experimental condition
of human data (besides congruency, which it accounts for simutaneously).
This function allows the user to fix some parameters (using the fixed
variable).
Usage
fitDSTP_fixed(
data,
conditionName = NULL,
parms = c(0.145, 0.08, 0.1, 0.07, 0.325, 1.3, 0.24),
cdfs = c(0.1, 0.3, 0.5, 0.7, 0.9),
cafs = c(0.25, 0.5, 0.75),
maxParms = c(1, 1, 1, 1, 1, 2, 1),
nTrials = 50000,
multipleSubjects = TRUE,
fixed = c(FALSE, FALSE, FALSE, FALSE, FALSE, FALSE, FALSE),
seed = NULL
)
fit_dstp_fixed(
data,
conditionName = NULL,
parms = c(0.145, 0.08, 0.1, 0.07, 0.325, 1.3, 0.24),
cdfs = c(0.1, 0.3, 0.5, 0.7, 0.9),
cafs = c(0.25, 0.5, 0.75),
maxParms = c(1, 1, 1, 1, 1, 2, 1),
nTrials = 50000,
multipleSubjects = TRUE,
fixed = c(FALSE, FALSE, FALSE, FALSE, FALSE, FALSE, FALSE),
seed = NULL
)
Arguments
data |
A data frame containing human data. See |
conditionName |
If there is an additional experimental manipulation (i.e., other than target congruency) the model can only be fit to one at a time. Tell the function which condition is currently being fit by passing a string to the function (e.g., "present"). The function by default assumes no additional condition (e.g., conditionName is set to NULL). |
parms |
A vector of starting parameters to use in the minimisation
routine. Must be in the order: |
cdfs |
A vector of quantile values for cumulative distribution functions to be estimated from the human data. The model will attempt to find the best-fitting parameters that match this distributional data. |
cafs |
A vector of quantiles for conditional accuracy functions to be estimated from the human data. The model will attempt to find the best- fitting parameters that match this distributional data. |
maxParms |
A vector containing upper limits on possible parameter values. |
nTrials |
An integer stating how many trials to simulate per iteration of the fitting cycle for each congruency type. |
multipleSubjects |
A boolean stating whether the fit is to multiple subjects (multipleSubjects = TRUE) or to a single subject (multipleSubjects = FALSE). |
fixed |
A vector of TRUE/FALSE stating whether each parameter should be
fixed (TRUE) or free (FALSE) during the fitting routine. Must be in the
order: |
seed |
The value for the |
Details
This function can be employed by the user to find the best-fitting
parameters of the DSTP model to fit the human data of a single experimental
condition. The fitting procedure accounts for congruent and incongruent
trials simultaneously. The fit is obtained by a gradient-descent method
(using the Nelder-Mead method contained in R's optim function) and is
fit to the proportion of data contained in human CDF and CAF distributional
data.
Value
bestParameters A vector of the best-fitting parameters found
by the current fit run.
g2 The value of Wilks likelihood ratio (G2) obtained by the
current fit run.
bBIC The value of the Bayesian Information Criterion (BIC)
obtained by the current fit run. This is calculated using the BIC equation
for binned data, hence bBIC (binned BIC).
Examples
# Load the example data the comes with the \code{flankr} package
data(exampleData)
# Fix the first parameter (A) during the fit.
parms <- c(0.145, 0.08, 0.1, 0.07, 0.325, 1.3, 0.24)
fixed <- c(TRUE, FALSE, FALSE, FALSE, FALSE, FALSE, FALSE)
# fit the model.
# (Note this is a toy example with very low trial numbers to speed up the
# example. For proper use, increase nTrials.)
fit <- fitDSTP_fixed(exampleData, conditionName = "present", parms = parms,
fixed = fixed, nTrials = 100)
Fit the DSTP model to human data with mutiple starting parmaeters
Description
fitMultipleDSTP fits the DSTP model to a single experimental condition
of human data (besides congruency, which it accounts for simutaneously).
This function explores multiple starting parameters.
Usage
fitMultipleDSTP(
data,
conditionName = NULL,
parms = c(0.145, 0.08, 0.1, 0.07, 0.325, 1.3, 0.24),
var = 10,
nParms = 20,
cdfs = c(0.1, 0.3, 0.5, 0.7, 0.9),
cafs = c(0.25, 0.5, 0.75),
maxParms = c(1, 1, 1, 1, 1, 2, 1),
nTrials = 50000,
multipleSubjects = TRUE,
seed = NULL
)
fit_multiple_dstp(
data,
conditionName = NULL,
parms = c(0.145, 0.08, 0.1, 0.07, 0.325, 1.3, 0.24),
var = 10,
nParms = 20,
cdfs = c(0.1, 0.3, 0.5, 0.7, 0.9),
cafs = c(0.25, 0.5, 0.75),
maxParms = c(1, 1, 1, 1, 1, 2, 1),
nTrials = 50000,
multipleSubjects = TRUE,
seed = NULL
)
fit_multiple_dstp(
data,
conditionName = NULL,
parms = c(0.145, 0.08, 0.1, 0.07, 0.325, 1.3, 0.24),
var = 10,
nParms = 20,
cdfs = c(0.1, 0.3, 0.5, 0.7, 0.9),
cafs = c(0.25, 0.5, 0.75),
maxParms = c(1, 1, 1, 1, 1, 2, 1),
nTrials = 50000,
multipleSubjects = TRUE,
seed = NULL
)
Arguments
data |
A data frame containing human data. See |
conditionName |
If there is an additional experimental manipulation (i.e., other than target congruency) the model can only be fit to one at a time. Tell the function which condition is currently being fit by passing a string to the function (e.g., "present"). The function by default assumes no additional condition (e.g., conditionName is set to NULL). |
parms |
A vector of starting parameters to use in the minimisation
routine. Must be in the order: |
var |
An integer stating the percentage of each parameter value that should be used for finding random parameter starting points. |
nParms |
An integer stating how many random starting points to explore |
cdfs |
A vector of quantile values for cumulative distribution functions to be estimated from the human data. The model will attempt to find the best-fitting parameters that match this distributional data. |
cafs |
A vector of quantiles for conditional accuracy functions to be estimated from the human data. The model will attempt to find the best- fitting parameters that match this distributional data. |
maxParms |
A vector containing upper limits on possible parameter values. |
nTrials |
An integer stating how many trials to simulate per iteration of the fitting cycle for each congruency type. |
multipleSubjects |
A boolean stating whether the fit is to multiple subjects (multipleSubjects = TRUE) or to a single subject (multipleSubjects = FALSE). |
seed |
The value for the |
Details
This function can be employed by the user to find the best-fitting
parameters of the DSTP model to fit the human data of a single experimental
condition. The fitting procedure accounts for congruent and incongruent
trials simultaneously. The fit is obtained by a gradient-descent method
(using the Nelder-Mead method contained in R's optim function) and is
fit to the proportion of data contained in human CDF and CAF distributional
data. Multiple starting points of parameters are used.
Value
bestParameters A vector of the best-fitting parameters found
by the current fit run.
g2 The value of Wilks likelihood ratio (G2) obtained by the
current fit run.
bBIC The value of the Bayesian Information Criterion (BIC)
obtained by the current fit run. This is calculated using the BIC equation
for binned data, hence bBIC (binned BIC).
Examples
# Load the example data the comes with the \code{flankr} package
data(exampleData)
# Fit the model to the condition "present" in the example data set using
# the default settings in the model.
# (Note this is a toy example with very low trial numbers to speed up the
# example. For proper use, increase nTrials.)
fit <- fitMultipleDSTP(data = exampleData, conditionName = "present", nTrials = 100)
Fit the DSTP model to human data with multiple starting parameters with some fixed parameters
Description
fitMultipleDSTP_fixed fits the DSTP model to a single experimental
condition of human data (besides congruency, which it accounts for
simutaneously). This function explores multiple starting parameters and
allows user to fix model parameters.
Usage
fitMultipleDSTP_fixed(
data,
conditionName = NULL,
parms = c(0.145, 0.08, 0.1, 0.07, 0.325, 1.3, 0.24),
var = 10,
nParms = 20,
cdfs = c(0.1, 0.3, 0.5, 0.7, 0.9),
cafs = c(0.25, 0.5, 0.75),
maxParms = c(1, 1, 1, 1, 1, 2, 1),
nTrials = 50000,
multipleSubjects = TRUE,
fixed = c(FALSE, FALSE, FALSE, FALSE, FALSE, FALSE, FALSE)
)
fit_multiple_dstp_fixed(
data,
conditionName = NULL,
parms = c(0.145, 0.08, 0.1, 0.07, 0.325, 1.3, 0.24),
var = 10,
nParms = 20,
cdfs = c(0.1, 0.3, 0.5, 0.7, 0.9),
cafs = c(0.25, 0.5, 0.75),
maxParms = c(1, 1, 1, 1, 1, 2, 1),
nTrials = 50000,
multipleSubjects = TRUE,
fixed = c(FALSE, FALSE, FALSE, FALSE, FALSE, FALSE, FALSE)
)
Arguments
data |
A data frame containing human data. See |
conditionName |
If there is an additional experimental manipulation (i.e., other than target congruency) the model can only be fit to one at a time. Tell the function which condition is currently being fit by passing a string to the function (e.g., "present"). The function by default assumes no additional condition (e.g., conditionName is set to NULL). |
parms |
A vector of starting parameters to use in the minimisation
routine. Must be in the order: |
var |
An integer stating the percentage of each parameter value that should be used for finding random parameter starting points. |
nParms |
An integer stating how many random starting points to explore |
cdfs |
A vector of quantile values for cumulative distribution functions to be estimated from the human data. The model will attempt to find the best-fitting parameters that match this distributional data. |
cafs |
A vector of quantiles for conditional accuracy functions to be estimated from the human data. The model will attempt to find the best- fitting parameters that match this distributional data. |
maxParms |
A vector containing upper limits on possible parameter values. |
nTrials |
An integer stating how many trials to simulate per iteration of the fitting cycle for each congruency type. |
multipleSubjects |
A boolean stating whether the fit is to multiple subjects (multipleSubjects = TRUE) or to a single subject (multipleSubjects = FALSE). |
fixed |
A vector of TRUE/FALSE stating whether each parameter should be
fixed (TRUE) or free (FALSE) during the fitting routine. Must be in the
order: |
Details
This function can be employed by the user to find the best-fitting
parameters of the DSTP model to fit the human data of a single experimental
condition. The fitting procedure accounts for congruent and incongruent
trials simultaneously. The fit is obtained by a gradient-descent method
(using the Nelder-Mead method contained in R's optim function) and is
fit to the proportion of data contained in human CDF and CAF distributional
data. Multiple starting points of parameters are used.
Value
bestParameters A vector of the best-fitting parameters found
by the current fit run.
g2 The value of Wilks likelihood ratio (G2) obtained by the
current fit run.
bBIC The value of the Bayesian Information Criterion (BIC)
obtained by the current fit run. This is calculated using the BIC equation
for binned data, hence bBIC (binned BIC).
Examples
# Load the example data the comes with the \code{flankr} package
data(exampleData)
# Fit the model whilst fixing the first parameter (A)
# (Note this is a toy example with very low trial numbers to speed up the
# example. For proper use, increase nTrials.)
parms <- c(0.145, 0.08, 0.1, 0.07, 0.325, 1.3, 0.24)
fixed <- c(TRUE, FALSE, FALSE, FALSE, FALSE, FALSE, FALSE)
fit <- fitMultipleDSTP_fixed(exampleData, conditionName = "present",
parms = parms, fixed = fixed, nTrials = 100)
Fit the SSP model to human data with multiple starting parameters
Description
fitSSPMultiple fits the SSP model to a single experimental condition
of human data (besides congruency, which it accounts for simutaneously).
Usage
fitMultipleSSP(
data,
conditionName = NULL,
parms = c(0.05, 0.3, 0.4, 0.05, 1.5),
var = 10,
nParms = 20,
cdfs = c(0.1, 0.3, 0.5, 0.7, 0.9),
cafs = c(0.25, 0.5, 0.75),
maxParms = c(1, 1, 1, 1, 2),
nTrials = 50000,
multipleSubjects = TRUE,
seed = NULL
)
fit_multiple_ssp(
data,
conditionName = NULL,
parms = c(0.05, 0.3, 0.4, 0.05, 1.5),
var = 10,
nParms = 20,
cdfs = c(0.1, 0.3, 0.5, 0.7, 0.9),
cafs = c(0.25, 0.5, 0.75),
maxParms = c(1, 1, 1, 1, 2),
nTrials = 50000,
multipleSubjects = TRUE,
seed = NULL
)
fit_multiple_ssp(
data,
conditionName = NULL,
parms = c(0.05, 0.3, 0.4, 0.05, 1.5),
var = 10,
nParms = 20,
cdfs = c(0.1, 0.3, 0.5, 0.7, 0.9),
cafs = c(0.25, 0.5, 0.75),
maxParms = c(1, 1, 1, 1, 2),
nTrials = 50000,
multipleSubjects = TRUE,
seed = NULL
)
Arguments
data |
A data frame containing human data. See |
conditionName |
If there is an additional experimental manipulation (i.e., other than target congruency) the model can only be fit to one at a time. Tell the function which condition is currently being fit by passing a string to the function (e.g., "present"). The function by default assumes no additional condition (e.g., conditionName is set to NULL). |
parms |
A vector of starting parameters to use in the minimisation
routine. Must be in the order: |
var |
An integer stating the percentage of each parameter value that should be used for finding random parameter starting points. |
nParms |
An integer stating how many random starting points to explore |
cdfs |
A vector of quantile values for cumulative distribution functions to be estimated from the human data. The model will attempt to find the best-fitting parameters that match this distributional data. |
cafs |
A vector of quantiles for conditional accuracy functions to be estimated from the human data. The model will attempt to find the best- fitting parameters that match this distributional data. |
maxParms |
A vector containing upper limits on possible parameter values. |
nTrials |
An integer stating how many trials to simulate per iteration of the fitting cycle for each congruency type. |
multipleSubjects |
A boolean stating whether the fit is to multiple subjects (multipleSubjects = TRUE) or to a single subject (multipleSubjects = FALSE). |
seed |
The value for the |
Details
This function can be employed by the user to find the best-fitting
parameters of the SSP model to fit the human data of a single experimental
condition. The fitting procedure accounts for congruent and incongruent
trials simultaneously. The fit is obtained by a gradient-descent method
(using the Nelder-Mead method contained in R's optim function) and is
fit to the proportion of data contained in human CDF and CAF distributional
data.
Value
bestParameters A vector of the best-fitting parameters found
by the current fit run.
g2 The value of Wilks likelihood ratio (G2) obtained by the
current fit run.
bBIC The value of the Bayesian Information Criterion (BIC)
obtained by the current fit run. This is calculated using the BIC equation
for binned data, hence bBIC (binned BIC).
Examples
# Load the example data the comes with the \code{flankr} package
data(exampleData)
# Fit the model to the condition "present" in the example data set using
# the default settings in the model.
# (Note this is a toy example with very low trial numbers to speed up the
# example. For proper use, increase nTrials.)
fit <- fitMultipleSSP(data = exampleData, conditionName = "present",
nTrials = 100)
Fit the SSP model to human data with mutiple starting parmaeters with some fixed parameters
Description
fitMultipleSSP_fixed fits the SSP model to a single experimental
condition of human data (besides congruency, which it accounts for
simutaneously). This function explores multiple starting parameters and
allows user to fix model parameters.
Usage
fitMultipleSSP_fixed(
data,
conditionName = NULL,
parms = c(0.05, 0.3, 0.4, 0.05, 1.5),
var = 10,
nParms = 20,
cdfs = c(0.1, 0.3, 0.5, 0.7, 0.9),
cafs = c(0.25, 0.5, 0.75),
maxParms = c(1, 1, 1, 1, 2),
nTrials = 50000,
multipleSubjects = TRUE,
fixed = c(FALSE, FALSE, FALSE, FALSE, FALSE)
)
fit_multiple_ssp_fixed(
data,
conditionName = NULL,
parms = c(0.05, 0.3, 0.4, 0.05, 1.5),
var = 10,
nParms = 20,
cdfs = c(0.1, 0.3, 0.5, 0.7, 0.9),
cafs = c(0.25, 0.5, 0.75),
maxParms = c(1, 1, 1, 1, 2),
nTrials = 50000,
multipleSubjects = TRUE,
fixed = c(FALSE, FALSE, FALSE, FALSE, FALSE)
)
Arguments
data |
A data frame containing human data. See |
conditionName |
If there is an additional experimental manipulation (i.e., other than target congruency) the model can only be fit to one at a time. Tell the function which condition is currently being fit by passing a string to the function (e.g., "present"). The function by default assumes no additional condition (e.g., conditionName is set to NULL). |
parms |
A vector of starting parameters to use in the minimisation
routine. Must be in the order: |
var |
An integer stating the percentage of each parameter value that should be used for finding random parameter starting points. |
nParms |
An integer stating how many random starting points to explore |
cdfs |
A vector of quantile values for cumulative distribution functions to be estimated from the human data. The model will attempt to find the best-fitting parameters that match this distributional data. |
cafs |
A vector of quantiles for conditional accuracy functions to be estimated from the human data. The model will attempt to find the best- fitting parameters that match this distributional data. |
maxParms |
A vector containing upper limits on possible parameter values. |
nTrials |
An integer stating how many trials to simulate per iteration of the fitting cycle for each congruency type. |
multipleSubjects |
A boolean stating whether the fit is to multiple subjects (multipleSubjects = TRUE) or to a single subject (multipleSubjects = FALSE). |
fixed |
A vector of TRUE/FALSE stating whether each parameter should be
fixed (TRUE) or free (FALSE) during the fitting routine. Must be in the
order: |
Details
This function can be employed by the user to find the best-fitting
parameters of the SSP model to fit the human data of a single experimental
condition. The fitting procedure accounts for congruent and incongruent
trials simultaneously. The fit is obtained by a gradient-descent method
(using the Nelder-Mead method contained in R's optim function) and is
fit to the proportion of data contained in human CDF and CAF distributional
data. Multiple starting points of parameters are used.
Value
bestParameters A vector of the best-fitting parameters found
by the current fit run.
g2 The value of Wilks likelihood ratio (G2) obtained by the
current fit run.
bBIC The value of the Bayesian Information Criterion (BIC)
obtained by the current fit run. This is calculated using the BIC equation
for binned data, hence bBIC (binned BIC).
Examples
data(exampleData)
# Fix the first parameter (A) during the fit.
parms = c(0.050, 0.300, 0.400, 0.050, 1.500)
fixed <- c(TRUE, FALSE, FALSE, FALSE, FALSE)
# run the model
# (Note this is a toy example with very low trial numbers to speed up the
# example. For proper use, increase nTrials.)
fit <- fitMultipleSSP_fixed(exampleData, conditionName = "present",
parms = parms, fixed = fixed, nTrials = 100)
Fit the SSP model to human data
Description
fitSSP fits the SSP model to a single experimental condition of
human data (besides congruency, which it accounts for simutaneously).
Usage
fitSSP(
data,
conditionName = NULL,
parms = c(0.05, 0.3, 0.4, 0.05, 1.5),
cdfs = c(0.1, 0.3, 0.5, 0.7, 0.9),
cafs = c(0.25, 0.5, 0.75),
maxParms = c(1, 1, 1, 1, 3),
nTrials = 50000,
multipleSubjects = TRUE,
seed = NULL
)
fit_ssp(
data,
conditionName = NULL,
parms = c(0.05, 0.3, 0.4, 0.05, 1.5),
cdfs = c(0.1, 0.3, 0.5, 0.7, 0.9),
cafs = c(0.25, 0.5, 0.75),
maxParms = c(1, 1, 1, 1, 3),
nTrials = 50000,
multipleSubjects = TRUE,
seed = NULL
)
Arguments
data |
A data frame containing human data. See |
conditionName |
If there is an additional experimental manipulation (i.e., other than target congruency) the model can only be fit to one at a time. Tell the function which condition is currently being fit by passing a string to the function (e.g., "present"). The function by default assumes no additional condition (e.g., conditionName is set to NULL). |
parms |
A vector of starting parameters to use in the minimisation
routine. Must be in the order: |
cdfs |
A vector of quantile values for cumulative distribution functions to be estimated from the human data. The model will attempt to find the best-fitting parameters that match this distributional data. |
cafs |
A vector of quantiles for conditional accuracy functions to be estimated from the human data. The model will attempt to find the best- fitting parameters that match this distributional data. |
maxParms |
A vector containing upper limits on possible parameter values. |
nTrials |
An integer stating how many trials to simulate per iteration of the fitting cycle for each congruency type. |
multipleSubjects |
A boolean stating whether the fit is to multiple subjects (multipleSubjects = TRUE) or to a single subject (multipleSubjects = FALSE). |
seed |
The value for the |
Details
This function can be employed by the user to find the best-fitting
parameters of the SSP model to fit the human data of a single experimental
condition. The fitting procedure accounts for congruent and incongruent
trials simultaneously. The fit is obtained by a gradient-descent method
(using the Nelder-Mead method contained in R's optim function) and is
fit to the proportion of data contained in human CDF and CAF distributional
data.
Value
bestParameters A vector of the best-fitting parameters found
by the current fit run.
g2 The value of Wilks likelihood ratio (G2) obtained by the
current fit run.
bBIC The value of the Bayesian Information Criterion (BIC)
obtained by the current fit run. This is calculated using the BIC equation
for binned data, hence bBIC (binned BIC).
Examples
# Load the example data the comes with the \code{flankr} package
data(exampleData)
# Fit the model to the condition "present" in the example data set using
# the default settings in the model.
# (Note this is a toy example with very low trial numbers to speed up the
# example. For proper use, increase nTrials.)
fit <- fitSSP(data = exampleData, conditionName = "present", nTrials = 100)
Fit the SSP model to human data with some fixed parameters
Description
fitSSP_fixed fits the SSP model to a single experimental condition of
human data (besides congruency, which it accounts for simutaneously). This
function allows the user to fix some parameters (using the fixed
variable).
Usage
fitSSP_fixed(
data,
conditionName = NULL,
parms = c(0.05, 0.3, 0.4, 0.05, 1.5),
cdfs = c(0.1, 0.3, 0.5, 0.7, 0.9),
cafs = c(0.25, 0.5, 0.75),
maxParms = c(1, 1, 1, 1, 2),
nTrials = 50000,
multipleSubjects = TRUE,
fixed = c(FALSE, FALSE, FALSE, FALSE, FALSE),
seed = NULL
)
fit_ssp_fixed(
data,
conditionName = NULL,
parms = c(0.05, 0.3, 0.4, 0.05, 1.5),
cdfs = c(0.1, 0.3, 0.5, 0.7, 0.9),
cafs = c(0.25, 0.5, 0.75),
maxParms = c(1, 1, 1, 1, 2),
nTrials = 50000,
multipleSubjects = TRUE,
fixed = c(FALSE, FALSE, FALSE, FALSE, FALSE),
seed = NULL
)
Arguments
data |
A data frame containing human data. See |
conditionName |
If there is an additional experimental manipulation (i.e., other than target congruency) the model can only be fit to one at a time. Tell the function which condition is currently being fit by passing a string to the function (e.g., "present"). The function by default assumes no additional condition (e.g., conditionName is set to NULL). |
parms |
A vector of starting parameters to use in the minimisation
routine. Must be in the order: |
cdfs |
A vector of quantile values for cumulative distribution functions to be estimated from the human data. The model will attempt to find the best-fitting parameters that match this distributional data. |
cafs |
A vector of quantiles for conditional accuracy functions to be estimated from the human data. The model will attempt to find the best- fitting parameters that match this distributional data. |
maxParms |
A vector containing upper limits on possible parameter values. |
nTrials |
An integer stating how many trials to simulate per iteration of the fitting cycle for each congruency type. |
multipleSubjects |
A boolean stating whether the fit is to multiple subjects (multipleSubjects = TRUE) or to a single subject (multipleSubjects = FALSE). |
fixed |
A vector of TRUE/FALSE stating whether each parameter should be
fixed (TRUE) or free (FALSE) during the fitting routine. Must be in the
order: |
seed |
The value for the |
Details
This function can be employed by the user to find the best-fitting
parameters of the SSP model to fit the human data of a single experimental
condition. The fitting procedure accounts for congruent and incongruent
trials simultaneously. The fit is obtained by a gradient-descent method
(using the Nelder-Mead method contained in R's optim function) and is
fit to the proportion of data contained in human CDF and CAF distributional
data.
Value
bestParameters A vector of the best-fitting parameters found
by the current fit run.
g2 The value of Wilks likelihood ratio (G2) obtained by the
current fit run.
bBIC The value of the Bayesian Information Criterion (BIC)
obtained by the current fit run. This is calculated using the BIC equation
for binned data, hence bBIC (binned BIC).
Examples
# Load the example data the comes with the \code{flankr} package
data(exampleData)
# Fix the first parameter (A) during the fit.
parms = c(0.050, 0.300, 0.400, 0.050, 1.500)
fixed <- c(TRUE, FALSE, FALSE, FALSE, FALSE)
# fit the model
# (Note this is a toy example with very low trial numbers to speed up the
# example. For proper use, increase nTrials.)
fit <- fitSSP_fixed(exampleData, conditionName = "present", parms = parms,
fixed = fixed, nTrials = 100)
Plot the fit of the DSTP model to human data.
Description
plotFitDSTP will plot the fit of the model to human distributional
data.
Usage
plotFitDSTP(
modelFit,
data,
conditionName = NULL,
nTrials = 50000,
cdfs = c(0.1, 0.3, 0.5, 0.7, 0.9),
cafs = c(0.25, 0.5, 0.75),
multipleSubjects = TRUE,
seed = NULL
)
plot_fit_dstp(
modelFit,
data,
conditionName = NULL,
nTrials = 50000,
cdfs = c(0.1, 0.3, 0.5, 0.7, 0.9),
cafs = c(0.25, 0.5, 0.75),
multipleSubjects = TRUE,
seed = NULL
)
Arguments
modelFit |
The object obtained by the model fit. |
data |
The data frame of human data. |
conditionName |
The name of the condition that was fit. By default, it is set to conditionName = NULL. |
nTrials |
How many trials used to generate the model's best predictions. This should be higher than that used to fit the model. |
cdfs |
The cut-off points for the cumulative distribution functions. |
cafs |
The cut-off points for the conditional accuracy functions. |
multipleSubjects |
A boolean stating whether the fit is to multiple subjects (multipleSubjects = TRUE) or to a single subject (multipleSubjects = FALSE). |
seed |
The value for the |
Details
This function is passed the object obtained by the model fitting procedure, as well as the human data and the condition that was fitted by the routine. The function simulates 100,000 trials (by default) using the best-fitting parameters found by the fit procedure. This synthetic data is then considered as the model's best predictions. The function then provides a plot of the model fit to cumulative distribution functions (CDFs) of correct response time, and conditional accuracy functions (CAFs) to show fit to accuracy data. The function also returns the data used to plot the fit so that the user can use their own plotting methods.
Value
cdfs The CDF values requested by the user.
cafs The CAF values requested by the user.
humanConCDFs The response time cut-off values for each CDF
bin for congruent human data.
humanInconCDFs The response time cut-off values for each CDF
bin for incongruent human data.
humanConCAFsRT The mean response times for each bin of the
CAF functions for congruent human data.
humanInconCAFsRT The mean response times for each bin of the
CAF functions for incongruent human data.
humanConCAFsError The percent accuracy for each bin of the
CAF functions for congruent human data.
humanConCAFsError The percent accuracy for each bin of the
CAF functions for congruent human data.
modelConCDFs The quantile cut-off points for the model
predictions for congruent data. A perfect fit would match the cdfs asked
for by the user (e.g., .1, .3, .5, .7, .9).
modelInconCDFs The quantile cut-off points for the model
predictions for incongruent data. A perfect fit would match the cdfs asked
for by the user (e.g., .1, .3, .5, .7, .9).
modelConCAFs The percentage accuracy predicted for each CAF
bin by the model for congruent data.
modelInconCAFs The percentage accuracy predicted for each CAF
bin by the model for incongruent data.
Examples
# Assume that the model was just fit to the data contained in
# \code{exampleData} (condition "present") and saved to the variable called
# "fit", then we can obtain a plot of that fit by using the following:
# (Note this is a toy example with very low trial numbers to speed up the
# example. For proper use, increase nTrials.)
fit <- fitDSTP(data = exampleData, conditionName = "present", nTrials = 100)
plot <- plotFitDSTP(modelFit = fit, data = exampleData,
conditionName = "present", nTrials = 100)
Plot the fit of the SSP model to human data.
Description
plotFitSSP will plot the fit of the model to human distributional
data.
Usage
plotFitSSP(
modelFit,
data,
conditionName = NULL,
nTrials = 50000,
cdfs = c(0.1, 0.3, 0.5, 0.7, 0.9),
cafs = c(0.25, 0.5, 0.75),
multipleSubjects = TRUE,
seed = NULL
)
plot_fit_ssp(
modelFit,
data,
conditionName = NULL,
nTrials = 50000,
cdfs = c(0.1, 0.3, 0.5, 0.7, 0.9),
cafs = c(0.25, 0.5, 0.75),
multipleSubjects = TRUE,
seed = NULL
)
Arguments
modelFit |
The object obtained by the model fit. |
data |
The data frame of human data. |
conditionName |
The name of the condition that was fit. By default, it is set to conditionName = NULL. |
nTrials |
How many trials used to generate the model's best predictions. This should be higher than that used to fit the model. |
cdfs |
The cut-off points for the cumulative distribution functions. |
cafs |
The cut-off points for the conditional accuracy functions. |
multipleSubjects |
A boolean stating whether the fit is to multiple subjects (multipleSubjects = TRUE) or to a single subject (multipleSubjects = FALSE). |
seed |
The value for the |
Details
This function is passed the object obtained by the model fitting procedure, as well as the human data and the condition that was fitted by the routine. The function simulates 100,000 trials (by default) using the best-fitting parameters found by the fit procedure. This synthetic data is then considered as the model's best predictions. The function then provides a plot of the model fit to cumulative distribution functions (CDFs) of correct response time, and conditional accuracy functions (CAFs) to show fit to accuracy data. The function also returns the data used to plot the fit so that the user can use their own plotting methods.
Value
cdfs The CDF values requested by the user.
cafs The CAF values requested by the user.
humanConCDFs The response time cut-off values for each CDF
bin for congruent human data.
humanInconCDFs The response time cut-off values for each CDF
bin for incongruent human data.
humanConCAFsRT The mean response times for each bin of the
CAF functions for congruent human data.
humanInconCAFsRT The mean response times for each bin of the
CAF functions for incongruent human data.
humanConCAFsError The percent accuracy for each bin of the
CAF functions for congruent human data.
humanConCAFsError The percent accuracy for each bin of the
CAF functions for congruent human data.
modelConCDFs The quantile cut-off points for the model
predictions for congruent data. A perfect fit would match the cdfs asked
for by the user (e.g., .1, .3, .5, .7, .9).
modelInconCDFs The quantile cut-off points for the model
predictions for incongruent data. A perfect fit would match the cdfs asked
for by the user (e.g., .1, .3, .5, .7, .9).
modelConCAFs The percentage accuracy predicted for each CAF
bin by the model for congruent data.
modelInconCAFs The percentage accuracy predicted for each CAF
bin by the model for incongruent data.
Examples
# Assume that the model was just fit to the data contained in
# \code{exampleData} (condition "present") and saved to the variable called
# "fit", then we can obtain a plot of that fit by using the following:
# (Note this is a toy example with very low trial numbers to speed up the
# example. For proper use, increase nTrials.)
fit <- fitSSP(data = exampleData, conditionName = "present", nTrials = 100)
plot <- plotFitSSP(modelFit = fit, data = exampleData,
conditionName = "present", nTrials = 100)
Obtain simulated response times and accuracy from the DSTP model
Description
simulateDSTP generates synthetic data from the DSTP model in the
form of response time (RT) in seconds and accuracy for both congruent and
incongruent trials.
Usage
simulateDSTP(parms, nTrials, var = 0.01, dt = 1/1000, seed = NULL)
simulate_dstp(parms, nTrials, var = 0.01, dt = 1/1000, seed = NULL)
Arguments
parms |
The set of parameters to use to simulate the data. Must be
contained in a vector in the order: |
nTrials |
How many trials to simulate per congruency condition. |
var |
The variance of the diffusion process. By default this is set to 0.01. |
dt |
The diffusion scaling parameter (i.e., time steps). By default, this is set to 0.001. |
seed |
The value for the |
Details
This function can be employed by the user to generate synthetic data, but its main purpose is to be used by the fitting procedure to generate model predictions for a set of parameter values when trying to find the best- fitting values.d
Value
Returns a data frame with three columns: rt (response time) in seconds, accuracy of the model's response (1 for correct, 0 for error), and congruency condition.
Examples
# declare the parameters
parms <- c(0.070, 0.086, 0.045, 0.065, 0.368, 1.575, 0.225)
# simulate the data. (Note this is a toy example with very low trial numbers
# to speed up the example. For proper use, increase nTrials.)
modelData <- simulateDSTP(parms, nTrials = 100)
Obtain simulated response times and accuracy from the SSP model
Description
simulateSSP generates synthetic data from the DSTP model in the
form of response time (RT) in seconds and accuracy for both congruent and
incongruent trials.
Usage
simulateSSP(parms, nTrials, var = 0.01, dt = 1/1000, seed = NULL)
simulate_ssp(parms, nTrials, var = 0.01, dt = 1/1000, seed = NULL)
Arguments
parms |
The set of parameters to use to simulate the data. Must be
contained in a vector in the order: |
nTrials |
How many trials to simulate per congruency condition. |
var |
The variance of the diffusion process. By default this is set to 0.01. |
dt |
The diffusion scaling parameter (i.e., time steps). By default, this is set to 0.001. |
seed |
The value for the |
Details
This function can be employed by the user to generate synthetic data, but its main purpose is to be used by the fitting procedure to generate model predictions for a set of parameter values when trying to find the best- fitting values.
Value
Returns a data frame with three columns: rt (response time) in seconds, accuracy of the model's response (1 for correct, 0 for error), and congruency condition.
Examples
# declare the parameters
parms <- c(0.050, 0.300, 0.400, 0.040, 1.500)
# simulate the data
# (Note this is a toy example with very low trial numbers to speed up the
# example. For proper use, increase nTrials.)
modelData <- simulateSSP(parms, nTrials = 100)