fddm (version 1.0-2)

pfddm: Distribution 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).

Usage

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

Value

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

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

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.

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.

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.

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