Skip to contents

Run a fully customizable NIMBLE MCMC configuration in parallel (baseline / onlySlice / overrides)

Source: R/diagnostics.R
run_custom_mcmc_parallel.Rd

General-purpose parallel backend to run multiple independent NIMBLE MCMC chains while programmatically controlling the sampler configuration: a global "base policy" (e.g. baseline samplers or onlySlice=TRUE) plus optional targeted overrides on specific nodes or node families (e.g. force NUTS on beta, set RW_block on logq[1:5], etc.). This is designed for robust, model-agnostic experimentation in diagnostic-driven workflows.

Usage

run_custom_mcmc_parallel(
  build_fn,
  niter,
  nburnin = floor(0.25 * niter),
  thin = 1L,
  monitors = NULL,
  nchains = 1L,
  seed = 1L,
  n_cores = nchains,
  extra_export = character(0),
  parallel_backend = c("PSOCK", "FORK", "AUTO"),
  worker_log = TRUE,
  base_policy = c("baseline", "onlySlice", "none"),
  useConjugacy = FALSE,
  override_nodes = NULL,
  override_families = NULL,
  family_roots = NULL,
  ensure_unsampled = TRUE,
  allow_hmc = TRUE,
  mcmc_project = c("cmodel", "model"),
  buildDerivs = NULL
)

Arguments

build_fn

Function that builds one chain. Preferably supports build_fn(chain_id = 1L, export_global = FALSE) and returns at least model, and optionally cmodel and conf.

niter

Integer; total number of MCMC iterations.

nburnin

Integer; burn-in iterations to discard.

thin

Integer; thinning interval (keep 1 draw every thin iterations).

monitors

Character vector of monitor roots; passed to configuration (or added when possible).

nchains

Integer; number of independent chains.

seed

Integer; base RNG seed; chain i uses seed + i - 1.

n_cores

Integer; number of workers (default = nchains).

extra_export

Character vector of additional global object names to export to PSOCK workers.

parallel_backend

One of "PSOCK", "FORK", or "AUTO".

worker_log

Logical; if TRUE (PSOCK), writes worker output to a temporary log and appends tail on errors.

base_policy

One of "baseline", "onlySlice", "none".

useConjugacy

Logical; forwarded to nimble::configureMCMC when building a fresh config.

override_nodes

Optional list of override rules for explicit targets. Each element is a list with fields: target (character vector of node names), type (sampler type), optional control (list).

override_families

Optional list of override rules for families. Each element is a list with fields: family (root name), type, optional control.

family_roots

Optional named list mapping family root -> explicit node vector, used to override default family expansion.

ensure_unsampled

Logical; if TRUE, add slice to any remaining unsampled nodes after applying overrides.

allow_hmc

Logical; if TRUE, enables nimbleHMC integration when overrides request NUTS/HMC.

mcmc_project

One of "cmodel" or "model"; controls the project= argument used when compiling the MCMC. Use "model" to match some legacy patterns (e.g. GEREM historical scripts).

buildDerivs

Optional (reserved for future compatibility); currently ignored because the model is built in build_fn.

Value

A list with samples, runtime_s, conf, and conf_by_chain.

Details

Key features:

  • Base policy:

    "baseline"

    Use conf returned by build_fn (e.g. default RW/dirichlet/posterior_predictive).

    "onlySlice"

    Rebuild MCMC configuration with nimble::configureMCMC(..., onlySlice=TRUE).

    "none"

    Start from a configuration with all samplers removed, then add only what is requested via overrides (advanced).

  • Targeted overrides:

    override_nodes

    List of rules applied to explicit node targets.

    override_families

    List of rules applied to all stochastic nodes sharing the same root (family).

    Rules are lists with at least type and target (for nodes) or family (for families), and optional control. Supported sampler type values include "slice", "RW", "RW_block", "AF_slice", "NUTS", "NUTS_block" (the latter require nimbleHMC).

  • Unsampled-node safety: if ensure_unsampled=TRUE, any remaining unsampled stochastic nodes receive a slice sampler to avoid invalid configurations.

  • Parallel backends: "PSOCK" (portable) or "FORK" (Unix); "AUTO" selects "FORK" on Unix and "PSOCK" otherwise.

  • GEREM-style stability option: mcmc_project controls whether the compiled MCMC is built against the compiled model ("cmodel") or the uncompiled nimbleModel ("model"). Some legacy scripts and certain models may be more stable with mcmc_project="model".

Requirements / contract:

  • build_fn must return a list containing at least $model (a nimbleModel object).

  • For base_policy="baseline", build_fn must also provide $conf (a MCMCconf).

  • If $cmodel is not returned, it is compiled internally (per chain).

  • For true parallel execution, build_fn should accept chain_id (and optionally export_global) so each worker can build an independent chain with distinct initial values.

Returned object:

  • samples: an mcmc.list when possible (otherwise a list of per-chain samples)

  • runtime_s: the maximum wall time across chains for the runMCMC phase

  • conf: NULL in parallel mode (unambiguous); a single conf object in sequential mode

  • conf_by_chain: list of per-chain MCMCconf objects (also stored as an attribute)