OpenBUGS is another open-source program that is very similar to JAGS. It too takes as inputs data and a model speciﬁcation ﬁle (written in OpenBUGS’ own language) and draws samples from the posterior distribution of the model’s parameters or latent variables, using an expert system to pick the most appropriate method for sampling from the posterior.
BayES’ openbugs() function provides a convenient interface to OpenBUGS, which allows the user to:
- pass BayES matrices as input data to OpenBUGS
- request OpenBUGS to draw samples from the posterior distribution of parameters speciﬁed by the user, given a model speciﬁcation ﬁle
- retrieve the draws from OpenBUGS, summarize them and print summary statistics on the BayES console
- store the draws from OpenBUGS in a BayES model item, making them available for post estimation analysis
The general syntax of the openbugs() function is the following:3
, "data"=<list of matrices to pass to OpenBUGS>
, "monitor"=<list of parameters to monitor>
, "summarize"=<list of parameters to summarize>
, "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 openbugs() function. If no model name is provided the results from OpenBUGS 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 OpenBUGS model. If the speciﬁcation ﬁle is not in the current working 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 openbugs() function.
- "data" speciﬁes the data matrices that will be passed as input to OpenBUGS. <list of matrices> is a list of the id values of matrices (comma-separated names inside curly brackets), as they appear in the OpenBUGS model speciﬁcation ﬁle. These matrices must be deﬁned in the current workspace.
- "monitor" speciﬁes the parameters or latent variables for which OpenBUGS 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 OpenBUGS model speciﬁcation ﬁle. If no monitors are set OpenBUGS 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 openbugs() function.
- "summarize" speciﬁes the parameters or latent variables for which OpenBUGS will set “summary monitors". OpenBUGS will sample from the posterior of these parameters/latent variables but, instead of storing these draws, it will only provide summary statistics for them (calculated inline). This option can lead to a large reduction in memory usage compared to the case where a large number of parameters/latent variables are monitored using the "monitor" option. The "summarize" option is currently not implemented and will be ignored.
- "inits" speciﬁes the initial values per chain used by OpenBUGS. <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 OpenBUGS 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 OpenBUGS 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 OpenBUGS will run in parallel. The right-hand side must be a positive integer and the default value is 1. Note that OpenBUGS can use up to 14 diﬀerent values for the seed number of its random-number generators. If more than 14 chains are requested by the user these seed values will be recycled, eﬀectively leading to chains with exactly the same draws from the posterior.
- "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 OpenBUGS. The right-hand side must be a positive integer and the default value is 42.
- "window" speciﬁes whether OpenBUGS should run in its own graphical environment (under Microsoft® Windows® only) or print any output on the BayES console. The default value value is true, which requests OpenBUGS to run using its own GUI. Under Linux systems OpenBUGS does not provide a GUI and, therefore, this option is ignored.
- "debug" speciﬁes whether the OpenBUGS window will remain open after completion of the Gibbs sampler (under Microsoft® Windows® only). The default value is "false", in which case the OpenBUGS window closes after completion of the Gibbs sampler and control is returned to BayES automatically. Because the "debug" option requires an OpenBUGS window, the value of the "window" option is overwritten to true whenever the user sets "debug" to true. This option is ignored under Linux systems.
When OpenBUGS runs using its GUI (under Microsoft® Windows® only) it prints any output on its own output window. When OpenBUGS runs without its GUI then BayES grabs any OpenBUGS output intended for the system’s command console and redirects it to the BayES console in real time. This output is entirely determined by OpenBUGS and it includes information on the stage of the estimation process (model check, loading data, etc.) and very limited information on the progress of the sampler (only whether the burn-in phase is complete).
Many of the sample script ﬁles in "$BayESHOME/Samples/3JAGSOpenBUGSStan" contain examples of using the openbugs() function, along with OpenBUGS model speciﬁcation ﬁles for simple models. The OpenBUGS interface is also accessible from the BayES main menu via Interfaces → OpenBUGS.
3Arguments inside square brackets are optional. Optional arguments passed to the openbugs() 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).