Skip to Content

bugs {R2WinBUGS}

Run WinBUGS and OpenBUGS from R or S-PLUS
Package: 
R2WinBUGS
Version: 
2.1-19

Description

The bugs function takes data and starting values as input. It automatically writes a WinBUGS script, calls the model, and saves the simulations for easy access in R or S-PLUS.

Usage

bugs(data, inits, parameters.to.save, model.file="model.bug",
    n.chains=3, n.iter=2000, n.burnin=floor(n.iter/2),
    n.thin=max(1, floor(n.chains * (n.iter - n.burnin) / n.sims)),
    n.sims = 1000, bin=(n.iter - n.burnin) / n.thin,
    debug=FALSE, DIC=TRUE, digits=5, codaPkg=FALSE,
    bugs.directory="c:/Program Files/WinBUGS14/",
    program=c("WinBUGS", "OpenBUGS", "winbugs", "openbugs"),
    working.directory=NULL, clearWD=FALSE,
    useWINE=.Platform$OS.type != "windows", WINE=NULL,
    newWINE=TRUE, WINEPATH=NULL, bugs.seed=NULL, summary.only=FALSE,
    save.history=!summary.only, over.relax = FALSE)

Arguments

data
either a named list (names corresponding to variable names in the model.file) of the data for the WinBUGS model, or (which is not recommended and unsafe) 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.
inits
a list with n.chains elements; each element of the list is itself a list of starting values for the WinBUGS model, or a function creating (possibly random) initial values. Alternatively, if inits=NULL, initial values are generated by WinBUGS. 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.
parameters.to.save
character vector of the names of the parameters to save which should be monitored
model.file
file containing the model written in WinBUGS code. The extension can be either ‘.bug’ or ‘.txt’. If the extension is ‘.bug’ and program=="WinBUGS", a copy of the file with extension ‘.txt’ will be created in the bugs() call and removed afterwards. Note that similarly named ‘.txt’ files will be overwritten. 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.
n.chains
number of Markov chains (default: 3)
n.iter
number of total iterations per chain (including burn in; default: 2000)
n.burnin
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.
n.thin
thinning rate. Must be a positive integer. Set n.thin > 1 to save memory and computation time if n.iter is large. Default is max(1, floor(n.chains *     (n.iter-n.burnin) / 1000)) which will only thin if there are at least 2000 simulations.
n.sims
The approximate number of simulations to keep after thinning.
bin
number of iterations between saving of results (i.e. the coda files are saved after each bin iterations); default is to save only at the end.
debug
if FALSE (default), WinBUGS is closed automatically when the script has finished running, otherwise WinBUGS remains open for further investigation
DIC
logical; if TRUE (default), compute deviance, pD, and DIC. This is done in WinBUGS directly using the rule pD =     Dbar - Dhat. If there are less iterations than required for the adaptive phase, the rule pD=var(deviance) / 2 is used.
digits
number of significant digits used for WinBUGS input, see formatC
codaPkg
logical; if FALSE (default) a bugs object is returned, if TRUE file names of WinBUGS output are returned for easy access by the coda package through function read.bugs (not used if program="OpenBUGS"). 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 R2WinBUGS).
bugs.directory
directory that contains the WinBUGS executable. If the global option R2WinBUGS.bugs.directory is not NULL, it will be used as the default.
program
the program to use, either winbugs/WinBUGS or openbugs/OpenBUGS, the latter makes use of function openbugs and requires the CRAN package BRugs. The openbugs/OpenBUGS choice is not available in S-PLUS.
working.directory
sets working directory during execution of this function; WinBUGS' in- and output will be stored in this directory; if NULL, a temporary working directory via tempdir is used.
clearWD
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 WinBUGS has finished. If set to TRUE, this argument is only respected if codaPkg=FALSE.
useWINE
logical; attempt to use the Wine emulator to run WinBUGS, defaults to FALSE on Windows, and TRUE otherwise. Not available in S-PLUS.
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.
bugs.seed
random seed for WinBUGS (default is no seed)
summary.only
If TRUE, only a parameter summary for very quick analyses is given, temporary created files are not removed in that case.
save.history
If TRUE (the default), trace plots are generated at the end.
over.relax
If TRUE, over-relaxed form of MCMC is used if available from WinBUGS.

Details

To run:

  1. Write a BUGS model in an ASCII file (hint: use write.model).
  2. Go into R / S-PLUS.
  3. Prepare the inputs for the bugs function and run it (see Example section).
  4. A WinBUGS window will pop up and R / S-PLUS will freeze up. The model will now run in WinBUGS. It might take awhile. You will see things happening in the Log window within WinBUGS. When WinBUGS is done, its window will close and R / S-PLUS will work again.
  5. If an error message appears, re-run with debug=TRUE.

BUGS version support:

  • WinBUGS 1.4.*default
  • OpenBUGS 2.*via argument program="OpenBUGS"

Operation system support:

  • MS Windowsno problem
  • Linux, Mac OS X and Unix in generalpossible with Wine emulation via useWINE=TRUE, but only for WinBUGS 1.4.*

If useWINE=TRUE is used, all paths (such as working.directory and model.file, must be given in native (Unix) style, but bugs.directory can be given in Windows path style (e.g. “c:/Program Files/WinBUGS14/”) or native (Unix) style (e.g. “/path/to/wine/folder/dosdevices/c:/Program Files/WinBUGS14”). This is done to achieve greatest portability with default argument value for bugs.directory.

Values

If codaPkg=TRUE the returned values are the names of coda output files written by WinBUGS 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:

n.chains
see Section ‘Arguments’
n.iter
see Section ‘Arguments’
n.burnin
see Section ‘Arguments’
n.thin
see Section ‘Arguments’
n.keep
number of iterations kept per chain (equal to (n.iter-n.burnin) / n.thin)
n.sims
number of posterior simulations (equal to n.chains * n.keep)
sims.array
3-way array of simulation output, with dimensions n.keep, n.chains, and length of combined parameter vector
sims.list
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)
sims.matrix
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
summary statistics and convergence information for each saved parameter.
mean
a list of the estimated parameter means
sd
a list of the estimated parameter standard deviations
median
a list of the estimated parameter medians
root.short
names of argument parameters.to.save and “deviance”
long.short
indexes; programming stuff
dimension.short
dimension of indexes.short
indexes.short
indexes of root.short
last.values
list of simulations from the most recent iteration; they can be used as starting points if you wish to run WinBUGS for further iterations
pD
an estimate of the effective number of parameters, for calculations see the section “Arguments”.
DIC
mean(deviance) + pD

References

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.

See Also

print.bugs, plot.bugs, as well as coda and BRugs packages

Examples

# An example model file is given in:
model.file <- system.file(package="R2WinBUGS", "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=J, y=y, sigma.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")
 
 
## Not run:
## You may need to edit "bugs.directory",
## also you need write access in the working directory:
schools.sim <- bugs(data, inits, parameters, model.file,
    n.chains=3, n.iter=5000,
    bugs.directory="c:/Program Files/WinBUGS14/")
print(schools.sim)
plot(schools.sim)
## End(Not run)

Author(s)

Andrew Gelman, gelman@stat.columbia.edu, http:/www.stat.columbia.edu/~gelman/bugsR/; modifications and packaged by Sibylle Sturtz, sturtz@statistik.tu-dortmund.de, and Uwe Ligges.

Documentation reproduced from package R2WinBUGS, version 2.1-19. License: GPL-2