R2WinBUGS (version 0.2-7)

bugs: Run WinBUGS from R

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.

Usage

bugs(data, inits, parameters.to.save, model.file = "model.txt",
    n.chains = 3, n.iter = 2000, n.burnin = floor(n.iter/2),
    n.thin = max(1, floor(n.chains * (n.iter - n.burnin)/1000)),
    bin = (n.iter - n.burnin) / n.thin,
    debug = FALSE, DIC = TRUE, digits = 5, codaPkg = FALSE,
    bugs.directory = "c:/Program Files/WinBUGS14/",
    working.directory = NULL)

Arguments

data

either a named list (names corresponding to variable names in the model.file) of the data for the WinBUGS model, or a vector or list of the names of the data objects used by the model. If data = "data.txt"

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

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 .bug, a copy of the file with extension .txt will be created in the bugs() call

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 the

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

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

bugs.directory

directory that contains the WinBUGS executable

working.directory

sets working directory during execution of this function; WinBUGS' in- and output will be stored in this directory; if NULL, the current working directory is chosen.

Value

• 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.
• 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.array and sims.list have been randomly permuted)
• summary
  summary statistics and convergence information for each element of 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
  var(deviance)/2, an estimate of the effective number of parameters (the variance is computed as the average of the within-chain variances, which gives a more reasonable estimate when convergence has not been reached)
• DIC
  mean(deviance) + pD

Details

To run:

1. Write a WinBUGS model in a ASCII file.
2. Go into R.
3. Prepare the inputs to thebugsfunction and run it (see Example).
4. A WinBUGS window will pop up amd R 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 will work again.
5. If an error message appears, re-run withdebug = TRUE.

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, and the coda package

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", "y", "sigma.y")
inits <- function(){
    list(theta = rnorm(J, 0, 100), mu.theta = rnorm(1, 0, 100),
        sigma.theta = runif(1, 0, 100))
}
parameters <- c("theta", "mu.theta", "sigma.theta")

## 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 = 1000,
    bugs.directory = "c:/Program Files/WinBUGS14/",
    working.directory = NULL)
print(schools.sim)
plot(schools.sim)