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

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 = 6, z_absolute = FALSE, stop_on_error = TRUE,
  stop_on_zero = FALSE)

ddynaViTE(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 = 6, z_absolute = FALSE, stop_on_error = TRUE,
  stop_on_zero = FALSE)

rdynaViTE(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)

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 = 6, 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)

ddynaViTE(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 = 6, z_absolute = FALSE, stop_on_error = TRUE,
  stop_on_zero = FALSE)

rdynaViTE(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)

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. Determines the step size of integration w.r.t. z and t0. Represents the number of decimals precisely computed on average. Default is 6.
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.

Value

ddynaViTE 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.

rdynaViTE 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.

Details

The function dWEV was renamed to ddynaViTE in version 0.1.0 of the package. It is still here for reasons of backwards compatibility. The function just calls the ddynaViTE function (and produces a deprecation warning).

The dynamical visibility, time, and evidence (dynaViTE) model and the weighted evidence and visibility model (dynWEV) 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.

The functions dWEV and rWEV were renamed to ddynaViTE and rdynaViTE, respectively in version 0.1.0 of the package. They are still here for reasons of backwards compatibility. The functions just calls their counterpar ddynaViTE and rdynaViTE (and produce a deprecation warning).

Note

The parameterization of the non-decisional components, t0 and st0, differs from the parameterization sometimes used in the literature. In the present case t0 is the lower bound of the uniform distribution of length st0, but not its midpoint. The parameterization employed here is in line with the functions in the rtdists package.

The default diffusion constant s is 1 and not 0.1 as in most applications of Roger Ratcliff and others. Usually s is not specified as the other parameters: a, v, sv, muvis, sigvis, and svis respectively, may be scaled to produce the same distributions (as is done in the code).

The function code is basically an extension of the ddiffusion function from the package rtdists for the Ratcliff diffusion model.

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.

Author

Sebastian Hellmann

Examples

# Plot rt distribution ignoring confidence
curve(ddynaViTE(x, "upper", -Inf, Inf, tau=1, a=2, v=0.4, sz=0.2, sv=0.9), xlim=c(0, 2), lty=2)
curve(ddynaViTE(x, "lower", -Inf, Inf,tau=1, a=2, v=0.4, sz=0.2, sv=0.9), col="red", lty=2, add=TRUE)
curve(ddynaViTE(x, "upper", -Inf, Inf,  tau=1, a=2, v=0.4),add=TRUE)
curve(ddynaViTE(x, "lower", -Inf, Inf, tau=1, a=2, v=0.4), col="red", add=TRUE)

# Generate a random sample
df1 <- rdynaViTE(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 <- rdynaViTE(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)
#>     rt response      conf
#> 1 1.69       -1 1.0872480
#> 2 0.62        1 0.2294306
#> 3 0.90       -1 0.9971245
#> 4 0.25        1 0.7956949
#> 5 0.61       -1 0.2074780
#> 6 0.66        1 0.9746094

# Scaling diffusion parameters leads do same density values
ddynaViTE(df1[1:5,], th1=-Inf, th2=Inf, a=2, v=.5)[1:5]
#> [1] 0.04794175 0.55400499 0.14018232 0.69021832 0.20645267
s <- 2
ddynaViTE(df1[1:5,], th1=-Inf, th2=Inf, a=2*s, v=.5*s, s=2)[1:5]
#> [1] 0.04794175 0.55400499 0.14018232 0.69021832 0.20645267

# Diffusion constant also scales confidence parameters
ddynaViTE(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]
#> [1] 0.01444580 0.16444043 0.04968365 0.23214570 0.07777312
s <- 2
ddynaViTE(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]
#> [1] 0.01444580 0.16444043 0.04968365 0.23214570 0.07777312


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")
}
#> Warning: Removed 1276 rows containing non-finite outside the scale range
#> (`stat_density2d()`).
#> Warning: Removed 1584 rows containing missing values or values outside the scale range
#> (`geom_raster()`).


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

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

# Plot rt distribution ignoring confidence
curve(ddynaViTE(x, "upper", -Inf, Inf, tau=1, a=2, v=0.4,
                    sz=0.2, sv=0.9),
      xlim=c(0, 2), lty=2)
curve(ddynaViTE(x, "lower", -Inf, Inf,tau=1, a=2, v=0.4,
                    sz=0.2, sv=0.9),
     col="red", lty=2, add=TRUE)
curve(ddynaViTE(x, "upper", -Inf, Inf,  tau=1, a=2, v=0.4),add=TRUE)
curve(ddynaViTE(x, "lower", -Inf, Inf, tau=1, a=2, v=0.4), col="red", add=TRUE)

# Generate a random sample
df1 <- rdynaViTE(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 <- rdynaViTE(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)
#>     rt response       conf
#> 1 1.50       -1  0.1559510
#> 2 1.27        1  2.2108897
#> 3 0.34       -1 -0.3533676
#> 4 4.21       -1  1.9163242
#> 5 0.45       -1 -0.5065651
#> 6 0.75        1  1.9477587

# Scaling diffusion parameters leads do same density values
ddynaViTE(df1[1:5,], th1=-Inf, th2=Inf, a=2, v=.5)[1:5]
#> [1] 0.062062309 0.230587478 0.268787117 0.001562148 0.249336491
s <- 2
ddynaViTE(df1[1:5,], th1=-Inf, th2=Inf, a=2*s, v=.5*s, s=2)[1:5]
#> [1] 0.062062309 0.230587478 0.268787117 0.001562148 0.249336491

# Diffusion constant also scales confidence parameters
ddynaViTE(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]
#> [1] 0.0194293248 0.0562615326 0.1071384832 0.0003029661 0.0971342257
s <- 2
ddynaViTE(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]
#> [1] 0.0194293248 0.0562615326 0.1071384832 0.0003029661 0.0971342257


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")
}
#> Warning: Removed 1302 rows containing non-finite outside the scale range
#> (`stat_density2d()`).
#> Warning: Removed 1584 rows containing missing values or values outside the scale range
#> (`geom_raster()`).


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

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