Checkpoint Sampling: brms — chkpt

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

chkpt_brms(
  formula,
  data,
  iter_warmup = 1000,
  iter_sampling = 1000,
  iter_per_chkpt = 100,
  iter_typical = 150,
  parallel_chains = 2,
  threads_per = 1,
  chkpt_progress = TRUE,
  control = NULL,
  brmsfit = TRUE,
  seed = 1,
  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_warmup: (positive integer) The number of warmup iterations to run per chain (defaults to 1000).
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).
iter_typical: (positive integer) The number of iterations in the initial warmup, which finds the so-called typical set. This is an initial phase, and not included in iter_warmup. Note that a large enough value is required to ensure convergence (defaults to 150).
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.
brmsfit: Logical. Should a brmsfit object be returned (defaults to TRUE).
seed: (positive integer). The seed for random number generation to make results reproducible.
path: Character string. The path to the folder, that is used for saving the checkpoints.
...: Additional arguments based to make_stancode, including, for example, user-defined prior distributions and the brmsfamily (e.g., family = poisson()).

Value

An object of class brmsfit (with brmsfit = TRUE) or chkpt_brms (with brmsfit = FALSE)

Examples

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

# path for storing checkpoint info
path <- create_folder(folder_name  = "chkpt_folder_fit1")

# "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 = path)
                   
# brmsfit output
fit1

# path for storing checkpoint info
 path <- create_folder(folder_name  = "chkpt_folder_fit2")

# 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 = path)
                   
# brmsfit output
fit2

# compare models
loo(fit1, fit2)


# using custom priors
path <- create_folder(folder_name = "chkpt_folder_fit3")

# 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  = path,
    prior = bprior,
    iter_warmup = 1000,
    iter_sampling = 1000,
    iter_per_chkpt = 250, 
  )


# check priors
prior_summary(fit3)

}