Run one or more MCMC engines for one model specification, with timing and performance metrics calculated. See details for special case of precompiled nimble MCMCs.
compareMCMCs(
modelInfo = list(),
MCMCcontrol = list(niter = 10000, thin = 1, burnin = 2000),
MCMCs = names(nimbleMCMCdefs),
monitors = character(),
nimbleMCMCdefs = list(),
externalMCMCinfo = list(),
metrics = c("mean", "median", "sd", "CI95_low", "CI95_upp", "efficiency_coda"),
metricOptions = list(),
conversions = list(),
seed = NULL,
needRmodel,
verbose = TRUE,
sessionInfo = TRUE
)A list of MCMCresult objects.
A list of nimble model-specification information (which may
be relevant for JAGS, WinBUGS and/or OpenBUGS as well) and/or a nimble
model itself. To provide information for a different MCMC engine, see
argument externalMCMCinfo. Named elements in modelInfo can
include code (model code as returned from nimbleCode), data (a list
with data), constants (a list with data and/or constants), inits (a
list of initial values), and/or model (an object returned from
nimbleModel). If model is not provided, and if an R model will be
needed, then nimbleModel will be called to create one using code,
data, and/or inits. See nimbleModel in package nimble for for
information on these arguments. For JAGS, WinBUGS and OpenBUGS, many models
can be run from the same specification since they use nearly the same model
language. If model is provided, the other elements will not be needed if
only nimble MCMCs are used but will be needed if JAGS, WinBUGS or OpenBUGS
will be used. (Note: There is currently no built-in support for WinBUGS or
OpenBUGS. They are mentioned here in case one makes a plug-in to use them.)
If model is a compiled nimble model, then other list elements will be
ignored and the only MCMCs that can be run are compiled nimble MCMCs
provided in nimbleMCMCdefs.
A list with fields niter (number of
iterations), thin (thinning interval), and burnin (number
of iterations to discard from the beginning of the MCMC
sample).
A character vector of MCMC cases to run. This can include
"nimble" (default nimble samplers), "jags", "stan", one of several nimble
special cases (see details below), custom nimble sampler configurations
provided via argument nimbleMCMCdefs, and external MCMC engines
registered via registerMCMCengine. See builtin_MCMCs
for information on "jags" and "stan". Support for OpenBUGS and WinBUGS is
pending. Default is names(nimbleMCMCdefs), so that all provided nimble
cases will be run. (If a compiled nimble model is provided in
modelInfo$model, then MCMCs can include only names of
nimbleMCMCdefs.)
A character vector of variable names to monitor (record in MCMC output). If missing, this will be determined from the nimble model as all top-level parameter names (e.g. hyper-parameters).
A list of information for custom sampler configurations
in nimble. See package vignette for details. If a compiled nimble model
is provided in modelInfo$model, then nimbleMCMCdefs must be a named
list of compiled nimble MCMCs.
A list of arbitrary information for
external MCMC engines, named by engine names. If there is an
external MCMC engine named "myMCMC", then a list element myMCMC
of externalMCMCinfo will be passed to the engine as its
MCMCinfo argument.
Either a character vector of registered metric names
to apply to each sample, or a list of elements with either
metric names or metric functions to apply to each sample. See
addMetrics for more information. A useful set of
default metrics is provided.
Optional named list of individual metric
options passed as the third argument ("options") of
addMetrics when MCMC metrics are calculated.
List of parameter conversion (transformation) specifications, useful when different MCMCs use different parameterizations.
An (arbitrary) numeric value passed to set.seed to
set the random-number generator seed before calling each MCMC
engine. If NULL, no seed is set. To obtain identical results
from one call of compareMCMCs to the next, use identical seed
values.
If TRUE, a nimble model object should definitely be created
(if necessary, or obtained from modelInfo$model if provided) and
used, for example to determine variable names. If missing, needRmodel
will be set
TRUE if MCMCs includes "nimble", "jags", "openbugs", or
"winbugs".
If TRUE, more verbose output may be generated.
If TRUE, record the results of
sessionInfo(), run before calling each MCMC, with each MCMC
result.
The special cases provided for the MCMCs argument
include:
"nimble_noConj": use adaptive random-walk Metropolis-Hastings (ARWMH) samplers in place of Gibbs (conjugate) samplers.
"nimble_RW": use all adaptive random-walk Metropolis-Hastings samplers.
"nimble_slice": use all slice samplers.
If you have already used compileNimble to compile both a nimble model and
one or more nimble MCMCs, provide the compiled model as modelInfo$model and
provide the compiled MCMCs as elements of a named list for nimbleMCMCdefs.
In that case, the monitors will already be set in the MCMCs and can't be
changed. However, you can still use the monitors argument to subset and/or
re-order the monitored nodes (parameters).
See package vignette for more details and examples.