Run a grid of MCMCs

Fits each grid cell by maximum likelihood, checks estimability, runs SparseNUTS::sample_snuts(), and saves each cell as a portable grid<N>.sbt.rds sbt_fit object. Fixed grid values are read from columns in grid; currently h, psi, m0, and m10 are recognised and mapped to their corresponding log-scale parameters.

Usage

run_grid_mcmc(
  data,
  parameters,
  grid,
  bounds,
  map = list(),
  random = c(),
  grid_dir = "grid_mcmc",
  file_prefix = "grid",
  control = list(eval.max = 10000L, iter.max = 10000L),
  n_passes = 3L,
  b0_start_step = 1.25,
  b0_start_max = 10,
  check = TRUE,
  stop_on_failure = TRUE,
  mcmc_args = list(),
  overwrite = FALSE,
  cells = NULL,
  resume = TRUE,
  run_metadata = list()
)

Arguments

data

A list containing the data created using get_data.

parameters

A list containing the base parameter inputs.

grid

A data.frame containing grid values. Recognised columns are h, psi, m0, and m10.

bounds

A data.frame or list with lower and upper elements defining parameter bounds, created using get_bounds.

map

A list defining fixed/mapped parameters passed to MakeADFun. Default is an empty list.

random

A character vector defining random effect parameters. Default is an empty vector.

grid_dir

Character directory for saved grid-cell files.

file_prefix

Character prefix for saved <prefix><N>.sbt.rds grid-cell files. Default is "grid".

control

A list of control parameters passed to nlminb.

n_passes

Integer maximum number of repeated nlminb passes per grid cell. Default is 3.

b0_start_step

Numeric multiplier applied to the par_log_B0 starting value when the initial objective is non-finite. Default is 1.25.

b0_start_max

Numeric maximum total B0 start multiplier. Default is 10.

check

Logical. If TRUE, run check_estimability() after optimisation and before MCMC. Default is TRUE.

stop_on_failure

Logical. If TRUE, stop before MCMC when the MLE does not converge or the estimability check fails. Default is TRUE.

mcmc_args

A named list of arguments passed to SparseNUTS::sample_snuts. obj, init, and globals are added when omitted.

overwrite

Logical. If TRUE, overwrite existing grid-cell files. Default is FALSE.

cells

Optional integer vector of original grid-cell row numbers to run. The default runs all cells and preserves their row numbers in file names and diagnostics.

resume

Logical. If TRUE (the default), a valid existing grid<N>.sbt.rds file is checked against the current model inputs, bounds, sampler-global implementations, recursive biological-state validator implementation, contract, retained-posterior payload checksum, and run settings, then skipped. Invalid or incompatible files cause an error unless overwrite = TRUE.

run_metadata

Optional named list of run provenance to save in every grid-cell file and include in the validated run signature. Aggregate sidecars expose all cell run signatures and only report uniform run metadata when every included cell matches the current invocation.

Value

A list with summary, checks, files, and run_metadata.

Details

Integer-like controls and all scientific settings should be validated by the calling workflow before launch. Each worker writes only its requested canonical cell files; aggregate sidecars are snapshots of the cells visible to that process and should be reconciled after all independent workers finish.

See also

Other grid workflows: grid_mcmc_to_tmbfit(), grid_to_tmbfit(), make_mle_grid_parameters(), run_grid(), sample_grid(), select_balanced_grid_iters(), summarise_mle_grid(), validate_mle_grid_state_records()

Examples

if (FALSE) { # \dontrun{
fit <- sbt_example_fit()
grid <- expand.grid(
  h = c(0.55, 0.63, 0.72, 0.80),
  psi = c(1.50, 1.75, 2.00),
  m0 = c(0.40, 0.45, 0.50),
  m10 = c(0.065, 0.085, 0.105)
)
grid$Cell <- seq_len(nrow(grid))
output_dir <- tempfile("sbt-grid-")
dir.create(output_dir)
result <- run_grid_mcmc(
  data = fit$data,
  parameters = fit$parameters,
  grid = grid,
  bounds = fit$bounds,
  map = fit$map,
  grid_dir = output_dir,
  cells = 1L,
  mcmc_args = list(
    num_samples = 500L,
    num_warmup = 1000L,
    chains = 4L,
    cores = 4L
  )
)
} # }