rjags-package
Bayesian graphical models using MCMC
Description
The rjags package provides an interface from R to the JAGS library for Bayesian data analysis.
JAGS uses Markov Chain Monte Carlo (MCMC) to generate a sequence of dependent samples
from the posterior distribution of the parameters.
Details
JAGS is a clone of BUGS (Bayesian analysis Using Gibbs Sampling). See Lunn et al (2009) for
a history of the BUGS project. Note that the rjags package does not include a copy of the JAGS
library: you must install this separately. For instructions on downloading JAGS, see the home page
at https://mcmc-jags.sourceforge.io.
To fully understand how JAGS works, you need to read the JAGS User Manual. The manual ex-
plains the basics of modelling with JAGS and shows the functions and distributions available in the
dialect of the BUGS language used by JAGS. It also describes the command line interface. The
rjags package does not use the command line interface but provides equivalent functionality using
R functions.
Analysis using the rjags package proceeds in steps:
1. Define the model using the BUGS language in a separate file.
2. Read in the model file using the jags.model function. This creates an object of class “jags”.
3. Update the model using the update method for “jags” objects. This constitutes a ‘burn-in’
period.
4. Extract samples from the model object using the coda.samples function. This creates an ob-
ject of class “mcmc.list” which can be used to summarize the posterior distribution. The coda
package also provides convergence diagnostics to check that the output is valid for analysis
(see Plummer et al 2006).
Author(s)
Martyn Plummer
adapt
Adaptive phase for JAGS models
Description
Update the model in adaptive mode.
Usage
adapt(object, n.iter, end.adaptation=FALSE,...)
Arguments
object
a jags model object
n.iter
length of the adaptive phase
end.adaptation logical flag. If TRUE then adaptive mode will be turned off on exit.
...
additional arguments to the update method
Details
This function is not normally called by the user. It is called by the jags.model function when the
model object is created.
When a JAGS model is compiled, it may require an initial sampling phase during which the sam-
plers adapt their behaviour to maximize their efficiency (e.g. a Metropolis-Hastings random walk
algorithm may change its step size). The sequence of samples generated during this adaptive phase
is not a Markov chain, and therefore may not be used for posterior inference on the model.
The adapt function updates the model for n.iter iterations in adaptive mode. Then each sampler
reports whether it has acheived optimal performance (e.g. whether the rejection rate of a Metropolis-
Hasting sampler is close to the theoretical optimum). If any sampler reports failure of this test then
adapt returns FALSE.
If end.adaptation = TRUE, then adaptive mode is turned off on exit, and further calls to adapt() do
nothing. The model may be maintained in adaptive mode with the default option end.adaptation
= FALSE so that successive calls to adapt() may be made until adaptation is satisfactory.
Value
Returns TRUE if all the samplers in the model have successfully adapted their behaviour to optimum
performance and FALSE otherwise.
coda.samples
Generate posterior samples in mcmc.list format
Description
This is a wrapper function for jags.samples which sets a trace monitor for all requested nodes,
updates the model, and coerces the output to a single mcmc.list object.
Usage
coda.samples(model, variable.names, n.iter, thin = 1, na.rm=TRUE,...)
Arguments
model
a jags model object
variable.names a character vector giving the names of variables to be monitored
n.iter
number of iterations to monitor
thin
thinning interval for monitors
na.rm
logical flag that indicates whether variables containing missing values should be
omitted. See details.
...
optional arguments that are passed to the update method for jags model objects
Details
If na.rm=TRUE (the default) then elements of a variable that are missing (NA) for any iteration in at
least one chain will be dropped.
This argument was added to handle incompletely defined variables. From JAGS version 4.0.0,
users may monitor variables that are not completely defined in the BUGS language description of
the model, e.g. if y[i] is defined in a for loop starting from i=3 then y[1], y[2] are not defined.
The user may still monitor variable y and the monitored values corresponding to y[1], y[2] will
have value NA for all iterations in all chains. Most of the functions in the coda package cannot
handle missing values so these variables are dropped by default.
Value
An mcmc.list object.
control
Advanced control over JAGS
Description
JAGS modules contain factory objects for samplers, monitors, and random number generators for a
JAGS model. These functions allow fine-grained control over which factories are active.
Usage
list.factories(type)
set.factory(name, type, state)
Arguments
name
name of the factory to set
type
type of factory to query or set. Possible values are "sampler", "monitor", or
"rng"
state
a logical. If TRUE then the factory will be active, otherwise the factory will
become inactive.
Value
list.factories returns a data frame with two columns, the first column shows the names of the
factories and the second column shows their current state. set.factory returns the state of the
factory after it has been set.
