3.2 Interface to JAGS

Just Another Gibbs Sampler (JAGS) is an open-source program which takes as inputs data and a model specification file (written in JAGS’ own language) and draws samples from the posterior distribution of the model’s parameters or latent variables, picking the most appropriate sampling method automatically.

BayES’ jags() function provides a convenient interface to JAGS, which allows the user to:

• pass BayES matrices as input data to JAGS
• request JAGS to draw samples from the posterior distribution of parameters specified by the user, given a model specification file
• retrieve the draws from JAGS, summarize them and print summary statistics on the BayES console
• store the draws from JAGS in a BayES model item, making them available for post estimation analysis

The general syntax of the jags() function is the following:²

where:

• <model name> is a BayES id value which will be associated with the model resulting from executing the jags() function. If no model name is provided the results from JAGS will still be returned to BayES and summarized, but they will not be stored for further analysis. jags(), openbugs() and stan() are the three interface functions that provide the highest level of integration with BayES: the results from these functions are stored in BayES model items, on which all BayES functions which operate on models can be used.
• <model specification file> is a string pointing to the file which contains the specification of the JAGS model. If the specification file is not in the current directory then the file name must be prepended by the path to the file, either in absolute terms (eg. "C:/MyFiles/myModel.txt") or relative to the current working directory (eg. "../myModel.txt"). This is the only mandatory argument of the jags() function.
• "data" specifies the data matrices that will be passed as input to JAGS. <list of matrices> is a list of the id values of matrices (comma-separated names inside curly brackets), as they appear in the JAGS model specification file. These matrices must be defined in the current workspace.
• "monitor" specifies the parameters or latent variables for which JAGS will store the draws obtained from their posterior distributions. <list of parameters to monitor> is a list of strings (comma-separated strings inside curly brackets) that specify the names of the parameters/latent data that should be monitored, as they appear in the JAGS model specification file. If no monitors are set JAGS will still draw samples from the posterior but these will not be saved and, subsequently, no BayES model item will be defined upon return of the jags() function.
• "inits" specifies the initial values per chain used by JAGS. <structure of initial values> is a BayES structure, the elements of which could be structures themselves. Each element of the chain-specific structure corresponds to a parameter or latent variable, using the same id values as the ones used in the JAGS model specification file. It is possible to provide initial values for all parameters/latent variables or only a subset of them. It is also possible to leave entire chains uninitialized. In such cases JAGS will generate initial values for the chains/parameters/latent variables which are not initialized by the user.
• "chains" specifies the number of chains that JAGS will run in parallel. The right-hand side must be a positive integer and the default value is 1.
• "burnin" specifies the number of draws from the posterior that will be discarded (per chain) to avoid dependence of the results on initial values. The right-hand side must be a positive integer and the default value is 10,000.
• "draws" specifies the number of draws from the posterior that will be retained, per chain. The right-hand side must be a positive integer and the default value is 20,000.
• "thin" specifies the number of draws from the posterior that will be skipped (after the burn-in phase) per retained draw, to avoid high autocorrelation of the retained draws. For example, if the thinning parameter is set to 3, then only one in three consecutive draws will be retained and become available for inference and post-estimation analysis. The right-hand side must be a positive integer and the default value is 1.
• "seed" specifies the seed for the random-number generator used by JAGS. The right-hand side must be a positive integer and the default value is 42.

Under Linux and macOS systems, the path to the JAGS model specification file must not contain any spaces.

As the jags() function executes, JAGS attempts to print output on the system’s command console. BayES grabs this output and redirects it to the BayES main console in real time. This output is entirely determined by JAGS and it includes information on the model specification file used in the current run, any errors or warnings and, most importantly, information on the progress of the sampler relative to the total number of requested draws from the posterior.

Many of the sample script files in "$BayESHOME/Samples/3$-$JAGS$-$OpenBUGS$-$Stan" contain examples of using the jags() function, along with JAGS model specification files for simple models. The JAGS interface is also accessible from the BayES main menu via Interfaces → JAGS.