runMCMC: Run one or more chains of an MCMC algorithm and return...
In nimble: MCMC, Particle Filtering, and Programmable Hierarchical Modeling

runMCMC

R Documentation

Run one or more chains of an MCMC algorithm and return samples, summary and/or WAIC

Description

Takes as input an MCMC algorithm (ideally a compiled one for speed) and runs the MCMC with one or more chains, any returns any combination of posterior samples, posterior summary statistics, and a WAIC value.

Usage

runMCMC(
  mcmc,
  niter = 10000,
  nburnin = 0,
  thin,
  thin2,
  nchains = 1,
  inits,
  setSeed = FALSE,
  progressBar = getNimbleOption("MCMCprogressBar"),
  samples = TRUE,
  samplesAsCodaMCMC = FALSE,
  summary = FALSE,
  WAIC = FALSE,
  perChainWAIC = FALSE
)

Arguments

`mcmc`	A NIMBLE MCMC algorithm. See details.
`niter`	Number of iterations to run each MCMC chain. Default value is 10000.
`nburnin`	Number of initial, pre-thinning, MCMC iterations to discard. Default value is 0.
`thin`	Thinning interval for collecting MCMC samples, corresponding to `monitors`. Thinning occurs after the initial nburnin samples are discarded. Default value is 1.
`thin2`	Thinning interval for collecting MCMC samples, corresponding to the second, optional set of `monitors2`. Thinning occurs after the initial nburnin samples are discarded. Default value is 1.
`nchains`	Number of MCMC chains to run. Default value is 1.
`inits`	Optional argument to specify initial values for each chain. See details.
`setSeed`	Logical or numeric argument. If a single numeric value is provided, R's random number seed will be set to this value at the onset of each MCMC chain. If a numeric vector of length `nchains` is provided, then each element of this vector is provided as R's random number seed at the onset of the corresponding MCMC chain. Otherwise, in the case of a logical value, if `TRUE`, then R's random number seed for the ith chain is set to be `i`, at the onset of each MCMC chain. Note that specifying the argument `setSeed = 0` does not prevent setting the RNG seed, but rather sets the random number generation seed to `0` at the beginning of each MCMC chain. Default value is `FALSE`.
`progressBar`	Logical argument. If `TRUE`, an MCMC progress bar is displayed during execution of each MCMC chain. Default value is defined by the nimble package option MCMCprogressBar.
`samples`	Logical argument. If `TRUE`, then posterior samples are returned from each MCMC chain. These samples are optionally returned as `coda` `mcmc` objects, depending on the `samplesAsCodaMCMC` argument. Default value is `TRUE`. See details.
`samplesAsCodaMCMC`	Logical argument. If `TRUE`, then a `coda` `mcmc` object is returned instead of an R matrix of samples, or when `nchains > 1` a `coda` `mcmc.list` object is returned containing `nchains` `mcmc` objects. This argument is only used when `samples` is `TRUE`. Default value is `FALSE`. See details.
`summary`	Logical argument. When `TRUE`, summary statistics for the posterior samples of each parameter are also returned, for each MCMC chain. This may be returned in addition to the posterior samples themselves. Default value is `FALSE`. See details.
`WAIC`	Logical argument. When `TRUE`, the WAIC (Watanabe, 2010) of the model is calculated and returned. Note that in order for the WAIC to be calculated, the `mcmc` object must have also been created with the argument 'enableWAIC = TRUE'. If multiple chains are run, then a single WAIC value is calculated using the posterior samples from all chains. Default value is `FALSE`. See `help(waic)`.
`perChainWAIC`	Logical argument. When `TRUE` and multiple chains are run, the WAIC for each chain is returned as a means of helping assess the stability of the WAIC estimate. Default value is `FALSE`.

Details

At least one of samples, summary or WAIC must be TRUE, since otherwise, nothing will be returned. Any combination of these may be TRUE, including possibly all three, in which case posterior samples and summary statistics are returned for each MCMC chain, and an overall WAIC value is calculated and returned.

When samples = TRUE, the form of the posterior samples is determined by the samplesAsCodaMCMC argument, as either matrices of posterior samples, or coda mcmc and mcmc.list objects.

Posterior summary statistics are returned individually for each chain, and also as calculated from all chains combined (when nchains > 1).

If provided, the inits argument can be one of three things:

(1) a function to generate initial values, which will be executed to generate initial values at the beginning of each MCMC chain, or (2) a single named list of initial values which, will be used for each chain, or (3) a list of length nchains, each element being a named list of initial values which be used for one MCMC chain.

The inits argument may also be omitted, in which case the current values in the model object will be used as the initial values of the first chain, and subsequent chains will begin using starting values where the previous chain ended.

Other aspects of the MCMC algorithm, such as the specific sampler assignments, must be specified in advance using the MCMC configuration object (created using configureMCMC), which is then used to build an MCMC algorithm (using buildMCMC) argument.

The niter argument specifies the number of pre-thinning MCMC iterations, and the nburnin argument specifies the number of pre-thinning MCMC samples to discard. After discarding these burn-in samples, thinning of the remaining samples will take place. The total number of posterior samples returned will be floor((niter-nburnin)/thin).

The MCMC option mcmc$run(..., reset = FALSE), used to continue execution of an MCMC chain, is not available through runMCMC().

Value

A list is returned with named elements depending on the arguments passed to nimbleMCMC, unless this list contains only a single element, in which case only that element is returned. These elements may include samples, summary, and WAIC, and when the MCMC is monitoring a second set of nodes using monitors2, also samples2. When nchains = 1, posterior samples are returned as a single matrix, and summary statistics as a single matrix. When nchains > 1, posterior samples are returned as a list of matrices, one matrix for each chain, and summary statistics are returned as a list containing nchains+1 matrices: one matrix corresponding to each chain, and the final element providing a summary of all chains, combined. If samplesAsCodaMCMC is TRUE, then posterior samples are provided as coda mcmc and mcmc.list objects. When WAIC is TRUE, a WAIC summary object is returned.

Author(s)

Daniel Turek

Examples

## Not run: 
code <- nimbleCode({
    mu ~ dnorm(0, sd = 1000)
    sigma ~ dunif(0, 1000)
    for(i in 1:10) {
        x[i] ~ dnorm(mu, sd = sigma)
    }
})
Rmodel <- nimbleModel(code)
Rmodel$setData(list(x = c(2, 5, 3, 4, 1, 0, 1, 3, 5, 3)))
Rmcmc <- buildMCMC(Rmodel)
Cmodel <- compileNimble(Rmodel)
Cmcmc <- compileNimble(Rmcmc, project = Rmodel)
inits <- function() list(mu = rnorm(1,0,1), sigma = runif(1,0,10))
samplesList <- runMCMC(Cmcmc, niter = 10000, nchains = 3, inits = inits)

## End(Not run)

nimble documentation built on July 9, 2023, 5:24 p.m.