Prediction of confidence and RT distributions for several sequential sampling confidence models and parameter constellations in parallel
Source:R/predictRTConfModels.R
predictRTConfModels.RdThis function is a wrapper around the functions predictRTConf (see
there for more information). It calls the respective function for predicting the
response distribution (discrete decision and rating outcomes) and the rt density
(density for decision, rating and response time) for every model and
participant combination in paramDf.
Also, see dWEV, d2DSD, and dRM for more
information about the parameters.
Usage
predictConfModels(paramDf, maxrt = 15, subdivisions = 100L,
simult_conf = FALSE, stop.on.error = FALSE, .progress = TRUE,
parallel = FALSE, n.cores = NULL)
predictRTModels(paramDf, maxrt = 9, subdivisions = 100L, minrt = NULL,
simult_conf = FALSE, scaled = FALSE, DistConf = NULL,
.progress = TRUE, parallel = FALSE, n.cores = NULL)Arguments
- paramDf
a dataframe with one row per combination of model and participant/parameter set. Columns may include a
participant(sbj, orsubject) column, and must include amodelcolumn and the names of the model parameters. For different stimulus quality/mean drift rates, names should bev1,v2,v3,.... Differentsparameters are possible withs1,s2,s3... with equally many steps as for drift rates (same forsvparameter in dynWEV and 2DSD). Additionally, the confidence thresholds should be given by names withthetaUpper1,thetaUpper2,...,thetaLower1,... or, for symmetric thresholds only bytheta1,theta2,....- maxrt
numeric. The maximum RT for the integration/density computation. Default: 15 (for
predictConfModels(integration)) and 9 (forpredictRTModels).- subdivisions
integer(default: 100). ForpredictConfModelsit is used as argument for the inner integral routine. ForpredictRTModelsit is the number of points for which the density is computed.- simult_conf
logical, only relevant for dynWEV and 2DSD. Whether in the experiment confidence was reported simultaneously with the decision, as then decision and confidence judgment are assumed to have happened subsequent before response and computations are different, when there is an observable interjudgment time (then
simult_confshould be FALSE).- stop.on.error
logical. Argument directly passed on to integrate. Default is FALSE, since the densities invoked may lead to slow convergence of the integrals (which are still quite accurate) which causes R to throw an error.
- .progress
logical. If TRUE (default) a progress bar is drawn to the console. (Works for some OS only when
parallel=FALSE.)- parallel
logical. If TRUE, prediction is parallelized over participants and models (i.e. over the calls for the respective
predictRTConffunctions).- n.cores
integer. If
parallelis TRUE, the number of cores used for parallelization is required. IfNULL(default) the number of available cores -1 is used.- minrt
numeric or
NULL(default). The minimum rt for the density computation. IfNULL, the minimal possible response time possible with given parameters will be used (min(t0)).- scaled
logical. Whether the computed density should be scaled to integrate to one (additional column
densscaled). Otherwise the output contains only the defective density (i.e. its integral is equal to the probability of a response and not 1). IfTRUE, the argumentDistConfshould be given, if available. Default:FALSE.- DistConf
NULLordata.frame. Adata.framewith participant and model columns and columns, giving the distribution of response and rating choices for different conditions and stimulus categories in the form of the output ofpredictConfModels. It is only necessary ifscaled=TRUE, because these probabilities are used for scaling. Ifscaled=TRUEandDistConf=NULL, it will be computed with the functionpredictConfModels, which takes some time and the function will throw a message. Default:NULL
Value
predictConfModels returns a data.frame/tibble with columns: participant (or sbj,
subject depending on the input), model, condition, stimulus,
response, rating, correct, p, info, err. p is the predicted probability of a response
and rating, given the stimulus category and condition. info and err refer to the
respective outputs of the integration routine used for the computation.
predictRTModels returns a data.frame/tibble with columns: participant (or sbj,
subject depending on the input), model, condition, stimulus,
response, rating, correct, rt and dens (and densscaled, if scaled=TRUE).
Details
These functions merely split the input data frame by model participants combinations,
call the equivalent predictRTConf functions for the individual parameter sets
and bind the outputs together. They are included for convenience and the easy parallelization,
which facilitates speeding up computations considerably. For the argument
paramDf, the output of the fitting function fitRTConfModels with the
respective models and participants may be used.
The function predictConf (called by predictConfModels)
consists merely of an integration of the reaction time density or the given model,
{d*model*}, over the reaction time in a reasonable interval (0 to maxrt).
The function predictRT (called by predictRTModels) wraps these
density functions to a parameter set input and a data.frame output. '
Note, that the encoding for stimulus identity is different between diffusion based models
(2DSD, dynWEV) and race models (IRM(t), PCRM(t)). Therefore, in the columns stimulus and
response there will be a mix of encodings: -1/1 for diffusion based models and 1/2 for
race models. This, usually is not important, since for further aggregation models will
not be mixed.
Note
Different parameters for different conditions are only allowed for drift rate
v, drift rate variability sv (only dynWEV and 2DSD), and process variability
s. All other parameters are used for all conditions.
Examples
# First example for 2 participant and the "dynWEV" model
# (equivalent applicable for
# all other models (with different parameters!))
# 1. Define two parameter sets from different participants
paramDf <- data.frame(participant = c(1,2), model="dynWEV",
a=c(1.5, 2),v1=c(0.2,0.1), v2=c(1, 1.5),
t0=c(0.1, 0.2),z=c(0.52,0.45),
sz=c(0.0,0.3),sv=c(0.4,0.7), st0=c(0,0.01),
tau=c(2,3), w=c(0.5,0.2),
theta1=c(1,1.5), svis=c(0.5,0.1), sigvis=c(0.8, 1.2))
paramDf
#> participant model a v1 v2 t0 z sz sv st0 tau w theta1 svis
#> 1 1 dynWEV 1.5 0.2 1.0 0.1 0.52 0.0 0.4 0.00 2 0.5 1.0 0.5
#> 2 2 dynWEV 2.0 0.1 1.5 0.2 0.45 0.3 0.7 0.01 3 0.2 1.5 0.1
#> sigvis
#> 1 0.8
#> 2 1.2
# 2. Predict discrete Choice x Confidence distribution:
# model is not an extra argument but must be a column of paramDf
preds_Conf <- predictConfModels(paramDf, maxrt = 15, simult_conf=TRUE,
.progress=TRUE, parallel = FALSE)
# 3. Compute RT density
preds_RT <- predictRTModels(paramDf, maxrt=6, subdivisions=100,
scaled=TRUE, DistConf = preds_Conf,
parallel=FALSE, .progress = TRUE)
head(preds_RT)
#> condition stimulus response correct rating rt dens densscaled
#> 1 1 1 1 1 1 0.1000000 0.0000000 0.0000000
#> 2 1 1 1 1 1 0.1595960 0.1645173 0.5293651
#> 3 1 1 1 1 1 0.2191919 0.5064871 1.6297166
#> 4 1 1 1 1 1 0.2787879 0.5633260 1.8126064
#> 5 1 1 1 1 1 0.3383838 0.5203048 1.6741774
#> 6 1 1 1 1 1 0.3979798 0.4576166 1.4724665
#> model participant
#> 1 dynWEV 1
#> 2 dynWEV 1
#> 3 dynWEV 1
#> 4 dynWEV 1
#> 5 dynWEV 1
#> 6 dynWEV 1
# \donttest{
# produces a warning, if scaled=TRUE and DistConf missing
preds_RT <- predictRTModels(paramDf, scaled=TRUE)
#> scaled is TRUE and DistConf is NULL.
#> Confidence distribution is calculated before computing the RT densities,
#> this takes considerable additional time...
#> ...finished computation of confidence distribution.
# }
# Use PDFtoQuantiles to get predicted RT quantiles
head(PDFtoQuantiles(preds_RT, scaled = FALSE))
#> # A tibble: 6 × 9
#> condition stimulus response correct rating model participant p q
#> <int> <dbl> <dbl> <dbl> <int> <chr> <dbl> <dbl> <dbl>
#> 1 1 -1 -1 1 1 dynWEV 1 0.1 0.280
#> 2 1 -1 -1 1 1 dynWEV 1 0.3 0.370
#> 3 1 -1 -1 1 1 dynWEV 1 0.5 0.549
#> 4 1 -1 -1 1 1 dynWEV 1 0.7 0.729
#> 5 1 -1 -1 1 1 dynWEV 1 0.9 1.18
#> 6 1 -1 -1 1 1 dynWEV 2 0.1 0.370
# Second Example: only one parameter set but for two different models
# \donttest{
paramDf1 <- data.frame(model="dynWEV", a=1.5,v1=0.2, v2=1, t0=0.1,z=0.52,
sz=0.3,sv=0.4, st0=0, tau=3, w=0.5,
theta1=1, svis=0.5, sigvis=0.8)
paramDf2 <- data.frame(model="PCRMt", a=2,b=2, v1=0.5, v2=1, t0=0.1,st0=0,
wx=0.6, wint=0.2, wrt=0.2, theta1=4)
paramDf <- dplyr::full_join(paramDf1, paramDf2)
#> Joining with `by = join_by(model, a, v1, v2, t0, st0, theta1)`
paramDf # each model parameters sets hat its relevant parameters
#> model a v1 v2 t0 z sz sv st0 tau w theta1 svis sigvis b wx wint
#> 1 dynWEV 1.5 0.2 1 0.1 0.52 0.3 0.4 0 3 0.5 1 0.5 0.8 NA NA NA
#> 2 PCRMt 2.0 0.5 1 0.1 NA NA NA 0 NA NA 4 NA NA 2 0.6 0.2
#> wrt
#> 1 NA
#> 2 0.2
predictConfModels(paramDf, parallel=FALSE, .progress=TRUE)
#> condition stimulus response correct rating p info err
#> 1 1 1 1 1 1 2.753968e-01 OK 7.492716e-05
#> 2 2 1 1 1 1 5.679945e-02 OK 7.931960e-05
#> 3 1 -1 1 0 1 2.681838e-01 OK 6.398393e-05
#> 4 2 -1 1 0 1 1.195826e-01 OK 3.433863e-05
#> 5 1 1 -1 0 1 2.416201e-01 OK 5.497316e-05
#> 6 2 1 -1 0 1 1.012471e-01 OK 4.170548e-05
#> 7 1 -1 -1 1 1 2.525929e-01 OK 5.147610e-05
#> 8 2 -1 -1 1 1 5.262247e-02 OK 6.837657e-05
#> 9 1 1 1 1 2 3.102957e-01 OK 4.229500e-06
#> 10 2 1 1 1 2 7.520082e-01 OK 1.191037e-05
#> 11 1 -1 1 0 2 1.837230e-01 OK 2.486981e-06
#> 12 2 -1 1 0 2 1.004361e-01 OK 1.176693e-04
#> 13 1 1 -1 0 2 1.726883e-01 OK 2.781425e-05
#> 14 2 1 -1 0 2 8.994525e-02 OK 1.025351e-04
#> 15 1 -1 -1 1 2 2.955013e-01 OK 4.785949e-05
#> 16 2 -1 -1 1 2 7.273538e-01 OK 2.353133e-05
#> 17 1 1 1 1 1 7.417137e-01 OK 2.745013e-06
#> 18 2 1 1 1 1 8.157263e-01 OK 7.653117e-06
#> 19 1 2 1 0 1 9.326453e-02 OK 2.393541e-07
#> 20 2 2 1 0 1 1.477359e-02 OK 8.495599e-05
#> 21 1 1 2 0 1 9.326453e-02 OK 2.393541e-07
#> 22 2 1 2 0 1 1.477359e-02 OK 8.495599e-05
#> 23 1 2 2 1 1 7.417137e-01 OK 2.745013e-06
#> 24 2 2 2 1 1 8.157263e-01 OK 7.653117e-06
#> 25 1 1 1 1 2 1.474394e-01 OK 1.112900e-04
#> 26 2 1 1 1 2 1.693368e-01 OK 6.823879e-06
#> 27 1 2 1 0 2 2.130333e-03 OK 1.111883e-04
#> 28 2 2 1 0 2 8.926463e-05 OK 8.605212e-05
#> 29 1 1 2 0 2 2.130333e-03 OK 1.111883e-04
#> 30 2 1 2 0 2 8.926463e-05 OK 8.605212e-05
#> 31 1 2 2 1 2 1.474394e-01 OK 1.112900e-04
#> 32 2 2 2 1 2 1.693368e-01 OK 6.823879e-06
#> model sbj
#> 1 dynWEV 1
#> 2 dynWEV 1
#> 3 dynWEV 1
#> 4 dynWEV 1
#> 5 dynWEV 1
#> 6 dynWEV 1
#> 7 dynWEV 1
#> 8 dynWEV 1
#> 9 dynWEV 1
#> 10 dynWEV 1
#> 11 dynWEV 1
#> 12 dynWEV 1
#> 13 dynWEV 1
#> 14 dynWEV 1
#> 15 dynWEV 1
#> 16 dynWEV 1
#> 17 PCRMt 1
#> 18 PCRMt 1
#> 19 PCRMt 1
#> 20 PCRMt 1
#> 21 PCRMt 1
#> 22 PCRMt 1
#> 23 PCRMt 1
#> 24 PCRMt 1
#> 25 PCRMt 1
#> 26 PCRMt 1
#> 27 PCRMt 1
#> 28 PCRMt 1
#> 29 PCRMt 1
#> 30 PCRMt 1
#> 31 PCRMt 1
#> 32 PCRMt 1
# }