MCMCconfObjects of this class configure an MCMC algorithm, specific to a particular model. Objects are normally created by calling configureMCMC.
Given an MCMCconf object, the actual MCMC function can be built by calling buildMCMC(conf).
See documentation below for method initialize() for details of creating an MCMCconf object.
addMonitors(..., ind = 1, print = TRUE)Adds variables to the list of monitors.
Arguments:
...: One or more character vectors of indexed nodes, or variables, which are to be monitored. These are added onto the current monitors list.
print: A logical argument specifying whether to print all current monitors (default TRUE).
Details: See the initialize() function
addMonitors2(..., print = TRUE)Adds variables to the list of monitors2.
Arguments:
...: One or more character vectors of indexed nodes, or variables, which are to be monitored. These are added onto the current monitors2 list.
print: A logical argument specifying whether to print all current monitors (default TRUE).
Details: See the initialize() function
addSampler(target, type = "RW", control = list(), print = FALSE, name,
silent = FALSE, ...)Adds a sampler to the list of samplers contained in the MCMCconf object.
Arguments:
target: The target node or nodes to be sampled. This may be specified as a character vector of model node and/or variable names. This argument is required.
type: The type of sampler to add, specified as either a character string or a nimbleFunction object. If the character argument type='newSamplerType', then either newSamplerType or sampler_newSamplertype must correspond to a nimbleFunction (i.e. a function returned by nimbleFunction, not a specialized nimbleFunction). Alternatively, the type argument may be provided as a nimbleFunction itself rather than its name. In that case, the 'name' argument may also be supplied to provide a meaningful name for this sampler. The default value is 'RW' which specifies scalar adaptive Metropolis-Hastings sampling with a normal proposal distribution. This default will result in an error if 'target' specifies more than one target node.
control: A list of control arguments specific to the sampler function. These will override those specified in the control list argument to configureMCMC().
print: Logical argument, specifying whether to print the details of the newly added sampler, as well as its position in the list of MCMC samplers.
name: Optional character string name for the sampler, which is used by the printSamplers method. If 'name' is not provided, the 'type' argument is used to generate the sampler name.
silent: Logical argument, specifying whether to print warning messages when assigning samplers.
...: Additional named arguments passed through ... will be used as additional control list elements.
Details: A single instance of the newly configured sampler is added to the end of the list of samplers for this MCMCconf object.
Invisibly returns a list of the current sampler configurations, which are samplerConf reference class objects.
getMonitors()Returns a character vector of the current monitors
Details: See the initialize() function
getMonitors2()Returns a character vector of the current monitors2
Details: See the initialize() function
getSamplerDefinition(ind)Returns the nimbleFunction definition of an MCMC sampler.
Arguments:
ind: A numeric vector or character vector. A numeric vector may be used to specify the index of the sampler definition to return, or a character vector may be used to indicate a target node for which the sampler acting on this nodes will be printed. For example, getSamplerDefinition('x[2]') will return the definition of the sampler whose target is model node 'x[2]'. If more than one sampler function is specified, only the first is returned.
Returns a list object, containing the setup function, run function, and additional member methods for the specified nimbleFunction sampler.
getSamplerExecutionOrder()Returns a numeric vector, specifying the ordering of sampler function execution.
The indices of execution specified in this numeric vector correspond to the enumeration of samplers printed by printSamplers(), or returned by getSamplers().
getSamplers(ind)Returns a list of samplerConf objects.
Arguments:
ind: A numeric vector or character vector. A numeric vector may be used to specify the indices of the samplerConf objects to return, or a character vector may be used to indicate a set of target nodes and/or variables, for which all samplers acting on these nodes will be returned. For example, getSamplers('x') will return all samplerConf objects whose target is model node 'x', or whose targets are contained (entirely or in part) in the model variable 'x'. If omitted, then all samplerConf objects in this MCMC configuration object are returned.
initialize(model, nodes, control = list(), rules, monitors, thin = 1,
monitors2 = character(), thin2 = 1, useConjugacy = TRUE,
onlyRW = FALSE, onlySlice = FALSE, multivariateNodesAsScalars = FALSE,
enableWAIC = nimbleOptions("enableWAIC"), warnNoSamplerAssigned = TRUE,
print = FALSE, ...)Creates a MCMC configuration for a given model. The resulting object is suitable as an argument to buildMCMC.
Arguments:
model: A NIMBLE model object, created from nimbleModel(...)
nodes: An optional character vector, specifying the nodes for which samplers should be created. Nodes may be specified in their indexed form, 'y[1, 3]', or nodes specified without indexing will be expanded fully, e.g., 'x' will be expanded to 'x[1]', 'x[2]', etc. If missing, the default value is all non-data stochastic nodes. If NULL, then no samplers are added.
control: An optional list of control arguments to sampler functions. If a control list is provided, the elements will be provided to all sampler functions which utilize the named elements given. For example, the standard Metropolis-Hastings random walk sampler (sampler_RW) utilizes control list elements 'adaptive', 'adaptInterval', 'scale'. The default values for control list arguments for samplers (if not otherwise provided as an argument to configureMCMC() or addSampler()) are contained in the setup code of each sampling algorithm.
monitors: A character vector of node names or variable names, to record during MCMC sampling. This set of monitors will be recorded with thinning interval 'thin', and the samples will be stored into the 'mvSamples' object. The default value is all top-level stochastic nodes of the model -- those having no stochastic parent nodes.
monitors2: A character vector of node names or variable names, to record during MCMC sampling. This set of monitors will be recorded with thinning interval 'thin2', and the samples will be stored into the 'mvSamples2' object. The default value is an empty character vector, i.e. no values will be recorded.
thin: The thinning interval for 'monitors'. Default value is one.
thin2: The thinning interval for 'monitors2'. Default value is one.
useConjugacy: A logical argument, with default value TRUE. If specified as FALSE, then no conjugate samplers will be used, even when a node is determined to be in a conjugate relationship.
onlyRW: A logical argument, with default value FALSE. If specified as TRUE, then Metropolis-Hastings random walk samplers will be assigned for all non-terminal continuous-valued nodes nodes. Discrete-valued nodes are assigned a slice sampler, and terminal nodes are assigned a posterior_predictive sampler.
onlySlice: A logical argument, with default value FALSE. If specified as TRUE, then a slice sampler is assigned for all non-terminal nodes. Terminal nodes are still assigned a posterior_predictive sampler.
multivariateNodesAsScalars: A logical argument, with default value FALSE. If specified as TRUE, then non-terminal multivariate stochastic nodes will have scalar samplers assigned to each of the scalar components of the multivariate node. The default value of FALSE results in a single block sampler assigned to the entire multivariate node. Note, multivariate nodes appearing in conjugate relationships will be assigned the corresponding conjugate sampler (provided useConjugacy == TRUE), regardless of the value of this argument.
enableWAIC: A logical argument, specifying whether to enable WAIC calculations for the resulting MCMC algorithm. Defaults to the value of nimbleOptions('enableWAIC'), which in turn defaults to FALSE. Setting nimbleOptions('enableWAIC' = TRUE) will ensure that WAIC is enabled for all calls to configureMCMC and buildMCMC.
warnNoSamplerAssigned: A logical argument specifying whether to issue a warning when no sampler is assigned to a node, meaning there is no matching sampler assignment rule. Default is TRUE.
print: A logical argument specifying whether to print the ordered list of default samplers. Default is FALSE.
...: Additional named control list elements for default samplers, or additional arguments to be passed to the autoBlock function when autoBlock = TRUE.
printMonitors()Prints all current monitors and monitors2
Details: See the initialize() function
printSamplers(ind, type, displayControlDefaults = FALSE,
displayNonScalars = FALSE, displayConjugateDependencies = FALSE,
executionOrder = FALSE)Prints details of the MCMC samplers.
Arguments:
ind: A numeric vector or character vector. A numeric vector may be used to specify the indices of the samplers to print, or a character vector may be used to indicate a set of target nodes and/or variables, for which all samplers acting on these nodes will be printed. For example, printSamplers('x') will print all samplers whose target is model node 'x', or whose targets are contained (entirely or in part) in the model variable 'x'. If omitted, then all samplers are printed.
type: a character vector containing sampler type names. Only samplers with one of these specified types, as printed by this printSamplers method, will be displayed. Standard regular expression mathing using is also applied.
displayConjugateDependencies: A logical argument, specifying whether to display the dependency lists of conjugate samplers (default FALSE).
displayNonScalars: A logical argument, specifying whether to display the values of non-scalar control list elements (default FALSE).
executionOrder: A logical argument, specifying whether to print the sampler functions in the (possibly modified) order of execution (default FALSE).
removeSampler(...)Alias for removeSamplers method
removeSamplers(ind, print = FALSE)Removes one or more samplers from an MCMCconf object.
Arguments:
This function also has the side effect of resetting the sampler execution ordering so as to iterate over the remaining set of samplers, sequentially, executing each sampler once.
ind: A numeric vector or character vector specifying the samplers to remove. A numeric vector may specify the indices of the samplers to be removed. Alternatively, a character vector may be used to specify a set of model nodes and/or variables, and all samplers whose 'target' is among these nodes will be removed. If omitted, then all samplers are removed.
print: A logical argument specifying whether to print the current list of samplers once the removal has been done (default FALSE).
resetMonitors()Resets the current monitors and monitors2 lists to nothing.
Details: See the initialize() function
setEnableWAIC(waic = TRUE)Sets the value of enableWAIC.
Arguments:
waic: A logical argument, indicating whether to enable WAIC calculations in the resulting MCMC algorithm (default TRUE).
setSamplerExecutionOrder(order, print = FALSE)Sets the ordering in which sampler functions will execute.
This allows some samplers to be "turned off", or others to execute multiple times in a single MCMC iteration. The ordering in which samplers execute can also be interleaved.
Arguments:
order: A numeric vector, specifying the ordering in which the sampler functions will execute. The indices of execution specified in this numeric vector correspond to the enumeration of samplers printed by printSamplers(), or returned by getSamplers(). If this argument is omitted, the sampler execution ordering is reset so as to sequentially execute each sampler once.
print: A logical argument specifying whether to print the current list of samplers in the modified order of execution (default FALSE).
setSamplers(ind, print = FALSE)Sets the ordering of the list of MCMC samplers.
This function also has the side effect of resetting the sampler execution ordering so as to iterate over the specified set of samplers, sequentially, executing each sampler once.
Arguments:
ind: A numeric vector or character vector. A numeric vector may be used to specify the indicies for the new list of MCMC samplers, in terms of the current ordered list of samplers. For example, if the MCMCconf object currently has 3 samplers, then the ordering may be reversed by calling MCMCconf$setSamplers(3:1), or all samplers may be removed by calling MCMCconf$setSamplers(numeric(0)).
Alternatively, a character vector may be used to specify a set of model nodes and/or variables, and the sampler list will modified to only those samplers acting on these target nodes.
As another alternative, a list of samplerConf objects may be used as the argument, in which case this ordered list of samplerConf objects will define the samplers in this MCMC configuration object, completely over-writing the current list of samplers. No checking is done to ensure the validity of the contents of these samplerConf objects; only that all elements of the list argument are, in fact, samplerConf objects.
print: A logical argument specifying whether to print the new list of samplers (default FALSE).
setThin(thin, print = TRUE)Sets the value of thin.
Arguments:
thin: The new value for the thinning interval 'thin'.
print: A logical argument specifying whether to print all current monitors (default TRUE).
Details: See the initialize() function
setThin2(thin2, print = TRUE)Sets the value of thin2.
Arguments:
thin2: The new value for the thinning interval 'thin2'.
print: A logical argument specifying whether to print all current monitors (default TRUE).
Details: See the initialize() function
# NOT RUN {
code <- nimbleCode({
mu ~ dnorm(0, 1)
x ~ dnorm(mu, 1)
})
Rmodel <- nimbleModel(code)
conf <- configureMCMC(Rmodel)
conf$setSamplers(1)
conf$addSampler(target = 'x', type = 'slice', control = list(adaptInterval = 100))
conf$addMonitors('mu')
conf$addMonitors2('x')
conf$setThin(5)
conf$setThin2(10)
conf$printMonitors()
conf$printSamplers()
# }
Run the code above in your browser using DataLab