JAGS Version 4.3.0 user manual
28 June 2017
1 Introduction 4
Copyright By PowCoder代写 加微信 powcoder
1.1 DownloadingJAGS…………………………… 4
1.2 Gettinghelp………………………………. 4
1.3 Acknowledgements …………………………… 5
2 The BUGS language 6
2.1 Relations ……………………………….. 6
2.2 Arraysandsubsetting …………………………. 6
2.2.1 Subsettingvectors ……………………….. 7
2.2.2 Subsettingmatrices ………………………. 7
2.2.3 Restrictionsonindexexpressions………………… 7
2.3 Constructingvectors………………………….. 8
2.4 Forloops ……………………………….. 8
2.5 Datatransformations………………………….. 9 2.5.1 Modellingsimulateddata ……………………. 9
2.6 NodeArraydimensions ………………………… 10 2.6.1 Arraydeclarations ……………………….. 10 2.6.2 Undeclarednodes………………………… 10 2.6.3 Queryingarraydimensions …………………… 11
3 Steps in running a model 13
3.1 Modules………………………………… 13
3.2 Compilation………………………………. 14 3.2.1 Compilationfailures ………………………. 15 3.2.2 Parallelchains …………………………. 15
3.3 Initialization ……………………………… 15 3.3.1 Initialvalues ………………………….. 16 3.3.2 RandomNumberGenerators ………………….. 17 3.3.3 Samplers ……………………………. 17
3.4 Adaptationandburn-in ………………………… 18
3.5 Monitoring ………………………………. 18
3.6 Errors…………………………………. 18
4 Running JAGS from R 20
4.1 rjags………………………………….. 20 4.2 runjags ………………………………… 21
4.3 R2jags…………………………………. 22 4.4 jagsUI…………………………………. 23
5 Running JAGS on the command line 25 5.1 Scriptingcommands ………………………….. 25 5.2 Dataformat………………………………. 31
6 Functions 32
6.1 LinkFunctions …………………………….. 32 6.2 Vectorization ……………………………… 32 6.3 Functionsassociatedwithdistributions…………………. 33 6.4 Functionaliases…………………………….. 33
7 Distributions 35
7.1 Truncatingdistributions………………………… 35 7.2 ObservableFunctions………………………….. 36 7.3 Ordereddistributions………………………….. 36 7.4 Distributionaliases…………………………… 37
8 The base module 38
8.1 Functionsinthebasemodule ……………………… 38
8.2 Samplersinthebasemodule ……………………… 39 8.2.1 Inversion ……………………………. 39 8.2.2 Slicesampling …………………………. 39 8.2.3 RNGsinthebasemodule ……………………. 40 8.2.4 Monitorsinthebasemodule ………………….. 40
9 The bugs module 41
9.1 Functionsinthebugsmodule……………………… 41
9.1.1 Scalarfunctions…………………………. 41
9.1.2 Scalar-valuedfunctionswitharrayarguments . . . . . . . . . . . . . . 41
9.1.3 Vector-andarray-valuedfunctions ……………….. 41
9.2 Distributionsinthebugsmodule ……………………. 43
9.2.1 Continuousunivariatedistributions……………….. 43
9.2.2 Discreteunivariatedistributions ………………… 49
9.2.3 Multivariatedistributions ……………………. 52
9.2.4 Observablefunctionsinthebugsmodule. . . . . . . . . . . . . . . . . 55
9.3 Samplersinthebugsmodule ……………………… 58
10 The glm module 59
10.1Distributionsintheglmmodule…………………….. 59 10.1.1 Orderedcategoricaldistributions ………………… 59 10.1.2 Distributionsforprecisionparameters . . . . . . . . . . . . . . . . . . 60
10.2Samplersintheglmmodule………………………. 62
11 The dic module 64
11.1Monitorsinthedicmodule ………………………. 64 11.1.1 Thedeviancemonitor ……………………… 64 11.1.2 ThepDmonitor…………………………. 64 11.1.3 Thepoptmonitor ……………………….. 65
12 The mix module 66
13 The msm module 67
14 The lecuyer module 68
A Differences between JAGS and OpenBUGS 69 A.1 Dataformat………………………………. 69 A.2 Distributions ……………………………… 69 A.3 Censoringandtruncation ……………………….. 70 A.4 Datatransformations………………………….. 70
Chapter 1 Introduction
JAGS is “Just Another ”. It is a program for the analysis of Bayesian models using Markov Chain Monte Carlo (MCMC) which is not wholly unlike OpenBUGS (http: //www.openbugs.info). JAGS is written in C++ and is portable to all major operating systems.
JAGS is designed to work closely with the R language and environment for statistical computation and graphics (http://www.r-project.org). You will find it useful to install the coda package for R to analyze the output. Several R packages are available to run a JAGS model. See chapter 4.
JAGS is licensed under the GNU General Public License version 2. You may freely modify and redistribute it under certain conditions (see the file COPYING for details).
1.1 Downloading JAGS
JAGS is hosted on Sourceforge at https://sourceforge.net/projects/mcmc-jags/. Bi- nary distributions of JAGS for Windows and macOS can be downloaded directly from there. Binaries for various Linux distributions are also available, but not directly from Sourceforge. See http://mcmc-jags.sourceforge.net for details.
You can also download the source tarball from Sourceforge. Details on installing JAGS from source are given in a separate JAGS Installation manual.
1.2 Getting help
The best way to get help on JAGS is to use the discussion forums hosted on Sourceforge at https://sourceforge.net/p/mcmc-jags/discussion/. You will need to create a Source- forge account in order to post.
Bug reports can be sent to Occasionally, JAGS will stop with an error instructing you to send a message to this address. I am partic- ularly interested in the following issues:
• Crashes, including both segmentation faults and uncaught exceptions. • Incomprehensible error messages
• Models that should compile, but don’t
• Output that cannot be validated against other software such as OpenBUGS
• Documentation erors
If you submit a bug report, it must be reproducible. Please send the model file, the data file, the initial value file and a script file that will reproduce the problem. Describe what you think should happen, and what did happen.
1.3 Acknowledgements
Many thanks to the BUGS development team, without whom JAGS would not exist. Thanks also to for pioneering JAGS on Windows and for getting JAGS on Mac OS X to work. found many bugs while getting JAGS to work on Solaris using Sun development tools and libraries. , , and also provided useful feedback. Special thanks to Jean- who has been very diligent in providing feedback on JAGS. is a co- developer of JAGS with full access to the Sourceforge repository.
The BUGS language
A JAGS model is defined in a text file using a dialect of the BUGS language [Lunn et al., 2012]. The model definition consists of a series of relations inside a block delimited by curly brackets { and } and preceded by the keyword model. Here is a simple linear regression example:
for (i in 1:N) {
Y[i] ~ dnorm(mu[i], tau)
mu[i] <- alpha + beta * (x[i] - x.bar)
<- mean(x)
~ dnorm(0.0, 1.0E-4)
~ dnorm(0.0, 1.0E-4)
<- 1.0/sqrt(tau)
~ dgamma(1.0E-3, 1.0E-3)
2.1 Relations
Each relation defines a node in the model. The node on the left of a relation is defined in terms of other nodes – referred to as parent nodes – that appear on the right hand side. Taken together, the nodes in the model form a directed acyclic graph (with the parent/child relationships represented as directed edges). The very top-level nodes in the graph, with no parents, are constant nodes, which are defined either in the model definition (e.g. 1.0E-3), or in the data when the model is compiled (e.g. x[1]).
Relations can be of two types. A stochastic relation (~) defines a stochastic node, repre- senting a random variable in the model. A deterministic relation (<-) defines a deterministic node, the value of which is determined exactly by the values of its parents. The equals sign (=) can be used for a deterministic relation in place of the left arrow (<-).
2.2 Arrays and subsetting
Nodes defined by a relation are embedded in named arrays. Arrays can be vectors (one- dimensional), or matrices (two-dimensional), or they may have more than two dimensions.
Array names may contain letters, numbers, decimal points and underscores, but they must start with a letter. In the code example above, the node array mu is a vector of length N containing N nodes (mu[1], . . ., mu[N]). The node array alpha is a scalar. JAGS follows the S language convention that scalars are considered as vectors of length 1. Hence the array alpha contains a single node alpha[1].
2.2.1 Subsetting vectors
Subsets of node arrays may be obtained with expressions of the form alpha[e] where e is any expression that evaluates to an integer vector. Typically expressions of the form L:U are used, where L and U are integer arguments to the operator “:”. This creates an integer vector of length U −L+1 with elements L,L+1,...U −1,U.1 Both the arguments L and U must be fixed because JAGS does not allow the length of a node to change from one iteration to the next.
2.2.2 Subsetting matrices
For a two-dimensional array B, the element in row r and column c is accessed as B[r,c]. Complex subsets may be obtained with expressions of the form B[rows, cols] where rows is an integer vector of row indices and cols is an integer vector of column indices. An index expression in any dimension may be omitted, and this implies taking the whole range of possible indices. So if B is an M ×N matrix then B[r,] is the whole of row r, and is equivalent to B[r,1:N]. Likewise B[,c] is the whole of column c and is equivalent to B[1:M,c]. Finally, B[,] is the whole matrix, equivalent to B[1:M,1:N]. In this case, one may also simply write B without any square brackets. Note that writing B[] for a 2-dimensional array will result in a compilation error: the number of indices separated by commas within the square brackets must match the dimensions of the array.
2.2.3 Restrictions on index expressions
There are some restrictions on index expressions that are allowed on the left hand side of a relation. Firstly, they must be fixed, meaning that they must be expressed in terms of data, or constants defined in the model, or the index of an enclosing for loop (see below). As a counter-example, the following code snippet is illegal:
i ~ dcat(p)
x[i] ~ dnorm(0, 1)
unless i is observed and is supplied with the data. This restriction ensures that the node x[i] can be unambiguously referred to elsewhere in the model – e.g. as a function argument or the parameter for a distribution – and does not change from one iteration to another. Secondly, for vector-valued subsets, the same index must not be repeated. For example, supposed μ is a 2-vector and T is a 2 × 2 matrix. Then dmnorm(mu, T) defines a bivariate normal random variable. However, this code snippet is illegal:
indices <- c(1,1)
x[indices] ~ dmnorm(mu, T)
1If L > U then the operator : returns a vector of length zero, which may not be used to take array subsets 7
as it implies writing two different values to the same element x[1].
2.3 Constructing vectors
Vectors can be constructed using the combine function c from the bugs module, e.g.
y <- c(x1, x2, x3)
creates a new vector y combining the elements of x1, x2, and x3. The combine function can be used with a single array argument
In this case the return value v is a vector with the values of the input array a in column-major order (i.e. with the left hand index moving fastest). For example if a is a 2 × 2 matrix then this is equivalent to
v <- c(a[1,1], a[2,1], a[1,2], a[2,2])
2.4 For loops
For loops are used in the the BUGS language to simplify writing repeated expressions. A for loop takes the form:
for (i in exp) {
where exp is any expression that evaluates to an integer vector. The contents of the for loop inside the curly braces will then be expanded with the index i taking each value in the vector exp. For example
for (i in 1:3) {
Y[i] ~ dnorm(mu, tau)
is equivalent to
Y[1] ~ dnorm(mu, tau)
Y[2] ~ dnorm(mu, tau)
Y[3] ~ dnorm(mu, tau)
As in the above example, for loops generally use the sequence operator : to generate an increasing sequence of integers. This operator has high precedence, so is important to use brackets to ensure that the expression is interpreted correctly. For example, to get a for loop from 1 to m + 1 the correct expression is
for (i in 1:(m+1)) {
Omitting the brackets as in the following expression:
for (i in 1:m+1) {
gives a for loop from 2 to m+1.
The sequence operator : can only produce increasing sequences. If n < m then m:n
produces a vector of length zero and when this is used in a for loop index expression the contents of loop inside the curly brackets are skipped. Note that this behaviour is different from the sequence operator in R, where m:n will produce a decreasing sequence if n < m.
2.5 Data transformations
Sometimes it is useful to transform the data before analysing them. For example, a trans- formation of outcomes may be necessary to reduce skewness and allow the outcome to be represented by a normal or other symmetric distribution.
You can transform the data supplied to JAGS in a separate block of relations preceded by the keyword data. Here for example, the input data y is transformed via a square-root transformation to z, which is then used as an outcome variable in the model block:
for (i in 1:N) {
z[i] <- sqrt(y[i])
for (i in 1:N) {
z[i] ~ dnorm(mu, tau)
In effect, the data block defines a distinct model, which describes how the data are generated. Each node in this model is forward-sampled once, and then the node values are read back into the data table.
2.5.1 Modelling simulated data
The data block is not limited to logical relations, but may also include stochastic relations. You may therefore use it in simulations, generating data from a stochastic model that is different from the one used to analyse the data in the model statement.
This example shows a simple location-scale problem in which the “true” values of the parameters mu and tau are generated from a given prior in the data block, and the generated data is analyzed in the model block.
for (i in 1:N) {
y[i] ~ dnorm(mu.true, tau.true)
mu.true ~ dnorm(0,1);
tau.true ~ dgamma(1,3);
for (i in 1:N) {
y[i] ~ dnorm(mu, tau)
mu ~ dnorm(0, 1.0E-3)
tau ~ dgamma(1.0E-3, 1.0E-3)
Beware, however, that every node in the data statement will be considered as data in the sub- sequent model statement. This example, although superficially similar, has a quite different interpretation.
for (i in 1:N) {
y[i] ~ dnorm(mu, tau)
mu ~ dnorm(0,1);
tau ~ dgamma(1,3);
for (i in 1:N) {
y[i] ~ dnorm(mu, tau)
mu ~ dnorm(0, 1.0E-3)
tau ~ dgamma(1.0E-3, 1.0E-3)
Since the names mu and tau are used in both data and model blocks, these nodes will be considered as observed in the model and their values will be fixed at those values generated in the data block.
2.6 Node Array dimensions 2.6.1 Array declarations
JAGS allows the option of declaring the dimensions of node arrays in the model file. The declarations consist of the keyword var (for variable) followed by a comma-separated list of array names, with their dimensions in square brackets. The dimensions may be given in terms of any expression of the data that returns a single integer value.
In the linear regression example, the model block could be preceded by
var x[N], Y[N], mu[N], alpha, beta, tau, sigma, x.bar;
2.6.2 Undeclared nodes
If a node array is not declared then JAGS has three methods of determining its size.
1. Using the data. The dimension of an undeclared node array may be inferred if it is supplied in the data file.
2. Using the left hand side of the relations. The maximal index values on the left hand side of a relation are taken to be the dimensions of the node array. For example, in this case:
for (i in 1:N) {
for (j in 1:M) {
Y[i,j] ~ dnorm(mu[i,j], tau)
Y would be inferred to be an N × M matrix. This method cannot be used when there are empty indices (e.g. Y[i,]) on the left hand side of the relation.
3. Using the dimensions of the parents If a whole node array appears on the left hand side of a relation, then its dimensions can be inferred from the dimensions of the nodes on the right hand side. For example, if A is known to be an N × N matrix and
B <- inverse(A)
Then B is also an N ×N matrix.
2.6.3 Querying array dimensions
The JAGS compiler has two built-in functions for querying array sizes. The length() function returns the number of elements in a node array, and the dim() function returns a vector containing the dimensions of an array. These two functions may be used to simplify the data preparation. For example, if Y represents a vector of observed values, then using the length() function in a for loop:
for (i in 1:length(Y)) {
Y[i] ~ dnorm(mu[i], tau)
avoids the need to put a separate data value N in the file representing the length of Y.
For multi-dimensional arrays, the dim function serves a similar purpose. The dim function returns a vector, which must be stored in an array before its elements can be accessed. For
this reason, calls to the dim function must always be in a data block (see section 2.5).
D <- dim(Z)
for (i in 1:D[1]) {
for (j in 1:D[2]) {
Z[i,j] <- dnorm(alpha[i] + beta[j], tau)
Clearly, the length() and dim() functions can only work if the size of the node array can be inferred, using one of the three methods outlined above.
Note: the length() and dim() functions are different from all other functions in JAGS: they do not act on nodes, but only on node arrays. As a consequence, an expression such as dim(a %*% b) is syntactically incorrect.
Steps in running a model
JAGS is designed for inference on Bayesian models using Markov Chain Monte Carlo (MCMC) simulation. Running a model refers to generating samples from the posterior distribution of the model parameters. This takes place in five steps:
1. Definition of the model 2. Compilation
3. Initialization
4. Adaptation and burn-in 5. Monitoring
The next stages of analysis are done outside of JAGS: convergence diagnostics, model criticism, and summarizing the samples must be done using other packages more suited to this task. There are several R packages designed for running a JAGS model and analyzing the output. See chapter 4 for details.
3.1 Modules
The JAGS library is distributed along with dynamically loadable modules that extend its functionality. A module can define new objects of the following classes:
1. Functions and distributions, the basic building blocks of the BUGS language.
2. Samplers, the objects which update the parameters of the model at each iteration, and
sampler factories, the objects that create new samplers for specific model structures.
3. Monitors, the objects that record sampled values for later analysis, and monitor
factories that create them.
4. Random number generators, the objects that drive the MCMC algorithm and RNG factories that create them.
The base module and the bugs module are loaded automat
程序代写 CS代考 加微信: powcoder QQ: 1823890830 Email: powcoder@163.com