ezdm_dist: Distribution functions for the EZ-Diffusion Model (ezdm)

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

Distribution functions for the EZ-Diffusion Model (ezdm)

Description

Density and random generation functions for the EZ-Diffusion Model. The model operates on aggregated data: mean reaction time, variance of reaction time, and number of responses to the upper boundary.

Usage

dezdm(
  mean_rt,
  var_rt,
  n_upper,
  n_trials,
  drift,
  bound,
  ndt,
  zr = 0.5,
  s = 1,
  version = c("3par", "4par"),
  log = TRUE
)

rezdm(
  n,
  n_trials,
  drift,
  bound,
  ndt,
  zr = 0.5,
  s = 1,
  version = c("3par", "4par")
)

Arguments

mean_rt	Observed mean reaction time(s) in seconds. For version "3par", a numeric vector or single value. For version "4par", either a vector of length 2 (c(mean_rt_upper, mean_rt_lower)) for single observation, or a matrix with 2 columns for multiple observations.
var_rt	Observed variance of reaction times in seconds^2. For version "3par", a numeric vector or single value. For version "4par", either a vector of length 2 (c(var_rt_upper, var_rt_lower)) for single observation, or a matrix with 2 columns for multiple observations.
n_upper	Number of responses to the upper boundary
n_trials	Total number of trials
drift	Drift rate (evidence accumulation rate; can be positive or negative for below-chance performance).
bound	Boundary separation (distance between decision thresholds).
ndt	Non-decision time (seconds).
zr	Relative starting point (0 to 1). Only used for version "4par".
s	Diffusion constant (standard deviation of noise), default = 1.
version	Character; either "3par" (default) or "4par"
log	Logical; if TRUE, values are returned on the log scale.
n	Number of samples to generate

Details

The number of upper-boundary responses is binomial. The two RT summaries follow the joint sampling distribution of the mean and the variance of n independent decision times, matched to the exact first four cumulants of the first-passage time. Writing \mathrm{MDT} and \mathrm{VRT} for its mean and variance and \kappa_3, \kappa_4 for its third and fourth cumulants, and W = \kappa_4 / n + 2\,\mathrm{VRT}^2 / (n - 1) for the exact variance of the sample variance,

\mathrm{var\_rt} \sim \mathrm{Gamma}(\mathrm{VRT}^2 / W, \mathrm{VRT} / W),

\mathrm{mean\_rt} \mid \mathrm{var\_rt} \sim N\left(\mathrm{ndt} + \mathrm{MDT} + \frac{\kappa_3 / n}{W}(\mathrm{var\_rt} - \mathrm{VRT}),\ \sqrt{\mathrm{VRT} / n - (\kappa_3 / n)^2 / W}\right),

so that \mathrm{Var}(\mathrm{mean\_rt}) = \mathrm{VRT} / n and \mathrm{Cov}(\mathrm{mean\_rt}, \mathrm{var\_rt}) = \kappa_3 / n are exact. Decision times are right-skewed (with a symmetric start point their kurtosis is 8.8 at zero drift and falls towards 3 as drift grows), so the older form that assumes normal reaction times — independent normal and scaled chi-square \mathrm{Gamma}((n - 1)/2, (n - 1)/(2\,\mathrm{VRT})) terms — understates the sampling variance of var_rt by a factor of 1 + (\mathrm{kurtosis} - 3)(n - 1)/(2n): about 3.8 with 100 trials per cell and 3.5 to 3.6 with 10, less at accuracies above .95. With an asymmetric start point in version "4par" it is more at the boundary nearer the start point (up to 5.7 for zr between .3 and .7) and less at the other. It also ignores a correlation of about 0.7 between the two statistics, making posteriors too narrow. The terms above reduce to it when \kappa_3 = \kappa_4 = 0.

For version "3par" the start point is symmetric, so the decision time is independent of which boundary is hit and all n_trials responses inform one set of cumulants. For version "4par" the two boundaries have different decision-time distributions, so each is given its own summaries and its own response count. A boundary reached fewer than twice has no sample variance, and one whose summaries are NA has nothing to evaluate; dezdm() lets either contribute only through the binomial term. rezdm() and ezdm_summary_stats() code such summaries as NA, and bmm() keeps these cells: it replaces the summaries of such a boundary with a placeholder that the likelihood never reads, so the response counts still inform the fit. The per-boundary formulas condition on the realised counts, which are themselves random.

The two additional cumulants cost sampling time. In two simulated designs (30 subjects with 200 or 250 trials, 3 seeds each, one machine) a gradient of the whole model took 1.3 times as long as with the older form for version "3par" and 1.9 times for version "4par". The likelihood alone took 1.5 to 2.0 and 1.7 to 2.5 times as long, most where accuracy is near chance, so the ratio grows with the number of cells.

Simulated mean_rt is not truncated at ndt. When a summary rests on few responses (a handful of trials in version "3par", or a rarely reached boundary in version "4par", whatever n_trials is), rezdm() can return mean_rt below ndt or even mean_rt <= 0, which bmm() rejects; drop those rows before fitting.

Value

dezdm gives the log-density of the observed summary statistics under the EZDM, and rezdm generates random summary statistics from the implied sampling distributions.

References

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.

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.

Examples

# 3-parameter version (single observation)
dezdm(
  mean_rt = 0.5, var_rt = 0.02, n_upper = 80, n_trials = 100,
  drift = 2, bound = 1.5, ndt = 0.3
)

# 3-parameter version (vectorized)
dezdm(
  mean_rt = c(0.5, 0.55), var_rt = c(0.02, 0.025),
  n_upper = c(80, 75), n_trials = c(100, 100),
  drift = 2, bound = 1.5, ndt = 0.3
)

# 4-parameter version (single observation)
dezdm(
  mean_rt = c(0.45, 0.55), var_rt = c(0.018, 0.025),
  n_upper = 80, n_trials = 100,
  drift = 2, bound = 1.5, ndt = 0.3, zr = 0.55, version = "4par"
)

# generate random summary statistics
rezdm(n = 100, n_trials = 100, drift = 2, bound = 1.5, ndt = 0.3)
rezdm(
  n = 100, n_trials = 100, drift = 2, bound = 1.5, ndt = 0.3,
  zr = 0.55, version = "4par"
)

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