compareMCMCs {compareMCMCs}

run a set of MCMCs for performance comparison

Description

run one or more MCMC engines for one model specification, with timing and performance metrics calculated.

Usage

compareMCMCs(
  modelInfo = list(),
  MCMCcontrol = list(niter = 10000, thin = 1, burnin = 2000),
  MCMCs = "nimble",
  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
)

Arguments

modelInfo

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..

MCMCcontrol

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).

MCMCs

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.

monitors

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).

nimbleMCMCdefs

A list of information for custom sampler configurations in nimble. See package vignette for details.

externalMCMCinfo

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.

metrics

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.

metricOptions

Optional named list of individual metric options passed as the third argument ("options") of addMetrics when MCMC metrics are calculated.

conversions

List of parameter conversion (transformation) specifications, useful when different MCMCs use different parameterizations.

seed

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.

needRmodel

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".

verbose

If TRUE, more verbose output may be generated.

sessionInfo

If TRUE, record the results of sessionInfo(), run before calling each MCMC, with each MCMC result.

Details

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.

See package vignette for more details and examples.

Value

A list of MCMCresult objects.