build_abi_input: Build input for Amortized Bayesian Inference (ABI)

In eam: Evidence Accumulation Models

Build input for Amortized Bayesian Inference (ABI)

Description

Prepares simulation output for Amortized Bayesian Inference (ABI) analysis using the NeuralEstimators package. Extracts parameters and summary statistics from simulation results, splits data into training and validation sets, and formats them into matrices suitable for neural network training.

Usage

build_abi_input(
  simulation_output,
  theta,
  Z,
  train_ratio = 0.8,
  n_test = 100,
  rank_levels = NULL
)

Arguments

simulation_output	A eam_simulation_output object from run_simulation or load_simulation_output.
theta	Character vector of parameter names to extract from simulation_output. These parameters will be used as the target variables for inference.
Z	Character vector of summary statistic column names to extract from the simulation output dataset (e.g., "rt", "item_idx", "choice").
train_ratio	Numeric value between 0 and 1 specifying the proportion of non-test conditions to use for training, with the remainder used for validation (default: 0.8).
n_test	Integer specifying the number of conditions to use for testing (default: 10).
rank_levels	Numeric vector specifying which rank indices to include. If NULL (default), uses all ranks from 1 to n_items from simulation config.

Details

This function provides a streamlined workflow for preparing ABI inputs. It requires that simulation_output be created by run_simulation or load_simulation_output. The function automatically handles missing trials and ranks by filling with zeros to ensure complete data matrices.

The output format is optimized for the abi package's training functions, with parameters formatted as matrices (each column is a condition) and summary statistics formatted as lists of matrices (one per condition, with trials as columns).

Value

A list with components suitable for abi package training:

theta_train

Matrix of training parameters (parameters × conditions)

theta_val

Matrix of validation parameters (parameters × conditions)

theta_test

Matrix of test parameters (parameters × conditions)

Z_train

List of matrices, one per training condition (ranks*Z × trials)

Z_val

List of matrices, one per validation condition (ranks*Z × trials)

Z_test

List of matrices, one per test condition (ranks*Z × trials)

train_idx

Vector of condition indices used for training

val_idx

Vector of condition indices used for validation

test_idx

Vector of condition indices used for testing

train_ratio

The training ratio used (train / non-test conditions)

n_test

The number of test conditions used

rank_levels

The rank levels included in Z matrices

theta

Character vector of parameter names used

Z

Character vector of summary statistic names used

Examples

# Load the example dataset
rdm_minimal_example <- system.file("extdata", "rdm_minimal", package = "eam")
sim_output <- load_simulation_output(file.path(rdm_minimal_example, "simulation"))

# build the ABI input
abi_input <- build_abi_input(
  sim_output,
  c(
    "V_beta_1",
    "V_beta_group"
  ),
  c(
    "item_idx",
    "rt",
    "choice"
  )
)

# view the structure of the ABI input
str(abi_input)

## Not run: 
# Example of using the ABI input for training
# (requires NeuralEstimators package and build your estimator first, see our tutorials)
train(
  estimator,
  theta_train = abi_input$theta_train,
  theta_val = abi_input$theta_val,
  Z_train = abi_input$Z_train,
  Z_val = abi_input$Z_val,
  epochs = 500,
  stopping_epochs = 200
)

## End(Not run)

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