predictMTLNR: Prediction of Confidence Rating and Reaction Time Distribution in the multiple-threshold log-normal noise race model

Description

predictMTLNR_Conf predicts the categorical response distribution of decision and confidence ratings, predictMTLNR_RT computes the RT distribution (density) in the multiple-threshold log-normal noise race model (Reynolds et al., 2020), given specific parameter constellations. See dMTLNR for more information about the models and parameters.

Usage

predictMTLNR_Conf(paramDf, maxrt = Inf, subdivisions = 100L,
  stop.on.error = FALSE, .progress = TRUE)
predictMTLNR_RT(paramDf, maxrt = 9, subdivisions = 100L, minrt = NULL,
  scaled = FALSE, DistConf = NULL, .progress = TRUE)

Value

predictMTLNR_Conf returns a data.frame/tibble with columns: 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. predictMTLNR_RT returns a data.frame/tibble with columns: condition, stimulus, response, rating, correct, rt and dens (and densscaled, if scaled=TRUE).

Arguments

paramDf: a list or data frame with one row. Column names should match the following names (see dMTLNR): For different stimulus quality/mean drift rates, names should be v1, v2, v3,.... (corresponding to the mean parameter for the accumulation rate for the stimulus-corresponding accumulator, therefore mu_v1 and mu_v2 are not used in this context but replaced by the parameter v); mu_d1 and mu_d2 correspond to the mean parameters for boundary distance of the two accumulators; s1 and s2 correspond to the variance parameters of the first and second boundary hitting time; rho corresponds to the correlation of boundary hitting times. Note that s_v1,s_v2,rho_v,s_d1,s_d2, and rho_d are not used in this context, although the accumulation rate-related parameters can be used to replace the above-mentioned variance parameters. Additionally, the confidence thresholds should be given by names with thetaUpper1, thetaUpper2,..., thetaLower1,... or, for symmetric thresholds only by theta1, theta2,.... (see Details for the correspondence to the data)
maxrt: numeric. The maximum RT for the integration/density computation. Default: 15 (for predictMTLNR_Conf (integration)), 9 (for predictMTLNR_RT).
subdivisions: integer (default: 100). For predictMTLNR_Conf it is used as argument for the inner integral routine. For predictMTLNR_RT it is the number of points for which the density is computed.
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.
minrt: numeric or NULL(default). The minimum rt for the density computation.
scaled: logical. For predictMTLNR_RT. 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). If TRUE, the argument DistConf should be given, if available. Default: FALSE.
DistConf: NULL or data.frame. A data.frame or matrix with column names, giving the distribution of response and rating choices for different conditions and stimulus categories in the form of the output of predictMTLNR_Conf. It is only necessary, if scaled=TRUE, because these probabilities are used for scaling. If scaled=TRUE and DistConf=NULL, it will be computed with the function predictMTLNR_Conf, which takes some time and the function will throw a message. Default: NULL

Author

Sebastian Hellmann.

Details

The function predictMTLNR_Conf consists merely of an integration of the response time density, dMTLNR, over the response time in a reasonable interval (0 to maxrt). The function predictMTLNR_RT wraps these density functions to a parameter set input and a data.frame output. For the argument paramDf, the output of the fitting function fitRTConf with the respective model may be used.

The names of the accumulation rate parameters differ from those used in dMTLNR because the accumulation rates for the two options depend on stimulus and condition. Here, the mean parameter for the accumulation rate of the correct accumulator is v (v1, v2,... respectively) in paramDf and the other one has a mean parameter of 0.

References

Reynolds, A., Kvam, P. D., Osth, A. F., & Heathcote, A. (2020). Correlated racing evidence accumulator models. Journal of Mathematical Psychology, 96, 102331. doi: doi: 10.1016/j.jmp.2020.102331

Examples

Run this code

# 1. Define some parameter set in a data.frame
paramDf <- data.frame(v1=0.5, v2=1.0, t0=0.1, st0=0,
                      mu_d1=1, mu_d2=1,
                      s1=0.5, s2=0.5, rho=0.2,
                      theta1=0.8, theta2=1.5)

# 2. Predict discrete Choice x Confidence distribution:
preds_Conf <- predictMTLNR_Conf(paramDf, maxrt=7, subdivisions=50)
head(preds_Conf)

# 3. Compute RT density
preds_RT <- predictMTLNR_RT(paramDf, maxrt=7, subdivisions=50)
# same output with scaled density column:
preds_RT <- predictMTLNR_RT(paramDf, maxrt=7, subdivisions=50,
                         scaled=TRUE, DistConf = preds_Conf)
head(preds_RT)
# \donttest{
  # produces a warning, if scaled=TRUE and DistConf missing
  preds_RT <- predictMTLNR_RT(paramDf, maxrt=7, subdivisions=50,
                           scaled=TRUE)
# }

# \donttest{
  # Example of visualization
  library(ggplot2)
  preds_Conf$rating <- factor(preds_Conf$rating, labels=c("unsure", "medium", "sure"))
  preds_RT$rating <- factor(preds_RT$rating, labels=c("unsure", "medium", "sure"))
  ggplot(preds_Conf, aes(x=interaction(rating, response), y=p))+
    geom_bar(stat="identity")+
    facet_grid(cols=vars(stimulus), rows=vars(condition), labeller = "label_both")
  ggplot(preds_RT, aes(x=rt, color=interaction(rating, response), y=dens))+
    geom_line(stat="identity")+
    facet_grid(cols=vars(stimulus), rows=vars(condition), labeller = "label_both")+
    theme(legend.position = "bottom")
  ggplot(aggregate(densscaled~rt+correct+rating+condition, preds_RT, mean),
         aes(x=rt, color=rating, y=densscaled))+
    geom_line(stat="identity")+
    facet_grid(cols=vars(condition), rows=vars(correct), labeller = "label_both")+
    theme(legend.position = "bottom")
# }
# \donttest{
  # Use PDFtoQuantiles to get predicted RT quantiles
  # (produces warning because of few rt steps (--> inaccurate calculations))
  PDFtoQuantiles(preds_RT, scaled = FALSE)
# }

# Example with asymmetric confidence thresholds
paramDf_asym <- data.frame(v1=0.5, v2=1.0, t0=0.1, st0=0,
                          mu_d1=1, mu_d2=1,
                          s1=0.5, s2=0.5, rho=0.2,
                          thetaLower1=0.5, thetaLower2=1.2,
                          thetaUpper1=0.7, thetaUpper2=1.8)

preds_Conf_asym <- predictMTLNR_Conf(paramDf_asym, maxrt=7, subdivisions=50)
head(preds_Conf_asym)

# Example with multiple conditions
paramDf_multi <- data.frame(v1=0.3, v2=0.6, v3=1.2, t0=0.1, st0=0,
                           mu_d1=1, mu_d2=1,
                           s1=0.5, s2=0.5, rho=0.2,
                           theta1=0.8, theta2=1.5)

preds_Conf_multi <- predictMTLNR_Conf(paramDf_multi, maxrt=7, subdivisions=50)
head(preds_Conf_multi)

Run the code above in your browser using DataLab