Checkpoint Sampling: brms — chkpt

Fit Bayesian generalized (non-)linear multivariate multilevel models using brms with checkpointing.

chkpt_brms(
  formula,
  data,
  iter_adaptation = 150,
  iter_warmup = 1000,
  iter_sampling = 1000,
  iter_per_chkpt = 100,
  parallel_chains = 4,
  threads_per = 1,
  chkpt_progress = TRUE,
  control = NULL,
  seed = 1,
  stop_after = NULL,
  reset = FALSE,
  path,
  ...
)

Arguments

formula: An object of class formula, brmsformula, or brms{mvbrmsformula}. Further information can be found in brmsformula.
data: An object of class data.frame (or one that can be coerced to that class) containing data of all variables used in the model.
iter_adaptation: (positive integer) The number of iterations in the initial warmup, which are used for the adaptation of the step size and inverse mass matrix. This is equivalent to the traditional warmup stage. Checkpointing will begin only after this stage is complete.
iter_warmup: (positive integer) The number of warmup iterations to run per chain after the adaptation stage (defaults to 1000). During this stage the step size and inverse mass matrix are fixed to the values found during the adaptation stage. There is no further adaptation performed.
iter_sampling: (positive integer) The number of post-warmup iterations to run per chain (defaults to 1000).
iter_per_chkpt: (positive integer). The number of iterations per checkpoint. Note that iter_sampling is divided by iter_per_chkpt to determine the number of checkpoints. This must result in an integer (if not, there will be an error).
parallel_chains: (positive integer) The maximum number of MCMC chains to run in parallel. If parallel_chains is not specified then the default is to look for the option mc.cores, which can be set for an entire R session by options(mc.cores=value). If the mc.cores option has not been set then the default is 1.
threads_per: (positive integer) Number of threads to use in within-chain parallelization (defaults to 1).
chkpt_progress: logical. Should the chkptstanr progress be printed (defaults to TRUE) ? If set to FALSE, the standard cmdstanr progress bar is printed for each checkpoint (which does not actually keep track of checkpointing progress)
control: A named list of parameters to control the sampler's behavior. It defaults to NULL so all the default values are used. For a comprehensive overview see stan.
seed: (positive integer). The seed for random number generation to make results reproducible.
stop_after: (positive integer). The number of iterations to sample before stopping. If NULL, then all iterations are sampled (defaults to NULL). Note that sampling will stop at the end of the first checkpoint which has an iteration number greater than or equal to stop_after.
reset: logical. Should the checkpointing be reset? If TRUE, then the model will begin sampling from the beginning (defaults to FALSE). WARNING: This will remove all previous checkpointing information (see reset_checkpoints()). If the model is unchanged and previously compiled, sampling will begin without recompiling the model.
path: Character string. The path to the folder, that is used for saving the checkpoints (see Details). You can provide either a relative path to the current working directory or a full path. You no longer need to create the folder, as this is done automatically.
...: Any additional arguments passed to brm, including, but not limited to, user-defined prior distributions, the brmsfamily (e.g., family = poisson()), data2, custom_families, etc.

Value

An object of class brmsfit

Note

A folder specified by path is created with four subfolders:

cmd_output: The cmdstanr output_files (one for each checkpoint and chain).
cp_info: Mass matrix, step size, and initial values for next checkpoint (last iteration from previous checkpoint).
cp_samples: Samples from the posterior distribution (post warmup)
stan_model: Complied Stan model

Examples

if (FALSE) {
library(brms)
library(cmdstanr)


# "random" intercept
fit1 <- chkpt_brms(
  bf(
    formula = count ~ zAge + zBase * Trt + (1 | patient),
    family = poisson()
  ),
  data = epilepsy, ,
  iter_warmup = 1000,
  iter_sampling = 1000,
  iter_per_chkpt = 250,
  path = "chkpt_folder_fit1"
)

# brmsfit output
fit1


# remove "random" intercept (for model comparison)
fit2 <- chkpt_brms(
  bf(
    formula = count ~ zAge + zBase * Trt,
    family = poisson()
  ),
  data = epilepsy, ,
  iter_warmup = 1000,
  iter_sampling = 1000,
  iter_per_chkpt = 250,
  path = "chkpt_folder_fit2"
)

# brmsfit output
fit2

# compare models
loo(fit1, fit2)


# priors
bprior <- prior(constant(1), class = "b") +
  prior(constant(2), class = "b", coef = "zBase") +
  prior(constant(0.5), class = "sd")

# fit model
fit3 <-
  chkpt_brms(
    bf(
      formula = count ~ zAge + zBase + (1 | patient),
      family = poisson()
    ),
    data = epilepsy,
    path = "chkpt_folder_fit3",
    prior = bprior,
    iter_warmup = 1000,
    iter_sampling = 1000,
    iter_per_chkpt = 250,
  )

# check priors
prior_summary(fit3)
}