Test and compare MCMC strategies on selected bottleneck nodes

Runs a small, reproducible workflow to:

build and run a baseline MCMC configuration,
optionally try full-model HMC/NUTS (if nimbleHMC is available and the model supports derivatives),
then apply alternative samplers in a strict, user-defined order on one or two bottleneck targets (singleton and then optional block on the union).

Usage

test_strategy(
  build_fn,
  monitors = NULL,
  try_hmc = TRUE,
  nchains = 3L,
  pilot_niter = 20000,
  pilot_burnin = 5000,
  thin = 1L,
  out_dir = "outputs/diagnostics",
  nbot = 1L,
  strict_scalar_seq = c("NUTS", "slice", "RW"),
  strict_block_seq = c("NUTS_block", "AF_slice", "RW_block"),
  force_singletons = NULL,
  force_union_nodes = NULL,
  force_union = NULL,
  ask = TRUE,
  ask_before_hmc = TRUE,
  block_max = 20L,
  slice_control = list(),
  rw_control = list(),
  rwblock_control = list(adaptScaleOnly = TRUE),
  af_slice_control = list(),
  slice_max_contractions = 5000L
)

Arguments

build_fn: Function (or prebuilt list with $model, $conf) that returns a fresh build object used by samplers in this package.
monitors: Optional character vector of monitors passed to the build.
try_hmc: Logical. If TRUE, try a full-model HMC/NUTS run first (ignored by the “surgical” singleton/block steps).
nchains: Integer number of MCMC chains for each run.
pilot_niter: Integer total iterations used in baseline and tests.
pilot_burnin: Integer burn-in iterations.
thin: Integer thinning interval.
out_dir: Directory where outputs (plots, etc.) will be written.
nbot: Integer. Number of bottleneck targets to operate on (1 or 2 typical; if >= 2, a block step on the union is attempted).
strict_scalar_seq: Character vector of scalar samplers to try in order. Supported values include "NUTS", "slice", "RW".
strict_block_seq: Character vector of block samplers to try in order. Supported values include "NUTS_block", "AF_slice", "RW_block".
force_singletons: Optional character vector of node names to force as singleton targets (first nbot valid nodes are used).
force_union_nodes: Optional character vector of node names to define the union for the block phase (must contain >= 2 valid nodes).
force_union: Deprecated alias of force_union_nodes.
ask: Logical. If TRUE, ask before moving to the next step.
ask_before_hmc: Logical. If TRUE, ask before running full HMC.
block_max: Integer cap on the size of the block union.
slice_control: List of controls passed to "slice" samplers.
rw_control: List of controls passed to "RW" samplers.
rwblock_control: List of controls passed to "RW_block" samplers.
af_slice_control: List of controls passed to "AF_slice" samplers.
slice_max_contractions: Integer safety cap for slice contractions.

Value

A list with elements such as:

status: Character status string.
mode: Character mode (e.g. "HMC_full", "surgical_*").
baseline: Baseline run info (runtime, samples, diagnostics).
targets: Chosen target node names.
steps: List of steps; each contains nodes, sampler, results, and directory.

Details

Results and diagnostic plots (R-hat bars and trace/density) are written under out_dir. When ask = TRUE, interactive yes/no prompts allow you to stop early at each step.

The procedure:

Build and run a baseline MCMC using run_baseline_config().
Optionally run full-model HMC/NUTS via configure_hmc_safely().
Select nbot bottleneck node(s) from diagnostics (or from force_singletons), then:
- apply strict_scalar_seq in order on the first node;
- if nbot >= 2, build the union {node1, node2} (or force_union_nodes) and apply strict_block_seq.
For each step, compile, run, compute diagnostics, and save plots.

Side effects

Creates subfolders and PNG files (R-hat bars, traces/densities) under out_dir. May load/unload compiled DLLs while switching samplers.

Examples

if (FALSE) { # \dontrun{
res <- test_strategy(
  build_fn = my_build_fn,
  monitors = c("theta","beta"),
  try_hmc  = TRUE,
  nbot     = 2,
  out_dir  = "outputs/diagnostics"
)
} # }