Skip to contents

Create a Simulation Configuration

Source: R/simulation-config.R
simulation_config.Rd

Creates a SimulationConfig S7 object that fully specifies a simulation study. This configuration defines the data generation grid, fitting grid, metrics, and execution parameters.

Usage

simulation_config(
  data_grid = NULL,
  fit_grid = NULL,
  task_grid = NULL,
  data_generator,
  fitter = NULL,
  metrics = NULL,
  n_replicates = 1L,
  seed,
  result_path = NULL,
  checkpoint_format = c("rds"),
  checkpoint_every = 50L,
  keep_checkpoints = 2L,
  retain = c("metrics", "diagnostics"),
  max_errors = Inf,
  daemon_setup = NULL,
  stop_on = NULL,
  summary_format = c("rds", "parquet")
)

Arguments

data_grid

A data.frame with data generation specifications. Each row represents a distinct data configuration to simulate.

fit_grid

A data.frame with model fitting specifications. Each row represents a distinct model configuration to fit.

task_grid

Optional pre-computed task grid. If provided, overrides data_grid and fit_grid. Must contain either data_spec/fit_spec list-columns or data_idx/fit_idx index columns.

data_generator

A function with signature (data_spec, task_ctx) -> data_bundle. Generates data for a single replicate given a data specification row. task_ctx$seed carries the per-task integer seed for backends that need one.

fitter

An S7 Fitter object that handles model fitting.

metrics

A list of Metric objects.

n_replicates

Positive integer. Number of replicates per data/fit combination.

seed

Integer. Base seed for reproducible random number generation.

result_path

NULL or character path. If provided, results are saved here.

checkpoint_format

Character scalar. Checkpoint storage format. Currently only "rds" is implemented for checkpoint persistence. (B4: excluded from the config fingerprint — it is runtime policy.)

checkpoint_every

Positive integer. Save progress every N tasks. This single knob also bounds the number of task results held in memory at once (B4: the former separate chunk_size knob was merged into this).

keep_checkpoints

Positive integer. Number of checkpoint commit directories to retain. Defaults to 2, preserving the newest commit plus one older fallback for corruption recovery. Pruning removes old commit directories only; the immutable outcome shards and ledger history are never pruned, so durable storage grows roughly linearly with completed tasks. Runtime policy; excluded from the config fingerprint.

retain

Character vector. What to retain in results. Must be subset of c("metrics", "diagnostics", "draws", "predictions", "fit", "data", "warnings"). A single profile name is also accepted: "minimal" (metrics only), "standard" (metrics, diagnostics, warnings), or "debug" (everything). Alternatively, a named list with success, warning, and error entries to retain more for tasks that warn or fail. "metrics" is always retained. (B4: excluded from the config fingerprint, but exclusion does not make every retention change legal on resume: a compatible resume may narrow retention, while widening is rejected once completed outcomes lack the requested artifacts — discarded artifacts cannot be recreated.)

max_errors

Numeric. Maximum errors before stopping. Use Inf for no limit. (B4: excluded from the config fingerprint.)

daemon_setup

Optional function run once per mirai daemon (via mirai::everywhere()) before tasks start, e.g. to configure cmdstan paths or load a model bank. Ignored when no daemons are set. Default NULL.

stop_on

Optional adaptive stopping policy (experimental). NULL (default) runs all tasks. Otherwise a list with elements: estimand (character parameter name), measure (one of "bias", "coverage", "emp_se", "mse", "model_se"), target_mcse (numeric > 0), min_reps (integer, default 50), check_every (integer, default 50). Once the MCSE of measure for estimand falls below target_mcse AND at least min_reps replicates have completed, remaining pending tasks are marked "skipped" and the run stops. (I3: excluded from the config fingerprint — it is runtime policy.)

summary_format

Character scalar. Output format for the final summary. "rds" (default) writes nothing extra – the durable run store (outcome shards plus ledger) carries the results and remains the resume artifact. "parquet" additionally writes <result_path>/summary.parquet using the suggested nanoparquet package, for downstream consumption (pandas, arrow, polars). (I8: excluded from the config fingerprint – runtime policy.)

Value

An S7 SimulationConfig object.

Examples

if (FALSE) { # \dontrun{
config <- simulation_config(
  data_grid = data.frame(n = c(100, 500), effect = c(0.5, 1.0)),
  fit_grid = data.frame(model = c("baseline", "full")),
  data_generator = my_data_gen,
  fitter = my_fitter,
  metrics = list(pred_rmse_metric(), pred_bias_metric()),
  n_replicates = 100L,
  seed = 42L,
  checkpoint_format = "rds"
)
} # }