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.
buildMCMC(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
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).
Note that there is not a unique value of WAIC for a model. The current version of
NIMBLE only provides the conditional WAIC, namely the version of WAIC where all
parameters directly involved in the likelihood are treated as \(theta\)
for the purposes of Equation 5 from Gelman et al. (2014). As a result, the user
must set the MCMC monitors (via the monitors argument) to include all stochastic
nodes that are parents of any data nodes; by default the MCMC monitors are only
the top-level nodes of the model. For more detail on the use of different predictive
distributions, see Section 2.5 from Gelman et al. (2014) or Ariyo et al. (2019).
Also note that WAIC relies on a partition of the observations, i.e., 'pointwise'
prediction. In NIMBLE the sum over log pointwise predictive density values treats
each data node as contributing a single value to the sum. When a data node is
multivariate, that data node contributes a single value to the sum based on the
joint density of the elements in the node. Note that if one wants the WAIC
calculation to be based on the joint predictive density for each group of observations
(e.g., grouping the observations from each person or unit in a longitudinal
data context), one would need to use a multivariate distribution for the
observations in each group (potentially by writing a user-defined distribution).
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).
resetMV: Boolean specifying whether to begin recording posterior sample chains anew. This argument is only considered when using reset = FALSE. Specifying reset = FALSE, resetMV = TRUE allows the MCMC algorithm to continue running from where it left off, but without appending the new posterior samples to the already existing samples, i.e. all previously obtained samples will be erased. This option can help reduce memory usage during burn-in (default = FALSE).
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 or list objects via:
as.matrix(mcmc$mvSamples)
as.list(mcmc$mvSamples)
as.matrix(mcmc$mvSamples2)
as.list(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.
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.
Ariyo, O., Quintero, A., Munoz, J., Verbeke, G. and Lesaffre, E. (2019). Bayesian model selection in linear mixed models for longitudinal data. Journal of Applied Statistics 47: 890-913.
# 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, monitors = c('mu', 'x'))
Rmcmc <- buildMCMC(conf, enableWAIC = TRUE)
Cmodel <- compileNimble(Rmodel)
Cmcmc <- compileNimble(Rmcmc, project=Rmodel)
Cmcmc$run(10000)
samples <- as.matrix(Cmcmc$mvSamples)
samplesAsList <- as.list(Cmcmc$mvSamples)
head(samples)
WAIC <- Cmcmc$calculateWAIC(nburnin = 1000)
# }
# NOT RUN {
# }
Run the code above in your browser using DataLab