Diffusion Decision Model

Usage

ddm(rt, response, links = NULL, ...)

Arguments

rt: Name of the reaction time variable coding reaction time in seconds in the data.
response: Name of the response variable coding the response numerically (0 = lower response / incorrect, 1 = upper response / correct)
links: A named list of links for the parameters, e.g. links = list(bound = "softplus"). For positive parameters (e.g. bound, ndt), "softplus" is available as an alternative to the default "log" link that grows linearly for large values and avoids the numerical blow-up of exp(). A name that is not a parameter of the model is an error, and a link that allows values the default link excludes (e.g. "identity" for a positive parameter) is a warning.
...: used internally for testing, ignore it

Value

An object of class bmmodel

Details

Domain: Decision Making / Response times
Task: Two-Alternative Force Choice RT
Name: Diffusion Decision Model
Citation:
- Ratcliff, R. (1978). A theory of memory retrieval. Psychological Review, 85(2), 59-108. https://doi.org/10.1037/0033-295X.85.2.59
Requirements:
- The response time should be in seconds and represent the time between onset of the target stimulus until the response execution

The response should be coded numerically: 0 = lower response, 1 = upper response

Parameters:
- drift: Drift rate = Average rate of evidence accumulation of the decision processes
- bound: Boundary separation = Distance between the decision boundaries that need to be reached
- ndt: Non-decision time = Additional time required beyond the evidence accumulation process
- zr: Relative starting point = Starting point as a proportion of the boundary separation, measured from the lower boundary (0.5 = unbiased, > 0.5 = biased towards the upper response).
Fixed parameters:
- zr = 0
- mu = 0
Default parameter links:
- drift = identity; bound = log; ndt = log; zr = logit
Default priors:
- drift:
  - main: cauchy(0,1)
  - effects: normal(0,0.5)
  - sd: exponential(1)
- bound:
  - main: normal(0,0.5)
  - effects: normal(0,0.5)
  - sd: exponential(2)
- ndt:
  - main: normal(-1.5,0.5)
  - effects: normal(0,0.3)
  - sd: exponential(2)
- zr:
  - main: normal(0,0.5)
  - effects: normal(0,0.3)
  - sd: exponential(2)

Default behavior

By default, zr is fixed at 0 on its logit link scale, that is at an unbiased starting point of zr = 0.5. If you want to estimate zr, add a formula for zr in your bmf() call. Estimates of zr are on the logit scale too, so use plogis() to read them as proportions.

With accuracy-coded responses (1 = correct, 0 = error) the unbiased default is the usual assumption. With response-coded data (1 and 0 for the two response options, e.g. "word" and "nonword"), a bias towards one option moves the starting point; with zr fixed, that bias is absorbed by the other parameters instead. Estimate zr for response-coded data, e.g. zr ~ 1, and code drift so that its sign follows the stimulus.

Examples

if (FALSE) { # identical(Sys.getenv("BMM_EXAMPLES"), "true")
# Simulate data for one subject using rddm
set.seed(123)
n_trials <- 500

# Simulate DDM data with fixed parameters
sim_data <- rddm(
  n = n_trials,
  drift = 1.5,    # drift rate
  bound = 1.2,    # boundary separation
  ndt = 0.3,      # non-decision time
  zr = 0.5        # relative starting point
)

# Prepare data frame
dat <- data.frame(
  rt = sim_data$rt,
  response = sim_data$response
)

# Define formula (intercept-only model)
ff <- bmmformula(
  drift ~ 1,
  bound ~ 1,
  ndt ~ 1
)

# Specify the DDM model
model <- ddm(rt = "rt", response = "response")

# Fit the model
fit <- bmm(
  formula = ff,
  data = dat,
  model = model,
  cores = 4,
  iter = 1000,
  backend = "cmdstanr"
)

# Check parameter recovery
summary(fit)
}