R2OpenBUGS (version 3.2-2.2)

bugs: Run OpenBUGS from R

Description

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.

Usage

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)

Arguments

data

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

inits

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

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 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

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. 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.

saveExec

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 a

restart

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 (i

debug

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.

DIC

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

digits

number of significant digits used for OpenBUGS input, see formatC

codaPkg

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

OpenBUGS.pgm

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 i

working.directory

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

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 OpenBUGS has finished

useWINE

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 Win

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 OpenBUGS. Must be an integer between 1-14. Seed specification changed between WinBUGS and OpenBUGS; see the OpenBUGS documentation for details.

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 OpenBUGS.

Value

• 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:
• 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 OpenBUGS for further iterations
• pD
  an estimate of the effective number of parameters, for calculations see the section Arguments.
• DIC
  mean(deviance) + pD

itemize

• MS Windows

item

• Linux, intel processors
• Mac OS X and Unix in general

code

OpenBUGS.pgm

dQuote

c:/Program Files/OpenBUGS/

cr

(e.g. /path/to/wine/folder/dosdevices/c:/Program Files/OpenBUGS/OpenBUGS321/OpenBUGS.exe).

Details

To run:

1. Write aBUGSmodel in an ASCII file (hint: usewrite.model).
2. Go intoR.
3. Prepare the inputs for thebugsfunction and run it (see Example section).
4. AnOpenBUGSwindow will pop up andRwill freeze up. The model will now run inOpenBUGS. It might take awhile. You will see things happening in the Log window withinOpenBUGS. WhenOpenBUGSis done, its window will close andRwill work again.
5. If an error message appears, re-run withdebug=TRUE.

BUGS version support:

• OpenBUGS

{>=3.2.1}

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="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)