R: Run one or more chains of an MCMC algorithm and return...

runMCMC {nimble} | 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)

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

### 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 single WAIC value is returned.

### Author(s)

Daniel Turek

### See Also

`configureMCMC` `buildMCMC` `nimbleMCMC`

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

[Package nimble version 0.9.1 Index]