MCMCsuite-class: Class 'MCMCsuite'

In thirdwing/nimble: Flexible BUGS-compatible system for hierarchical statistical modeling and algorithm development

Description

Creates, runs, and compiles samples from a suite of MCMC algorithms, all applied to the same model, data, and initial values. This can include BUGS and JAGS MCMCs, as well as NIMBLE MCMC algorithms. Trace plots and density plots for the MCMC samples may also be plotted. See documentation for method initialize(), for details of creating and running an MCMC Suite. Upon executing the MCMC algorithms, an internal output variable is created, which may be accessed via suite$output. output is a named list containing three elements: output$samples is a 3-dimensional array containing all MCMC samples. output$summary is a 3-dimensional array containing all summary statistics. output$timing is a numeric vector containing timing information. See the NIMBLE User Manual for more information about these output list elements.

Methods

initialize(model, constants = list(), data = list(), inits = list(), monitors = character(), niter = 10000, burnin = 2000, thin = 1, summaryStats = c("mean", "median", "sd", "CI95_low", "CI95_upp"), MCMCs = c("bugs", "jags", "nimble", "nimble_RW", "nimble_slice"), MCMCdefs = list(), bugs_directory = "C:/WinBUGS14", bugs_program = "WinBUGS", makePlot = TRUE, savePlot = TRUE, plotName = "MCMCsuite", debug = FALSE, runNow = TRUE)

Creates and runs an MCMC Suite. By default, this will execute the specified MCMCs, record all samples, generate summary statistics, and create and save trace plots and posterior density plots. This default behavior can ben altered via a variety of input arguments. Following execution of the MCMC algorithms, the interal 'output' list is created, which contains named 'samples', 'summary', and 'timing' elements. See the NIMBLE User Manual for more information about these 'output' list objects.

Arguments:

model: The quoted code expression representing the model, such as the return value from a call to nimbleCode(...). No default value, this is a required argument.

constants: A named list giving values of constants for the model. This is the same as the 'constants' argument which would be passed to nimbleModel(...). Default value is list().

data: A named list giving the data values for the model. This is the same as the 'data' argument which would be passed to nimbleModel(...) or model$setData(...). Default value is list().

inits: A named list giving the initial values for the model. This is the same as the 'inits' argument which would be passed to nimbleModel(...) or model$setInits(...). Default value is list().

monitors: A character vector giving the node names or variable names to monitor. The samples corresponding to these nodes will be stored in the output samples, will have summary statistics calculated, and density and trace plots generated. Default value is all top-level stochastic nodes of the model.

niter: Number of MCMC iterations to run. This applies to all MCMC algorithms in the suite. Default value is 10,000.

burnin: Number of initial, post-thinning, MCMC iterations to discard. Default value is 2,000.

thin: Thinning interval for the MCMC samples. This applies to all MCMC algorithms in the suite. The thinning occurs prior to the burnin samples being discarded. Default value is 1.

summaryStats: A character vector, specifying the summary statistics to calculate on the MCMC samples. Each element may be the character name of an exisiting R function (possibly user-defined) which acts on a numeric vector and returns a scalar (e.g., 'mean' or 'sd'), or a character string which when parsed and evaluted will define such a function (e.g., 'function(x) mean(sqrt(x))'). Default value is c('mean', 'median', 'sd', 'CI95_low', 'CI95_upp'), where the final two elements are functions which calculate the limits of a 95 percent Bayesian credible interval.

MCMCs: A character vector specifying the MCMC algorithms to run. 'bugs' specifies a WinBUGS/BUGS MCMC, and 'jags' specifies a JAGS MCMC. All other entries will be interpreted as NIMBLE MCMC algorithms. All NIMBLE algorithms must have an associated entry in the MCMCdefs argument. The MCMCdefs provides, by default, definitions for 'nimble', 'nimble_RW', and 'nimble_slice'. Default value is c('bugs', 'jags', 'nimble', 'nimble_RW', 'nimble_slice').

MCMCdefs: A named list of MCMC definitions. The names of list elements should corespond to any custom MCMC algorithms specified in the 'MCMCs' argument. The list elements should be quoted expressions, enclosed in braces. When executed, the internal code must return an MCMC specification object, specifying the corresponding MCMC algorithm; in particular, setting the appropriate samplers. The code may assume existance of the R model object 'Rmodel', and must *return* the MCMC specification object. Therefore, the final line of such a code block would frequently be a standalong 'mcmcspec', to return this object.

bugs_directory: A character string giving the directory of the executable BUGS program for the WinBUGS/BUGS MCMC. This argument will be passed directly to the bugs(...) call, from the R2WinBUGS library. Default value is 'C:/WinBUGS14'.

bugs_program: A character string giving the name of the BUGS program, for the WinBUGS/BUGS MCMC. This argument will be passed directly to the bugs(...) call, from the R2WinBUGS library. Default value is 'WinBUGS'.

makePlot: Logical argument, specifying whether to generate the trace plots and posterior density plots, for each monitored node. Default value is TRUE.

savePlot: Logical argument, specifying whether to save the trace plots and density plots. Plots will be saved into the current working directory. Only used when makePlot == TRUE. Default value is TRUE.

plotName: Character string, giving the file name for saving the trace plots and density plots. Only used when makePlot == TRUE and savePlot == TRUE. Default value is 'MCMCsuite'.

debug: Logical argument, specifying whether to enter a broswer() at the onset of executing each MCMC algrithm. For use in debugging individual MCMC algorithms, if necessary. Default value is FALSE.

runNow: Logical argument, specifying whether to run the MCMC algorithms straight away. If FALSE, the MCMC algorithms may be executed by calling suiteObject$run(). Default value is TRUE.

Author(s)

Daniel Turek

Examples

code <- nimbleCode({
    mu ~ dnorm(0, 1)
    x ~ dnorm(mu, 1)
})
suite <- MCMCsuite(code,
                   data = list(x=3),
                   inits = list(mu=0),
                   niter = 10000,
                   thin = 10,
                   monitors = 'mu',
                   MCMCs = c('bugs', 'jags', 'nimble'),
                   summaryStats = c('mean', 'sd', 'max', 'function(x) max(abs(x))'),
                   plotName = 'example')

thirdwing/nimble documentation built on May 31, 2019, 10:41 a.m.