nimbleHMC {nimbleHMC}

Builds and executes NIMBLE's HMC sampler

Description

nimbleHMC is the most direct entry point to using NIMBLE's HMC sampler. HMC sampling is applied to all unobserved dimensions of a hierarchical model. Discrete-valued model dimensions cannot be sampled using HMC, and will produce an error. See help(HMC) for details of the HMC algorithm.

Usage

nimbleHMC(
  code,
  constants = list(),
  data = list(),
  inits,
  dimensions = list(),
  model,
  type = "NUTS",
  monitors,
  thin = 1,
  niter = 10000,
  nburnin = 0,
  nchains = 1,
  check = TRUE,
  setSeed = FALSE,
  progressBar = getNimbleOption("MCMCprogressBar"),
  samples = TRUE,
  samplesAsCodaMCMC = FALSE,
  summary = FALSE,
  WAIC = FALSE
)

Arguments

code

The quoted code expression representing the model, such as the return value from a call to nimbleCode). Not required if model is provided.

constants

Named list of constants in the model. Constants cannot be subsequently modified. For compatibility with JAGS and BUGS, one can include data values with constants and nimbleModel will automatically distinguish them based on what appears on the left-hand side of expressions in code.

data

Named list of values for the data nodes. Values that are NA will not be flagged as data.

inits

Argument to specify initial values for each MCMC chain. See details.

dimensions

Named list of dimensions for variables. Only needed for variables used with empty indices in model code that are not provided in constants or data.

model

A compiled or uncompiled NIMBLE model object. When provided, this model will be used to configure the MCMC algorithm to be executed, rather than using the code, constants, data and inits arguments to create a new model object. However, if also provided, the inits argument will still be used to initialize this model prior to running each MCMC chain.

type

A character string specifying the type of HMC sampling to apply, either "NUTS" or "NUTS_classic". See 'help(NUTS)' or 'help(NUTS_classic)' for details of each sampler. The default sampler type is "NUTS".

monitors

A character vector giving the node names or variable names to monitor. The samples corresponding to these nodes will returned, and/or will have summary statistics calculated. Default value is all top-level stochastic nodes of the model.

thin

Thinning interval for collecting MCMC samples. Thinning occurs after the initial nburnin samples are discarded. Default value is 1.

niter

Number of MCMC iterations to run. Default value is 10000.

nburnin

Number of initial, pre-thinning, MCMC iterations to discard. Default value is 0.

nchains

Number of MCMC chains to run. Default value is 1.

check

Logical argument, specifying whether to check the model object for missing or invalid values. Default value is TRUE.

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. z

WAIC

Logical argument. When TRUE, the WAIC (Watanabe, 2010) of the model is calculated and returned. If multiple chains are run, then a single WAIC value is calculated using the posterior samples from all chains. Default value is FALSE. Note that the version of WAIC used is the default WAIC conditional on random effects/latent states and without any grouping of data nodes. See help(waic) for more details.

Details

nimbleHMC provides capability for running multiple MCMC chains, specifying the number of MCMC iterations, thinning, and burn-in, and which model variables should be monitored. It also provides options to return the posterior samples, to return summary statistics calculated from the posterior samples, and to return a WAIC value.

The entry point for this function is providing the code, constants, data and inits arguments, to create a new NIMBLE model object, or alternatively providing an exisiting NIMBLE model object as the model argument.

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, summary statistics, and WAIC values are returned for each MCMC chain.

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

The inits argument can be one of three things:

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

The inits argument may also be omitted, in which case the model will not be provided with initial values. This is not recommended.

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

Value

A list is returned with named elements depending on the arguments, unless only one among samples, summary, and WAIC are requested, in which case only that element is returned. These elements may include samples, summary, and WAIC. 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

See Also

configureHMC buildHMC configureMCMC buildMCMC runMCMC

Examples

code <- nimbleCode({
    mu ~ dnorm(0, sd = 1000)
    sigma ~ dunif(0, 1000)
    for(i in 1:10) {
        x[i] ~ dnorm(mu, sd = sigma)
    }
})
data <- list(x = c(2, 5, 3, 4, 1, 0, 1, 3, 5, 3))
inits <- function() list(mu = rnorm(1,0,1), sigma = runif(1,0,10))
mcmc.output <- nimbleHMC(code, data = data, inits = inits,
                         monitors = c("mu", "sigma"), thin = 10,
                         niter = 20000, nburnin = 1000, nchains = 3,
                         summary = TRUE, WAIC = TRUE)