nimble (version 0.6-6)

runMCMC: Run one or more chains of an MCMC algorithm and extract samples

Description

Takes as input an MCMC algorithm (ideally a compiled one for speed) and runs the MCMC with one or more chains, automatically extracting the samples.

Usage

runMCMC(mcmc, niter = 10000, nburnin = 0, nchains = 1, inits,
  setSeed = FALSE, progressBar = TRUE, silent = FALSE,
  returnCodaMCMC = FALSE)

Arguments

mcmc

A NIMBLE MCMC algorithm. See details.

niter

Number of iterations to run each MCMC chain (default = 10000).

nburnin

Number of initial samples to discard from each MCMC chain (default = 0).

nchains

Number of MCMC chains to run (default = 1).

inits

Optional argument to specify initial values for each chain. See details.

setSeed

Logical argument. If TRUE, then R's random number seed is set to i (using set.seed(i)) at the onset of each MCMC chain number i (default = FALSE).

progressBar

Logical argument. If TRUE, an MCMC progress bar is displayed during execution of each MCMC chain (default = TRUE).

silent

Logical argument. If TRUE, then all output is suppressed during execution. This overrides the progressBar argument (default = FALSE).

returnCodaMCMC

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 (default = FALSE).

Value

When nchains = 1, a matrix of MCMC samples. When nchains > 1, a list of length nchains, where each list element is a matrix of MCMC samples. If returnCodaMCMC = TRUE, then a coda mcmc or mcmc.list object is returned instead.

Details

The mcmc argument can be a compiled or uncompiled NIMBLE MCMC algorithm, which is generated using buildMCMC. Using a compiled algorithm will give substantially faster execution.

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, (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 sampler assignments and thinning, must be specified in advance using the MCMC configuration object (created using configureMCMC), which is then used to build the MCMC algorithm (using buildMCMC) argument.

The niter argument specifies the number of pre-thinning MCMC iterations, and the nburnin argument will remove post-thinning samples.

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

See Also

configureMCMC buildMCMC

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)
# }
# NOT RUN {
# }