*! version 1.1.1 27sep2013

Title

st2openbugs -- A simple Interface between Stata and OpenBUGS on Linux

Syntax

st2openbugs, st2openbugs_required_options [st2openbugs_other_options]

st2openbugs_required_options

model(filename) Name of the text file with the OpenBUGS model

data(filename) Name of the text file with the data

nchains(#) Number of chains to be run

inits(filenamelist) Name list of text file(s) with initial values
of the chain(s)

savepars(parlist) List of parameters to be saved

st2openbugs_other_options

wdpath(path) Path of working directory; by default the path set
by OpenBUGS

nburn(#) Number of 'burn-in' iterations; default is
nburn(5000)

nupdate(#) Number of updates after 'burn-in'; default is nupdate(20000)

prefix(literal) Prefix to be added to files created when running
the command

scriptname(filename) Name of the BUGS script; default is
'script.txt'

delcodafiles Delete auxiliary CODA files needed for creating dta
file

Description

st2openbugs implements a simple interface between Stata and OpenBUGS
(Lunn et al., 2009) on Linux. OpenBUGS is
called with a BUGS script written from within a Stata session. The CODA output
produced by the MCMC simulation performed by OpenBUGS is reformatted and saved
as a Stata dta file (note that names of parameters or nodes may result changed
to conform to Stata syntax; especifically, forbidden characters like '.' or '['
are replaced with underscores, '_'). This allows the use of Stata's capabilities
to further process the output (see the companion st2openbugsana command).

Options

model(filename) specifies the name of the ASCII file containing the
OpenBUGS model. The model must be defined using BUGS code. A required option.

data(filename) specifies the name of the ASCII file containing the data.
The data must be in BUGS format. A required option.

nchains(#) sets the number of chains that will be simulated. A required
option.

inits(filenamelist) specifies the name list of the ASCII file(s)
containing the initial values of the chain(s). The file(s) must be in BUGS
format. A required option.

savepars(parlist) specifies the parameters for which the values of the
simulated chain(s) will be saved. The 'deviance' node is always saved by default.
A required option.

wdpath(path) specifies the path of the directory in which a) the model,
data and initial values are located, b) OpenBUGS will be executed and c) all
the output files will be saved; if not set, it is the path set by OpenBUGS by
default (normally the path of the user's home directory). Due to OpenBUGS
syntax, the path must be fully specified, avoiding the use of the tilde (~) to
refer to the home directory.

nburn(#) sets the number of 'burn-in' iterations discarded at the
beginning of each chain. The default is nburn(5000).

nupdate(#) sets the number of MCMC iterations by chain (excluding
'burn-in'). The default is nupdate(20000).

prefix(literal) specifies the literal string that will be added as a
prefix a) to the name of the OpenBUGS script written, if it is not specified by
the scriptname option, b) to the name of the CODA and log files created
by OpenBUGS and c) to the Stata dta file saved, 'CODA.dta'. By default no
prefix is added.

scriptname(filename) specifies the name of the BUGS script to be written
and subsequently executed by OpenBUGS. The default name is 'script.txt'.

delcodafiles deletes auxiliary CODA files needed for creating the dta
file, but not needed for further analysis within Stata.

Remarks

The code is written for OpenBUGS version 3.2.2. This command does not provide any
facilities for writing model, data, or initialization ASCII files from within
Stata. To this end, the interested user may find useful some of the Stata
commands written by Thompson et al. (2006).
The whole set of commands is installed executing in Stata: net from website,
where 'website' is http://www2.le.ac.uk/departments/health-sciences/research/ships/genetic-epidemiology/software-programs-examples-datasets-and-downloads/winbugsfromstata

Examples

The files used in these examples are taken from the /doc/Examples directory of
the OpenBUGS distribution (they can also be copied from http://www.openbugs.info/Examples/Rats.html,
where the data is documented, but note that a typo in line 7 of the model,
where reads 'culmative' instead of 'cumulative', should be corrected). It is
assumed that the BUGS model is saved in 'Ratsmodel.txt', the data in
'Ratsdata.txt' and the two files with initial values are 'Ratsinits.txt' and
'Ratsinits1.txt'.

A MCMC simulation with only one chain, setting the initial values from the
'Ratsinits.txt' file, and saving parameters 'alpha', 'alpha0' and 'sigma' (note
that 'alpha' expands to 30 nodes, one for each rat). Files 'Ratsmodel.txt',
'Ratsdata.txt' and 'Ratsinits.txt' must be located on the default working
directory of OpenBUGS, which normally is the user's home directory, e.g.
/home/myname:

. st2openbugs, m(Ratsmodel.txt) d(Ratsdata.txt) n(1) i(Ratsinits.txt) s(alpha alpha0 sigma)

The same, but setting the number of 'burn-in' iterations to 1000 and the number
of update iterations to 10000:

. st2openbugs, m(Ratsmodel.txt) d(Ratsdata.txt) n(1) i(Ratsinits.txt) s(alpha alpha0 sigma) nb(1000) nu(10000)

Like the first example, but with 2 chains, whose respective initial values are
saved in the 'Ratsinits.txt' and 'Ratsinits1.txt' files. Besides, the
simulations corresponding to the 'alpha0' parameter are not saved, and the
prefix 'Rats' is added to the name of every file saved:

. st2openbugs, m(Ratsmodel.txt) d(Ratsdata.txt) n(2) i(Ratsinits.txt Ratsinits1.txt) s(alpha sigma) p(Rats)

Like the first example, but the working directory is set to /home/myname/bugs.
The 'Ratsmodel.txt', 'Ratsdata.txt' and 'Ratsinits.txt' files must be located
on that directory:

. st2openbugs, m(Ratsmodel.txt) d(Ratsdata.txt) n(1) i(Ratsinits.txt) s(alpha alpha0 sigma) w(/home/myname/bugs)

Author

Ignacio López de Ullibarri

Department of Mathematics

University of A Coruña, Spain

E-mail: ilu@udc.es

References

Lunn D, Spiegelhalter D, Thomas A and Best N (2009). The BUGS project: Evolution,
critique, and future directions, Statistics in Medicine, 28: 3049-3067

Thompson J, Palmer T and Moreno S (2006). Bayesian analysis in Stata
with WinBUGS, The Stata Journal, 6:530-549