batchBUGS: Run OpenBUGS from R in batch mode

Description

This function takes model, data, starting values, and a
properly formatted OpenBUGS script file as input and executes OpenBUGS
returning its output to R. OpenBUGS execution occurs in a temporary
directory with a unique name to avoid conflicts if multiple OpenBUGS
runs are initiated from the same directory.

Arguments

modelFile

Filename of the BUGS model code.
A full path to the model is needed unless the
file is saved in the baseDir directory.

data

A list with R variables to become the input data for the
BUGS model. The list variable names must be explicitly assigned in
the list and correspond to the names in the BUGS modelFile.
Alternatively, data can be the name of an external file (full
path if not in the baseDir directory) with the input data in
a valid BUGS data format. The data are written to the file
'data.txt' in the BUGS execution directory.

inits

A list of starting values for the BUGS model, or a
function creating initial values. The inits are written to files
with names 'inits1.txt' ... "initsmax.txt" in the the BUGS execution
directory. Each set of starting values must be in a list, and the
starting lists must be contained in a list, even if there is a
single list of starting values (i.e., a list with 1 list element).
Alternatively, inits can be a character vector of length numChains,
with the names of files containing the starting lists. If inits is
NULL, no init files are written and the script file must contain a
generate inits command.

cmdTemplate

Filename of the BUGS script meta-commands. A
full pathname is needed unless the file is in the baseDir
directory. A sample template is included below. It is important to
include modelQuit('yes') as the last command when executing in
Windows, or OpenBUGS will not return control to R. In linux, the
final command must be modelQuit(). If OpenBUGS encounters a trap in
Windows, control of execution will not return to R until an 'esc' is
typed in R. If OpenBUGS encounters a trap in linux, control returns
to R.

numChains

Number of Markov chains (default:1). If this number
is not equal to the default, corresponding changes have to made in the
BUGS command template.

digits

Number of significant digits used for BUGS data input
(default=5). It has no effect if data or inits files are supplied.

baseDir

The default is the current R work directory, but the
default search path for input files can be specified.

workName

The name of the directory for all BUGS input and
output (execution directory). The name is appended to
baseDir and the directory is created. If the directory
already exists, it is reused without warning. The default is
'temp'.

index

An integer combined with a data/time stamp appended to
the name of BUGSWorkName so it has a unique identifiable name
with Monte Carlo iterations. When Index=0, no number is appended.

codaStem

When FALSE, the coda output are read and returned as a
coda class R object. When TRUE, the names of the coda output
are returned which can be read by the function read.openbugs
in the coda R package.

delWorkFolders

Logical, whether to delete the temporary
folder (default =TRUE).

stripComments

When TRUE, comments are removed from the model
and data files. Versions 3.0.3 and earlier of OpenBUGS fail when
executed in linux if comments are present. The problem has been
corrected in later versions.

seed

A seed for the random number generator can be
specified. The value of the seed must be one of 1, 2, 3, ..., 14.
OpenBUGS uses the same starting seed by default (1) for all models,
so it is not required to set the seeds, but it does make
reproducibility more explicit. Note that seed set commands must be
added to the BUGS command template as indicated below. Note also
that setting seeds is not the same as setting initial values for
different chains.

useWINE

logical; attempt to use the Wine emulator

WINE

character, path to ‘wine’ binary file, it is tried
hard (by a guess and the utilities which and locate)
to get the information automatically if not given.

newWINE

Use new versions of Wine that have ‘winepath’
utility

WINEPATH

character, path to ‘winepath’ binary file, it is
tried hard (by a guess and the utilities which and
locate) to get the information automatically if not given.

Details

The BRugs package does not currently work properly in linux, and it
executes an old version of OpenBUGS in windows.
batchBUGSexecutes OpenBUGS from R using system calls that
automatically detect the operating system.

batchBUGS also executes under WINE for use on Apple Computers.
One objective is to execute BUGS from R in all of these computing
environments with a minimal number of changes.

The user must supply a BUGS script meta-file supplying the OpenBUGS
commands that correspond to menu selections. All input files should
be stored in the R working directory, or full pathnames must be
supplied. OpenBUGS includes documentation for the scripting commands.

BatchBUGS creates uniquely named directories for BUGS execution needed
for parallel executions common with Monte Carlo simulation. By
default, these work directories are not saved.

Older versions of OpenBUGS(<=3.0.3) fail when executed under linix if
a model or data file contains comments. The batchBUGS function
removes all comments and places copies of these modified files in the
BUGS working directory by default.

The batchBUGS code includes the bugsData,
bugsInits, write.datafile, and formatdata
functions from the BRugs package. It includes the
winedriveMap, winedriveTr, winedriveRTr,
win2native, and native2win, functions from the
R2WinBUGS package.

Value

A list with two elements. The first is codaCreated, which is 1
if CODA files were successfully created, and 0 otherwise. The second
element, named codaOut is a mcmc.list ("coda") object containing the
simulated values of the parameters monitored in the BUGS simulation.
Alternatively, the second element can be a text string with the
location (in the execution directory, which is not removed) of the
output coda ascii files. The codaOut object is a text string with the
temporary directory (not removed) containing the input files if BUGS
failed to create coda files.

Note

Before executing batchBUGS, place the model file and the BUGS
command template in the R working directory. Otherwise, the full path
to their locations must be explicitly specified in the arguments.

Filenames in the BUGS command script must have a pre-specified
symbolic pathname. The user must give a symbolic path named $TEMPDIR
in the command script, and this symbolic name is replaced with the
full path name by batchBUGS. The seed can also be set by including
the symbolic name $SEED. An example command script and model file for
use with the example R code follow. The code below must be stored in
the R working directory with names "cmds.txt" and "emaxmodel.txt" to
execute the example in the example section.