Skip to contents

EZ-Diffusion Model

Source: R/model_ezdm.R
ezdm.Rd

EZ-Diffusion Model

Usage

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

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.

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

Value

An object of class bmmodel

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/fk447c

  • 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. 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 between the decision thresholds relative to the upper bound.

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

Examples

if (FALSE) { # \dontrun{
# 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 (on log scale for drift/bound)
exp(brms::fixef(fit))
} # }