Analyse Models

Fit a Bayesian hierarchical model to data using Stan (via rstan or cmdstanr) or JAGS (via rjags). The estimation backend is determined by the model class (JAGS or Stan) and, for Stan models, by the stan_engine argument.

Usage

analyse(x, ...)

# S3 method for class 'mb_model'
analyse(
  x,
  data,
  nchains = getOption("mb.nchains", 3L),
  niters = getOption("mb.niters", 1000L),
  nthin = getOption("mb.thin", NULL),
  parallel = getOption("mb.parallel", FALSE),
  quiet = getOption("mb.quiet", TRUE),
  glance = getOption("mb.glance", TRUE),
  beep = getOption("mb.beep", TRUE),
  seed = sample.int(.Machine$integer.max, 1),
  stan_engine = getOption("mb.stan_engine", character(0)),
  niters_warmup = niters,
  ...
)

Arguments

x

An mb_model object.

...

Additional arguments passed to the underlying estimation function.

data

A data frame, or a named list of data frames for meta-analysis across datasets.

nchains

A count of the number of chains (default: 3).

niters

A count of the number of iterations to save per chain (default: 1000).

nthin

A count of the thinning interval.

parallel

A flag indicating whether to perform the analysis in parallel if possible.

quiet

A flag indicating whether to disable messages and warnings, including sampling progress.

glance

A flag indicating whether to print a model summary.

beep

A flag indicating whether to beep on completion of the analysis.

seed

A positive whole number specifying the seed to use. The default is random. This is currently only implemented for Stan models.

stan_engine

A string selecting the Stan engine:

• "cmdstan-mcmc": MCMC via cmdstanr::sample().

• "cmdstan-pathfinder": pathfinder via cmdstanr::pathfinder().

• "cmdstan-variational": variational ADVI via cmdstanr::variational().

• "cmdstan-optimize": optimization via cmdstanr::optimize().

• "cmdstan-laplace": Laplace approximation via cmdstanr::laplace().

Defaults to character(0). Any value other than the five above (including the empty default) falls back to MCMC via rstan::sampling(). Ignored for JAGS models, which always use rjags.

niters_warmup

A count of the number of warmup iterations. The default is to use the same number of iterations as niters. This is currently only implemented for Stan models.

Value

An mb_analysis if data is a single data frame, or an mb_meta_analysis if data is a named list of data frames.

Details

For Stan models using a cmdstan-* engine, embr sets a fixed set of cmdstanr arguments from its own parameters (listed in each engine section). These cannot be overridden via ... and are dropped with a warning if passed. Other cmdstanr arguments pass through ....

init is the sole exception: it can be overridden via ..., replacing inits generated by gen_inits() in model(). Non-MCMC engines do not use gen_inits().

nthin and niters_warmup are ignored by non-MCMC engines. For pathfinder, variational, and laplace, niters sets the number of draws from the approximated posterior.

cmdstan-mcmc

Calls cmdstanr::sample().

embr-controlled: chains, parallel_chains, iter_warmup, iter_sampling, thin, data, seed, init, show_messages, show_exceptions.

Common pass-throughs: adapt_delta, max_treedepth, step_size, refresh, output_dir, save_warmup.

cmdstan-pathfinder

Calls cmdstanr::pathfinder().

embr-controlled: data, seed, init, draws (from niters), show_messages, show_exceptions.

Common pass-throughs: num_paths, history_size, max_lbfgs_iters, psis_resample, tol_rel_grad.

cmdstan-variational

Calls cmdstanr::variational().

embr-controlled: data, seed, init, draws (from niters), show_messages, show_exceptions.

Common pass-throughs: algorithm ("meanfield" or "fullrank"), iter, tol_rel_obj, eval_elbo, eta.

cmdstan-optimize

Calls cmdstanr::optimize().

embr-controlled: data, seed, init, show_messages, show_exceptions.

Common pass-throughs: algorithm ("lbfgs", "bfgs", or "newton"), iter, tol_obj, history_size, jacobian.

cmdstan-laplace

Calls cmdstanr::laplace().

embr-controlled: data, seed, init, mode, draws (from niters), show_messages, show_exceptions.

Common pass-throughs: jacobian, opt_args.

rstan

For Stan models without a stan_engine matching one of the cmdstan options above, rstan::sampling() is called. Pass its arguments through ...; for example, control = list(adapt_delta = 0.95).

See also

• The analyse article for a walkthrough of the fitting workflow.

• model() to build a model.

• set_analysis_mode() to set session-wide sampling defaults.

• analyse.mb_models() to fit a list of models simultaneously.

• analyse.character() to fit from raw model code.

• predict.mb_analysis() and coef.mb_analysis() to summarise an analysis.

• reanalyse() to refit with different sampling settings.

Examples

if (FALSE) { # \dontrun{
# Stan model with cmdstanr MCMC
analysis <- analyse(stan_model, data,
  stan_engine = "cmdstan-mcmc",
  nchains = 4, niters = 1000
)

# JAGS model
analysis <- analyse(jags_model, data, nchains = 4, niters = 2000)

# Engine-specific argument via ...
analysis <- analyse(stan_model, data,
  stan_engine = "cmdstan-mcmc",
  adapt_delta = 0.99
)

# Override initial values for cmdstanr MCMC
init_fun <- function() list(bIntercept = 0)
analysis <- analyse(stan_model, data,
  stan_engine = "cmdstan-mcmc",
  init = init_fun
)

# Multiple datasets
analyses <- analyse(model, list(dataset1 = data1, dataset2 = data2))
} # }