buildAPT {nimbleAPT}

Create an APT function, from an MCMCconf object

Description

Adapted from nimble::buildMCMC. Accepts a single required argument, which may be of class MCMCconf, or inherit from class modelBaseClass (a NIMBLE model object). Returns an APT function; see details section.

Usage

buildAPT(conf, Temps, monitorTmax = TRUE, ULT = 1e+06, thinPrintTemps = 1, ...)

Arguments

conf

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

Temps

A numeric vector giving the initial temperature ladder.

monitorTmax

A logical indicator (default = TRUE) controlling if MCMC output should be stored at the hottest rung of the temperature ladder. Useful when monitoring the behaviour of APT. When TRUE mvSamples and mvSamples2 monitor T=1 and mvSamplesTmax and mvSamples2Tmax provide identically defined monitors (i.e. for exactly the same nodes) for T=Tmax.

ULT

A numeric value (default = 1E6) that provides an upper limit to temperature during APT.

thinPrintTemps

A numeric value controlling how often temperatures of the temperature ladder should be printed to screen when runtime parameter printTemps is TRUE. The default value of 1 is often too verbose. A good value to use is niter/10.

...

Additional arguments to be passed to configureMCMC if conf is a NIMBLE model object

Details

Calling buildAPT(conf,Temps,monitorTmax,ULT,thinPrintTemps) will produce an uncompiled (R) APT function object, say 'myAPT'.

The uncompiled MCMC function will have arguments:

niter The number of iterations to run the MCMC.

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

resetTempering Boolean specifying whether to reset the flexibility of the temperature ladder's adaptation process.

simulateAll Boolean specifying whether to simulate into all stochastic nodes. This will overwrite the current values in all stochastic nodes (default = FALSE).

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

adaptTemps Boolean specifying whether the temperature ladder will be adapted or not.

printTemps Boolean specifying whether the temperature ladder will be printed during the MCMC. The print frequency is controlled by thinPrintTemps. The output includes (in order): iteration number of current MCMC run; total number of iterations of the tempering scheme - this will include itterations from previous MCMC runs unless resetTempering=TRUE; the number of rows in mvSamples; the number of rows in mvSamples2; the temperature ladder.

tuneTemper1 Numeric tuning parameter of the adaptation process of the temperature ladder. See source code for buildAPT. Defaults to 10.

tuneTemper2 Numeric tuning parameter of the adaptation process of the temperature ladder. See source code for buildAPT. Defaults to 1.

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

thin Thinning to be applied to monitor.

thin2 Thinning to be applied to monitor2

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

Value

Calling buildAPT returns an uncompiled APT function object. This is very similar to how NIMBLE's buildMCMC function returns an uncompiled MCMC function object. See ?buildMCMC. Users should be familiar with the chapter 'MCMC' of the NIMBLE manual.

Author(s)

David Pleydell, Daniel Turek

Examples

## See the nimbleAPT vignette for more details.
bugsCode <- nimbleCode({
  for (ii in 1:nObs) {
    y[ii,1:2] ~ dmnorm(mean=absCentroids[1:2], cholesky=cholCov[1:2,1:2], prec_param=0)
  }
  absCentroids[1:2] <- abs(centroids[1:2])
  for (ii in 1:2) {
    centroids[ii] ~ dnorm(0, sd=1E3)
  }
})

nObs      <- 100
centroids <- rep(-3, 2)
covChol   <- chol(diag(2))

rModel <- nimbleModel(bugsCode,
                      constants=list(nObs=nObs, cholCov=covChol),
                      inits=list(centroids=centroids))
simulate(rModel, "y")
rModel <- nimbleModel(bugsCode,
                      constants=list(nObs=nObs, cholCov=covChol),
                      data=list(y=rModel$y),
                      inits=list(centroids=centroids))

conf <- configureMCMC(rModel, nodes="centroids", monitors="centroids", enableWAIC = TRUE)
conf$removeSamplers()
conf$addSampler("centroids[1]", type="sampler_RW_tempered", control=list(temperPriors=TRUE))
conf$addSampler("centroids[2]", type="sampler_RW_tempered", control=list(temperPriors=TRUE))
aptR <- buildAPT(conf, Temps=1:5, ULT= 1000, print=TRUE)