Skip to contents

Family-based sampler strategy: full HMC if allowed, else surgical on bottlenecks

Source: R/diagnostics.R
test_strategy_family.Rd

If the model is differentiable and try_hmc = TRUE, this runs a full HMC/NUTS configuration (via configure_hmc_safely()), executes the baseline, prints/plots diagnostics, and returns. Otherwise it switches to a surgical strategy: it ranks families by median efficiency, extracts stochastic bottleneck nodes, and iteratively applies samplers on 1 or more nodes (nbot) in the order:

  • scalar: NUTS -> slice -> RW

  • block (when nbot >= 2): NUTS_block -> AF_slice -> RW_block

After each assignment, a short MCMC is run, a side-by-side comparison versus the baseline is printed (runtime, AE = ESS/iter, CE = ESS/s, Rhat), clean plots are saved (Rhat bars + trace plots for the touched nodes), and the user is prompted to continue unless ask = FALSE.

Usage

test_strategy_family(
  build_fn,
  monitors = NULL,
  try_hmc = TRUE,
  nchains = 3L,
  pilot_niter = 10000L,
  pilot_burnin = 3000L,
  thin = 2L,
  out_dir = "outputs/diagnostics_family",
  nbot = 1L,
  strict_scalar_seq = c("NUTS", "slice", "RW"),
  strict_block_seq = c("NUTS_block", "AF_slice", "RW_block"),
  force_families = NULL,
  force_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; returns list(model, cmodel?, monitors?) used by the runners.

monitors

Character or NULL; root names to monitor (NULL = auto).

try_hmc

Logical; if TRUE and structure allows, run full HMC path.

nchains

Integer; number of chains.

pilot_niter

Integer; iterations for pilot runs.

pilot_burnin

Integer; burn-in for pilot runs.

thin

Integer; thinning factor.

out_dir

Character; output directory for diagnostics/plots.

nbot

Integer (\(\ge\) 1); number of bottleneck nodes to act on simultaneously.

strict_scalar_seq

Character; sampler order for scalar mode.

strict_block_seq

Character; sampler order for block mode (nbot >= 2).

force_families

Character or NULL; families to force.

force_nodes

List or NULL; per-family forced node vectors.

force_union

Character or NULL; families to union for block stage.

ask

Logical; interactive confirmation after each step.

ask_before_hmc

Logical; ask before attempting full-model HMC.

block_max

Integer; maximum block size.

slice_control, rw_control, rwblock_control, af_slice_control

Lists; sampler controls.

slice_max_contractions

Integer; informational safety for AF_slice.

Value

A list describing baseline, steps, configurations, diagnostics, and plot paths.