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. Excluded from the config fingerprint.

checkpoint_every

Positive integer. Save progress every N tasks. This also bounds the number of task results held in memory at once.

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. (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. (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. (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). (excluded from the config fingerprint – runtime policy.)

Value

An S7 SimulationConfig object.

See also

config_fingerprint() and vignette("reproducibility") for fingerprint inputs and limits on resume compatibility.

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"
)
} # }