Performs parameter estimation on a single mb_model object using Stan or JAGS.
The model fitting method dispatched depends on the class of the mb_model object and the stan_engine
argument.
If the model is a JAGS model, rjags is used for MCMC sampling.
If the model is a Stan model, rstan or cmdstanr is used, depending on the value provided to stan_engine
:
"cmdstan-mcmc"
for MCMC sampling viacmdstanr::sample()
"cmdstan-optimize"
for optimization viacmdstanr::optimize()
"cmdstan-pathfinder"
for pathfinder estimation viacmdstanr::pathfinder()
"cmdstan-variational"
for variational ADVI estimation viacmdstanr::variational()
"cmdstan-laplace"
for Laplace approximation viacmdstanr::laplace()
Any other character value will default to MCMC sampling via
rstan::sampling()
Usage
# 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 to analyse.
- data
The data frame to analyse, or a list of data frames for multiple 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 specifying the Stan engine to use:
"rstan"
for MCMC sampling viarstan::sampling()
(default)."cmdstan-mcmc"
for MCMC sampling viacmdstanr::sample()
"cmdstan-pathfinder"
for pathfinder estimation viacmdstanr::pathfinder()
"cmdstan-optimize"
for optimization viacmdstanr::optimize()
"cmdstan-laplace"
for Laplace approximation viacmdstanr::laplace()
- 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.- ...
Additional arguments passed to the underlying estimation function (see above for details).
Value
If
data
is a data.frame: An mb_analysis objectIf
data
is a list of data.frames: An mb_meta_analysis object
Details
For CmdStan models, additional arguments can be passed to the engine-specific estimation functions via the ...
argument.
For example, additional options in cmdstanr::sample()
include:
adapt_delta
- Target acceptance rate (0 < adapt_delta < 1)max_treedepth
- Maximum tree depth for NUTS samplerstep_size
- Initial step size for samplerrefresh
- How often to print sampling progressoutput_dir
- Directory to save output files (default: NULL, uses temporary directory)
Some additional options in cmdstanr::pathfinder()
include:
num_paths
- Number of single-path Pathfinders to run (default: 4)history_size
- L-BFGS history size for approximating Hessian (default: 5)max_lbfgs_iters
- Maximum L-BFGS iterations per path (default: 1000)psis_resample
- Whether to use Pareto-smoothed importance sampling (default: TRUE)
Some additional options in cmdstanr::variational()
include:
algorithm
- Variational algorithm: "meanfield" (default) or "fullrank"
Some aditional options in cmdstanr::optimize()
include:
algorithm
- Optimization algorithm: "lbfgs" (default), "bfgs", or "newton"
Some additional options in cmdstanr::laplace()
include:
mode
- CmdStanMLE object from previous optimization (if NULL, runs optimize)jacobian
- Whether mode used Jacobian adjustment (default: TRUE)
Each analyse1
method checks for the presence of conflicting arguments and will ignore these (e.g., iter_sampling
with stan_engine = 'cmdstan-mcmc'
will be ignored in favour of iterations set via niters
)
One exception is for init
, which can be passed via '...' to override defaults or inits generated via gen_inits()
in model()
. Non-MCMC model fitting methods cannot use gen_inits()
.
Some arguments in analyse.mb_model()
are unused in non-MCMC methods (e.g., nthin
, niters_warmup
).
For pathfinder, variational, and laplace methods, niters
samples are drawn from the approximated posterior distributions.
See also
analyse.character()
for analysing a character model templateanalyse.mb_models()
for analysing multiple models
Examples
if (FALSE) { # \dontrun{
# Stan model with RStan (default)
analysis <- analyse(stan_model, data, nchains = 4, niters = 1000)
# Stan model with CmdStanR MCMC
analysis <- analyse(stan_model, data,
stan_engine = "cmdstan-mcmc",
nchains = 4, niters = 1000
)
# Stan model with CmdStanR Pathfinder
analysis <- analyse(stan_model, data,
stan_engine = "cmdstan-pathfinder",
niters = 500
)
# JAGS model
analysis <- analyse(jags_model, data, nchains = 4, niters = 2000)
# Passing engine-specific arguments
analysis <- analyse(stan_model, data,
stan_engine = "cmdstan-mcmc",
nchains = 4, niters = 2000,
adapt_delta = 0.99, # cmdstanr::sample argument
iter_warmup = 500L
) # cmdstanr::sample argument
analysis <- analyse(stan_model, data,
nchains = 4, niters = 2000,
control = list(adapt_delta = 0.95)
) # rstan::sampling argument
# Multiple datasets
data_list <- list(dataset1 = data1, dataset2 = data2)
analyses <- analyse(model, data_list, nchains = 3)
} # }