Just Another Gibbs Sampler (JAGS) is an open-source program which takes as inputs data and a model speciﬁcation ﬁle (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 speciﬁed by the user, given a model speciﬁcation ﬁle
- 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:2
, "data"=<list of matrices to pass to JAGS>
, "monitor"=<list of parameters to monitor>
, "inits"=<structure of initial values>
, "chains"=<positive integer>
, "burnin"=<positive integer>
, "draws"=<positive integer>
, "thin"=<positive integer>
, "seed"=<positive integer>
- <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 ﬁle which contains the speciﬁcation of the JAGS model. If the speciﬁcation ﬁle is not in the current directory then the ﬁle name must be prepended by the path to the ﬁle, 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" speciﬁes 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 speciﬁcation ﬁle. These matrices must be deﬁned in the current workspace.
- "monitor" speciﬁes 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 speciﬁcation ﬁle. 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 deﬁned upon return of the jags() function.
- "inits" speciﬁes 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-speciﬁc structure corresponds to a parameter or latent variable, using the same id values as the ones used in the JAGS model speciﬁcation ﬁle. 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" speciﬁes 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" speciﬁes 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" speciﬁes 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" speciﬁes 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" speciﬁes 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 speciﬁcation ﬁle 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 speciﬁcation ﬁle 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 ﬁles in "$BayESHOME/Samples/3JAGSOpenBUGSStan" contain examples of using the jags() function, along with JAGS model speciﬁcation ﬁles for simple models. The JAGS interface is also accessible from the BayES main menu via Interfaces → JAGS.
2Arguments inside square brackets are optional. Optional arguments passed to the jags() function can be provided in any order, but always after the mandatory argument (model speciﬁcation ﬁle). Optional arguments always come in pairs (eg. "chains"=1).