Package {AccumulatR}

AccumulatR: Simulate and fit evidence-accumulation models

Description

Details

AccumulatR is for researchers who work with response-time models in which behavior is generated by competing or interacting accumulators. The package lets you describe a model in psychologically meaningful terms, simulate behavioral data, and evaluate likelihoods for fitting.

The main workflow is:

1. Start with race_spec().

2. Add accumulators, pools, outcomes, and timing relations.

3. Call finalize_model() and supply values with build_param_matrix().

4. Generate observations with simulate(), or use experimental data.

5. Call prepare_data() and make_context(), then evaluate candidate parameters with log_likelihood().

See vignette("getting_started", package = "AccumulatR") for a worked example.

Author(s)

Maintainer: Niek Stevenson niek.stevenson@gmail.com

See Also

Useful links:

• https://github.com/niekstevenson/AccumulatR

• https://niekstevenson.github.io/AccumulatR/

• Report bugs at https://github.com/niekstevenson/AccumulatR/issues

Add an accumulator to a model

Description

An accumulator has a random finishing time drawn from dist, shifted by its onset and nondecision time t0. Use add_outcome() to connect its completion to an observed response.

Usage

add_accumulator(spec, id, dist, onset = 0)

Arguments

Value

The updated race_spec.

See Also

set_parameters(), build_param_matrix(), after()

Examples

spec <- race_spec()
spec <- add_accumulator(spec, "A", "lognormal")

Define a mixture component

Description

Components are useful when trials can come from qualitatively different processing modes, such as fast versus slow processing. Component declarations define membership only; component probabilities are configured with set_mixture().

Usage

add_component(spec, id, members, n_outcomes = NULL)

Arguments

Value

The updated race_spec.

Define an observed response

Description

Attach a response label to a finishing rule. In a single-response model, the first available outcome determines the observed response and time.

Usage

add_outcome(spec, label, expr, options = list())

Arguments

Value

The updated race_spec.

Examples

spec <- race_spec()
spec <- add_accumulator(spec, "A", "lognormal")
spec <- add_outcome(spec, "A_win", "A")

Pool several accumulators under a shared label

Description

A pool finishes when its kth member finishes. Use the pool label in add_outcome(), another pool, or after().

Usage

add_pool(spec, id, members, k = 1L)

Arguments

Value

The updated race_spec.

Examples

spec <- race_spec()
spec <- add_accumulator(spec, "A", "lognormal")
spec <- add_accumulator(spec, "B", "lognormal")
spec <- add_pool(spec, "P1", members = c("A", "B"), k = 1L)

Add a shared absence trigger

Description

With probability given by name, all member accumulators are absent on a trial. Otherwise they follow their specified onsets and finishing-time distributions. Use separate triggers for independent absence events; set_parameters() can give those events a common probability.

Usage

add_trigger(spec, name, members)

Arguments

Value

The updated race_spec.

Start one accumulator after another process finishes

Description

This is useful for staged or contingent architectures, where one process can only begin after an earlier accumulator or pool has finished.

Usage

after(source, lag = 0)

Arguments

Value

A chained-onset specification for add_accumulator(onset = ...).

Examples

after("A")
after("pool1", lag = 0.05)

Define a response that requires several processes to finish

Description

Return a rule that finishes when all required events have completed. Any none_of() conditions are checked at that finishing time.

Usage

all_of(...)

Arguments

Value

An expression object.

Examples

all_of("A", "B")

Build a response rule from a quoted expression

Description

Convert a source label or quoted R expression into a response rule for add_outcome(). Within a quoted expression, & combines requirements, | allows alternative routes, and ! specifies an absence condition. These correspond to all_of(), first_of(), and none_of().

Usage

build_outcome_expr(expr)

Arguments

Value

An expression object used inside model specifications.

Examples

build_outcome_expr(quote(A & !B))

Create trial-level parameter values

Description

Expand a named parameter vector into the matrix used by simulate() and log_likelihood(). Each trial receives the same parameter values; rows are grouped by trial, with accumulators in their model declaration order.

Usage

build_param_matrix(model, param_values, n_trials = 1L)

Arguments

Details

Parameter domains are checked before expansion. All values must be finite, t0 must be nonnegative, and distribution scales must be positive. Trigger probabilities must lie in ⁠[0, 1]⁠; sampled mixture weights must be nonnegative and sum to at most one. See vignette("distributions", package = "AccumulatR") for distribution-specific constraints.

For trial-specific parameters, modify the relevant matrix rows while preserving their order and column layout. Likelihood and simulation calls use those values directly, so modified values must satisfy the same domains.

Value

A numeric matrix with one row per trial/accumulator pair. Columns contain trigger absence probability q, nondecision time t0, distribution parameters p1, p2, and so on, followed by sampled mixture weights. Distribution slots follow the order listed in the Supported Distributions vignette. Accumulators without a trigger have q = 0.

Examples

spec <- race_spec()
spec <- add_accumulator(spec, "A", "lognormal")
spec <- add_outcome(spec, "A_win", "A")
vals <- c(m = 0, s = 0.1)
build_param_matrix(finalize_model(spec), vals, n_trials = 2)

Inspect the size of a compiled likelihood plan

Description

Report how many symbolic regions, numerical operations, and integration kernels the model requires. Use these counts to investigate models whose context construction or likelihood evaluation is expensive.

Usage

complexity_metrics(context)

Arguments

Value

A list containing a variants data frame and a total list. Each variant is a compiled component plan. Columns count symbolic regions and cells, compiled roots and nodes, and integral kernels. Fields beginning with max_ report maxima; other total fields sum across variants.

Finalize a model for simulation and fitting

Description

Check source references, timing dependencies, response rules, and parameter grouping, and create the model object used by simulate(), prepare_data(), and build_param_matrix(). Build its likelihood context with make_context().

Usage

finalize_model(model)

Arguments

Value

A model_structure object.

Examples

spec <- race_spec()
spec <- add_accumulator(spec, "A", "lognormal")
spec <- add_outcome(spec, "A_win", "A")
finalize_model(spec)

Define a response that occurs when the first listed process finishes

Description

Return a rule whose finishing time is the earliest completion among its arguments. Each argument must contain an event that can generate a response.

Usage

first_of(...)

Arguments

Value

An expression object.

Examples

first_of("A", "B")

Define a response that is blocked by another process

Description

The response occurs when reference finishes, provided by has not finished strictly earlier. A blocker that finishes later does not cancel a response that has already occurred.

Usage

inhibit(reference, by)

Arguments

Value

A guarded expression object.

Examples

inhibit("A", "B")

Evaluate log-likelihoods of behavioral data

Description

Compute the summed log-likelihood by default, or trial-wise log-likelihoods when sum = FALSE. Build the context and prepare the observations once, then reuse them when evaluating candidate parameter matrices for the same model.

Usage

log_likelihood(
  context,
  data,
  parameters,
  ok = NULL,
  sum = TRUE,
  min_ll = log(1e-10)
)

Arguments

Details

Response-time observations contribute densities, so a log-likelihood can be positive. Missing responses and censoring contribute probability masses according to the observation rules.

Use prepare_data() and build_param_matrix() for the same model. Evaluation assumes matching layouts and valid parameters and does not repeat preparation checks.

Value

A summed log-likelihood by default, or a numeric vector of trial-wise log-likelihood values when sum = FALSE.

Examples

spec <- race_spec()
spec <- add_accumulator(spec, "A", "lognormal")
spec <- add_outcome(spec, "A_win", "A")
structure <- finalize_model(spec)
params_df <- build_param_matrix(
  structure,
  c(m = 0, s = 0.1),
  n_trials = 2
)
data_df <- simulate(structure, params_df, seed = 1)
prepared <- prepare_data(structure, data_df)
ctx <- make_context(structure)
log_likelihood(ctx, prepared, params_df)

Build a compiled likelihood context from a model

Description

Compile the model's response rules and dependencies for likelihood evaluation. Reuse the context across candidate parameter values and datasets for the same model. Prepare each dataset with prepare_data().

Usage

make_context(structure, diagnostics = FALSE)

Arguments

Value

An accumulatr_context object.

Examples

spec <- race_spec()
spec <- add_accumulator(spec, "A", "lognormal")
spec <- add_outcome(spec, "A_win", "A")
structure <- finalize_model(spec)
make_context(structure)

Define the absence of an event

Description

Use inside all_of() to require that expr has not finished before the conjunction completes. Absence supplies a condition, not a response time, so it cannot be an outcome on its own or a standalone first_of() branch.

Usage

none_of(expr)

Arguments

Value

An expression object.

Examples

all_of("go", none_of("stop"))

List the parameter names used by a model

Description

Return the names accepted by build_param_matrix(), after applying any grouping or renaming in set_parameters(). The list includes nondecision times, trigger probabilities, and sampled mixture weights where applicable. These names do not determine which parameters an optimizer must estimate; parameters can be held fixed by supplying constant values.

Usage

par_names(model)

Arguments

Value

A character vector of parameter names.

Examples

spec <- race_spec()
spec <- add_accumulator(spec, "A", "lognormal")
spec <- add_outcome(spec, "A_win", "A")
par_names(spec)

Plot accumulators and their timing relations

Description

Draw a schematic view of the model with time on the x-axis and evidence on the y-axis. Each accumulator is shown as a simple trajectory, and timing or blocking relations are overlaid so you can inspect the qualitative structure of the model before fitting.

Usage

plot_accumulators(
  model,
  xlim = NULL,
  ylim = c(0, 1),
  line_length = 1,
  angle_dodge = 10,
  accumulator_order = NULL,
  curve_strength = 0.18,
  line_col = "gray20",
  line_lwd = 3,
  axis_lwd = 3,
  blocker_lwd = 2.6,
  show_labels = TRUE,
  main = "Accumulator Schematic",
  xlab = "Time",
  ylab = "Evidence",
  ...
)

Arguments

Value

Invisibly returns a list with plotting coordinates and inferred structural links.

Examples

spec <- race_spec() |>
  add_accumulator("go", "lognormal") |>
  add_accumulator("stop", "lognormal", onset = 0.15) |>
  add_pool("P", c("go", "stop")) |>
  add_outcome("R", "P") |>
  finalize_model()
plot_accumulators(spec)

Prepare behavioral data for likelihood evaluation

Description

Check response labels, times, and observation conditions, and arrange the data into one row per accumulator per trial for log_likelihood().

Usage

prepare_data(structure, data_df, compress = FALSE)

Arguments

Details

Trial layout. Without a racer column, each row is one trial. Trials are numbered consecutively in input order. To supply accumulator-specific onsets, include trials and racer columns with one complete accumulator block per trial in model order. Repeat each trial's response and component values across its block. An onset replaces a fixed onset or adds an offset to a chained onset. Omit it to use model defaults.

Mixtures. A nonmissing component label conditions on that component. An omitted or NA label averages over the model's mixture probabilities.

Missing observations. For single-response models, R = NA and rt = NA denote no observed response. A finite rt requires a response label. A known response with rt = NA requires a censoring code or a model with an observation rule such as guess or map_outcome_to.

Ranked responses. Supply paired columns R2/rt2, R3/rt3, and so on. The first pair must be observed. Labels cannot repeat, and observed times must increase strictly. Later pairs may both be NA; all subsequent ranks must then also be missing. Ranked observations support neither censoring/truncation nor guessing/remapping rules.

Censoring and truncation. LT and UT define the observation window. An active truncation window conditions the likelihood on an observable response with LT \le rt \le UT. For a censored trial set rt = NA and use:

• missingness = 1 for LT \le rt < LC;

• missingness = 2 for UC < rt \le UT;

• missingness = 3 for the union of those intervals.

R may retain a known response or be NA. Uncensored trials use missingness = NA. Missing bounds default to LT = LC = 0 and UC = UT = Inf. These bounds describe the recorded response time. Times exactly at LC or UC remain uncensored.

Value

A data frame of class accumulatr_data, with accumulator rows grouped by trial and ordered as in the model. Response and component labels are factors with model-defined levels; attributes store the likelihood layout.

Examples

spec <- race_spec()
spec <- add_accumulator(spec, "A", "lognormal")
spec <- add_outcome(spec, "A_win", "A")
structure <- finalize_model(spec)
params_df <- build_param_matrix(
  structure,
  c(m = 0, s = 0.1),
  n_trials = 2
)
data_df <- simulate(structure, params_df, seed = 1)
prepare_data(structure, data_df)

Draw a processing tree for the responses in a model

Description

Show the observed responses, the accumulators or pools that feed them, and any blocking relationships as a directed graph.

Usage

processing_tree(model, outcome_label = NULL, return_dot = FALSE)

Arguments

Value

If DiagrammeR is available and return_dot = FALSE, a DiagrammeR graph. Otherwise, a list with dot, nodes, and edges.

Start a race-model specification

Description

Create an empty specification. Add accumulators and response rules, then call finalize_model() before simulation or likelihood evaluation.

Usage

race_spec(n_outcomes = 1L)

Arguments

Value

A race_spec object.

Examples

race_spec()

Evaluate marginal response probabilities

Description

Calculate the probability of each first response, integrated over response time and averaged over mixture components. With multiple trial blocks in parameters, return the mean probabilities across those blocks.

Usage

response_probabilities(context, parameters, include_na = TRUE)

Arguments

Value

A named numeric vector of marginal response probabilities. Names are observed outcome labels. When include_na = TRUE, a residual "NA" entry is included if the model assigns probability mass to unobserved or NA-mapped outcomes.

Examples

spec <- race_spec() |>
  add_accumulator("left", "lognormal") |>
  add_accumulator("right", "lognormal") |>
  add_outcome("left", "left") |>
  add_outcome("right", "right") |>
  set_parameters(separate = list(m = TRUE))

model <- finalize_model(spec)
params <- build_param_matrix(
  model,
  c(left.m = log(0.25), right.m = log(0.40), s = 0.20),
  n_trials = 1
)

response_probabilities(make_context(model), params)

Control how mixture components are combined

Description

Fixed mixtures use known component probabilities. Sampled mixtures expose automatic ⁠p.<component>⁠ parameters for every non-reference component; the reference component receives the residual probability. Both modes draw a component during simulation. In likelihood evaluation, a supplied component label conditions on that component; an absent or NA label averages over components using their probabilities.

Usage

set_mixture(
  spec,
  mode = c("fixed", "sample"),
  weights = NULL,
  reference = NULL
)

Arguments

Value

The updated race_spec.

Control parameter grouping and names

Description

Parameters are grouped by compatible type by default. For example, two lognormal accumulators expose one m, one s, and one t0 parameter unless you ask for specific parameters to be separate. Triggers expose their trigger name directly, and sampled mixtures expose automatic ⁠p.<component>⁠ parameters.

Usage

set_parameters(spec, separate = NULL, share = NULL, rename = NULL)

Arguments

Value

The updated race_spec.

Examples

spec <- race_spec() |>
  add_accumulator("go", "lognormal") |>
  add_accumulator("stop", "lognormal") |>
  add_outcome("go", "go") |>
  add_outcome("stop", "stop") |>
  set_parameters(
    separate = list(m = c("go", "stop")),
    rename = c(s = "spread", t0 = "nondecision")
  )

par_names(spec)

Simulate behavioral data from a model

Description

Generate one trial for each accumulator block in params_df, using the model's response rules, timing dependencies, triggers, and mixture weights.

Usage

simulate(
  structure,
  params_df,
  trial_df = NULL,
  seed = NULL,
  keep_detail = FALSE,
  keep_component = NULL
)

Arguments

Details

Use the same model to build params_df and simulate the data. Supply valid parameter values and keep the matrix and conditioning table in matching row order; simulation does not check their layout or domains.

Value

A data frame with one row per trial and columns trials, R, and rt. A trial with no observed response has R = NA and rt = NA. If n_outcomes > 1, additional ordered response pairs such as R2/rt2 are included; unobserved later ranks are NA.

See Also

prepare_data(), log_likelihood(), set_mixture()

Examples

spec <- race_spec()
spec <- add_accumulator(spec, "A", "lognormal")
spec <- add_outcome(spec, "A_win", "A")
structure <- finalize_model(spec)
params <- c(m = 0, s = 0.1)
df <- build_param_matrix(structure, params, n_trials = 3)
simulate(structure, df, seed = 123)