dynConfiR (version 0.0.4)

dynaViTE: Dynamical visibility, time, and evidence model (dynaViTE) and Dynamical weighted evidence and visibility model (dynWEV)

Description

Likelihood function and random number generator for the dynaViTE and dynWEV model (Hellmann et al., 2023). It includes following parameters from the drift diffusion model: a (threshold separation), z (starting point; relative), v (drift rate), t0 (non-decision time/response time constant), d (differences in speed of response execution), sv (inter-trial-variability of drift), st0 (inter-trial-variability of non-decisional components), sz (inter-trial-variability of relative starting point) and s (diffusion constant). For the computation of confidence following parameters were added: tau (post-decisional accumulation time), w (weight on the decision evidence (weight on visibility is (1-w))), muvis (mean drift rate of visibility process), svis (diffusion constant of visibility process), sigvis (variability in drift rate of visibility accumulator), th1 and th2 (lower and upper thresholds for confidence interval). lambda for dynaViTE only, the exponent of judgment time for the division by judgment time in the confidence measure, and Note that the parametrization or defaults of non-decision time variability st0 and diffusion constant s differ from what is often found in the literature.

Usage

dWEV(rt, response = "upper", th1, th2, a, v, t0 = 0, z = 0.5, d = 0,
  sz = 0, sv = 0, st0 = 0, tau = 1, w = 0.5, muvis = NULL,
  sigvis = 0, svis = 1, lambda = 0, s = 1, simult_conf = FALSE,
  precision = 1e-05, z_absolute = FALSE, stop_on_error = TRUE,
  stop_on_zero = FALSE)
rWEV(n, a, v, t0 = 0, z = 0.5, d = 0, sz = 0, sv = 0, st0 = 0,
  tau = 1, w = 0.5, muvis = NULL, sigvis = 0, svis = 1, lambda = 0,
  s = 1, delta = 0.01, maxrt = 15, simult_conf = FALSE,
  z_absolute = FALSE, stop_on_error = TRUE, process_results = FALSE)

Value

dWEV gives the density/likelihood/probability of the diffusion process producing a decision of response at time rt and a confidence judgment corresponding to the interval [ th1, th2]. The value will be a numeric vector of the same length as rt.

rWEV returns a data.frame with three columns and n rows. Column names are rt (response time), response (-1 (lower) or 1 (upper), indicating which bound was hit), and conf (the value of the confidence measure; not discretized!).

The distribution parameters (as well as response, tau, th1 and th2, w and sig) are recycled to the length of the result. In other words, the functions are completely vectorized for all parameters and even the response boundary.

Arguments

rt

a vector of RTs. Or for convenience also a data.frame with columns rt and response.

response

character vector, indicating the decision, i.e. which boundary was met first. Possible values are c("upper", "lower") (possibly abbreviated) and "upper" being the default. Alternatively, a numeric vector with values 1=lower and 2=upper or -1=lower and 1=upper, respectively. For convenience, response is converted via as.numeric also allowing factors. Ignored if the first argument is a data.frame.

th1

together with th2: scalars or numerical vectors giving the lower and upper bound of the interval of the confidence measure (see Details). Only values with th2>=th1 are accepted.

th2

(see th1)

a

threshold separation. Amount of information that is considered for a decision. Large values indicate a conservative decisional style. Typical range: 0.5 < a < 2

v

drift rate of decision process. Average slope of the information accumulation process. The drift gives information about the speed and direction of the accumulation of information. Large (absolute) values of drift indicate a good performance. If received information supports the response linked to the upper threshold the sign will be positive and vice versa. Typical range: -5 < v < 5

t0

non-decision time or response time constant (in seconds). Lower bound for the duration of all non-decisional processes (encoding and response execution). Typical range: 0.1 < t0 < 0.5. Default is 0.

z

(by default relative) starting point of decision process. Indicator of an a priori bias in decision making. When the relative starting point z deviates from 0.5, the amount of information necessary for a decision differs between response alternatives. Default is 0.5 (i.e., no bias).

d

differences in speed of response execution (in seconds). Positive values indicate that response execution is faster for responses linked to the upper threshold than for responses linked to the lower threshold. Typical range: -0.1 < d < 0.1. Default is 0.

sz

inter-trial-variability of starting point. Range of a uniform distribution with mean z describing the distribution of actual starting points from specific trials. Values different from 0 can predict fast errors (but can slow computation considerably). Typical range: 0 < sz < 0.2. Default is 0. (Given in relative range i.e. bounded by 2*min(z, 1-z))

sv

inter-trial-variability of drift rate of decision process. Standard deviation of a normal distribution with mean v describing the distribution of actual drift rates from specific trials. Values different from 0 can predict slow errors. Typical range: 0 < sv < 2. Default is 0.

st0

inter-trial-variability of non-decisional components. Range of a uniform distribution with mean t0 + st0/2 describing the distribution of actual t0 values across trials. Accounts for response times below t0. Reduces skew of predicted RT distributions. Values different from 0 can slow computation considerably. Typical range: 0 < st0 < 0.2. Default is 0.

tau

post-decisional accumulation time; the length of the time period after the decision was made until the confidence judgment is made. Range: tau>0. Default: tau=1.

w

weight put on the final state of the decision accumulator for confidence computation. 1-w is the weight on the visibility accumulator. Range: 0<w<1. Default: w=0.5.

muvis

mean drift of visibility process. If NULL (default), muvis will be set to the absolute value of v.

sigvis

the variability in drift rate of the visibility process (which varies independently from the drift rate in decision process). Range: sigvis>=0. Default: sigvis=0.

svis

diffusion constant of visibility process. Range: svis>0. Default: svis=1.

lambda

power for judgment time in the division of the confidence measure by the judgment time (Default: 0, i.e. no division which is the version of dynWEV proposed by Hellmann et al., 2023)

s

diffusion constant of decision process; standard deviation of the random noise of the diffusion process (i.e., within-trial variability), scales other parameters (see Note). Needs to be fixed to a constant in most applications. Default is 1. Note that the default used by Ratcliff and in other applications is often 0.1.

simult_conf

logical. Whether in the experiment confidence was reported simultaneously with the decision. If that is the case decision and confidence judgment are assumed to have happened subsequent before the response. Therefore tau is included in the response time. If the decision was reported before the confidence report, simul_conf should be FALSE.

precision

numerical scalar value. Precision of calculation. Corresponds to the step size of integration w.r.t. z and t0. Default is 1e-5.

z_absolute

logical. Determines whether z is treated as absolute start point (TRUE) or relative (FALSE; default) to a.

stop_on_error

Should the diffusion functions return 0 if the parameters values are outside the allowed range (= FALSE) or produce an error in this case (= TRUE).

stop_on_zero

Should the computation of densities stop as soon as a density value of 0 occurs. This may save a lot of time if the function is used for a likelihood function. Default: FALSE

n

integer. The number of samples generated.

delta

numeric. Discretization step size for simulations in the stochastic process

maxrt

numeric. Maximum decision time returned. If the simulation of the stochastic process exceeds a decision time of maxrt, the response will be set to 0 and the maxrt will be returned as rt.

process_results

logical. Whether the output simulations should contain the final state of the decision (and visibility) process as additional column. Default is FALSE, meaning that no additional columns for the final process states are returned.

Author

Sebastian Hellmann

Details

The dynamical visibility, time, and evidence (dynaViTE) model and the weighted evidence and visibility model are extensions of the 2DSD model for decision confidence (see d2DSD). It assumes that the decision follows a drift diffusion model with two additional assumptions to account for confidence. First, there is a post-decisional period of further evidence accumulation tau. Second, another accumulation process accrues information about stimulus reliability (the visibility process) including also evidence about decision irrelevant features. See Hellmann et al. (2023) for more information. The measure for confidence is then a weighted sum of the final state of the decision process X and the visibility process V over a power-function of total accumulation time, i.e. for a decision time T (which is not the response time), the confidence variable is $$conf = \frac{wX(T+\tau) + (1-w) V(T+\tau)}{(T+\tau)^\lambda}.$$ The dynWEV model is a special case of dynaViTE, with the parameter lambda=0.

All functions are fully vectorized across all parameters as well as the response to match the length or rt (i.e., the output is always of length equal to rt). This allows for trial wise parameters for each model parameter.

For convenience, the function allows that the first argument is a data.frame containing the information of the first and second argument in two columns (i.e., rt and response). Other columns (as well as passing response separately argument) will be ignored.

References

Hellmann, S., Zehetleitner, M., & Rausch, M. (2023). Simultaneous modeling of choice, confidence and response time in visual perception. Psychological Review 2023 Mar 13. doi: 10.1037/rev0000411. Epub ahead of print. PMID: 36913292.

Examples

# Plot rt distribution ignoring confidence
curve(dWEV(x, "upper", -Inf, Inf, tau=1, a=2, v=0.4, sz=0.2, sv=0.9), xlim=c(0, 2), lty=2)
curve(dWEV(x, "lower", -Inf, Inf,tau=1, a=2, v=0.4, sz=0.2, sv=0.9), col="red", lty=2, add=TRUE)
curve(dWEV(x, "upper", -Inf, Inf,  tau=1, a=2, v=0.4),add=TRUE)
curve(dWEV(x, "lower", -Inf, Inf, tau=1, a=2, v=0.4), col="red", add=TRUE)
# Generate a random sample
df1 <- rWEV(5000, a=2,v=0.5,t0=0,z=0.5,d=0,sz=0,sv=0, st0=0,  tau=1, s=1, w=0.9)
# Same RT and response distribution but different confidence distribution
df2 <- rWEV(5000, a=2,v=0.5,t0=0,z=0.5,d=0,sz=0,sv=0, st0=0,  tau=1, s=1, w=0.1)
head(df1)

# Scaling diffusion parameters leads do same density values
dWEV(df1[1:5,], th1=-Inf, th2=Inf, a=2, v=.5)[1:5]
s <- 2
dWEV(df1[1:5,], th1=-Inf, th2=Inf, a=2*s, v=.5*s, s=2)[1:5]

# Diffusion constant also scales confidence parameters
dWEV(df1[1:5,], th1=0.2, th2=1, a=2, v=.5, sv=0.2, w=0.5, sigvis = 0.2, svis = 1)[1:5]
s <- 2
dWEV(df1[1:5,], th1=0.2*s, th2=1*s, a=2*s, v=.5*s, s=2,
     sv=0.2*s, w=0.5, sigvis=0.2*s, svis=1*s)[1:5]


two_samples <- rbind(cbind(df1, w="high"),
                     cbind(df2, w="low"))
# no difference in RT distributions
boxplot(rt~w+response, data=two_samples)
# but different confidence distributions
boxplot(conf~w+response, data=two_samples)
if (requireNamespace("ggplot2", quietly = TRUE)) {
  require(ggplot2)
  ggplot(two_samples, aes(x=rt, y=conf))+
    stat_density_2d(aes(fill = after_stat(density)), geom = "raster", contour = FALSE) +
    xlim(c(0, 2))+ ylim(c(-1.5, 4))+
    facet_grid(cols=vars(w), rows=vars(response), labeller = "label_both")
}

# Restricting to specific confidence region
df1 <- df1[df1$conf >0 & df1$conf <1,]
dWEV(df1[1:5,], th1=0, th2=1, a=2, v=0.5)[1:5]

# If lower confidence threshold is higher than the upper, the function throws an error,
# except when stop_on_error is FALSE
dWEV(df1[1:5,], th1=1, th2=0, a=2, v=0.5, stop_on_error = FALSE)