R: Create an MCMC function from a NIMBLE model, or an MCMC...

buildMCMC {nimble} | R Documentation

## Create an MCMC function from a NIMBLE model, or an MCMC configuration object

### Description

First required argument, which may be of class `MCMCconf` (an MCMC configuration object), or inherit from class `modelBaseClass` (a NIMBLE model object). Returns an uncompiled executable MCMC function. See details.

### Usage

    buildMCMC(conf, ...)

### Arguments

`conf` | An MCMC configuration object of class `MCMCconf` that specifies the model, samplers, monitors, and thinning intervals for the resulting MCMC function. See `configureMCMC` for details of creating MCMC configuration objects. Alternatively, `conf` may a NIMBLE model object, in which case an MCMC function corresponding to the default MCMC configuration for this model is returned.
`...` | Additional arguments to be passed to `configureMCMC` if `conf` is a NIMBLE model object

### Details

Calling buildMCMC(conf) will produce an uncompiled MCMC function object. The uncompiled MCMC function will have arguments:

`niter`: The number of iterations to run the MCMC.

`thin`: The thinning interval for the `monitors` that were specified in the MCMC configuration. If this argument is provided at MCMC runtime, it will take precedence over the `thin` interval that was specified in the MCMC configuration. If omitted, the `thin` interval from the MCMC configuration will be used.

`thin2`: The thinning interval for the second set of monitors (`monitors2`) that were specified in the MCMC configuration. If this argument is provided at MCMC runtime, it will take precedence over the `thin2` interval that was specified in the MCMC configuration. If omitted, the `thin2` interval from the MCMC configuration will be used.

`reset`: Boolean specifying whether to reset the internal MCMC sampling algorithms to their initial state (in terms of self-adapting tuning parameters), and begin recording posterior sample chains anew. Specifying `reset = FALSE` allows the MCMC algorithm to continue running from where it left off, appending additional posterior samples to the already existing sample chains. Generally, `reset = FALSE` should only be used when the MCMC has already been run (default = TRUE).

`nburnin`: Number of initial, pre-thinning, MCMC iterations to discard (default = 0).

`time`: Boolean specifying whether to record runtimes of the individual internal MCMC samplers. When `time = TRUE`, a vector of runtimes (measured in seconds) can be extracted from the MCMC using the method `mcmc$getTimes()` (default = FALSE).

`progressBar`: Boolean specifying whether to display a progress bar during MCMC execution (default = TRUE). The progress bar can be permanently disabled by setting the system option `nimbleOptions(MCMCprogressBar = FALSE)`.

Samples corresponding to the `monitors` and `monitors2` from the MCMCconf are stored into the interval variables `mvSamples` and `mvSamples2`, respectively. These may be accessed and converted into R matrix objects via: `as.matrix(mcmc$mvSamples)` `as.matrix(mcmc$mvSamples2)`

The uncompiled MCMC function may be compiled to a compiled MCMC object, taking care to compile in the same project as the R model object, using: `Cmcmc <- compileNimble(Rmcmc, project = Rmodel)`

The compiled function will function identically to the uncompiled object, except acting on the compiled model object.

### Calculating WAIC

After the MCMC has been run, calling the `calculateWAIC()` method of the MCMC object will return the WAIC for the model, calculated using the posterior samples from the MCMC run.

`calculateWAIC()` accepts a single arugment:

`nburnin`: The number of pre-thinning MCMC samples to remove from the beginning of the posterior samples for WAIC calculation (default = 0). These samples are discarded in addition to any burn-in specified when running the MCMC.

The `calculateWAIC` method can only be used if the `enableWAIC` argument to `configureMCMC` or to `buildMCMC` is set to `TRUE`, or if the NIMBLE option `enableWAIC` is set to `TRUE`. If a user attempts to call `calculateWAIC` without having set `enableWAIC = TRUE` (either in the call to `configureMCMC`, or `buildMCMC`, or as a NIMBLE option), an error will occur.

The `calculateWAIC` method calculates the WAIC of the model that the MCMC was performed on. The WAIC (Watanabe, 2010) is calculated from Equations 5, 12, and 13 in Gelman et al. (2014) (i.e. using pWAIC2). The set of all stochastic nodes monitored by the MCMC object will be treated as theta for the purposes of Equation 5 from Gelman et al. (2014). All non-monitored nodes downstream of the monitored nodes that are necessary to calculate p(y|theta) will be simulated from the posterior samples of theta. This allows customization of exactly what predictive distribution p(y|theta) to use for calculations. For more detail on the use of different predictive distributions, see Section 2.5 from Gelman et al. (2014). Note that by default only top-level stochastic nodes are monitored, but in many situations one would want to set monitors on all stochastic nodes so that all stochastic nodes are treated as theta for the WAIC calculation.

Note that there exist sets of monitored parameters that do not lead to valid WAIC calculations. Specifically, for a valid WAIC calculation, every node that a data node depends on must be either monitored, or be downstream from monitored nodes. An easy way to ensure this is satisfied is to monitor all top-level parameters in a model (NIMBLE's default). Another way to guarantee correctness is to monitor all nodes directly upstream from a data node. However, other combinations of monitored nodes are also valid. If `enableWAIC = TRUE`, NIMBLE checks to see if the set of monitored nodes is valid, and returns an error if not.

### Author(s)

Daniel Turek

### References

Watanabe, S. (2010). Asymptotic equivalence of Bayes cross validation and widely applicable information criterion in singular learning theory. Journal of Machine Learning Research 11: 3571-3594.

Gelman, A., Hwang, J. and Vehtari, A. (2014). Understanding predictive information criteria for Bayesian models. Statistics and Computing 24(6): 997-1016.

### See Also

`configureMCMC` `runMCMC` `nimbleMCMC`

### Examples

    ## Not run:
    code <- nimbleCode({
        mu ~ dnorm(0, 1)
        x ~ dnorm(mu, 1)
        y ~ dnorm(x, 1)
    })
    Rmodel <- nimbleModel(code, data = list(y = 0))
    conf <- configureMCMC(Rmodel)
    Rmcmc <- buildMCMC(conf, enableWAIC = TRUE)
    Cmodel <- compileNimble(Rmodel)
    Cmcmc <- compileNimble(Rmcmc, project=Rmodel)
    Cmcmc$run(10000)
    samples <- as.matrix(Cmcmc$mvSamples)
    head(samples)
    WAIC <- Cmcmc$calculateWAIC(nburnin = 1000)

    ## End(Not run)

[Package nimble version 0.9.1 Index]