Simulation and Likelihood Tools for Evidence-Accumulation Models

Toolbox for designing, simulating and fitting custom racing evidence-accumulation models to behavioral data. Users define a model in terms of accumulators, pooled channels, logical response rules, and timing dependencies. This allows more direct embedding of psychological hypotheses into the model. With that model you can simulate decision-making data and evaluate the likelihood of observed responses under alternative parameter values. The user-facing interface stays in R, while the simulation and likelihood calculations are handled in C++ for speed.

editor_options: markdown: wrap: 72

AccumulatR

AccumulatR is an R/C++ toolkit for race-model simulation and likelihood evaluation.

You can define your own race model, simulate behavioral data, and evaluate how well different parameter values explain observed response times and choices.

Installation

AccumulatR is not yet on CRAN. To install the current development version from GitHub:

remotes::install_github("niekstevenson/AccumulatR")

What the package does

AccumulatR is organized around a simple workflow:

1. Define a model with accumulators, pools, and observed responses.
2. Turn that specification into an object ready for simulation or fitting.
3. Simulate behavioral data from known parameter values.
4. Evaluate the log-likelihood of observed data under candidate parameters.

A two-choice race

The example below defines a two-choice race model, simulates response-time data, and then evaluates the likelihood of those same data under the generating parameters.

library(AccumulatR)

spec <- race_spec() |>
  add_accumulator("left", "lognormal") |>
  add_accumulator("right", "lognormal") |>
  add_outcome("left", "left") |>
  add_outcome("right", "right")

model <- finalize_model(spec)

pars <- c(
  m = log(0.30),
  s = 0.17,
  t0 = 0
)

param_df <- build_param_matrix(model, pars, n_trials = 8)
sim <- simulate(model, param_df, seed = 123)
head(sim[c("trials", "R", "rt")])

prepared <- prepare_data(model, sim[c("trials", "R", "rt")])
ctx <- make_context(model)
log_likelihood(ctx, prepared, param_df)

simulate() returns behavioral data with one row per trial. In the simplest case that means a response column (R) and a response-time column (rt). log_likelihood() then evaluates how probable those data are under a set of model parameters.

Parameters with the same name are shared by default. Use set_parameters() to give accumulators separate values, and par_names(model) to see the names accepted by build_param_matrix(). The parameter matrix has one row per accumulator per trial; the simulated data have one row per trial.

Prepare the observations and build the context once, then reuse them while evaluating candidate parameter matrices for the same model.

Start with Getting Started for the data conventions, or Supported Distributions for parameter definitions. The function reference describes each argument and return value.