RJAGS Package in R
RJAGS Package in R
RJAGS Package in R
URL https://mcmc-jags.sourceforge.io
Suggests tcltk
Description Interface to the JAGS MCMC library.
License GPL (== 2)
NeedsCompilation yes
Author Martyn Plummer [aut, cre],
Alexey Stukalov [ctb],
Matt Denwood [ctb]
Maintainer Martyn Plummer <martyn.plummer@gmail.com>
Repository CRAN
Date/Publication 2023-04-23 19:10:02 UTC
R topics documented:
rjags-package . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 2
adapt . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 3
coda.samples . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 4
control . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 5
dic.samples . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 6
diffdic . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 7
jags.model . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 8
jags.module . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 10
jags.object . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 11
jags.samples . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 12
jags.version . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 13
line . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 14
1
2 rjags-package
mcarray.object . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 14
parallel . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 15
read.jagsdata . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 16
rjags-deprecated . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 17
update . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 18
Index 19
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:
Author(s)
Martyn Plummer
adapt 3
References
Lunn D, Spiegelhalter D, Thomas A, Best N. (2009) The BUGS project: Evolution, critique and
future directions. Statistics in Medicine, 28:3049-67.
Plummer M, Best N, Cowles K, Vines K (2006). CODA: Convergence Diagnosis and Output Anal-
ysis for MCMC, R News, 6:7-11.
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.
4 coda.samples
Author(s)
Martyn Plummer
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.
Author(s)
Martyn Plummer
control 5
See Also
jags.samples
Examples
data(LINE)
LINE$recompile()
LINE.out <- coda.samples(LINE, c("alpha","beta","sigma"), n.iter=1000)
summary(LINE.out)
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
factory objects in the currently loaded modules, and the second column is a logical vector indicating
whether the corresponding factory is active or not.
set.factory is called to change the future behaviour of factory objects. If a factory is set to inactive
then it will be skipped.
Note
When a module is loaded, all of its factory objects are active. This is also true if a module is
unloaded and then reloaded.
Author(s)
Martyn Plummer
6 dic.samples
Examples
list.factories("sampler")
list.factories("monitor")
list.factories("rng")
set.factory("base::Slice", "sampler", FALSE)
list.factories("sampler")
set.factory("base::Slice", "sampler", TRUE)
Description
Function to extract random samples of the penalized deviance from a jags model.
Usage
dic.samples(model, n.iter, thin = 1, type, ...)
Arguments
model a jags model object
n.iter number of iterations to monitor
thin thinning interval for monitors
type type of penalty to use
... optional arguments passed to the update method for jags model objects
Details
The dic.samples function generates penalized deviance statistics for use in model comparison.
The two alternative penalized deviance statistics generated by dic.samples are the deviance infor-
mation criterion (DIC) and the penalized expected deviance. These are chosen by giving the values
“pD” and “popt” respectively as the type argument.
DIC (Spiegelhalter et al 2002) is calculated by adding the “effective number of parameters” (pD) to
the expected deviance. The definition of pD used by dic.samples is the one proposed by Plummer
(2002) and requires two or more parallel chains in the model.
DIC is an approximation to the penalized plug-in deviance, which is used when only a point esti-
mate of the parameters is of interest. The DIC approximation only holds asymptotically when the
effective number of parameters is much smaller than the sample size, and the model parameters
have a normal posterior distribution.
The penalized expected deviance (Plummer 2008) is calculated by adding the optimism (popt) to
the expected deviance. The popt penalty is at least twice the size of the pD penalty, and penalizes
complex models more severely.
diffdic 7
Value
An object of class “dic”. This is a list containing the following elements:
deviance A numeric vector, with one element for each observed stochastic node, contain-
ing the mean deviance for that node
penalty A numeric vector, with one element for each observed stochastic node, contain-
ing an estimate of the contribution towards the penalty
type A string identifying the type of penalty: “pD” or “popt”
Note
The popt penalty is estimated by importance weighting, and may be numerically unstable.
Author(s)
Martyn Plummer
References
Spiegelhalter, D., N. Best, B. Carlin, and A. van der Linde (2002), Bayesian measures of model
complexity and fit (with discussion). Journal of the Royal Statistical Society Series B 64, 583-639.
Plummer, M. (2002), Discussion of the paper by Spiegelhalter et al. Journal of the Royal Statistical
Society Series B 64, 620.
Plummer, M. (2008) Penalized loss functions for Bayesian model comparison. Biostatistics doi:
10.1093/biostatistics/kxm049
See Also
diffdic
Description
Compare two models by the difference of two dic objects.
Usage
dic1 - dic2
diffdic(dic1, dic2)
Arguments
dic1, dic2 Objects inheriting from class “dic”
8 jags.model
Details
A diffdic object represents the difference in penalized deviance between two models. A negative
value indicates that dic1 is preferred and vice versa.
Value
An object of class “diffdic”. This is a numeric vector with an element for each observed stochastic
node in the model.
The diffdic class has its own print method, which will display the sum of the differences, and its
sample standard deviation.
Note
The problem of determining what is a noteworthy difference in DIC (or other penalized deviance)
between two models is currently unsolved. Following the results of Ripley (1996) on the Akaike
Information Criterion, Plummer (2008) argues that there is no absolute scale for comparison of two
penalized deviance statistics, and proposes that the difference should be calibrated with respect to
the sample standard deviation of the individual contributions from each observed stochastic node.
Author(s)
Martyn Plummer
References
Ripley, B. (1996) Statistical Pattern Recognition and Neural Networks. Cambridge University
Press.
Plummer, M. (2008) Penalized loss functions for Bayesian model comparison. Biostatistics doi:
10.1093/biostatistics/kxm049
See Also
dic
Description
jags.model is used to create an object representing a Bayesian graphical model, specified with a
BUGS-language description of the prior distribution, and a set of data.
Usage
jags.model(file, data, inits,
n.chains = 1, n.adapt=1000, quiet=FALSE)
jags.model 9
Arguments
file the name of the file containing a description of the model in the JAGS dialect of
the BUGS language.
Alternatively, file can be a readable text-mode connection, or a complete URL.
data a list or environment containing the data. Any numeric objects in data cor-
responding to node arrays used in file are taken to represent the values of
observed nodes in the model.
inits optional specification of initial values in the form of a list or a function (see
Initialization below). If omitted, initial values will be generated automati-
cally. It is an error to supply an initial value for an observed node.
n.chains the number of parallel chains for the model
n.adapt the number of iterations for adaptation. See adapt for details. If n.adapt = 0
then no adaptation takes place.
quiet if TRUE then messages generated during compilation will be suppressed, as well
as the progress bar during adaptation.
Value
jags.model returns an object inheriting from class jags which can be used to generate dependent
samples from the posterior distribution of the parameters
An object of class jags is a list of functions that share a common environment. This environment
encapsulates the state of the model, and the functions can be used to query or modify the model
state.
Initialization
There are various ways to specify initial values for a JAGS model. If no initial values are sup-
plied, then they will be generated automatically by JAGS. See the JAGS User Manual for details.
Otherwise, the options are as follows:
1. A list of numeric values. Initial values for a single chain may supplied as a named list of
numeric values. If there are multiple parallel chains then the same list is re-used for each
chain.
10 jags.module
2. A list of lists. Distinct initial values for each chain may be given as a list of lists. In this case,
the list should have the same length as the number of chains in the model.
3. A function. A function may be supplied that returns a list of initial values. The function
is called repeatedly to generate initial values for each chain. Normally this function should
call some random number generating functions so that it returns different values every time
it is called. The function should either have no arguments, or have a single argument named
chain. In the latter case, the supplied function is called with the chain number as argument.
In this way, initial values may be generated that depend systematically on the chain number.
Author(s)
Martyn Plummer
Description
A JAGS module is a dynamically loaded library that extends the functionality of JAGS. These
functions load and unload JAGS modules and show the names of the currently loaded modules.
Usage
load.module(name, path, quiet=FALSE)
unload.module(name, quiet=FALSE)
list.modules()
jags.object 11
Arguments
name name of the load module to be loaded
path file path to the location of the DLL. If omitted, the option jags.moddir is used
to locate the modules
quiet a logical. If TRUE, no message will be printed about loading the package
Author(s)
Martyn Plummer
Examples
list.modules()
load.module("glm")
list.modules()
unload.module("glm")
list.modules()
Description
A jags object represents a Bayesian graphical model described using the BUGS language.
Usage
## S3 method for class 'jags'
coef(object, chain=1, ...)
## S3 method for class 'jags'
variable.names(object, ...)
list.samplers(object)
Arguments
object a jags model object
chain chain number to query
... additional arguments to the call (ignored)
Value
The coef function returns a list with an entry for each Node array that contains an unobserved
Node. Elements corresponding to observed Nodes or deterministic Nodes are given missing values.
The variable.names function returns a character vector of names of node arrays used in the model.
The list.samplers function returns a named list with an entry for each Sampler used by the model.
Each list element is a character vector containing the names of stochastic Nodes that are updated
12 jags.samples
together in a block. The names of the list elements indicate the sampling methods that are used to
update each block. Stochastic nodes that are updated by forward sampling from the prior are not
listed.
Author(s)
Martyn Plummer
Examples
data(LINE)
LINE$recompile()
coef(LINE)
variable.names(LINE)
list.samplers(LINE)
Description
Function to extract random samples from the posterior distribution of the parameters of a jags
model.
Usage
jags.samples(model, variable.names, n.iter, thin = 1,
type="trace", force.list=FALSE, ...)
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
type type of monitor (can be vectorised)
force.list option to consistently return a named list of monitor types even if a single mon-
itor type is requested
... optional arguments passed to the update method for jags model objects
Details
The jags.samples function creates monitors for the given variables, runs the model for n.iter
iterations and returns the monitored samples.
jags.version 13
Value
A list of mcarray objects, with one element for each element of the variable.names argument. If
more than one type of monitor is requested (or if force.list is TRUE) then the return value will be a
(named) list of lists of mcarray objects, with one element for each monitor type.
Author(s)
Martyn Plummer
See Also
jags.model, coda.samples
Examples
data(LINE)
LINE$recompile()
LINE.samples <- jags.samples(LINE, c("alpha","beta","sigma"),
n.iter=1000)
LINE.samples
LINE.samples <- jags.samples(LINE, c("alpha","beta","sigma"),
force.list=TRUE, n.iter=1000)
LINE.samples
LINE.samples <- jags.samples(LINE, c("alpha","alpha"),
n.iter=1000, type=c("trace","mean"))
LINE.samples$trace
LINE.samples$mean
Description
Get the version of the JAGS library which is currently linked to this R session
Usage
jags.version()
Value
Description
The LINE model is a trivial linear regression model with only 5 observations. It’s main use is to
allow automated checks of the rjags package.
Format
A jags.model object, which must be recompiled before use.
Description
An mcarray object is used by the jags.samples function to represent MCMC output from a JAGS
model. It is an array with named dimensions, for which the dimensions "iteration" and "chain" have
a special status
Usage
## S3 method for class 'mcarray'
summary(object, FUN, ...)
## S3 method for class 'mcarray'
print(x, ...)
## S3 method for class 'mcarray'
as.mcmc.list(x, ...)
Arguments
object,x an mcarray object
FUN a function to be used to generate summary statistics
... additional arguments to the call
Details
The coda package defines mcmc objects for representing output from an MCMC sampler, and
mcmc.list for representing output from multiple parallel chains. These objects emphasize the
time-series aspect of the MCMC output, but lose the original array structure of the variables they
represent. The mcarray class attempts to rectify this by preserving the dimensions of the original
node array defined in the JAGS model.
parallel 15
Value
The summary method for mcarray objects applies the given function to the array, marginalizing the
"chain" and "iteration" dimensions.
The print method applies the summary function with FUN=mean.
The as.mcmc.list method coerces an mcarray to an mcmc.list object so that the diagnostics
provided by the coda package can be applied to the MCMC output it represents.
Author(s)
Martyn Plummer
Description
On a multi-processor system, you may wish to run parallel chains using multiple jags.model ob-
jects, each running a single chain on a separate processor. This function returns a list of values that
may be used to initialize the random number generator of each chain.
Usage
parallel.seeds(factory, nchain)
Arguments
factory Name of the RNG factory to use.
nchain Number of chains for which to initialize RNGs.
Value
parallel.seeds returns a list of RNG states. Each element is a list of length 2 with the following
elements:
Note
It is not yet possible to make the results of parallel.seeds reproducible. This will be fixed in a
future version of JAGS.
Author(s)
Martyn Plummer
16 read.jagsdata
See Also
jags.model, section “Random number generators”, for further details on RNG initialization; list.factories
to find the names of available RNG factories.
Examples
##The BaseRNG factory generates up to four distinct types of RNG. If
##more than 4 chains are requested, it will recycle the RNG types, but
##use different initial values
parallel.seeds("base::BaseRNG", 3)
## The lecuyer module provides the RngStream factory, which allows large
## numbers of independent parallel RNGs to be generated.
load.module("lecuyer")
list.factories(type="rng")
parallel.seeds("lecuyer::RngStream", 5);
Description
Read data for a JAGS model from a file.
Usage
read.jagsdata(file)
read.bugsdata(file)
Arguments
file name of a file containing a text repesentation of the data for a jags model
Details
The command line interface for JAGS reads data and initial values from a text file. The data format
used for jags data files is the same as the R dump function. Thus the data values can be read into
an R session using the source function, but this will create objects in the global environment. The
read.jagsdata function is a simple wrapper that reads the data into a list instead.
OpenBUGS also reads data and initial values from a text file. The format of these files is described
as "S-PLUS" format by the OpenBUGS authors. It superficially resembles the format used by the
dput function (and in fact can be parsed by the dget function). However, in BUGS "S-PLUS"
format, arrays are stored in row-major order instead of the column-major order used by R. The
read.bugsdata function reads OpenBUGS "S-PLUS" format files and permutes the elements of
arrays so that they appear in the correct order.
Either function returns a list which can be used as the data or inits argument of jags.model.
rjags-deprecated 17
Value
Note
Earlier versions of the rjags package had a read.data function which read data in either format, but
the function name was ambiguous (There are many data file format in R) so this is now deprecated.
Author(s)
Martyn Plummer
Description
These functions are provided for compatibility with older versions of the rjags package and will
soon be defunct.
Usage
read.data(file, format=c("jags","bugs"))
Arguments
file name of a file containing a text repesentation of the data for a jags model
format format of the data
Details
read.data with format="jags" is a deprecated synonym for read.jagsdata and with format="bugs"
is a deprecated synonym for read.bugsdata.
18 update
Description
Update the Markov chain associated with the model.
Usage
## S3 method for class 'jags'
update(object, n.iter=1, by, progress.bar, ...)
Arguments
object a jags model object
n.iter number of iterations of the Markov chain to run
by refresh frequency for progress bar. See Details
progress.bar type of progress bar. Possible values are "text", "gui", and "none". See
Details.
... additional arguments to the update method (ignored)
Details
Since MCMC calculations are typically long, a progress bar is displayed during the call to update.
The type of progress bar is determined by the progress.bar argument. Type "text" is displayed
on the R console. Type "gui" is a graphical progress bar in a new window. The progress bar is
suppressed if progress.bar is "none" or NULL, if the update is less than 100 iterations, or if R is
not running interactively.
The default progress bar type is taken from the option jags.pb.
The progress bar is refreshed every by iterations. The update can only be interrupted when the
progress bar is refreshed. Therefore it is advisable not to set by to a very large value. By default by
is either n.iter/50 or 100, whichever is smaller.
Value
The update method for jags model objects modifies the original object and returns NULL.
Author(s)
Martyn Plummer
Index
∗ datasets jags.samples, 5, 12
line, 14 JAGS.version (jags.version), 13
∗ file jags.version, 13
read.jagsdata, 16
∗ interface LINE (line), 14
jags.module, 10 line, 14
∗ misc list.factories, 16
rjags-deprecated, 17 list.factories (control), 5
∗ models list.modules (jags.module), 10
adapt, 3 list.samplers (jags.object), 11
coda.samples, 4 load.module (jags.module), 10
control, 5
dic.samples, 6 mcarray.object, 14
diffdic, 7
package_version, 13
jags.model, 8
parallel, 15
jags.object, 11
parallel.seeds, 10
jags.samples, 12 print.mcarray (mcarray.object), 14
mcarray.object, 14
parallel, 15 read.bugsdata, 17
update, 18 read.bugsdata (read.jagsdata), 16
∗ package read.data (rjags-deprecated), 17
rjags-package, 2 read.jagsdata, 16, 17
rjags (rjags-package), 2
adapt, 3, 9 rjags-deprecated, 17
as.mcmc.list.mcarray (mcarray.object), rjags-package, 2
14
set.factory (control), 5
coda.samples, 4, 13 summary.mcarray (mcarray.object), 14
coef.jags, 9
coef.jags (jags.object), 11 unload.module (jags.module), 10
control, 5 update, 18
update.jags, 9
dic, 8
dic (dic.samples), 6 variable.names.jags (jags.object), 11
dic.samples, 6
diffdic, 7, 7
jags.model, 8, 13, 16
jags.module, 10
jags.object, 11
19