ezdm: EZ-Diffusion Model

In bmm: Easy and Accessible Bayesian Measurement Models Using 'brms'

EZ-Diffusion Model

Description

EZ-Diffusion Model

Usage

ezdm(
  mean_rt,
  var_rt,
  n_upper,
  n_trials,
  links = NULL,
  version = c("3par", "4par"),
  ...
)

Arguments

mean_rt	The names of the variable or variables (for 4par version) coding the mean reaction time in seconds in the data.
var_rt	The names of the variable or variables (for 4par version) coding the variance of the reaction time in seconds in the data
n_upper	The name of the variable coding the number of responses that hit the upper response threshold (typically the number of correct responses) in the data.
n_trials	The name of the variable coding the number of trials that was used to calculated the aggregated statistics.
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.
version	A character label for the version of the model. There is a three-parameter version (version = "3par") of the ezdm that fixes the relative starting point zr to 0.5, and a four parameter version (version = "4par"), that allows to freely estimate the starting point.
...	used internally for testing, ignore it

Details

• Domain: Decision Making / Response times

• Task: Choice Reaction Time tasks

• Name: EZ-Diffusion Model

• Citation:

  • Wagenmakers, E.-J., Van Der Maas, H. L. J., & Grasman, R. P. P. P. (2007). An EZ-diffusion model for response time and accuracy. Psychonomic Bulletin & Review, 14(1), 3-22. https://doi.org/10.3758/BF03194023

  • Chávez De la Peña, A. F., & Vandekerckhove, J. (2025). An EZ Bayesian hierarchical drift diffusion model for response time and accuracy. Psychonomic Bulletin & Review, 32(6), 3067-3087. https://doi.org/10.3758/s13423-025-02729-y

• Version: 4par

• Requirements:

  Provide aggregated statistics for each subject and condition that model parameters should vary over:

• Mean reaction times (mean_rt) in seconds

• Variance of reaction times (var_rt) in seconds

• Number of responses to the upper decision threshold (n_upper)

• Total number of trials used to calculate aggregated statistics (n_trials)

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

  • s: The diffusion constant, that is the standard deviation of the Gaussian noise during sampling

• Fixed parameters:

  • s = 0

  • mu = 0

• Default parameter links:

  • drift = identity; bound = log; ndt = log; zr = logit; s = log

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

  • s:

    • main: normal(0,1)

    • effects: normal(0,0.3)

    • sd: exponential(2)

  In version "4par", a boundary reached fewer than twice, or without RT summaries (NA), enters the model through the response counts only. bmm() adds two columns to the data, rt_used_upper and rt_used_lower, which it sets to 0 for such a boundary and to 1 otherwise, and replaces the summaries of such a boundary with a placeholder the likelihood never reads. A 0 already in these columns is kept, so that update() does not read the placeholders in fit$data as data.

  newdata passed to log_lik(), predict() or posterior_predict() needs these columns too. Rows of fit$data have them. For raw data, set both to 1: a boundary reached fewer than twice or with NA summaries is then still left out of the likelihood. brms functions that compare the response with predictions, predictive_error() and residuals(method = "posterior_predict"), read the placeholders as data in cells whose rt_used_upper is 0, so leave those cells out first, for example with newdata = subset(fit$data, rt_used_upper == 1).

Value

An object of class bmmodel

Examples

## Not run: 
# Minimal parameter recovery example with 3-parameter EZDM

# Simulate data from known parameters
set.seed(123)
sim_data <- rezdm(
  n = 10,
  n_trials = 100,
  drift = 2,
  bound = 1.5,
  ndt = 0.3,
  version = "3par"
)

# Add subject ID
sim_data$id <- 1:10

# Specify model
model <- ezdm(
  mean_rt = "mean_rt",
  var_rt = "var_rt",
  n_upper = "n_upper",
  n_trials = "n_trials",
  version = "3par"
)

# Specify formula with random effects
formula <- bmf(
  drift ~ 1 + (1 | id),
  bound ~ 1 + (1 | id),
  ndt ~ 1
)

# Fit model (using cmdstanr backend)
fit <- bmm(
  formula = formula,
  data = sim_data,
  model = model,
  backend = "cmdstanr",
  cores = 4,
  chains = 4,
  iter = 2000,
  warmup = 1000
)

# Check parameter recovery
summary(fit)

# Extract population-level effects
# True values: drift = 2, bound = 1.5, ndt = 0.3
# drift has an identity link; bound and ndt have log links
fixed_effects <- brms::fixef(fit)
fixed_effects["drift_Intercept", "Estimate"]
exp(fixed_effects[c("bound_Intercept", "ndt_Intercept"), "Estimate"])

## End(Not run)

bmm documentation built on Oct. 16, 2026, 9:08 a.m.