JAGS 4.0.0 is released

After a long gestation period, JAGS 4.0.0 was finally released last week. If you go to the project page on Sourceforge then you should see an appropriate download link for your platform (binary packages for Windows and Mac OS X; source tarball for other platforms). Binary packages are also available for some Linux distributions. See the JAGS homepage for details.

Mac users should note that you need OS X 10.9 or later (i.e. Mavericks, Yosemite, or El Capitan). Older releases are no longer supported.

The rjags package for R has been updated to work with the new release of JAGS. It is not yet uploaded to CRAN, and the version of rjags that is available on CRAN (rjags_3-15) does not work with JAGS 4.0.0. However, you can download rjags_4-3 from Sourceforge. Again, binary packages are available for Windows (.zip) and Mac OS X (.tgz).

What’s new in JAGS 4.0.0 part 4/4: Things that are not new

Somewhat undermining the premise of this series of posts, the last entry is about things that are not new.

The JAGS documentation needs a major overhaul. Although I started revising the documentation, I backed out my changes for the release of JAGS 4.0.0 because it would have taken too long to complete. It was much more important to get the new release out than to update the documentation. One motivation for writing these blog posts was to draw users’ attention to new features that I wanted people to be aware of, even though they are not documented. There are other features – new distributions and samplers – that are currently undocumented and hence hidden. These will miraculously appear as “new” features as they are documented during the JAGS 4.x.y release series.

What’s new in JAGS 4.0.0 part 3/4: R-style features

The BUGS language is syntactically very similar to R and there are several packages that allow R users to interface with the JAGS library. When you are using both R and JAGS simultaneously, small differences between the languages can be frustrating. Consequently there is some pressure to narrow the gap between the two languages.  There are some things we cannot change, such as the parameterization of the distributions, but there is a tendency for JAGS to become more R-like with each release. JAGS 4.0.0 introduces a few more R-like features. Continue reading

What’s new in JAGS 4.0.0 part 2/4: dealing with undefined nodes

I know from questions in the JAGS forums that undefined nodes can be a source of frustration for JAGS users. Here is a simple example:

for (i in 2:N) {
    x[i] ~ dnorm(0, 1)

The compiler creates a node array x of size N, but the element x[1] is undefined. In JAGS 3.4.0 this can potentially cause two problems.

Firstly, if you tried to set a trace monitor for x then you would get an unhelpful message “Node not found”. This is a frequent issue with state space models, in which the observations for series i start at time T[i] and anything that happens in the range 1:(T[i]-1) is undefined.

Up until now, the remedial action has been to identify the undefined elements of the array and fill them in with an arbitrary constant value, e.g.

x[1] <- 0

so that the node x[1:N] can be defined and monitored. This is no longer necessary. JAGS 4.0.0 allows you to create a trace monitor for a node array that has undefined values. The elements of the monitor corresponding to the undefined elements have value NA (not available).

The second problem occurs if you reference the undefined value x[1] in the model, by using it on the right hand of a relation. It is easy to do this indirectly. For example, given this

y <- sum(x)

the compiler will try, and fail, to create a node y that is the sum of all the elements of x. The error message from the compiler in this case is

Unable to resolve node XXX. This may be due to an undefined
ancestor node or a directed cycle in the graph

where “XXX” is some node in the graph. It might be the missing node x[1] but usually it is another node that depends on it (e.g. y or some node that that depends on y). This is why the error message refers to an “undefined ancestor”. Tracing the error back from the cited node XXX to the source of the problem can be hard work. In addition, the message fails to distinguish between two completely different issues: undefined nodes versus directed cycles.

In JAGS 4.0.0, the compiler tries a lot harder to zero in on the source of the problem and distinguish between the two issues. The error message for the above model is now.

Unable to resolve the following parameters:
Either supply values for these nodes with the data
or define them on the left hand side of a relation.

If you have a directed cycle, like this

model {
   y[1] ~ dnorm(y[2], tau)
   y[2] ~ dnorm(y[1], tau)
   tau ~ dgamma(1,1)

then the message will be

Possible directed cycle involving some or all
of the following nodes:

There is no remedial action in the case of a directed cycle, as these are still forbidden in JAGS.

Don’t forget the brackets

I have been helping a user who found some discrepancies between the results from JAGS and OpenBUGS. Such problems always concern me and I give them high priority. In this case, there were several differences in parameterizatino between the JAGS and OpenBUGS models. Among them, the JAGS model included this line:

prec[g] <- 1.0 / sigma[g]*sigma[g]

Most users will recognize the calculation as a transformation from a standard deviation (sigma) to a precision parameter (prec). It is common practice to define a prior on standard deviation and then transform it to the precision parameter required by the dnorm distribution. Unfortunately, this expression is incorrect. To understand why you need to know something about operator precedents.

Like all other languages, operators in JAGS has built-in precedence. For example, multiplications (*) and divisions (/) are carried out before additions (+) and subtractions (-). The multiplication and division operators have the same precedence and when they appear in the same expression they are evaluated from left to right. So in the above expression  JAGS first divides 1.0 by sigma[g] and then multiplies it by sigma[g]. The two operations cancel out so the relation that defines prec[g] is equivalent to

prec[g] <- 1.0

In a small model the consequences of this should be easy to spot. Since the value of sigma[g] has no influence on any other node, its posterior distribution is the same as the prior. Spotting this requires the user to monitor sigma[g] and in a large model with many sigma parameters it might be easy to miss this step.

The solution of course is to put brackets in the expression so that the order of evaluation is clear

prec[g] <- 1.0 /( sigma[g]*sigma[g])

Do not hesitate to do this. Brackets are never harmful (provided you put them in the right place, of course).

The standard-deviation-to-precision transformation is such a common practice that I am now wondering how much code is out there that repeats this simple error. It would be helpful for JAGS to raise some kind of “red flag” to the user in cases such as this.

What’s new in JAGS 4.0.0 part 1/4: Reproducibility and testing

As promised, this is the first of a series of posts explaining some of the changes in JAGS 4.0.0 compared to previous versions. This post deals with two important changes that are may not be obvious


Previous versions of JAGS had problems with reproducibility. Specifically, JAGS did not produce exactly the same output when given the same seeds for the random number generators in each chain. This problem is now fixed in JAGS 4.0.0. It required a major overhaul to fix, but the effort was worthwhile. It is important for scientific research to be reproducible and it is a requirement in commercial environments where analyses need to be validated.

The underlying problem was that the very first versions of JAGS stored nodes in memory in an order that was, in principle, arbitrary, with the consequence that the sampling order of the nodes was also arbitrary. This was not obvious at first because I tested JAGS on small problems and used the standalone command line interface. Under these conditions the internal ordering of nodes was the same from one run to another. But when people started using JAGS with larger problems and the R interface was developed, the reproducibility problem emerged. It first came to my attention 3 years ago.

All analyses in JAGS 4.0.0 should be reproducible, and if they are not then please let me know. Please note that I can only guarantee reprodicibility of analyses using exactly the same JAGS version, i.e. when the next release comes out it may produce different results from JAGS 4.0.0, although it should still be internally consistent. One isse to watch out for if you care about reproducibility is that some highly optimized math libraries (such as Intel MKL) sacrifice bitwise reproducibility for speed.This behaviour can be modified but is much slower, losing the advantage of a high-performance library.


JAGS is becoming quite popular. Version 3.4.0 was downloaded nearly 50,000 times from the Sourceforge web site. With this popularity comes the responsibility to ensure that it is working correctly.  So JAGS 4.0.0 introduces unit tests to ensure that the functions and distributions in JAGS are working as documented.

If you are using a binary version of JAGS this will not affect you (You can assume the person who built the binary package ran the tests for you). If you are installing JAGS from source then you can run the tests from the build directory with

make check

The underlying test framework id CppUnit, so you need to have this installed to run the tests. This choice may have been a mistake because it turns out that CppUnit is no longer actively developed.  So I may change to an alternative testing framework in the future, but my immediate priority is to improve coverage of the tests during the 4.x.y release series.