new_simulation_config: Create a new simulation configuration

In eam: Evidence Accumulation Models

Create a new simulation configuration

Description

This function creates a new eam simulation configuration object that contains all parameters needed to run a simulation.

Usage

new_simulation_config(
  prior_params = list(),
  prior_formulas = list(),
  between_trial_formulas = list(),
  item_formulas = list(),
  n_conditions_per_chunk = NULL,
  n_conditions,
  n_trials_per_condition,
  n_items,
  max_reached = n_items,
  max_t,
  dt = 0.001,
  noise_mechanism = "add",
  noise_factory = NULL,
  model = "ddm",
  parallel = FALSE,
  n_cores = NULL,
  rand_seed = NULL
)

Arguments

prior_params	A list or data frame of initial values for prior
prior_formulas	A list of formulas defining prior distributions for condition-level parameters
between_trial_formulas	A list of formulas defining between-trial parameters
item_formulas	A list of formulas defining item-level parameters
n_conditions_per_chunk	Number of conditions to process per chunk (optional, typically does not need to be set. It determine the storage and in-memory size of each chunk, if you find memory issues, try reducing this number)
n_conditions	Total number of conditions to simulate
n_trials_per_condition	Number of trials per condition
n_items	Number of items per trial
max_reached	Maximum number of items that can be recalled (default: n_items)
max_t	Maximum simulation time
dt	Time step size (default: 0.001)
noise_mechanism	Noise mechanism ("add", "mult_evidence", or "mult_t", default: "add")
noise_factory	Function that creates noise functions.
model	Model name or backend names (e.g., "ddm", "rdm", "lca")
parallel	Whether to run in parallel (default: FALSE)
n_cores	Number of cores for parallel processing (default: NULL, auto-detect)
rand_seed	Random seed for parallel processing (default: NULL)

Details

This function only creates the configuration object and does not run the simulation. To actually execute the simulation, you must pass the returned configuration object to run_simulation.

Supported Models:

This package supports three evidence accumulation models. The appropriate backend is automatically selected based on the model parameter and the parameters defined in your formulas.

DDM (Drift Diffusion Model)

Models evidence accumulation towards a single upper threshold. Items either reach the threshold and are recalled, or time out.

Required parameters (must appear in prior_formulas, between_trial_formulas, or item_formulas):

• A - Upper decision boundary/threshold

• V - Drift rate (evidence accumulation rate)

• Z - Starting point of evidence

• ndt - Non-decision time

Set model = "ddm"

RDM (Racing Diffusion Model)

Models multiple racing evidence accumulators, each with upper and lower thresholds for binary decisions (correct/incorrect).

Required parameters:

• A_upper - Upper decision boundary (correct response)

• A_lower - Lower decision boundary (incorrect response)

• V - Drift rate

• Z - Starting point of evidence

• ndt - Non-decision time

Set model = "rdm". Note: If you set model = "ddm" but define A_upper instead of A, the model will automatically switch to RDM.

LCA (Leaky Competing Accumulator)

Models competitive evidence accumulation with leakage and mutual inhibition between accumulators.

Required parameters:

• A - Decision threshold

• V - Input strength/drift rate

• Z - Starting point of evidence

• ndt - Non-decision time

• beta - Self-excitation/leak parameter

• k - Lateral inhibition strength

Set model = "lca"

LFM (Lévy Flight Model)

Uses the same parameters as DDM. See DDM above.

Set model = "lfm"

LBA (Linear Ballistic Accumulator)

Uses the same parameters as RDM. See RDM above.

Set model = "lba"

Note: All required parameters must be defined at least once across prior_params, prior_formulas, between_trial_formulas, and item_formulas.

Parameter Hierarchy and Formula Evaluation:

The simulation uses a hierarchical parameter system with sequential formula evaluation, allowing later formulas to reference earlier ones:

1. prior_params - Initial constant values available to all formulas

2. prior_formulas - Evaluated once per condition, can reference prior_params. Use for condition-level parameters that vary across conditions.

3. between_trial_formulas - Evaluated once per trial within each condition. Can reference both prior_params and variables from prior_formulas. Use for trial-level variability.

4. item_formulas - Evaluated once per item within each trial. Can reference all previous parameters. Use for item-specific parameters.

Using Distributions:

You can use the distributional package to define random parameters. For example:

• A ~ distributional::dist_uniform(0.5, 2.0) - Uniform distribution

• V_condition ~ distributional::dist_normal(1.0, 0.2) - Normal distribution

• sigma ~ 0.5 - Constant value

• V ~ distributional::dist_normal(V_condition, sigma) - Reference earlier parameters

Each formula is evaluated sequentially, so you can build complex parameter dependencies. For instance, you might define a base drift rate V in prior_formulas, then add trial-level noise in between_trial_formulas, and finally scale by item position in item_formulas.

Value

An S3 object of class eam_simulation_config containing validated simulation parameters. This object should be passed to run_simulation to execute the simulation.

Examples

# Define formulas for the simulation
prior_formulas <- list(
  V ~ distributional::dist_uniform(0.1, 1.0),
  ndt ~ 0.3,
  noise_coef ~ 1
)

between_trial_formulas <- list()

item_formulas <- list(
  A_upper ~ 1,
  A_lower ~ -1,
  V ~ V
)

# Define noise factory
noise_factory <- function(context) {
  noise_coef <- context$noise_coef
  function(n, dt) {
    noise_coef * rnorm(n, mean = 0, sd = sqrt(dt))
  }
}

# Create configuration
config <- new_simulation_config(
  prior_formulas = prior_formulas,
  between_trial_formulas = between_trial_formulas,
  item_formulas = item_formulas,
  n_conditions = 10,
  n_trials_per_condition = 10,
  n_items = 5,
  max_reached = 5,
  max_t = 10,
  dt = 0.01,
  noise_mechanism = "add",
  noise_factory = noise_factory,
  model = "ddm",
  parallel = FALSE
)

# print the config
config

# Run simulation
sim_output <- run_simulation(config)
sim_output

eam documentation built on March 29, 2026, 5:07 p.m.