dv_dfddm: Partial Derivative of 5-parameter DDM PDF with respect to v...

In fddm: Fast Implementation of the Diffusion Decision Model

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

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

fddm documentation built on July 2, 2024, 5:06 p.m.