Repository Mirror for your Cloud Server and Webhosting

Type:

Package

Title:

Fast Implementation of the Diffusion Decision Model

Version:

1.0-2

Description:

Provides the probability density function (PDF), cumulative distribution function (CDF), the first-order and second-order partial derivatives of the PDF, and a fitting function for the diffusion decision model (DDM; e.g., Ratcliff & McKoon, 2008, <doi:10.1162/neco.2008.12-06-420>) with across-trial variability in the drift rate. Because the PDF, its partial derivatives, and the CDF of the DDM both contain an infinite sum, they need to be approximated. 'fddm' implements all published approximations (Navarro & Fuss, 2009, <doi:10.1016/j.jmp.2009.02.003>; Gondan, Blurton, & Kesselmeier, 2014, <doi:10.1016/j.jmp.2014.05.002>; Blurton, Kesselmeier, & Gondan, 2017, <doi:10.1016/j.jmp.2016.11.003>; Hartmann & Klauer, 2021, <doi:10.1016/j.jmp.2021.102550>) plus new approximations. All approximations are implemented purely in 'C++' providing faster speed than existing packages.

License:

GPL-2 | GPL-3 [expanded from: GPL (≥ 2)]

Imports:

Rcpp (≥ 1.0.1), stats, methods, Formula

LinkingTo:

Rcpp, RcppEigen

Depends:

R (≥ 3.5.0)

Suggests:

rtdists, RWiener, ggplot2, reshape2, testthat, knitr, rmarkdown, microbenchmark, ggnewscale, ggforce, WienR, emmeans, estimability, lmtest, numDeriv

URL:

https://github.com/rtdists/fddm

BugReports:

https://github.com/rtdists/fddm/issues

RoxygenNote:

7.3.1

Encoding:

UTF-8

VignetteBuilder:

knitr

NeedsCompilation:

yes

Packaged:

2024-07-01 13:22:08 UTC; kendal

Author:

Kendal B. Foster [aut], Henrik Singmann

[ctb, cre], Achim Zeileis [ctb] (methods partially taken from betareg)

Maintainer:

Henrik Singmann <singmann@gmail.com>

Repository:

CRAN

Date/Publication:

2024-07-02 16:00:07 UTC

Second-Order Partial Derivative of 5-parameter DDM PDF with respect to a (threshold separation)

Description

Second-Order Partial Derivative of the density function for the 5-parameter variant of the Ratcliff diffusion decision model (DDM) with respect to a, the threshold separation. This variant contains the following parameters: v (drift rate), a (threshold separation), t0 (non-decision time/response time constant), w (relative starting point), sv (inter-trial variability of drift), and sigma (diffusion coefficient of underlying Wiener process).

Usage

da2_dfddm(
  rt,
  response,
  v,
  a,
  t0,
  w = 0.5,
  sv = 0,
  sigma = 1,
  sl_thresh = 0.5,
  err_tol = 1e-06
)

Arguments

rt

A vector of response times (in seconds). If a response time is non-positve, then its density will evaluate to 0 if log = FALSE and -∞ if log = TRUE.

response

Binary response(s) that correspond(s) to either the "lower" or "upper" threshold. This model parameter can either be a singular value or a vector. The value(s) in 'response' can be of the following data types:

integers or doubles (1 → "lower", 2 → "upper");
factors (the first level gets mapped to "lower", and the second level gets mapped to "upper"; any additional levels are ignored).
strings (only the first character is checked, "L" → "lower" or "U" → "upper", case insensitive);
logicals (FALSE → "lower", TRUE → "upper");

v

Drift rate. 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, then the sign will be positive; similarly a negative value indicates that the received information supports the response linked to the lower threshold. Allowed range: v is a real number. Typical range: -5 < v < 5.

a

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

t0

Non-decision time or response time constant (in seconds). Lower bound for the duration of all non-decisional processes (encoding and response execution). If this value is greater than rt, then the resulting density is returned as if rt \le 0. Allowed range: 0 \le t0. Typical range: 0.1 < t0 < 0.5.

w

Relative starting point. Indicator of an a priori bias in decision making. When the relative starting point w deviates from 0.5, the amount of information necessary for a decision differs between response alternatives. Allowed range: 0 < w < 1. Default value is 0.5 (i.e., no bias).

sv

Inter-trial-variability of drift rate. 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. Allowed range: 0 \le sv. Typical range: 0 < sv < 2. Default value is 0, which indicates no drift in the function call. See Details for more information.

sigma

Diffusion coefficient of the underlying Wiener process. Allowed range: 0 < sigma. Default value is 1. This parameter simply scales the parameters v, a, and sv as follows. See Details for more information.

a → a / sigma
v → v / sigma
sv → sv / sigma

sl_thresh

Threshold for deciding when to use the "small-time" variant or the "large-time" variant. If the "effective response time" is greater than sl_thresh (i.e., \frac{rt}{a^2} > sl_thresh), then the "large-time" variant is used; otherwise, the "small-time" variant is used. Allowed values are any real number; however any non-positive number means that the "large-time" variant will always be used. Similarly, any very large positive number (e.g., +Inf) means that the "small-time" variant will always be used. Default value is 0.5.

err_tol

Allowed error tolerance of the overall calculation. Since the partial derivative of the density function contains the sum of two infinite sums, each approximation of these two infinite sums will have an individual error tolerance of err_tol / 2; thus the total overall error of the calculation will be at most err_tol. If the provided error tolerance is less than 1e-300, it is set to 1e-300. Default is 1e-6.

Details

All of the model inputs and parameters (rt, response, v, a, t0, w, sv, sigma) can be input as a single value or as a vector of values. If input as a vector of values, then the standard R input wrapping will occur.

sv - Both the "small-time" and "large-time" variants of the density function have two further variants: one with a constant drift rate v (i.e., sv = 0), and one with a variable drift rate v (i.e., sv > 0). The details of the differences between these two density functions can be found in our associated paper. To use the density function with a constant drift rate, leave the parameter sv to its default value of sv = 0, as this will indicate no drift to the function. To use the density function with a variable drift rate, set the parameter sv to some non-negative value, i.e., sv > 0.

sigma - The default value of this parameter is 1 because it only scales the parameters v, a, and sv, as shown above. However, other formulations of the DDM may set sigma = 0.1 (see Ratcliff (1978), the fourth reference), so care must be taken when comparing the results of different formulations.

Value

A vector containing the second-order partial derivatives of the DDM PDF with precision err_tol whose length matches that of the longest input parameter (usually rt).

References

Navarro, D. J., & Fuss, I. G. (2009). Fast and accurate calculations for first-passage times in Wiener diffusion models. Journal of Mathematical Psychology, 53(4), 222-230.

Gondan, M., Blurton, S. P., & Kesselmeier, M. (2014). Even faster and even more accurate first-passage time densities and distributions for the Wiener diffusion model. Journal of Mathematical Psychology, 60, 20-22.

Blurton, S. P., Kesselmeier, M., & Gondan, M. (2017). The first-passage time distribution for the diffusion model with variable drift. Journal of Mathematical Psychology, 76, 7-12.

Hartmann, R., Klauer, K. C. (2021). Partial derivatives for the first-passage time distribution in Wiener diffusion models. Journal of Mathematical Psychology, 103, 102550.

Ratcliff, R. (1978). A theory of memory retrieval. Psychological review, 85(2), 59.

Examples

# derivative with respect to rt (response time)
dt_dfddm(rt = 1.2, response = "lower", a = 1, v = -1, t0 = 0.3, w = 0.5,
         sv = 0.4, err_tol = 1e-6)

# derivative with respect to t0 (non-decision time)
dt0_dfddm(rt = 1.2, response = "lower", a = 1, v = -1, t0 = 0.3, w = 0.5,
          sv = 0.4, err_tol = 1e-6)

# derivative with respect to a (threshold separation)
da_dfddm(rt = 1.2, response = "lower", a = 1, v = -1, t0 = 0.3, w = 0.5,
         sv = 0.4, err_tol = 1e-6)

# derivative with respect to v (drift rate)
dv_dfddm(rt = 1.2, response = "lower", a = 1, v = -1, t0 = 0.3, w = 0.5,
         sv = 0.4, err_tol = 1e-6)

# derivative with respect to w (relative starting point)
dw_dfddm(rt = 1.2, response = "lower", a = 1, v = -1, t0 = 0.3, w = 0.5,
         sv = 0.4, err_tol = 1e-6)

# derivative with respect to sv (inter-trial variability in the drift rate)
dsv_dfddm(rt = 1.2, response = "lower", a = 1, v = -1, t0 = 0.3, w = 0.5,
          sv = 0.4, err_tol = 1e-6)

#-------- Log Versions --------#

# # derivative with respect to rt (response time)
# dt_log_dfddm(rt = 1.2, response = "lower", a = 1, v = -1, t0 = 0.3, w = 0.5,
#              sv = 0.4, err_tol = 1e-6)

# # derivative with respect to t0 (non-decision time)
# dt0_log_dfddm(rt = 1.2, response = "lower", a = 1, v = -1, t0 = 0.3, w = 0.5,
#               sv = 0.4, err_tol = 1e-6)

# # derivative with respect to a (threshold separation)
# da_log_dfddm(rt = 1.2, response = "lower", a = 1, v = -1, t0 = 0.3, w = 0.5,
#              sv = 0.4, err_tol = 1e-6)

# # derivative with respect to v (drift rate)
# dv_log_dfddm(rt = 1.2, response = "lower", a = 1, v = -1, t0 = 0.3, w = 0.5,
#              sv = 0.4, err_tol = 1e-6)

# # derivative with respect to w (relative starting point)
# dw_log_dfddm(rt = 1.2, response = "lower", a = 1, v = -1, t0 = 0.3, w = 0.5,
#              sv = 0.4, err_tol = 1e-6)

# # derivative with respect to sv (inter-trial variability in the drift rate)
# dsv_log_dfddm(rt = 1.2, response = "lower", a = 1, v = -1, t0 = 0.3, w = 0.5,
#               sv = 0.4, err_tol = 1e-6)

Partial Derivative of 5-parameter DDM PDF with respect to a (threshold separation)

Description

Partial Derivative of the density function for the 5-parameter variant of the Ratcliff diffusion decision model (DDM) with respect to a, the threshold separation. This variant contains the following parameters: v (drift rate), a (threshold separation), t0 (non-decision time/response time constant), w (relative starting point), sv (inter-trial variability of drift), and sigma (diffusion coefficient of underlying Wiener process).

Usage

da_dfddm(
  rt,
  response,
  v,
  a,
  t0,
  w = 0.5,
  sv = 0,
  sigma = 1,
  sl_thresh = 0.5,
  err_tol = 1e-06
)

Arguments

rt

A vector of response times (in seconds). If a response time is non-positve, then its density will evaluate to 0 if log = FALSE and -∞ if log = TRUE.

response

integers or doubles (1 → "lower", 2 → "upper");
factors (the first level gets mapped to "lower", and the second level gets mapped to "upper"; any additional levels are ignored).
strings (only the first character is checked, "L" → "lower" or "U" → "upper", case insensitive);
logicals (FALSE → "lower", TRUE → "upper");

v

a

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

t0

w

sv

sigma

a → a / sigma
v → v / sigma
sv → sv / sigma

sl_thresh

err_tol

Details

Value

A vector containing the partial derivatives of the DDM PDF with precision err_tol whose length matches that of the longest input parameter (usually rt).

References

Navarro, D. J., & Fuss, I. G. (2009). Fast and accurate calculations for first-passage times in Wiener diffusion models. Journal of Mathematical Psychology, 53(4), 222-230.

Blurton, S. P., Kesselmeier, M., & Gondan, M. (2017). The first-passage time distribution for the diffusion model with variable drift. Journal of Mathematical Psychology, 76, 7-12.

Hartmann, R., Klauer, K. C. (2021). Partial derivatives for the first-passage time distribution in Wiener diffusion models. Journal of Mathematical Psychology, 103, 102550.

Ratcliff, R. (1978). A theory of memory retrieval. Psychological review, 85(2), 59.

Examples

# derivative with respect to rt (response time)
dt_dfddm(rt = 1.2, response = "lower", a = 1, v = -1, t0 = 0.3, w = 0.5,
         sv = 0.4, err_tol = 1e-6)

# derivative with respect to t0 (non-decision time)
dt0_dfddm(rt = 1.2, response = "lower", a = 1, v = -1, t0 = 0.3, w = 0.5,
          sv = 0.4, err_tol = 1e-6)

# derivative with respect to a (threshold separation)
da_dfddm(rt = 1.2, response = "lower", a = 1, v = -1, t0 = 0.3, w = 0.5,
         sv = 0.4, err_tol = 1e-6)

# derivative with respect to v (drift rate)
dv_dfddm(rt = 1.2, response = "lower", a = 1, v = -1, t0 = 0.3, w = 0.5,
         sv = 0.4, err_tol = 1e-6)

# derivative with respect to w (relative starting point)
dw_dfddm(rt = 1.2, response = "lower", a = 1, v = -1, t0 = 0.3, w = 0.5,
         sv = 0.4, err_tol = 1e-6)

# derivative with respect to sv (inter-trial variability in the drift rate)
dsv_dfddm(rt = 1.2, response = "lower", a = 1, v = -1, t0 = 0.3, w = 0.5,
          sv = 0.4, err_tol = 1e-6)

#-------- Log Versions --------#

# # derivative with respect to rt (response time)
# dt_log_dfddm(rt = 1.2, response = "lower", a = 1, v = -1, t0 = 0.3, w = 0.5,
#              sv = 0.4, err_tol = 1e-6)

# # derivative with respect to t0 (non-decision time)
# dt0_log_dfddm(rt = 1.2, response = "lower", a = 1, v = -1, t0 = 0.3, w = 0.5,
#               sv = 0.4, err_tol = 1e-6)

# # derivative with respect to a (threshold separation)
# da_log_dfddm(rt = 1.2, response = "lower", a = 1, v = -1, t0 = 0.3, w = 0.5,
#              sv = 0.4, err_tol = 1e-6)

# # derivative with respect to v (drift rate)
# dv_log_dfddm(rt = 1.2, response = "lower", a = 1, v = -1, t0 = 0.3, w = 0.5,
#              sv = 0.4, err_tol = 1e-6)

# # derivative with respect to w (relative starting point)
# dw_log_dfddm(rt = 1.2, response = "lower", a = 1, v = -1, t0 = 0.3, w = 0.5,
#              sv = 0.4, err_tol = 1e-6)

# # derivative with respect to sv (inter-trial variability in the drift rate)
# dsv_log_dfddm(rt = 1.2, response = "lower", a = 1, v = -1, t0 = 0.3, w = 0.5,
#               sv = 0.4, err_tol = 1e-6)

Estimation of 5-Parameter DDM

Description

Fit the 5-parameter DDM (Diffusion Decision Model) via maximum likelihood estimation. The model for each DDM parameter can be specified symbolically using R's formula interface. With the exception of the drift rate (which is always estimated) all parameters can be either fixed or estimates.

Usage

ddm(
  drift,
  boundary = ~1,
  ndt = ~1,
  bias = 0.5,
  sv = 0,
  data,
  optim = "nlminb",
  args_optim = list(init = NULL, lo_bds = NULL, up_bds = NULL, control = list()),
  args_ddm = list(err_tol = 1e-06),
  use_gradient = TRUE,
  compiled_model = TRUE,
  model = TRUE,
  mmatrix = TRUE,
  response = TRUE,
  na.action,
  subset,
  contrasts = NULL
)

Arguments

drift

Two-sided formula. The left-hand side describes the response, the right-hand side provides a symbolic description of the regression model underlying the drift rate (v). The left-hand side needs to specify the column in the data containing response time and corresponding binary decision, concatenated by + , e.g., rt + response ~ ...

boundary, ndt, bias, sv

Either a one-sided formula providing a symbolic description of the regression model or a scalar number given the value this parameter should be fixed to. Boundary separation (a), non-decision time (t0), relative initial bias (w), or inter-trial variability in the drift rate (sv)

data, na.action, subset

arguments controlling formula processing via model.frame.

optim

character string or fitting function indicating which numerical optimization method should be used. The default "nlminb" uses the corresponding function.

args_optim

named list of additional arguments for the optimization function. The available options are:

init vector containing the initial values to be used in the optimization for each coefficient. Note that the number and type of coefficients used (i.e., intercept or difference) is determined by the model matrices, which are in turn determined by the formulas assigned to each DDM parameter (see the Details section for an overview of formulas and coefficients). For an example, run the ddm() function with parameter set to its default value, and view the initial value vector via the slot $optim_info$args_optim$init. By default for intercept coefficients, the initial values for the drift rate (v), boundary separation (a), and non-decision time (t0) will be generated using EZ-Diffusion (Wagenmakers et al. 2007); bias (w) is initialized to 0.5; inter-trial variability in the drift rate (sv) is initialized to 0.0. Difference coefficients are initialized to 0.0.
lo_bds vector containing the lower bounds to be used in the optimization for each coefficient. The same consideration of coefficient types occurs here as it does with init. The defaults for intercept coefficients are: drift rate v > -Inf, boundary separation a > 0, non-decision time t0 > 0, bias w > 0, inter-trial variability in the drift rate sv \le 0. All difference coefficients have a lower bound of -Inf.
up_bds vector containing the upper bounds to be used in the optimization for each coefficient. The same consideration of coefficient types occurs here as it does with init. The defaults for intercept coefficients are: drift rate v < Inf, boundary separation a < Inf, non-decision time t0 < Inf, bias w < 1, inter-trial variability in the drift rate sv < Inf. All difference coefficients have a upper bound of Inf.
control additional control arguments passed to control argument of optimization function specified in optim

args_ddm

named list of additional arguments passed to density function calculation. Currently, the only option for this is err_tol, the desired error tolerance used in the density function calculation.

use_gradient

logical. Should gradient be used during numerical optimization? Default is TRUE.

compiled_model, model, mmatrix, response

logicals. If TRUE the corresponding components of the fit (the compiled model object, the model frame, the model matrix, the response matrix) are returned.

contrasts

optional list. See the contrasts.arg of model.matrix.default

Details

ddm uses model.matrix for transforming the symbolic description of the regression model underlying each parameter into estimated coefficients. The following provides a few examples:

~ 1 estimates a single coefficient, named (Intercept)
~ condition estimates the intercept plus k - 1 coefficients for a factor with k levels (e.g., intercept plus one coefficient if condition has two levels). The interpretation of the coefficients depend on the factor contrasts employed, which are usually based on the contrasts specified in options("contrasts"). For the default treatment contrasts (contr.treatment), the intercept corresponds to the first factor level and the additional coefficients correspond to the difference from the intercept (i.e., first factor level). When using contr.sum the intercept corresponds to the grand mean and the additional coefficients correspond to the differences from the grand mean.
~ 0 + condition estimates no intercept but one coefficient per factor level. This specification can also be used to get one coefficient per cell for a multi-factorial design, e.g., ~ 0 + condition1:condition2.
~ 0 + condition1 + condition1:condition2 estimates one "intercept" per level of condition1 factor (which is not called intercept) plus k - 1 difference parameters from the condition-specific intercept for the k-levels of condition2. The interpretation of the difference parameters again depends on the contrasts used (e.g., treatment vs. sum-to-zero contrasts, see examples). This formula specification can often make sense for the drift rate when condition1 is the factor (such as item type) mapped to upper and lower response boundary of the DDM and condition2 is another factor by which we want the drift rate to differ. This essentially gives one overall drift rate per response boundary plus the differences from this overall one (note again that with treatment contrasts this overall drift rate is the first factor level of condition2).

To get meaningful results it is necessary to estimate separate drift rates for the different condition/item-types that are mapped onto the upper and lower boundary of the diffusion model.

If a non-default fitting function is used, it needs to minimize the negative log-likelihood, accept the following arguments, init, objective, gradient, lower, upper, control , and return a list with the following arguments coefficients, loglik, converged, optim (where converged is boolean and optim can be an arbitrary list with additional information).

Value

Object of class ddm (i.e., a list with components as listed below) for which a number of common methods such as print, coef, and logLik are implemented, see ddm-methods.

coefficients a named list whose elements are the values of the estimated model parameters
dpar a character vector containing the names of the estimated model parameters
fixed_dpar a named list whose elements are the values of the fixed model parameters
loglik the value of the log-likelihood function at the optimized parameter values
hessians a named list whose elements are the individual Hessians for each of the model parameters
vcov a named list whose elements are the individual variance-covariance matrices for each of the model parameters
nobs the number of observations in the data used for fitting
npar the number of parameters used to fit the model (i.e., the estimated model parameters plus any hyperparameters)
df.residual the residual degrees of freedom (the number of observations - the number of parameters)
call the original function call to ddm
formula the formulas used in the model (1 indicates that the model parameter was estimated with a single coefficient; 0 indicates that the model parameter was fixed)
dpar_formulas a named list whose elements are the formulas for the model parameters (1 indicates that the model parameter was estimated with a single coefficient; 0 indicates that the model parameter was fixed)
na.action na.action
terms a named list whose elements are the model parameters, except the last element is named full and shows the breakdown of the model with all model parameters
levels a named list whose elements are the levels associated with any parameters that are factors (the elements are NULL if the parameter is not a factor), and whose last element is named FULL and shows all of the levels used in the model
contrasts a named list whose elements are the type of contrasts used in the model
args_ddm a named list whose elements are the optional arguments used in the calculation of the DDM log-likelihood function
link a named list whose elements show information about the link function used for each model parameter (currently the only link function is the identity function)
converged a logical indicating whether the optimization converged (TRUE) or not (FALSE)
optim_info a named list whose elements are information about the optimization process (e.g., the name of the algorithm used, the final value of the objective function, the number of evaluations of the gradient function, etc.)
model the data used in the model (might need to check this)
response the response data used in the model
mmatrix a named list whose elements are the model matrices for each of the estimated parameters
compiled_model C++ object that contains the compiled model (see list below for more details)

The C++ object accessible via the compiled_model component of the above R object of class ddm contains the following components:

rt a numeric vector of the response time data used in the model
response an integer vector of the response data used in the model (coded such that 1 corresponds to the "lower" boundary and 2 corresponds to the "upper" boundary)
err_tol the error tolerance used in the calculations for fitting the DDM
coefficients a numeric vector containing the current set of coefficients for the formulas provided to the ddm() function call; the coefficients correspond to the DDM parameters in the following order: v, a, t0, w, sv
likelihood a double containing the log-likelihood for the current set of coefficients (note this can be changed by calling the function calculate_loglik() below)
modmat_v a numeric matrix containing the model matrix for v, the drift rate, determined by the formula input to the argument drift in the ddm() function call
modmat_a a numeric matrix containing the model matrix for a, the boundary separation, determined by the formula input to the argument boundary in the ddm() function call
modmat_t0 a numeric matrix containing the model matrix for t0, the non-decision time, determined by the formula input to the argument ndt in the ddm() function call
modmat_w a numeric matrix containing the model matrix for w, the inital bias, determined by the formula input to the argument bias in the ddm() function call
modmat_sv a numeric matrix containing the model matrix for sv, the inter-trial variability in the drift rate, determined by the formula input to the argument sv in the ddm() function call
hess_v a numeric matrix containing the Hessian for v, the drift rate, whose dimensions are determined by the formula input to the argument drift in the ddm() function call
hess_a a numeric matrix containing the Hessian for a, the boundary separation, whose dimensions are determined by the formula input to the argument drift in the ddm() function call
hess_t0 a numeric matrix containing the Hessian for t0, the non-decision time, whose dimensions are determined by the formula input to the argument drift in the ddm() function call
hess_w a numeric matrix containing the Hessian for w, the initial bias, whose dimensions are determined by the formula input to the argument drift in the ddm() function call
hess_sv a numeric matrix containing the Hessian for sv, the inter-trial variability in the drift rate, whose dimensions are determined by the formula input to the argument drift in the ddm() function call
vcov_v a numeric matrix containing the variance-covariance matrix for v, the drift rate, whose dimensions are determined by the formula input to the argument drift in the ddm() function call
vcov_a a numeric matrix containing the variance-covariance matrix for a, the boundary separation, whose dimensions are determined by the formula input to the argument boundary in the ddm() function call
vcov_t0 a numeric matrix containing the variance-covariance matrix for t0, the non-decision time, whose dimensions are determined by the formula input to the argument ndt in the ddm() function call
vcov_w a numeric matrix containing the variance-covariance matrix for w, the inital bias, whose dimensions are determined by the formula input to the argument bias in the ddm() function call
vcov_sv a numeric matrix containing the variance-covariance matrix for v, the inter-trial variability in the drift rate, whose dimensions are determined by the formula input to the argument sv in the ddm() function call
calculate_loglik calculates and returns a double containing the negated log-likelihood (note that this will overwrite the likelihood component of the C++ object)
calculate_gradient calculates and returns a numeric vector of the negated gradients for the provided coefficient values; the gradients are stored in the same manner as their corresponding coefficents (note that this will overwrite the likelihood) component of the C++ object)
calculate_hessians calculates and returns a named list of the negated Hessians for each model parameter for the provided coefficient values (note that this will overwrite the likelihood, hess_v, hess_a, hess_t0, hess_w, and hess_sv components of the C++ object)
calculate_vcov calculates and returns a named list of the variance-covariance matrices for each model parameter for the stored coefficients (note that this will overwrite the likelihood, hess_v, hess_a, hess_t0, hess_w, hess_sv, vcov_v, vcov_a, vcov_t0, vcov_w, and vcov_sv components of the C++ object)
calculate_standard_error calculates and returns a numeric vector of the standard errors of the stored coefficients; the standard errors are stored in the same manner as their corresponding coefficients (note that this will overwrite the likelihood, hess_v, hess_a, hess_t0, hess_w, hess_sv, vcov_v, vcov_a, vcov_t0, vcov_w, and vcov_sv components of the C++ object)

Examples

# prepare data
data(med_dec, package = "fddm")
med_dec <- med_dec[which(med_dec[["rt"]] >= 0), ] ## only use valid RTs
## select data from one participant
p1 <- med_dec[med_dec[["id"]] == 2 & med_dec[["group"]] == "experienced", ]
head(p1)


##----------------------------------------------
##        Easiest: Fitting using emmeans       -
##----------------------------------------------

## Because we use an ANOVA approach, we set orthogonal sum-to-zero contrasts
op <- options(contrasts = c('contr.sum', 'contr.poly'))

fit0 <- ddm(rt + response ~ classification*difficulty, data = p1)
summary(fit0)

## for more tests, we use emmeans:
if (requireNamespace("emmeans")) {
# for ANOVA table:
emmeans::joint_tests(fit0)
# get conditional main effects of difficulty (for each level of classification):
emmeans::joint_tests(fit0, by = "classification")

# get mean drift rates per condition:
em1 <- emmeans::emmeans(fit0, "difficulty", by = "classification")
em1
# compare mean drift rates per condition
pairs(em1)
update(pairs(em1), by = NULL, adjust = "holm")
}

options(op) # reset contrasts


##----------------------------------------------------------------
##              Fitting with custom parametrisation              -
##----------------------------------------------------------------

## one drift rate per classification by difficulty design cell
fit1 <- ddm(rt + response ~ 0 + classification:difficulty, data = p1)
summary(fit1)

## set default contrasts (just in case contrasts have been changed)
op <- options(contrasts = c('contr.treatment', 'contr.poly'))
## one drift rate "intercept" per classification condition (blast vs. non-blast)
## corresponding to first level of difficulty factor (easy)
## plus one further coefficient per classification condition corresponding to
## difference from "intercept" (hard - easy)
fit1b <- ddm(rt + response ~ 0 + classification + classification:difficulty,
             data = p1, args_optim = list(control = list(iter.max = 1000,
                                                         eval.max = 1000)))
summary(fit1b)
options(op) # reset contrasts

## set orthogonal sum-to-zero contrasts
op <- options(contrasts = c('contr.sum', 'contr.poly'))
## one drift rate "intercept" per classification condition (blast vs. non-blast)
## corresponding to mean drift rate for the classification condition
## plus one further coefficient per classification condition corresponding to
## difference from "intercept" (hard/easy - mean drift rate)
fit1c <- ddm(rt + response ~ 0 + classification + classification:difficulty,
             data = p1)
summary(fit1c)
options(op) ## reset contrasts

## all variants produce same fit, only meaning of parameters differs
logLik(fit1)
logLik(fit1b)
logLik(fit1c)
logLik(fit0) ## also model above

## all models estimate same drift rates, but in different parametrisation:
coef(fit1)  ## drift rates per design cell
## same drift rates based on fit1b:
c(coef(fit1b)[1:2],
  coef(fit1b)[1] + coef(fit1b)[3], coef(fit1b)[2] + coef(fit1b)[4])
## same drift rates based on fit1c:
c(coef(fit1c)[1] + coef(fit1c)[3], coef(fit1c)[2] + coef(fit1c)[4],
  coef(fit1c)[1] - coef(fit1c)[3], coef(fit1c)[2] - coef(fit1c)[4])

# we can estimate a model that freely estimates response bias
# (instead of fixing it at 0.5)
fit2 <- ddm(rt + response ~ 0 + classification:difficulty, bias = ~1, data = p1)
summary(fit2)
## Note: estimating bias only makes sense in situations like here where the
## response boundaries do not correspond to correct/incorrect but to the
## actual responses participants gave (here: blast vs. non-blast classification)

## now let's perform a likelihood ratio test to check if estimating response
## bias freely leads to a significant increase in model fit?
if (requireNamespace("lmtest")) { ## requires package lmtest
  lmtest::lrtest(fit1, fit2)
  ## does not look like it (p = 0.1691)
}


# we can also make a DDM parameter, such as boundary, depend on a numeric
# variable, such as block number
fit3 <- ddm(rt + response ~ 0 + classification:difficulty,
            boundary = ~ block, data = p1)
summary(fit3)

## does making boundary depend on block leads to a significant increase in model
## fit?
if (requireNamespace("lmtest")) { ## requires package lmtest
  lmtest::lrtest(fit1, fit3)
  ## does not look like it (p = 0.198)
}


##----------------------------------------------------------------
##              Fitting with optimization arguments              -
##----------------------------------------------------------------
## example of how to use your own initial values and bounds for the optimization
## of the coefficients (determined by the model matrices/formulas)
options(op) # reset contrasts

# this uses the default generated initial values and bounds
fitex0 <- ddm(rt + response ~ 0 + classification:difficulty, data = p1)

# we can see the number of coefficients (and thus the number of initial values
# and bounds) required if we wish to use our own
fitex0$optim_info$args_optim$init
fitex0$optim_info$args_optim$lo_bds
fitex0$optim_info$args_optim$up_bds
# -1.9270279  2.5408864 -1.9270279  0.3181987  1.7907438  0.1264035
# -Inf        -Inf      -Inf        -Inf       0          0
# Inf         Inf       Inf         Inf        Inf        0.461
# the first four coefficients are for the drift rate (given by the formula we
# provided), and the last two are for the boundary separation and non-decision
# time, respectively (note that the default is to estimate these two model
# parameters with a single coefficient).

# to use our own initial values, we can include them in the `args_optim` list,
# but note that they must be within the generated bounds
fitex1 <- ddm(rt + response ~ 0 + classification:difficulty, data = p1,
              args_optim = list(init = c(-1.5, 1, -1, 1, 1.5, 0.3)))

# to use our own bounds, we again can include them in the `args_optim` list,
# but note that they must contain the generated initial values
fitex2 <- ddm(rt + response ~ 0 + classification:difficulty, data = p1,
              args_optim = list(lo_bds = c(-20, -20, -20, -20, 0, 0),
                                up_bds = c(20, 20, 20, 20, 10, 0.5)))

# to use both our own initial values and bounds, we include them in the
# `args_optim` list, and the bounds must contain the initial values
fitex3 <- ddm(rt + response ~ 0 + classification:difficulty, data = p1,
              args_optim = list(init = c(-1.5, 1, -1, 1, 1.5, 0.3),
                                lo_bds = c(-20, -20, -20, -20, 0, 0),
                                up_bds = c(20, 20, 20, 20, 10, 0.5)))

# the only other option in the `args_optim` list is the control parameters
# directly used by the optimization function (e.g., the maximum number of
# iterations); here we'll set the maximum number of iterations and function
# evaluations
fitex4 <- ddm(rt + response ~ 0 + classification:difficulty, data = p1,
              args_optim = list(control = list(iter.max = 1000,
                                               eval.max = 1000)))

Methods for ddm objects

Description

Implemented S3 methods for objects of class ddm as returned by function ddm().

Usage

## S3 method for class 'ddm'
print(x, digits = max(3, getOption("digits") - 3), ...)

## S3 method for class 'ddm'
summary(object, ...)

## S3 method for class 'summary.ddm'
print(x, digits = max(3, getOption("digits") - 3), ...)

## S3 method for class 'ddm'
coef(object, dpar = c("drift", "boundary", "ndt", "bias", "sv", "full"), ...)

## S3 method for class 'ddm'
vcov(object, dpar = c("drift", "boundary", "ndt", "bias", "sv"), ...)

## S3 method for class 'ddm'
model.frame(formula, ...)

## S3 method for class 'ddm'
model.matrix(object, dpar = c("drift", "boundary", "ndt", "bias", "sv"), ...)

## S3 method for class 'ddm'
terms(x, dpar = c("drift", "boundary", "ndt", "bias", "sv"), ...)

## S3 method for class 'ddm'
logLik(object, ...)

## S3 method for class 'ddm'
update(object, ...)

recover_data.ddm(object, data, ...)

emm_basis.ddm(
  object,
  trms,
  xlev,
  grid,
  dpar = c("drift", "boundary", "ndt", "bias", "sv"),
  ...
)

Arguments

digits

minimal number of significant digits, see print.default.

...

further arguments passed to or from other methods.

object, x

object of class ddm

dpar

which distributional parameter or DDM parameter to focus on. In addition to the five DDM parameters c("drift", "boundary", "ndt", "bias", "sv"), some methods accept "full" which returns information for all estimated parameters.

formula

see model.frame

data, trms, xlev, grid

arguments needed for emmeans support.

Details

The methods should fail with an informative error if a distributional parameter is selected in dpar that is fixed and not estimated.

Density of Ratcliff Diffusion Decision Model

Description

Density function for the Ratcliff diffusion decision model (DDM) with following parameters: v (drift rate), a (threshold separation), t0 (non-decision time/response time constant), w (relative starting point), sv (inter-trial variability of drift), and sigma (diffusion coefficient of underlying Wiener process). If you are looking to fit the DDM, see ddm().

Usage

dfddm(
  rt,
  response,
  v,
  a,
  t0,
  w = 0.5,
  sv = 0,
  sigma = 1,
  err_tol = 1e-06,
  log = FALSE,
  switch_mech = "eff_rt",
  switch_thresh = 0.8,
  n_terms_small = "SWSE",
  summation_small = "2017"
)

Arguments

rt

A vector of response times (in seconds). If a response time is non-positve, then its density will evaluate to 0 if log = FALSE and -∞ if log = TRUE.

response

integers or doubles (1 → "lower", 2 → "upper");
factors (the first level gets mapped to "lower", and the second level gets mapped to "upper"; any additional levels are ignored).
strings (only the first character is checked, "L" → "lower" or "U" → "upper", case insensitive);
logicals (FALSE → "lower", TRUE → "upper");

v

a

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

t0

w

sv

sigma

Diffusion coefficient of the underlying Wiener process. Allowed range: 0 < sigma. Default value is 1. This parameter simply scales the parameters a, v, and sv as follows. See Details for more information.

a → a / sigma
v → v / sigma
sv → sv / sigma

err_tol

Allowed error tolerance of the density function. The density function contains an infinite sum that must be approximated; this parameter is the upper bound of the total error incurred from this approximation (in absolute value). See Details for more information. Default is 1e-6.

log

Logical; if TRUE, probabilities p are given as log(p). Default is FALSE, which gives the density on the probability scale.

switch_mech

Which switching mechanism to use in the choice of the "large-time" or "small-time" density function. Can be one of {"eff_rt", "terms_large", "terms", "small", "large"}. Note that the large-time approximation is unstable for small effective response times ((rt-t0) /(a*a) < 0.009). See Details for more information. Default is "eff_rt".

switch_thresh

Threshold for determining whether the effective response time ((rt-t0) /(a*a)) is "large" or "small". This parameter is only considered if switch_mech = "eff_rt" or switch_mech = "terms_large". If switch_mech = "eff_rt", an effective response time greater than switch_thresh is considered "large", and the "large-time" variant of the density function is used; otherwise, the "small-time" variant of the density function is used. The default is 0.8. If switch_mech = "terms_large", this parameter is treated as ceiling(switch_thresh); the smallest integer that is not less than switch_thresh. In this case, the default is ceiling(0.8) = 1. See the switch_mech section of Details for more information. Note that if switch_thresh \le 0, then the effective response time is always treated as "large"; contrarily, if switch_thresh = ∞ then the effective response time is always treated as "small". However, it is better to simply set switch_mech = "large" or switch_mech = "small" to always use the "large-time" or "small-time" variant, respectively.

n_terms_small

Which method to use for calculating the "small-time" approximation to the density function. Only applicable if switch_mech = "terms" or switch_mech = "small"; all other values of switch_mech cause this parameter to be ignored. If switch_mech = "small", the allowed values are "SWSE", "Gondan", and "Navarro". The default value is "SWSE". If switch_mech = "terms", the allowed values are "Gondan" and "Navarro". Note that if the user inputs switch_mech = "terms", then the user must also explicitly input either n_terms_small = "Gondan" or n_terms_small = "Navarro". See Details for more information.

summation_small

Which style of summation to use for the small-time approximation to the infinite sum. Can be one of {"2017", "2014"}. Only applicable if switch_mech is one of {"eff_rt", "terms_large", "terms", "small"}. See Details for more information. Default is "2017".

Details

The default settings of switch_mech = "eff_rt", switch_thresh = "0.8", n_terms_small = "SWSE", summation_small = "2017" produce the fastest and most accurate results, as shown in our associated paper.

err_tol - The density function is composed of an infinite sum (that must be approximated) and a multiplicative term outside the infinite sum, m. The total error of the approximation is the error incurred from truncating the infinite sum multiplied by m. Thus, to ensure that the total error is bounded by the user-provided error tolerance, err_tol, the approximation to the infinite sum uses a modified error tolerance (err_tol / m). If the error tolerance is small and m is large, the modified error tolerance can underflow to 0. To protect against this, we check that the modified error tolerance is at least 1e-300 (near the smallest value that is representable by a floating point number with double precision). If the modified error tolerance is smaller than this threshold, then we silently change it to 1e-300. This case should only be encountered if extreme values of error tolerance are used (i.e., on the scale of 1e-300).

switch_mech - The density function for the DDM has traditionally been written in two forms: a "large-time" variant, and a "small-time" variant (Navarro and Fuss, 2009). These two forms are more efficient at calculating the density for large and small response times, respectively. The parameter switch_mech determines how dfddm decides which of these two variants is used. switch_mech = "small" uses only the "small-time" variant, and switch_mech = "large" uses only the "large-time" variant. The "large-time" variant is unstable for small effective response times ((rt-t0) / (a*a) < 0.009) and may produce inaccurate densities; thus, we do not recommend using the switch_mech = "large" option if the inputs may contain such small effective response times. To circumvent this accuracy issue and resolve the differing efficiencies of the "large-time" and "small-time" variants, there are three switching mechanisms that can be used to determine which of the two variants is more efficient. First, switch_mech = "terms" is the traditional approach and pre-calculates the number of terms required for the "large-time" and "small-time" sums, and then uses whichever variant requires fewer terms. This is the mechanism used in the Navarro and Fuss (2009) and Gondan, Blurton, and Kesselmeier (2014) papers. Second, switch_mech = "terms_large" pre-calculates the number of terms only for the "large-time" variant, and compares that to the constant value of ceil(switch_thresh) (default value of ceil(0.8) = 1) to determine if the "large-time" variant is sufficiently efficient. Third, switch_mech = "eff_rt" determines whether a given effective response time ((rt-t0) /(a*a)) is considered "large" or "small" by comparing it to the value of the parameter switch_thresh (default value of 0.8); it then uses the corresponding variant. Both switch_mech = "terms_large" and switch_mech = "eff_rt" only use the SWSE "small-time" approximation in the case that the "small-time" variant is more efficient. switch_mech = "eff_rt" is the most efficient method to determine which variant of the density function should be used.

switch_thresh - This parameter determines what effective response times (rt/(a *a)) are "large" and "small". The paper_analysis folder in the fddm GitHub repository contains plots showing the relative efficiencies of a range of values for the switch_thresh parameter when used with switch_mech = "eff_rt" and also switch_mech = "terms_large". Note that this parameter changed name and purpose with the release of fddm version 0.5-0.

n_terms_small - The "small-time" variant has three different methods for how to truncate the infinite sum in the density function. These different methods are discussed extensively in our associated paper, but the key distinction is that n_terms_small = "SWSE" uses a new method of truncating the infinite sum. The n_terms_small = "SWSE" method is currently recommended (when possible) because it is the fastest and most stable algorithm when used with switch_mech = "eff_rt".

summation_small - The "large-time" variant of the density function does not have any further variants, but the "small-time" variant has more options with respect to evaluating the infinite sum. There are two equivalent styles of summation, summation_small = "2017" and summation_small = "2014", of which the "2017" version evaluates slightly faster and thus earns our recommendation. These different styles of summation are discussed in our associated paper.

Value

A vector containing the densities of the DDM with precision err_tol whose length matches that of the longest input parameter (usually rt).

References

Navarro, D. J., & Fuss, I. G. (2009). Fast and accurate calculations for first-passage times in Wiener diffusion models. Journal of Mathematical Psychology, 53(4), 222-230.

Blurton, S. P., Kesselmeier, M., & Gondan, M. (2017). The first-passage time distribution for the diffusion model with variable drift. Journal of Mathematical Psychology, 76, 7-12.

Ratcliff, R. (1978). A theory of memory retrieval. Psychological review, 85(2), 59.

Examples

# minimal example
dfddm(rt = 1.2, response = "lower", a = 1, v = -1, t0 = 0.3)

# example with all function parameters set to default or a practical value
dfddm(rt = c(1.2, 0.9, 1.1, 1.4, 0.8, 1.3),
      response = c("lower", "upper", "upper", "lower", "upper", "lower"),
      a = 1, v = -1, t0 = 0.2, w = 0.5, sv = 0, sigma = 1,
      err_tol = 1e-6, log = FALSE, switch_mech = "eff_rt", switch_thresh = 0.8,
      n_terms_small = "SWSE", summation_small = "2017")

# example of mismatched input lengths
dfddm(rt = c(1.2, 0.9, 1.1, 1.4, 0.8, 1.3),
      response = c("lower", "upper", "upper", "lower", "upper", "lower"),
      a = c(1, 3), v = c(-2, 2, 2, -2, 2, -2),
      t0 = 0.3, w = c(0.4, 0.5, 0.6), sv = 0.9,
      err_tol = 1e-10, log = FALSE, switch_mech = "large",
      summation_small = "2017")

# example with Wiener diffusion coefficient (sigma) not equal to 1
dfddm(rt = c(1.2, 0.9, 1.1, 1.4, 0.8, 1.3),
      response = c("lower", "upper", "upper", "lower", "upper", "lower"),
      a = 1, v = -1, t0 = 0.3, w = 0.5, sv = 0, sigma = 0.1,
      err_tol = 1e-10, log = TRUE, switch_mech = "terms_large",
      switch_thresh = 1, summation_small = "2017")


### examples of different response inputs

# integer
resp_int <- as.integer(c(1, 2, 2, 1, 2, 1))
dfddm(rt = c(1.2, 0.9, 1.1, 1.4, 0.8, 1.3), response = resp_int,
      a = 1, v = -2, t0 = 0.3, w = 0.5, sv = 0.1,
      err_tol = 1e-10, log = FALSE, switch_mech = "eff_rt",
      summation_small = "2017")

# double
resp_dbl <- as.double(c(1, 2, 2, 1, 2, 1))
dfddm(rt = c(1.2, 0.9, 1.1, 1.4, 0.8, 1.3), response = resp_dbl,
      a = 1, v = -2, t0 = 0.3, w = 0.5, sv = 0.1,
      err_tol = 1e-10, log = FALSE, switch_mech = "eff_rt",
      summation_small = "2017")

# factor (first level is mapped to "lower")
days <- c("Monday", "Friday", "Friday", "Monday", "Friday", "Monday")
resp_fac <- factor(days, levels = c("Monday", "Friday"))
dfddm(rt = c(1.2, 0.9, 1.1, 1.4, 0.8, 1.3), response = resp_fac,
      a = 1, v = -2, t0 = 0.3, w = 0.5, sv = 0.1,
      err_tol = 1e-10, log = FALSE, switch_mech = "eff_rt",
      summation_small = "2017")

# string
resp_str <- c("lower", "upper", "upper", "lower", "upper", "lower")
dfddm(rt = c(1.2, 0.9, 1.1, 1.4, 0.8, 1.3), response = resp_str,
      a = 1, v = -2, t0 = 0.3, w = 0.5, sv = 0.1,
      err_tol = 1e-10, log = FALSE, switch_mech = "eff_rt",
      summation_small = "2017")

# logical
resp_log <- c(FALSE, TRUE, TRUE, FALSE, TRUE, FALSE)
dfddm(rt = c(1.2, 0.9, 1.1, 1.4, 0.8, 1.3), response = resp_log,
      a = 1, v = -2, t0 = 0.3, w = 0.5, sv = 0.1,
      err_tol = 1e-10, log = FALSE, switch_mech = "eff_rt",
      summation_small = "2017")

Second-Order Partial Derivative of 5-parameter DDM PDF with respect to sv (inter-trial variability in the drift rate)

Description

Second-Order Partial Derivative of the density function for the 5-parameter variant of the Ratcliff diffusion decision model (DDM) with respect to sv, the inter-trial variability in the drift rate. This variant contains the following parameters: v (drift rate), a (threshold separation), t0 (non-decision time/response time constant), w (relative starting point), sv (inter-trial variability of drift), and sigma (diffusion coefficient of underlying Wiener process).

Usage

dsv2_dfddm(
  rt,
  response,
  v,
  a,
  t0,
  w = 0.5,
  sv = 0,
  sigma = 1,
  sl_thresh = 0.355,
  err_tol = 1e-06
)

Arguments

rt

A vector of response times (in seconds). If a response time is non-positve, then its density will evaluate to 0 if log = FALSE and -∞ if log = TRUE.

response

integers or doubles (1 → "lower", 2 → "upper");
factors (the first level gets mapped to "lower", and the second level gets mapped to "upper"; any additional levels are ignored).
strings (only the first character is checked, "L" → "lower" or "U" → "upper", case insensitive);
logicals (FALSE → "lower", TRUE → "upper");

v

a

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

t0

w

sv

sigma

a → a / sigma
v → v / sigma
sv → sv / sigma

sl_thresh

err_tol

Allowed error tolerance of the overall calculation. Since the partial derivative of the density function contains one infinite sum, this parameter defines the precision of the approximation to that infinite sum. If the provided error tolerance is less than 1e-300, it is set to 1e-300. Default is 1e-6.

Details

Value

A vector containing the second-order partial derivatives of the DDM PDF with precision err_tol whose length matches that of the longest input parameter (usually rt).

References

Navarro, D. J., & Fuss, I. G. (2009). Fast and accurate calculations for first-passage times in Wiener diffusion models. Journal of Mathematical Psychology, 53(4), 222-230.

Blurton, S. P., Kesselmeier, M., & Gondan, M. (2017). The first-passage time distribution for the diffusion model with variable drift. Journal of Mathematical Psychology, 76, 7-12.

Hartmann, R., Klauer, K. C. (2021). Partial derivatives for the first-passage time distribution in Wiener diffusion models. Journal of Mathematical Psychology, 103, 102550.

Ratcliff, R. (1978). A theory of memory retrieval. Psychological review, 85(2), 59.

Examples

# derivative with respect to rt (response time)
dt_dfddm(rt = 1.2, response = "lower", a = 1, v = -1, t0 = 0.3, w = 0.5,
         sv = 0.4, err_tol = 1e-6)

# derivative with respect to t0 (non-decision time)
dt0_dfddm(rt = 1.2, response = "lower", a = 1, v = -1, t0 = 0.3, w = 0.5,
          sv = 0.4, err_tol = 1e-6)

# derivative with respect to a (threshold separation)
da_dfddm(rt = 1.2, response = "lower", a = 1, v = -1, t0 = 0.3, w = 0.5,
         sv = 0.4, err_tol = 1e-6)

# derivative with respect to v (drift rate)
dv_dfddm(rt = 1.2, response = "lower", a = 1, v = -1, t0 = 0.3, w = 0.5,
         sv = 0.4, err_tol = 1e-6)

# derivative with respect to w (relative starting point)
dw_dfddm(rt = 1.2, response = "lower", a = 1, v = -1, t0 = 0.3, w = 0.5,
         sv = 0.4, err_tol = 1e-6)

# derivative with respect to sv (inter-trial variability in the drift rate)
dsv_dfddm(rt = 1.2, response = "lower", a = 1, v = -1, t0 = 0.3, w = 0.5,
          sv = 0.4, err_tol = 1e-6)

#-------- Log Versions --------#

# # derivative with respect to rt (response time)
# dt_log_dfddm(rt = 1.2, response = "lower", a = 1, v = -1, t0 = 0.3, w = 0.5,
#              sv = 0.4, err_tol = 1e-6)

# # derivative with respect to t0 (non-decision time)
# dt0_log_dfddm(rt = 1.2, response = "lower", a = 1, v = -1, t0 = 0.3, w = 0.5,
#               sv = 0.4, err_tol = 1e-6)

# # derivative with respect to a (threshold separation)
# da_log_dfddm(rt = 1.2, response = "lower", a = 1, v = -1, t0 = 0.3, w = 0.5,
#              sv = 0.4, err_tol = 1e-6)

# # derivative with respect to v (drift rate)
# dv_log_dfddm(rt = 1.2, response = "lower", a = 1, v = -1, t0 = 0.3, w = 0.5,
#              sv = 0.4, err_tol = 1e-6)

# # derivative with respect to w (relative starting point)
# dw_log_dfddm(rt = 1.2, response = "lower", a = 1, v = -1, t0 = 0.3, w = 0.5,
#              sv = 0.4, err_tol = 1e-6)

# # derivative with respect to sv (inter-trial variability in the drift rate)
# dsv_log_dfddm(rt = 1.2, response = "lower", a = 1, v = -1, t0 = 0.3, w = 0.5,
#               sv = 0.4, err_tol = 1e-6)

Partial Derivative of 5-parameter DDM PDF with respect to sv (inter-trial variability in the drift rate)

Description

Partial Derivative of the density function for the 5-parameter variant of the Ratcliff diffusion decision model (DDM) with respect to w, the inter-trial variability in the drift rate. This variant contains the following parameters: v (drift rate), a (threshold separation), t0 (non-decision time/response time constant), w (relative starting point), sv (inter-trial variability of drift), and sigma (diffusion coefficient of underlying Wiener process).

Usage

dsv_dfddm(
  rt,
  response,
  v,
  a,
  t0,
  w = 0.5,
  sv = 0,
  sigma = 1,
  sl_thresh = 0.355,
  err_tol = 1e-06
)

Arguments

rt

A vector of response times (in seconds). If a response time is non-positve, then its density will evaluate to 0 if log = FALSE and -∞ if log = TRUE.

response

integers or doubles (1 → "lower", 2 → "upper");
factors (the first level gets mapped to "lower", and the second level gets mapped to "upper"; any additional levels are ignored).
strings (only the first character is checked, "L" → "lower" or "U" → "upper", case insensitive);
logicals (FALSE → "lower", TRUE → "upper");

v

a

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

t0

w

sv

sigma

a → a / sigma
v → v / sigma
sv → sv / sigma

sl_thresh

err_tol

Details

Value

A vector containing the partial derivatives of the DDM PDF with precision err_tol whose length matches that of the longest input parameter (usually rt).

References

Navarro, D. J., & Fuss, I. G. (2009). Fast and accurate calculations for first-passage times in Wiener diffusion models. Journal of Mathematical Psychology, 53(4), 222-230.

Blurton, S. P., Kesselmeier, M., & Gondan, M. (2017). The first-passage time distribution for the diffusion model with variable drift. Journal of Mathematical Psychology, 76, 7-12.

Hartmann, R., Klauer, K. C. (2021). Partial derivatives for the first-passage time distribution in Wiener diffusion models. Journal of Mathematical Psychology, 103, 102550.

Ratcliff, R. (1978). A theory of memory retrieval. Psychological review, 85(2), 59.

Examples

# derivative with respect to rt (response time)
dt_dfddm(rt = 1.2, response = "lower", a = 1, v = -1, t0 = 0.3, w = 0.5,
         sv = 0.4, err_tol = 1e-6)

# derivative with respect to t0 (non-decision time)
dt0_dfddm(rt = 1.2, response = "lower", a = 1, v = -1, t0 = 0.3, w = 0.5,
          sv = 0.4, err_tol = 1e-6)

# derivative with respect to a (threshold separation)
da_dfddm(rt = 1.2, response = "lower", a = 1, v = -1, t0 = 0.3, w = 0.5,
         sv = 0.4, err_tol = 1e-6)

# derivative with respect to v (drift rate)
dv_dfddm(rt = 1.2, response = "lower", a = 1, v = -1, t0 = 0.3, w = 0.5,
         sv = 0.4, err_tol = 1e-6)

# derivative with respect to w (relative starting point)
dw_dfddm(rt = 1.2, response = "lower", a = 1, v = -1, t0 = 0.3, w = 0.5,
         sv = 0.4, err_tol = 1e-6)

# derivative with respect to sv (inter-trial variability in the drift rate)
dsv_dfddm(rt = 1.2, response = "lower", a = 1, v = -1, t0 = 0.3, w = 0.5,
          sv = 0.4, err_tol = 1e-6)

#-------- Log Versions --------#

# # derivative with respect to rt (response time)
# dt_log_dfddm(rt = 1.2, response = "lower", a = 1, v = -1, t0 = 0.3, w = 0.5,
#              sv = 0.4, err_tol = 1e-6)

# # derivative with respect to t0 (non-decision time)
# dt0_log_dfddm(rt = 1.2, response = "lower", a = 1, v = -1, t0 = 0.3, w = 0.5,
#               sv = 0.4, err_tol = 1e-6)

# # derivative with respect to a (threshold separation)
# da_log_dfddm(rt = 1.2, response = "lower", a = 1, v = -1, t0 = 0.3, w = 0.5,
#              sv = 0.4, err_tol = 1e-6)

# # derivative with respect to v (drift rate)
# dv_log_dfddm(rt = 1.2, response = "lower", a = 1, v = -1, t0 = 0.3, w = 0.5,
#              sv = 0.4, err_tol = 1e-6)

# # derivative with respect to w (relative starting point)
# dw_log_dfddm(rt = 1.2, response = "lower", a = 1, v = -1, t0 = 0.3, w = 0.5,
#              sv = 0.4, err_tol = 1e-6)

# # derivative with respect to sv (inter-trial variability in the drift rate)
# dsv_log_dfddm(rt = 1.2, response = "lower", a = 1, v = -1, t0 = 0.3, w = 0.5,
#               sv = 0.4, err_tol = 1e-6)

Second-Order Partial Derivative of 5-parameter DDM PDF with respect to t0 (non-decision time)

Description

Second-Order Partial Derivative of the density function for the 5-parameter variant of the Ratcliff diffusion decision model (DDM) with respect to t0, the non-decision time. This variant contains the following parameters: v (drift rate), a (threshold separation), t0 (non-decision time/response time constant), w (relative starting point), sv (inter-trial variability of drift), and sigma (diffusion coefficient of underlying Wiener process).

Usage

dt02_dfddm(
  rt,
  response,
  v,
  a,
  t0,
  w = 0.5,
  sv = 0,
  sigma = 1,
  sl_thresh = 0.44,
  err_tol = 1e-06
)

Arguments

rt

A vector of response times (in seconds). If a response time is non-positve, then its density will evaluate to 0 if log = FALSE and -∞ if log = TRUE.

response

integers or doubles (1 → "lower", 2 → "upper");
factors (the first level gets mapped to "lower", and the second level gets mapped to "upper"; any additional levels are ignored).
strings (only the first character is checked, "L" → "lower" or "U" → "upper", case insensitive);
logicals (FALSE → "lower", TRUE → "upper");

v

a

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

t0

w

sv

sigma

a → a / sigma
v → v / sigma
sv → sv / sigma

sl_thresh

err_tol

Details

Value

A vector containing the second-order partial derivatives of the DDM PDF with precision err_tol whose length matches that of the longest input parameter (usually rt).

References

Navarro, D. J., & Fuss, I. G. (2009). Fast and accurate calculations for first-passage times in Wiener diffusion models. Journal of Mathematical Psychology, 53(4), 222-230.

Blurton, S. P., Kesselmeier, M., & Gondan, M. (2017). The first-passage time distribution for the diffusion model with variable drift. Journal of Mathematical Psychology, 76, 7-12.

Hartmann, R., Klauer, K. C. (2021). Partial derivatives for the first-passage time distribution in Wiener diffusion models. Journal of Mathematical Psychology, 103, 102550.

Ratcliff, R. (1978). A theory of memory retrieval. Psychological review, 85(2), 59.

Examples

# derivative with respect to rt (response time)
dt_dfddm(rt = 1.2, response = "lower", a = 1, v = -1, t0 = 0.3, w = 0.5,
         sv = 0.4, err_tol = 1e-6)

# derivative with respect to t0 (non-decision time)
dt0_dfddm(rt = 1.2, response = "lower", a = 1, v = -1, t0 = 0.3, w = 0.5,
          sv = 0.4, err_tol = 1e-6)

# derivative with respect to a (threshold separation)
da_dfddm(rt = 1.2, response = "lower", a = 1, v = -1, t0 = 0.3, w = 0.5,
         sv = 0.4, err_tol = 1e-6)

# derivative with respect to v (drift rate)
dv_dfddm(rt = 1.2, response = "lower", a = 1, v = -1, t0 = 0.3, w = 0.5,
         sv = 0.4, err_tol = 1e-6)

# derivative with respect to w (relative starting point)
dw_dfddm(rt = 1.2, response = "lower", a = 1, v = -1, t0 = 0.3, w = 0.5,
         sv = 0.4, err_tol = 1e-6)

# derivative with respect to sv (inter-trial variability in the drift rate)
dsv_dfddm(rt = 1.2, response = "lower", a = 1, v = -1, t0 = 0.3, w = 0.5,
          sv = 0.4, err_tol = 1e-6)

#-------- Log Versions --------#

# # derivative with respect to rt (response time)
# dt_log_dfddm(rt = 1.2, response = "lower", a = 1, v = -1, t0 = 0.3, w = 0.5,
#              sv = 0.4, err_tol = 1e-6)

# # derivative with respect to t0 (non-decision time)
# dt0_log_dfddm(rt = 1.2, response = "lower", a = 1, v = -1, t0 = 0.3, w = 0.5,
#               sv = 0.4, err_tol = 1e-6)

# # derivative with respect to a (threshold separation)
# da_log_dfddm(rt = 1.2, response = "lower", a = 1, v = -1, t0 = 0.3, w = 0.5,
#              sv = 0.4, err_tol = 1e-6)

# # derivative with respect to v (drift rate)
# dv_log_dfddm(rt = 1.2, response = "lower", a = 1, v = -1, t0 = 0.3, w = 0.5,
#              sv = 0.4, err_tol = 1e-6)

# # derivative with respect to w (relative starting point)
# dw_log_dfddm(rt = 1.2, response = "lower", a = 1, v = -1, t0 = 0.3, w = 0.5,
#              sv = 0.4, err_tol = 1e-6)

# # derivative with respect to sv (inter-trial variability in the drift rate)
# dsv_log_dfddm(rt = 1.2, response = "lower", a = 1, v = -1, t0 = 0.3, w = 0.5,
#               sv = 0.4, err_tol = 1e-6)

Partial Derivative of 5-parameter DDM PDF with respect to t0 (non-decision time)

Description

Partial Derivative of the density function for the 5-parameter variant of the Ratcliff diffusion decision model (DDM) with respect to t0, the non-decision time. This variant contains the following parameters: v (drift rate), a (threshold separation), t0 (non-decision time/response time constant), w (relative starting point), sv (inter-trial variability of drift), and sigma (diffusion coefficient of underlying Wiener process).

Usage

dt0_dfddm(
  rt,
  response,
  v,
  a,
  t0,
  w = 0.5,
  sv = 0,
  sigma = 1,
  sl_thresh = 0.5,
  err_tol = 1e-06
)

Arguments

rt

A vector of response times (in seconds). If a response time is non-positve, then its density will evaluate to 0 if log = FALSE and -∞ if log = TRUE.

response

integers or doubles (1 → "lower", 2 → "upper");
factors (the first level gets mapped to "lower", and the second level gets mapped to "upper"; any additional levels are ignored).
strings (only the first character is checked, "L" → "lower" or "U" → "upper", case insensitive);
logicals (FALSE → "lower", TRUE → "upper");

v

a

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

t0

w

sv

sigma

a → a / sigma
v → v / sigma
sv → sv / sigma

sl_thresh

err_tol

Details

Value

A vector containing the partial derivatives of the DDM PDF with precision err_tol whose length matches that of the longest input parameter (usually rt).

References

Navarro, D. J., & Fuss, I. G. (2009). Fast and accurate calculations for first-passage times in Wiener diffusion models. Journal of Mathematical Psychology, 53(4), 222-230.

Blurton, S. P., Kesselmeier, M., & Gondan, M. (2017). The first-passage time distribution for the diffusion model with variable drift. Journal of Mathematical Psychology, 76, 7-12.

Hartmann, R., Klauer, K. C. (2021). Partial derivatives for the first-passage time distribution in Wiener diffusion models. Journal of Mathematical Psychology, 103, 102550.

Ratcliff, R. (1978). A theory of memory retrieval. Psychological review, 85(2), 59.

Examples

# derivative with respect to rt (response time)
dt_dfddm(rt = 1.2, response = "lower", a = 1, v = -1, t0 = 0.3, w = 0.5,
         sv = 0.4, err_tol = 1e-6)

# derivative with respect to t0 (non-decision time)
dt0_dfddm(rt = 1.2, response = "lower", a = 1, v = -1, t0 = 0.3, w = 0.5,
          sv = 0.4, err_tol = 1e-6)

# derivative with respect to a (threshold separation)
da_dfddm(rt = 1.2, response = "lower", a = 1, v = -1, t0 = 0.3, w = 0.5,
         sv = 0.4, err_tol = 1e-6)

# derivative with respect to v (drift rate)
dv_dfddm(rt = 1.2, response = "lower", a = 1, v = -1, t0 = 0.3, w = 0.5,
         sv = 0.4, err_tol = 1e-6)

# derivative with respect to w (relative starting point)
dw_dfddm(rt = 1.2, response = "lower", a = 1, v = -1, t0 = 0.3, w = 0.5,
         sv = 0.4, err_tol = 1e-6)

# derivative with respect to sv (inter-trial variability in the drift rate)
dsv_dfddm(rt = 1.2, response = "lower", a = 1, v = -1, t0 = 0.3, w = 0.5,
          sv = 0.4, err_tol = 1e-6)

#-------- Log Versions --------#

# # derivative with respect to rt (response time)
# dt_log_dfddm(rt = 1.2, response = "lower", a = 1, v = -1, t0 = 0.3, w = 0.5,
#              sv = 0.4, err_tol = 1e-6)

# # derivative with respect to t0 (non-decision time)
# dt0_log_dfddm(rt = 1.2, response = "lower", a = 1, v = -1, t0 = 0.3, w = 0.5,
#               sv = 0.4, err_tol = 1e-6)

# # derivative with respect to a (threshold separation)
# da_log_dfddm(rt = 1.2, response = "lower", a = 1, v = -1, t0 = 0.3, w = 0.5,
#              sv = 0.4, err_tol = 1e-6)

# # derivative with respect to v (drift rate)
# dv_log_dfddm(rt = 1.2, response = "lower", a = 1, v = -1, t0 = 0.3, w = 0.5,
#              sv = 0.4, err_tol = 1e-6)

# # derivative with respect to w (relative starting point)
# dw_log_dfddm(rt = 1.2, response = "lower", a = 1, v = -1, t0 = 0.3, w = 0.5,
#              sv = 0.4, err_tol = 1e-6)

# # derivative with respect to sv (inter-trial variability in the drift rate)
# dsv_log_dfddm(rt = 1.2, response = "lower", a = 1, v = -1, t0 = 0.3, w = 0.5,
#               sv = 0.4, err_tol = 1e-6)

Second-Order Partial Derivative of 5-parameter DDM PDF with respect to t (response time)

Description

Second-Order Partial Derivative of the density function for the 5-parameter variant of the Ratcliff diffusion decision model (DDM) with respect to t, the response time. This variant contains the following parameters: v (drift rate), a (threshold separation), t0 (non-decision time/response time constant), w (relative starting point), sv (inter-trial variability of drift), and sigma (diffusion coefficient of underlying Wiener process).

Usage

dt2_dfddm(
  rt,
  response,
  v,
  a,
  t0,
  w = 0.5,
  sv = 0,
  sigma = 1,
  sl_thresh = 0.5,
  err_tol = 1e-06
)

Arguments

rt

A vector of response times (in seconds). If a response time is non-positve, then its density will evaluate to 0 if log = FALSE and -∞ if log = TRUE.

response

integers or doubles (1 → "lower", 2 → "upper");
factors (the first level gets mapped to "lower", and the second level gets mapped to "upper"; any additional levels are ignored).
strings (only the first character is checked, "L" → "lower" or "U" → "upper", case insensitive);
logicals (FALSE → "lower", TRUE → "upper");

v

a

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

t0

w

sv

sigma

a → a / sigma
v → v / sigma
sv → sv / sigma

sl_thresh

err_tol

Details

Value

A vector containing the second-order partial derivatives of the DDM PDF with precision err_tol whose length matches that of the longest input parameter (usually rt).

References

Navarro, D. J., & Fuss, I. G. (2009). Fast and accurate calculations for first-passage times in Wiener diffusion models. Journal of Mathematical Psychology, 53(4), 222-230.

Blurton, S. P., Kesselmeier, M., & Gondan, M. (2017). The first-passage time distribution for the diffusion model with variable drift. Journal of Mathematical Psychology, 76, 7-12.

Hartmann, R., Klauer, K. C. (2021). Partial derivatives for the first-passage time distribution in Wiener diffusion models. Journal of Mathematical Psychology, 103, 102550.

Ratcliff, R. (1978). A theory of memory retrieval. Psychological review, 85(2), 59.

Examples

# derivative with respect to rt (response time)
dt_dfddm(rt = 1.2, response = "lower", a = 1, v = -1, t0 = 0.3, w = 0.5,
         sv = 0.4, err_tol = 1e-6)

# derivative with respect to t0 (non-decision time)
dt0_dfddm(rt = 1.2, response = "lower", a = 1, v = -1, t0 = 0.3, w = 0.5,
          sv = 0.4, err_tol = 1e-6)

# derivative with respect to a (threshold separation)
da_dfddm(rt = 1.2, response = "lower", a = 1, v = -1, t0 = 0.3, w = 0.5,
         sv = 0.4, err_tol = 1e-6)

# derivative with respect to v (drift rate)
dv_dfddm(rt = 1.2, response = "lower", a = 1, v = -1, t0 = 0.3, w = 0.5,
         sv = 0.4, err_tol = 1e-6)

# derivative with respect to w (relative starting point)
dw_dfddm(rt = 1.2, response = "lower", a = 1, v = -1, t0 = 0.3, w = 0.5,
         sv = 0.4, err_tol = 1e-6)

# derivative with respect to sv (inter-trial variability in the drift rate)
dsv_dfddm(rt = 1.2, response = "lower", a = 1, v = -1, t0 = 0.3, w = 0.5,
          sv = 0.4, err_tol = 1e-6)

#-------- Log Versions --------#

# # derivative with respect to rt (response time)
# dt_log_dfddm(rt = 1.2, response = "lower", a = 1, v = -1, t0 = 0.3, w = 0.5,
#              sv = 0.4, err_tol = 1e-6)

# # derivative with respect to t0 (non-decision time)
# dt0_log_dfddm(rt = 1.2, response = "lower", a = 1, v = -1, t0 = 0.3, w = 0.5,
#               sv = 0.4, err_tol = 1e-6)

# # derivative with respect to a (threshold separation)
# da_log_dfddm(rt = 1.2, response = "lower", a = 1, v = -1, t0 = 0.3, w = 0.5,
#              sv = 0.4, err_tol = 1e-6)

# # derivative with respect to v (drift rate)
# dv_log_dfddm(rt = 1.2, response = "lower", a = 1, v = -1, t0 = 0.3, w = 0.5,
#              sv = 0.4, err_tol = 1e-6)

# # derivative with respect to w (relative starting point)
# dw_log_dfddm(rt = 1.2, response = "lower", a = 1, v = -1, t0 = 0.3, w = 0.5,
#              sv = 0.4, err_tol = 1e-6)

# # derivative with respect to sv (inter-trial variability in the drift rate)
# dsv_log_dfddm(rt = 1.2, response = "lower", a = 1, v = -1, t0 = 0.3, w = 0.5,
#               sv = 0.4, err_tol = 1e-6)

Partial Derivative of 5-parameter DDM PDF with respect to t (response time)

Description

Partial Derivative of the density function for the 5-parameter variant of the Ratcliff diffusion decision model (DDM) with respect to t, the response time. This variant contains the following parameters: v (drift rate), a (threshold separation), t0 (non-decision time/response time constant), w (relative starting point), sv (inter-trial variability of drift), and sigma (diffusion coefficient of underlying Wiener process).

Usage

dt_dfddm(
  rt,
  response,
  v,
  a,
  t0,
  w = 0.5,
  sv = 0,
  sigma = 1,
  sl_thresh = 0.5,
  err_tol = 1e-06
)

Arguments

rt

A vector of response times (in seconds). If a response time is non-positve, then its density will evaluate to 0 if log = FALSE and -∞ if log = TRUE.

response

integers or doubles (1 → "lower", 2 → "upper");
factors (the first level gets mapped to "lower", and the second level gets mapped to "upper"; any additional levels are ignored).
strings (only the first character is checked, "L" → "lower" or "U" → "upper", case insensitive);
logicals (FALSE → "lower", TRUE → "upper");

v

a

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

t0

w

sv

sigma

a → a / sigma
v → v / sigma
sv → sv / sigma

sl_thresh

err_tol

Details

Value

A vector containing the partial derivatives of the DDM PDF with precision err_tol whose length matches that of the longest input parameter (usually rt).

References

Navarro, D. J., & Fuss, I. G. (2009). Fast and accurate calculations for first-passage times in Wiener diffusion models. Journal of Mathematical Psychology, 53(4), 222-230.

Blurton, S. P., Kesselmeier, M., & Gondan, M. (2017). The first-passage time distribution for the diffusion model with variable drift. Journal of Mathematical Psychology, 76, 7-12.

Hartmann, R., Klauer, K. C. (2021). Partial derivatives for the first-passage time distribution in Wiener diffusion models. Journal of Mathematical Psychology, 103, 102550.

Ratcliff, R. (1978). A theory of memory retrieval. Psychological review, 85(2), 59.

Examples

# derivative with respect to rt (response time)
dt_dfddm(rt = 1.2, response = "lower", a = 1, v = -1, t0 = 0.3, w = 0.5,
         sv = 0.4, err_tol = 1e-6)

# derivative with respect to t0 (non-decision time)
dt0_dfddm(rt = 1.2, response = "lower", a = 1, v = -1, t0 = 0.3, w = 0.5,
          sv = 0.4, err_tol = 1e-6)

# derivative with respect to a (threshold separation)
da_dfddm(rt = 1.2, response = "lower", a = 1, v = -1, t0 = 0.3, w = 0.5,
         sv = 0.4, err_tol = 1e-6)

# derivative with respect to v (drift rate)
dv_dfddm(rt = 1.2, response = "lower", a = 1, v = -1, t0 = 0.3, w = 0.5,
         sv = 0.4, err_tol = 1e-6)

# derivative with respect to w (relative starting point)
dw_dfddm(rt = 1.2, response = "lower", a = 1, v = -1, t0 = 0.3, w = 0.5,
         sv = 0.4, err_tol = 1e-6)

# derivative with respect to sv (inter-trial variability in the drift rate)
dsv_dfddm(rt = 1.2, response = "lower", a = 1, v = -1, t0 = 0.3, w = 0.5,
          sv = 0.4, err_tol = 1e-6)

#-------- Log Versions --------#

# # derivative with respect to rt (response time)
# dt_log_dfddm(rt = 1.2, response = "lower", a = 1, v = -1, t0 = 0.3, w = 0.5,
#              sv = 0.4, err_tol = 1e-6)

# # derivative with respect to t0 (non-decision time)
# dt0_log_dfddm(rt = 1.2, response = "lower", a = 1, v = -1, t0 = 0.3, w = 0.5,
#               sv = 0.4, err_tol = 1e-6)

# # derivative with respect to a (threshold separation)
# da_log_dfddm(rt = 1.2, response = "lower", a = 1, v = -1, t0 = 0.3, w = 0.5,
#              sv = 0.4, err_tol = 1e-6)

# # derivative with respect to v (drift rate)
# dv_log_dfddm(rt = 1.2, response = "lower", a = 1, v = -1, t0 = 0.3, w = 0.5,
#              sv = 0.4, err_tol = 1e-6)

# # derivative with respect to w (relative starting point)
# dw_log_dfddm(rt = 1.2, response = "lower", a = 1, v = -1, t0 = 0.3, w = 0.5,
#              sv = 0.4, err_tol = 1e-6)

# # derivative with respect to sv (inter-trial variability in the drift rate)
# dsv_log_dfddm(rt = 1.2, response = "lower", a = 1, v = -1, t0 = 0.3, w = 0.5,
#               sv = 0.4, err_tol = 1e-6)

Second-Order Partial Derivative of 5-parameter DDM PDF with respect to v (drift rate)

Description

Second-Order Partial Derivative of the density function for the 5-parameter variant of the Ratcliff diffusion decision model (DDM) with respect to v, the drift rate. This variant contains the following parameters: v (drift rate), a (threshold separation), t0 (non-decision time/response time constant), w (relative starting point), sv (inter-trial variability of drift), and sigma (diffusion coefficient of underlying Wiener process).

Usage

dv2_dfddm(
  rt,
  response,
  v,
  a,
  t0,
  w = 0.5,
  sv = 0,
  sigma = 1,
  sl_thresh = 0.355,
  err_tol = 1e-06
)

Arguments

rt

A vector of response times (in seconds). If a response time is non-positve, then its density will evaluate to 0 if log = FALSE and -∞ if log = TRUE.

response

integers or doubles (1 → "lower", 2 → "upper");
factors (the first level gets mapped to "lower", and the second level gets mapped to "upper"; any additional levels are ignored).
strings (only the first character is checked, "L" → "lower" or "U" → "upper", case insensitive);
logicals (FALSE → "lower", TRUE → "upper");

v

a

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

t0

w

sv

sigma

a → a / sigma
v → v / sigma
sv → sv / sigma

sl_thresh

err_tol

Details

Value

A vector containing the second-order partial derivatives of the DDM PDF with precision err_tol whose length matches that of the longest input parameter (usually rt).

References

Navarro, D. J., & Fuss, I. G. (2009). Fast and accurate calculations for first-passage times in Wiener diffusion models. Journal of Mathematical Psychology, 53(4), 222-230.

Blurton, S. P., Kesselmeier, M., & Gondan, M. (2017). The first-passage time distribution for the diffusion model with variable drift. Journal of Mathematical Psychology, 76, 7-12.

Hartmann, R., Klauer, K. C. (2021). Partial derivatives for the first-passage time distribution in Wiener diffusion models. Journal of Mathematical Psychology, 103, 102550.

Ratcliff, R. (1978). A theory of memory retrieval. Psychological review, 85(2), 59.

Examples

# derivative with respect to rt (response time)
dt_dfddm(rt = 1.2, response = "lower", a = 1, v = -1, t0 = 0.3, w = 0.5,
         sv = 0.4, err_tol = 1e-6)

# derivative with respect to t0 (non-decision time)
dt0_dfddm(rt = 1.2, response = "lower", a = 1, v = -1, t0 = 0.3, w = 0.5,
          sv = 0.4, err_tol = 1e-6)

# derivative with respect to a (threshold separation)
da_dfddm(rt = 1.2, response = "lower", a = 1, v = -1, t0 = 0.3, w = 0.5,
         sv = 0.4, err_tol = 1e-6)

# derivative with respect to v (drift rate)
dv_dfddm(rt = 1.2, response = "lower", a = 1, v = -1, t0 = 0.3, w = 0.5,
         sv = 0.4, err_tol = 1e-6)

# derivative with respect to w (relative starting point)
dw_dfddm(rt = 1.2, response = "lower", a = 1, v = -1, t0 = 0.3, w = 0.5,
         sv = 0.4, err_tol = 1e-6)

# derivative with respect to sv (inter-trial variability in the drift rate)
dsv_dfddm(rt = 1.2, response = "lower", a = 1, v = -1, t0 = 0.3, w = 0.5,
          sv = 0.4, err_tol = 1e-6)

#-------- Log Versions --------#

# # derivative with respect to rt (response time)
# dt_log_dfddm(rt = 1.2, response = "lower", a = 1, v = -1, t0 = 0.3, w = 0.5,
#              sv = 0.4, err_tol = 1e-6)

# # derivative with respect to t0 (non-decision time)
# dt0_log_dfddm(rt = 1.2, response = "lower", a = 1, v = -1, t0 = 0.3, w = 0.5,
#               sv = 0.4, err_tol = 1e-6)

# # derivative with respect to a (threshold separation)
# da_log_dfddm(rt = 1.2, response = "lower", a = 1, v = -1, t0 = 0.3, w = 0.5,
#              sv = 0.4, err_tol = 1e-6)

# # derivative with respect to v (drift rate)
# dv_log_dfddm(rt = 1.2, response = "lower", a = 1, v = -1, t0 = 0.3, w = 0.5,
#              sv = 0.4, err_tol = 1e-6)

# # derivative with respect to w (relative starting point)
# dw_log_dfddm(rt = 1.2, response = "lower", a = 1, v = -1, t0 = 0.3, w = 0.5,
#              sv = 0.4, err_tol = 1e-6)

# # derivative with respect to sv (inter-trial variability in the drift rate)
# dsv_log_dfddm(rt = 1.2, response = "lower", a = 1, v = -1, t0 = 0.3, w = 0.5,
#               sv = 0.4, err_tol = 1e-6)

Partial Derivative of 5-parameter DDM PDF with respect to v (drift rate)

Description

Partial Derivative of the density function for the 5-parameter variant of the Ratcliff diffusion decision model (DDM) with respect to v, the drift rate. This variant contains the following parameters: v (drift rate), a (threshold separation), t0 (non-decision time/response time constant), w (relative starting point), sv (inter-trial variability of drift), and sigma (diffusion coefficient of underlying Wiener process).

Usage

dv_dfddm(
  rt,
  response,
  v,
  a,
  t0,
  w = 0.5,
  sv = 0,
  sigma = 1,
  sl_thresh = 0.355,
  err_tol = 1e-06
)

Arguments

rt

A vector of response times (in seconds). If a response time is non-positve, then its density will evaluate to 0 if log = FALSE and -∞ if log = TRUE.

response

integers or doubles (1 → "lower", 2 → "upper");
factors (the first level gets mapped to "lower", and the second level gets mapped to "upper"; any additional levels are ignored).
strings (only the first character is checked, "L" → "lower" or "U" → "upper", case insensitive);
logicals (FALSE → "lower", TRUE → "upper");

v

a

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

t0

w

sv

sigma

a → a / sigma
v → v / sigma
sv → sv / sigma

sl_thresh

err_tol

Details

Value

A vector containing the partial derivatives of the DDM PDF with precision err_tol whose length matches that of the longest input parameter (usually rt).

References

Navarro, D. J., & Fuss, I. G. (2009). Fast and accurate calculations for first-passage times in Wiener diffusion models. Journal of Mathematical Psychology, 53(4), 222-230.

Blurton, S. P., Kesselmeier, M., & Gondan, M. (2017). The first-passage time distribution for the diffusion model with variable drift. Journal of Mathematical Psychology, 76, 7-12.

Hartmann, R., Klauer, K. C. (2021). Partial derivatives for the first-passage time distribution in Wiener diffusion models. Journal of Mathematical Psychology, 103, 102550.

Ratcliff, R. (1978). A theory of memory retrieval. Psychological review, 85(2), 59.

Examples

# derivative with respect to rt (response time)
dt_dfddm(rt = 1.2, response = "lower", a = 1, v = -1, t0 = 0.3, w = 0.5,
         sv = 0.4, err_tol = 1e-6)

# derivative with respect to t0 (non-decision time)
dt0_dfddm(rt = 1.2, response = "lower", a = 1, v = -1, t0 = 0.3, w = 0.5,
          sv = 0.4, err_tol = 1e-6)

# derivative with respect to a (threshold separation)
da_dfddm(rt = 1.2, response = "lower", a = 1, v = -1, t0 = 0.3, w = 0.5,
         sv = 0.4, err_tol = 1e-6)

# derivative with respect to v (drift rate)
dv_dfddm(rt = 1.2, response = "lower", a = 1, v = -1, t0 = 0.3, w = 0.5,
         sv = 0.4, err_tol = 1e-6)

# derivative with respect to w (relative starting point)
dw_dfddm(rt = 1.2, response = "lower", a = 1, v = -1, t0 = 0.3, w = 0.5,
         sv = 0.4, err_tol = 1e-6)

# derivative with respect to sv (inter-trial variability in the drift rate)
dsv_dfddm(rt = 1.2, response = "lower", a = 1, v = -1, t0 = 0.3, w = 0.5,
          sv = 0.4, err_tol = 1e-6)

#-------- Log Versions --------#

# # derivative with respect to rt (response time)
# dt_log_dfddm(rt = 1.2, response = "lower", a = 1, v = -1, t0 = 0.3, w = 0.5,
#              sv = 0.4, err_tol = 1e-6)

# # derivative with respect to t0 (non-decision time)
# dt0_log_dfddm(rt = 1.2, response = "lower", a = 1, v = -1, t0 = 0.3, w = 0.5,
#               sv = 0.4, err_tol = 1e-6)

# # derivative with respect to a (threshold separation)
# da_log_dfddm(rt = 1.2, response = "lower", a = 1, v = -1, t0 = 0.3, w = 0.5,
#              sv = 0.4, err_tol = 1e-6)

# # derivative with respect to v (drift rate)
# dv_log_dfddm(rt = 1.2, response = "lower", a = 1, v = -1, t0 = 0.3, w = 0.5,
#              sv = 0.4, err_tol = 1e-6)

# # derivative with respect to w (relative starting point)
# dw_log_dfddm(rt = 1.2, response = "lower", a = 1, v = -1, t0 = 0.3, w = 0.5,
#              sv = 0.4, err_tol = 1e-6)

# # derivative with respect to sv (inter-trial variability in the drift rate)
# dsv_log_dfddm(rt = 1.2, response = "lower", a = 1, v = -1, t0 = 0.3, w = 0.5,
#               sv = 0.4, err_tol = 1e-6)

Second-Order Partial Derivative of 5-parameter DDM PDF with respect to w (initial bias)

Description

Second-Order Partial Derivative of the density function for the 5-parameter variant of the Ratcliff diffusion decision model (DDM) with respect to w, the initial bias. This variant contains the following parameters: v (drift rate), a (threshold separation), t0 (non-decision time/response time constant), w (relative starting point), sv (inter-trial variability of drift), and sigma (diffusion coefficient of underlying Wiener process).

Usage

dw2_dfddm(
  rt,
  response,
  v,
  a,
  t0,
  w = 0.5,
  sv = 0,
  sigma = 1,
  sl_thresh = 0.5,
  err_tol = 1e-06
)

Arguments

rt

A vector of response times (in seconds). If a response time is non-positve, then its density will evaluate to 0 if log = FALSE and -∞ if log = TRUE.

response

integers or doubles (1 → "lower", 2 → "upper");
factors (the first level gets mapped to "lower", and the second level gets mapped to "upper"; any additional levels are ignored).
strings (only the first character is checked, "L" → "lower" or "U" → "upper", case insensitive);
logicals (FALSE → "lower", TRUE → "upper");

v

a

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

t0

w

sv

sigma

a → a / sigma
v → v / sigma
sv → sv / sigma

sl_thresh

Threshold for deciding when to use the "small-time" variant or the "large-time" variant in one half of the calculation of the partial derivative of the density function. This acts in exactly the same way as the parameter max_terms_large in the dfddm() function: it is the maximum number of terms to use for the "large-time" variant before switching to using the "small-time" variant. The other half of the calculation leverages a different type of comparison between the "large-time" and "small-time" variants that requires no input from the user. Allowed values are any real number; however any non-positive number means that the "small-time" variant will always be used. Similarly, any very large positive number (e.g., +Inf) means that the "large-time" variant will always be used. Default value is 1.

err_tol

Details

Value

A vector containing the second-order partial derivatives of the DDM PDF with precision err_tol whose length matches that of the longest input parameter (usually rt).

References

Navarro, D. J., & Fuss, I. G. (2009). Fast and accurate calculations for first-passage times in Wiener diffusion models. Journal of Mathematical Psychology, 53(4), 222-230.

Blurton, S. P., Kesselmeier, M., & Gondan, M. (2017). The first-passage time distribution for the diffusion model with variable drift. Journal of Mathematical Psychology, 76, 7-12.

Hartmann, R., Klauer, K. C. (2021). Partial derivatives for the first-passage time distribution in Wiener diffusion models. Journal of Mathematical Psychology, 103, 102550.

Ratcliff, R. (1978). A theory of memory retrieval. Psychological review, 85(2), 59.

Examples

# derivative with respect to rt (response time)
dt_dfddm(rt = 1.2, response = "lower", a = 1, v = -1, t0 = 0.3, w = 0.5,
         sv = 0.4, err_tol = 1e-6)

# derivative with respect to t0 (non-decision time)
dt0_dfddm(rt = 1.2, response = "lower", a = 1, v = -1, t0 = 0.3, w = 0.5,
          sv = 0.4, err_tol = 1e-6)

# derivative with respect to a (threshold separation)
da_dfddm(rt = 1.2, response = "lower", a = 1, v = -1, t0 = 0.3, w = 0.5,
         sv = 0.4, err_tol = 1e-6)

# derivative with respect to v (drift rate)
dv_dfddm(rt = 1.2, response = "lower", a = 1, v = -1, t0 = 0.3, w = 0.5,
         sv = 0.4, err_tol = 1e-6)

# derivative with respect to w (relative starting point)
dw_dfddm(rt = 1.2, response = "lower", a = 1, v = -1, t0 = 0.3, w = 0.5,
         sv = 0.4, err_tol = 1e-6)

# derivative with respect to sv (inter-trial variability in the drift rate)
dsv_dfddm(rt = 1.2, response = "lower", a = 1, v = -1, t0 = 0.3, w = 0.5,
          sv = 0.4, err_tol = 1e-6)

#-------- Log Versions --------#

# # derivative with respect to rt (response time)
# dt_log_dfddm(rt = 1.2, response = "lower", a = 1, v = -1, t0 = 0.3, w = 0.5,
#              sv = 0.4, err_tol = 1e-6)

# # derivative with respect to t0 (non-decision time)
# dt0_log_dfddm(rt = 1.2, response = "lower", a = 1, v = -1, t0 = 0.3, w = 0.5,
#               sv = 0.4, err_tol = 1e-6)

# # derivative with respect to a (threshold separation)
# da_log_dfddm(rt = 1.2, response = "lower", a = 1, v = -1, t0 = 0.3, w = 0.5,
#              sv = 0.4, err_tol = 1e-6)

# # derivative with respect to v (drift rate)
# dv_log_dfddm(rt = 1.2, response = "lower", a = 1, v = -1, t0 = 0.3, w = 0.5,
#              sv = 0.4, err_tol = 1e-6)

# # derivative with respect to w (relative starting point)
# dw_log_dfddm(rt = 1.2, response = "lower", a = 1, v = -1, t0 = 0.3, w = 0.5,
#              sv = 0.4, err_tol = 1e-6)

# # derivative with respect to sv (inter-trial variability in the drift rate)
# dsv_log_dfddm(rt = 1.2, response = "lower", a = 1, v = -1, t0 = 0.3, w = 0.5,
#               sv = 0.4, err_tol = 1e-6)

Partial Derivative of 5-parameter DDM PDF with respect to w (initial bias)

Description

Partial Derivative of the density function for the 5-parameter variant of the Ratcliff diffusion decision model (DDM) with respect to w, the initial bias. This variant contains the following parameters: v (drift rate), a (threshold separation), t0 (non-decision time/response time constant), w (relative starting point), sv (inter-trial variability of drift), and sigma (diffusion coefficient of underlying Wiener process).

Usage

dw_dfddm(
  rt,
  response,
  v,
  a,
  t0,
  w = 0.5,
  sv = 0,
  sigma = 1,
  sl_thresh = 1,
  err_tol = 1e-06
)

Arguments

rt

A vector of response times (in seconds). If a response time is non-positve, then its density will evaluate to 0 if log = FALSE and -∞ if log = TRUE.

response

integers or doubles (1 → "lower", 2 → "upper");
factors (the first level gets mapped to "lower", and the second level gets mapped to "upper"; any additional levels are ignored).
strings (only the first character is checked, "L" → "lower" or "U" → "upper", case insensitive);
logicals (FALSE → "lower", TRUE → "upper");

v

a

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

t0

w

sv

sigma

a → a / sigma
v → v / sigma
sv → sv / sigma

sl_thresh

err_tol

Details

Value

A vector containing the partial derivatives of the DDM PDF with precision err_tol whose length matches that of the longest input parameter (usually rt).

References

Navarro, D. J., & Fuss, I. G. (2009). Fast and accurate calculations for first-passage times in Wiener diffusion models. Journal of Mathematical Psychology, 53(4), 222-230.

Blurton, S. P., Kesselmeier, M., & Gondan, M. (2017). The first-passage time distribution for the diffusion model with variable drift. Journal of Mathematical Psychology, 76, 7-12.

Hartmann, R., Klauer, K. C. (2021). Partial derivatives for the first-passage time distribution in Wiener diffusion models. Journal of Mathematical Psychology, 103, 102550.

Ratcliff, R. (1978). A theory of memory retrieval. Psychological review, 85(2), 59.

Examples

# derivative with respect to rt (response time)
dt_dfddm(rt = 1.2, response = "lower", a = 1, v = -1, t0 = 0.3, w = 0.5,
         sv = 0.4, err_tol = 1e-6)

# derivative with respect to t0 (non-decision time)
dt0_dfddm(rt = 1.2, response = "lower", a = 1, v = -1, t0 = 0.3, w = 0.5,
          sv = 0.4, err_tol = 1e-6)

# derivative with respect to a (threshold separation)
da_dfddm(rt = 1.2, response = "lower", a = 1, v = -1, t0 = 0.3, w = 0.5,
         sv = 0.4, err_tol = 1e-6)

# derivative with respect to v (drift rate)
dv_dfddm(rt = 1.2, response = "lower", a = 1, v = -1, t0 = 0.3, w = 0.5,
         sv = 0.4, err_tol = 1e-6)

# derivative with respect to w (relative starting point)
dw_dfddm(rt = 1.2, response = "lower", a = 1, v = -1, t0 = 0.3, w = 0.5,
         sv = 0.4, err_tol = 1e-6)

# derivative with respect to sv (inter-trial variability in the drift rate)
dsv_dfddm(rt = 1.2, response = "lower", a = 1, v = -1, t0 = 0.3, w = 0.5,
          sv = 0.4, err_tol = 1e-6)

#-------- Log Versions --------#

# # derivative with respect to rt (response time)
# dt_log_dfddm(rt = 1.2, response = "lower", a = 1, v = -1, t0 = 0.3, w = 0.5,
#              sv = 0.4, err_tol = 1e-6)

# # derivative with respect to t0 (non-decision time)
# dt0_log_dfddm(rt = 1.2, response = "lower", a = 1, v = -1, t0 = 0.3, w = 0.5,
#               sv = 0.4, err_tol = 1e-6)

# # derivative with respect to a (threshold separation)
# da_log_dfddm(rt = 1.2, response = "lower", a = 1, v = -1, t0 = 0.3, w = 0.5,
#              sv = 0.4, err_tol = 1e-6)

# # derivative with respect to v (drift rate)
# dv_log_dfddm(rt = 1.2, response = "lower", a = 1, v = -1, t0 = 0.3, w = 0.5,
#              sv = 0.4, err_tol = 1e-6)

# # derivative with respect to w (relative starting point)
# dw_log_dfddm(rt = 1.2, response = "lower", a = 1, v = -1, t0 = 0.3, w = 0.5,
#              sv = 0.4, err_tol = 1e-6)

# # derivative with respect to sv (inter-trial variability in the drift rate)
# dsv_log_dfddm(rt = 1.2, response = "lower", a = 1, v = -1, t0 = 0.3, w = 0.5,
#               sv = 0.4, err_tol = 1e-6)

Medicial decision data

Description

Part of the accuracy and response time data presented in Trueblood et al. (2017) investigating medical decision making among medical professionals (pathologists) and novices (i.e., undergraduate students). The task of participants was to judge whether pictures of blood cells show cancerous cells (i.e., blast cells) or non-cancerous cells (i.e., non-blast cells). The current data set contains 200 decisions per participant (the "accuracy" condition from Trueblood et al.).

Usage

data(med_dec)

Format

A data frame with 11000 rows and 9 variables:

id: identification number of the participant
group: expertise of participant; "experienced", "inexperienced", or "novice". The first two levels refer to different type of medical professional (i.e., experts).
block: block number
trial: index of trial for each participant
classification: true classification of the pictured cell; i.e. the correct response
difficulty: adjudged difficulty of the task for the particular image
response: response given by the participant; either "blast" or "non-blast"
rt: the response time associated with the response, in seconds
stimulus: the image file used for the specific trial

Details

At the beginning of the experiment, both novices and medical experts completed a training to familiarize themselves with blast cells. After that, each participant performed the main task in which they judged whether or not presented images were blast cells or non-blast cells. Among them, some of the cells were judged as easy and some as difficult trials by an additional group of experts. The current data set only contains the data from the "accuracy" condition (i.e., Trueblood et al. considered additional conditions that are not part of the current data set).

The relevant part of the method section for the accuracy condition from the original paper is as follows:

"The main task consisted of six blocks with 100 trials in each block. The main task was the same as the practice block, where participants were asked to identify single images. However, participants did not receive trial-by-trial feedback about their choices. They received feedback about their performance at the end of each block. The 100 trials in each block were composed of equal numbers of easy blast images, hard blast images, easy non-blast images, and hard non-blast images, fully randomized.

There were three manipulations across blocks: accuracy, speed, and bias. In the accuracy blocks, participants were instructed to respond as accurately as possible and were given 5 s to respond. [...] If they responded after the deadline, they received the message "Too Slow!" The 5-s [...] response windows for the accuracy [...] [condition was] based on the response time data from the three expert raters. The 0.975 quantile of the expert raters' response times was 4.96 s; thus, we set the accuracy response window to 5 s.

The order of the first three blocks was randomized but with the constraint that there was one block for each type of manipulation (i.e., accuracy, speed, and bias). The order of the last three blocks was identical to the order of the first three blocks."

Note that this dataset contains some negative response times that indicate a missing response (i.e., the response value for that trial is NA). Take care in removing these values before using this dataset. See our Validity vignette for an example of use in an optimization setting.

Source

Trueblood, J.S., Holmes, W.R., Seegmiller, A.C. et al. The impact of speed and bias on the cognitive processes of experts and novices in medical image decision-making. Cogn. Research 3, 28 (2018). https://doi.org/10.1186/s41235-018-0119-2

Examples


data("med_dec", package = "fddm")
str(med_dec)

## number of participants per expertise condition:
aggregate(id ~ group, med_dec, function(x) length(unique(x)))

## number of trials per participant
aggregate(rt ~ group + id, med_dec, length)

Distribution of Ratcliff Diffusion Decision Model

Description

Usage

pfddm(
  rt,
  response,
  v,
  a,
  t0,
  w = 0.5,
  sv = 0,
  sigma = 1,
  err_tol = 1e-06,
  log = FALSE,
  method = "Mills"
)

Arguments

rt

A vector of response times (in seconds). If a response time is non-positve, then its density will evaluate to 0 if log = FALSE and -∞ if log = TRUE.

response

integers or doubles (1 → "lower", 2 → "upper");
factors (the first level gets mapped to "lower", and the second level gets mapped to "upper"; any additional levels are ignored).
strings (only the first character is checked, "L" → "lower" or "U" → "upper", case insensitive);
logicals (FALSE → "lower", TRUE → "upper");

v

a

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

t0

w

sv

sigma

a → a / sigma
v → v / sigma
sv → sv / sigma

err_tol

Allowed error tolerance of the density function. Since the density function contains an infinite sum, this parameter defines the precision of the approximation to that infinite sum. If the provided error tolerance is less than 1e-300, it is set to 1e-300. Default is 1e-6.

log

Logical; if TRUE, probabilities p are given as log(p). Default is FALSE.

method

Which method of calculating the CDF to use. Can be one of {"Mills", "NCDF"}, case-insensitive. Default is "Mills".

Details

Value

A vector containing the distribution of the DDM with precision err_tol whose length matches that of the longest input parameter (usually rt).

References

Navarro, D. J., & Fuss, I. G. (2009). Fast and accurate calculations for first-passage times in Wiener diffusion models. Journal of Mathematical Psychology, 53(4), 222-230.

Blurton, S. P., Kesselmeier, M., & Gondan, M. (2017). The first-passage time distribution for the diffusion model with variable drift. Journal of Mathematical Psychology, 76, 7-12.

Ratcliff, R. (1978). A theory of memory retrieval. Psychological review, 85(2), 59.

Examples

# minimal example
pfddm(rt = 1.2, response = "lower", a = 1, v = -1, t0 = 0.3)

# example with all function parameters set to default or a practical value
pfddm(rt = c(1.2, 0.9, 1.1, 1.4, 0.8, 1.3),
      response = c("lower", "upper", "upper", "lower", "upper", "lower"),
      a = 1, v = -1, t0 = 0.2, w = 0.5, sv = 0, sigma = 1,
      err_tol = 1e-6, log = FALSE, method = "Mills")

# example of mismatched input lengths
pfddm(rt = c(1.2, 0.9, 1.1, 1.4, 0.8, 1.3),
      response = c("lower", "upper", "upper", "lower", "upper", "lower"),
      a = c(1, 3), v = c(-2, 2, 2, -2, 2, -2),
      t0 = 0.3, w = c(0.4, 0.5, 0.6), sv = 0.9,
      err_tol = 1e-10, log = FALSE, method = "NCDF")

# example with Wiener diffusion coefficient (sigma) not equal to 1
pfddm(rt = c(1.2, 0.9, 1.1, 1.4, 0.8, 1.3),
      response = c("lower", "upper", "upper", "lower", "upper", "lower"),
      a = 1, v = -1, t0 = 0.3, w = 0.5, sv = 0, sigma = 0.1,
      err_tol = 1e-10, log = TRUE, method = "Mills")


### examples of different response inputs

# integer
resp_int <- as.integer(c(1, 2, 2, 1, 2, 1))
pfddm(rt = c(1.2, 0.9, 1.1, 1.4, 0.8, 1.3), response = resp_int,
      a = 1, v = -2, t0 = 0.3, w = 0.5, sv = 0.1,
      err_tol = 1e-10, log = FALSE, method = "Mills")

# double
resp_dbl <- as.double(c(1, 2, 2, 1, 2, 1))
pfddm(rt = c(1.2, 0.9, 1.1, 1.4, 0.8, 1.3), response = resp_dbl,
      a = 1, v = -2, t0 = 0.3, w = 0.5, sv = 0.1,
      err_tol = 1e-10, log = FALSE, method = "Mills")

# factor (first level is mapped to "lower")
days <- c("Monday", "Friday", "Friday", "Monday", "Friday", "Monday")
resp_fac <- factor(days, levels = c("Monday", "Friday"))
pfddm(rt = c(1.2, 0.9, 1.1, 1.4, 0.8, 1.3), response = resp_fac,
      a = 1, v = -2, t0 = 0.3, w = 0.5, sv = 0.1,
      err_tol = 1e-10, log = FALSE, method = "Mills")

# string
resp_str <- c("lower", "upper", "upper", "lower", "upper", "lower")
pfddm(rt = c(1.2, 0.9, 1.1, 1.4, 0.8, 1.3), response = resp_str,
      a = 1, v = -2, t0 = 0.3, w = 0.5, sv = 0.1,
      err_tol = 1e-10, log = FALSE, method = "Mills")

# logical
resp_log <- c(FALSE, TRUE, TRUE, FALSE, TRUE, FALSE)
pfddm(rt = c(1.2, 0.9, 1.1, 1.4, 0.8, 1.3), response = resp_log,
      a = 1, v = -2, t0 = 0.3, w = 0.5, sv = 0.1,
      err_tol = 1e-10, log = FALSE, method = "Mills")

Second-Order Partial Derivative of 5-parameter DDM PDF with respect to a (threshold separation)

Description

Usage

Arguments

Details

Value

References

Examples

Partial Derivative of 5-parameter DDM PDF with respect to a (threshold separation)

Description

Usage

Arguments

Details

Value

References

Examples

Estimation of 5-Parameter DDM

Description

Usage

Arguments

Details

Value

Examples

Methods for ddm objects

Description

Usage

Arguments

Details

Density of Ratcliff Diffusion Decision Model

Description

Usage

Arguments

Details

Value

References

See Also

Examples

Second-Order Partial Derivative of 5-parameter DDM PDF with respect to sv (inter-trial variability in the drift rate)

Description

Usage

Arguments

Details

Value

References

Examples

Partial Derivative of 5-parameter DDM PDF with respect to sv (inter-trial variability in the drift rate)

Description

Usage

Arguments

Details

Value

References

Examples

Second-Order Partial Derivative of 5-parameter DDM PDF with respect to t0 (non-decision time)

Description

Usage

Arguments

Details

Value

References

Examples

Partial Derivative of 5-parameter DDM PDF with respect to t0 (non-decision time)

Description

Usage

Arguments

Details

Value

References

Examples

Second-Order Partial Derivative of 5-parameter DDM PDF with respect to t (response time)

Description

Usage

Arguments

Details

Value

References

Examples

Partial Derivative of 5-parameter DDM PDF with respect to t (response time)

Description

Usage