Run a full campaign across DGPs, estimators, and seeds — cs_run

This function preserves two public execution modes. With plan, it executes advanced planned batches. Without plan, it executes the requested DGP-estimator-seed Cartesian product directly. For ordinary new workflows, cs_run_single(), cs_run_seeds(), and cs_run_grid() are the narrower entry points; this function's two return contracts remain supported.

Usage

cs_run_campaign(
  plan = NULL,
  dgp_ids = NULL,
  estimator_ids = NULL,
  dgp_id = NULL,
  estimator_id = NULL,
  seeds = NULL,
  n = NULL,
  defaults = list(),
  overrides = list(),
  campaign_seed = NULL,
  version = NULL,
  status = "stable",
  tau = cs_tau_oracle,
  bootstrap = FALSE,
  B = 0L,
  skip_existing = FALSE,
  board = NULL,
  staging_dir = NULL,
  parallel = FALSE,
  experimental_parallel = FALSE,
  workers = parallel::detectCores() - 1L,
  show_progress = TRUE,
  force = FALSE,
  quiet = FALSE,
  max_runtime = Inf,
  ...
)

Arguments

plan: Optional plan tibble from cs_plan_campaign(). If supplied, cs_run_campaign() will execute the planned batches and ignore the grid-based arguments.
dgp_ids: Character vector of DGP IDs.
estimator_ids: Character vector of estimator IDs.
dgp_id: Deprecated alias for dgp_ids (scalar character).
estimator_id: Deprecated alias for estimator_ids (scalar character).
seeds: Integer vector of seeds.
n: Integer sample size per run.
defaults: Optional default estimator config list forwarded to cs_run_single() (e.g., list(n_boot = 200, num_threads = 1L)). Common fields include ci_method (see cs_ci_methods).
overrides: Optional named list of estimator-specific config overrides (e.g., list(tmle_att = list(ci_method = "native"))). Each override is merged over defaults using utils::modifyList().
campaign_seed: Optional scalar integer used to deterministically shuffle task execution order for better load balancing without relying on ambient RNG state. If NULL, tasks are executed in deterministic grid order.
version: Optional DGP version string forwarded to cs_get_dgp().
status: Optional DGP status filter forwarded to cs_get_dgp().
tau: Numeric vector of quantile levels forwarded to cs_run_single().
bootstrap: Logical; runner-level convenience flag forwarded to cs_run_single(). When TRUE and ci_method is missing in the resolved config, bootstrap CIs are requested and the per-task seed is injected (see cs_ci_methods).
B: Integer; convenience alias forwarded to cs_run_single() for setting config$n_boot when bootstrap=TRUE.
skip_existing: Logical; if TRUE, skip tasks already pinned on board.
board: Optional pins board for persistence.
staging_dir: Optional staging directory for crash recovery.
parallel: Logical; if TRUE, uses furrr/future for parallel execution.
experimental_parallel: Logical; must be TRUE to enable experimental parallel execution.
workers: Number of parallel workers for plan-based execution.
show_progress: Logical; show progressr-based progress.
force: Logical; if TRUE, recompute even when existing pins are found.
quiet: Logical; if TRUE, suppress DGP governance warnings in per-task runs. Defaults to FALSE so governance warnings remain loud.
max_runtime: Numeric scalar; maximum allowed runtime in seconds per task.
...: Additional arguments forwarded to cs_run_single() in direct grid mode. Plan mode ignores the grid-mode arguments.

Value

In direct grid mode, a tibble with one row per executed run. In plan mode, invisibly returns the batch IDs executed.

Examples

if (FALSE) { # \dontrun{
plan <- cs_plan_campaign(
  dgp_list = "synth_baseline",
  estimator_list = "lm_att",
  n_seeds = 1:4,
  batch_size = 2,
  campaign_seed = 123,
  strategy_map = list(defaults = list(n = 200))
)
cs_run_campaign(
  plan = plan,
  staging_dir = "staging_batches",
  workers = 2,
  experimental_parallel = TRUE
)
cs_consolidate(staging_dir = "staging_batches", board = pins::board_temp())
} # }