The bugs function takes data and starting values as
input. It automatically writes a OpenBUGS script, calls the model, and
saves the simulations for easy access in R.
bugs(data, inits, parameters.to.save, n.iter, model.file="model.txt",
n.chains=3, n.burnin=floor(n.iter / 2), n.thin=1,
saveExec=FALSE,restart=FALSE,
debug=FALSE, DIC=TRUE, digits=5, codaPkg=FALSE,
OpenBUGS.pgm=NULL,
working.directory=NULL,
clearWD=FALSE, useWINE=FALSE, WINE=NULL,
newWINE=TRUE, WINEPATH=NULL, bugs.seed=1, summary.only=FALSE,
save.history=(.Platform$OS.type == "windows" | useWINE==TRUE),
over.relax = FALSE)either a named list (names corresponding to variable names
in the model.file) of the data for the OpenBUGS model,
or a vector or list of the names of the data objects used by
the model. If data is a one element character vector (such as "data.txt"),
it is assumed that data have already been written to the working directory into that file,
e.g. by the function bugs.data.
a list with n.chains elements; each element of the
list is itself a list of starting values for the OpenBUGS model,
or a function creating (possibly random) initial values.
Alternatively, if inits=NULL, initial values are generated
by OpenBUGS. If inits is a character vector with n.chains elements,
it is assumed that inits have already been written to the working directory into those files,
e.g. by the function bugs.inits.
character vector of the names of the parameters to save which should be monitored
File containing the model written in OpenBUGS code. The
extension must be .txt. The default location is given by working.directory.
The old convention allowing model.file to be named .bug has been eliminated
because the new OpenBUGS feature that allows the program image
to be saved and later restarted uses the .bug extension for the saved
images.
Alternatively, model.file can be an R function that contains a BUGS model that is written to a
temporary model file (see tempfile) using write.model.
number of Markov chains (default: 3)
number of total iterations per chain (including burn in; default: 2000)
length of burn in, i.e. number of iterations to
discard at the beginning. Default is n.iter/2, that is,
discarding the first half of the simulations.
Thinning rate. Must be a positive integer. The default is
n.thin = 1. The thinning is implemented in the OpenBUGS update phase, so
thinned samples are never stored, and they are not counted in n.burnin or
n.iter. Setting n.thin=2, doubles the number of iterations OpenBUGS
performs, but does not change n.iter or n.burnin. Thinning implemented
in this manner is not captured in summaries created by packages such as coda.
If TRUE, a re-startable image of the OpenBUGS execution is
saved with basename (model.file) and extension .bug in the working
directory, which must be specified. The .bug files can be large, so
users should monitor them carefully and remove them when not needed.
If TRUE, execution resumes with the final status from
the previous execution stored in the .bug file in the working directory.
If n.burnin=0,additional iterations are performed and all iterations since
the previous burnin are used (including those from past executions). If
n.burnin>0, a new burnin is performed, and the previous iterations are
discarded, but execution continues from the status at the end of the previous
execution. When restart=TRUE, only n.burnin, n.iter,
and saveExec inputs
should be changed from the call creating the .bug file, otherwise
failed or erratic results may be produced. Note the default has n.burnin>0.
if FALSE (default), OpenBUGS is closed automatically
when the script has finished running, otherwise OpenBUGS remains open
for further investigation. The debug option is not available for linux execution.
logical; if TRUE (default), compute deviance, pD,
and DIC. The results are extracted directly
from the OpenBUGS log, which uses the rule pD =
Dbar - Dhat. If extraction fails or
if there are less iterations than required for the
adaptive phase, the rule pD=var(deviance) / 2
is computed in R. See bugs.log for more
information on extracting results from the log file.
number of significant digits used for OpenBUGS input, see
formatC
logical; if FALSE (default) a bugs object
is returned, if TRUE file names of OpenBUGS output are
returned for easy access by the coda package through function
read.bugs.
A bugs object can be converted to an mcmc.list object as
used by the coda package with the method as.mcmc.list
(for which a method is provided by R2OpenBUGS).
For Windows or WINE execution, the full path
to the OpenBUGS
executable. For linux execution, the full path to the
OpenBUGS executable or shell script (the path to the shell
script is not
required if the OpenBUGS shell script is in the user's PATH variable).
If NULL (unset) and the environment variable
OpenBUGS_PATH is set the latter will be used as the default.
If NULL (unset), the environment variable
OpenBUGS_PATH is unset and the global option
R2OpenBUGS.pgm is not NULL the latter will be
used as the default.
If none of the former are set and OS is Windows, the
most recent OpenBUGS version
registered in the Windows registry will be used as the default.
For other operating systems, the location is guessed by Sys.which("OpenBUGS").
sets working directory during execution of
this function; OpenBUGS' input and output will be stored in this
directory; if NULL, a temporary working directory via
tempdir is used.
logical; indicating whether the files data.txt,
inits[1:n.chains].txt, log.odc, codaIndex.txt,
and coda[1:nchains].txt should be removed after OpenBUGS has
finished. If set to TRUE, this argument is only respected if
codaPkg=FALSE.
logical; attempt to use the Wine emulator to run
OpenBUGS. Default is FALSE. If WINE is used, the arguments OpenBUGS.pgm and working.directory must be given in form of Linux paths
rather than Windows paths (if not NULL).
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.
Use new versions of Wine that have winepath
utility
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.
Random seed for OpenBUGS. Must be an integer between 1-14. Seed specification changed between WinBUGS and OpenBUGS; see the OpenBUGS documentation for details.
If TRUE, only a parameter summary for very quick analyses is given,
temporary created files are not removed in that case.
If TRUE (the default), trace plots are generated at the end.
If TRUE, over-relaxed form of MCMC is used if available from OpenBUGS.
If codaPkg=TRUE the returned values are the names
of coda output files written by OpenBUGS containing
the Markov Chain Monte Carlo output in the CODA format.
This is useful for direct access with read.bugs.
If codaPkg=FALSE, the following values are returned:
see Section ‘Arguments’
see Section ‘Arguments’
see Section ‘Arguments’
see Section ‘Arguments’
number of iterations kept per chain (equal to
(n.iter-n.burnin) / n.thin)
number of posterior simulations (equal to
n.chains * n.keep)
3-way array of simulation output, with dimensions n.keep, n.chains, and length of combined parameter vector
list of simulated parameters:
for each scalar parameter, a vector of length n.sims
for each vector parameter, a 2-way array of simulations,
for each matrix parameter, a 3-way array of simulations, etc.
(for convenience, the n.keep*n.chains simulations in
sims.matrix and sims.list (but NOT sims.array) have been randomly
permuted)
matrix of simulation output, with
n.chains*n.keep rows and one column for each element of
each saved parameter (for convenience, the n.keep*n.chains
simulations in sims.matrix and sims.list (but NOT sims.array) have
been randomly permuted)
summary statistics and convergence information for each saved parameter.
a list of the estimated parameter means
a list of the estimated parameter standard deviations
a list of the estimated parameter medians
names of argument parameters.to.save and
“deviance”
indexes; programming stuff
dimension of indexes.short
indexes of root.short
list of simulations from the most recent iteration; they can be used as starting points if you wish to run OpenBUGS for further iterations
an estimate of the effective number of parameters, for calculations see the section “Arguments”.
mean(deviance) + pD
To run:
Write a BUGS model in an ASCII file (hint: use
write.model).
Go into R.
Prepare the inputs for the bugs function and run it (see
Example section).
An OpenBUGS window will pop up and R will freeze up. The model will now run in OpenBUGS. It might take awhile. You will see things happening in the Log window within OpenBUGS. When OpenBUGS is done, its window will close and R will work again.
If an error message appears, re-run with debug=TRUE.
BUGS version support:
OpenBUGS >=3.2.1
Operation system support:
MS Windows no problem
Linux, intel processors GUI display and graphics not available.
Mac OS X and Unix in
general possible with Wine emulation via useWINE=TRUE
If useWINE=TRUE is used, all paths (such as
working.directory and model.file, must be given in
native (Unix) style, but OpenBUGS.pgm can be given in
Windows path style (e.g. “c:/Program Files/OpenBUGS/”) or
native (Unix) style
(e.g. “/path/to/wine/folder/dosdevices/c:/Program
Files/OpenBUGS/OpenBUGS321/OpenBUGS.exe”).
Gelman, A., Carlin, J.B., Stern, H.S., Rubin, D.B. (2003): Bayesian Data Analysis, 2nd edition, CRC Press.
Sturtz, S., Ligges, U., Gelman, A. (2005): R2WinBUGS: A Package for Running WinBUGS from R. Journal of Statistical Software 12(3), 1-16.
print.bugs, plot.bugs, as well as
coda and BRugs packages
# NOT RUN {
# }
# NOT RUN {
# An example model file is given in:
model.file <- system.file(package="R2OpenBUGS", "model", "schools.txt")
# Let's take a look:
#file.show(model.file)
# Some example data (see ?schools for details):
data(schools)
schools
J <- nrow(schools)
y <- schools$estimate
sigma.y <- schools$sd
data <- list ("J", "y", "sigma.y")
inits <- function(){
list(theta=rnorm(J, 0, 100), mu.theta=rnorm(1, 0, 100),
sigma.theta=runif(1, 0, 100))
}
## or alternatively something like:
# inits <- list(
# list(theta=rnorm(J, 0, 90), mu.theta=rnorm(1, 0, 90),
# sigma.theta=runif(1, 0, 90)),
# list(theta=rnorm(J, 0, 100), mu.theta=rnorm(1, 0, 100),
# sigma.theta=runif(1, 0, 100))
# list(theta=rnorm(J, 0, 110), mu.theta=rnorm(1, 0, 110),
# sigma.theta=runif(1, 0, 110)))
parameters <- c("theta", "mu.theta", "sigma.theta")
## You may need to specify "OpenBUGS.pgm"
## also you need write access in the working directory:
schools.sim <- bugs(data, inits, parameters, model.file,
n.chains=3, n.iter=5000)
print(schools.sim)
plot(schools.sim)
# }
Run the code above in your browser using DataLab