Running WinBUGS and OpenBUGS from R / S-PLUS

Description

R2WinBUGS package provides possiblity to call a BUGS model, summarize inferences and convergence in a table and graph, and save the simulations in arrays for easy access in R / S-PLUS. In S-PLUS, the OpenBUGS functionality and the windows emulation functionality is not yet available. The main command is bugs.

Details

The following are sources of information on R2WinBUGS package:

Convert to bugs object

Description

Function converting results from Markov chain simulations, that might not be from BUGS, to bugs object. Used mainly to display results with plot.bugs.

Usage

as.bugs.array(sims.array, model.file=NULL, program=NULL,
    DIC=FALSE, DICOutput=NULL, n.iter=NULL, n.burnin=0, n.thin=1)

Arguments

Details

This function takes a 3-way array of simulations and makes it into a bugs object that can be conveniently displayed using print and plot and accessed using attach.bugs. If the third dimension of sims() has names, the resulting bugs object will respect that naming convention. For example, if the parameter names are “alpha[1]”, “alpha[2]”, ..., “alpha[8]”, “mu”, “tau”, then as.bugs.array will know that alpha is a vector of length 8, and mu and tau are scalar parameters. These will all be plotted appropriately by plot and attached appropriately by attach.bugs.

If DIC=TRUE then DIC can be either already passed to argument DICOutput as it is done in openbugs or calculated from deviance values in sims.array.

Value

A bugs object is returned

Author(s)

Jouni Kerman, kerman@stat.columbia.edu with modification by Andrew Gelman, gelman@stat.columbia.edu, packaged by Uwe Ligges, ligges@statistik.tu-dortmund.de.

See Also

bugs

Attach / detach elements of (bugs) objects to search path

Description

The database is attached/detached to the search path. See attach for details.

Usage

    attach.all(x, overwrite = NA, name = "attach.all")
    attach.bugs(x, overwrite = NA)
    detach.all(name = "attach.all")
    detach.bugs()

Arguments

Details

While attach.all attaches all elements of an object x to a database called name, attach.bugs attaches all elements of x$sims.list to the database bugs.sims itself making use of attach.all.

detach.all and detach.bugs are removing the databases mentioned above.
attach.all also attaches n.sims (the number of simulations saved from the MCMC runs) to the database.

Each scalar parameter in the model is attached as vectors of length n.sims, each vector is attached as a 2-way array (with first dimension equal to n.sims), each matrix is attached as a 3-way array, and so forth.

Value

attach.all and attach.bugs invisibly return the environment(s).

detach.all and detach.bugs detach the environment(s) named name created by attach.all.

Note

Without detaching, do not use attach.all or attach.bugs on another (bugs) object, because instead of the given name, an object called name is attached. Therefore strange things may happen ...

See Also

bugs, attach, detach

Examples

# An example model file is given in:
model.file <- system.file("model", "schools.txt", package="R2WinBUGS")
# Some example data (see ?schools for details):
data(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")
## 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 = 1000,
    bugs.directory = "c:/Program Files/WinBUGS14/",
    working.directory = NULL)

# Do some inferential summaries
attach.bugs(schools.sim)
# posterior probability that the coaching program in school A
# is better than in school C:
print(mean(theta[,1] > theta[,3]))
# 50
# and school C's program:
print(quantile(theta[,1] - theta[,3], c(.25, .75)))
plot(theta[,1], theta[,3])
detach.bugs()

## End(Not run)

Run WinBUGS and OpenBUGS from R or S-PLUS

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

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 Windows

no problem

Linux, Mac OS X and Unix in general

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

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:

Author(s)

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

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)

Writing input for WinBUGS

Description

Write file for WinBUGS to read - for internal use.

Usage

bugs.data(data, dir = getwd(), digits = 5, data.file = "data.txt")

Arguments

Value

The name of data.file is returned and as a side effect, the data file is written

See Also

The main function to be called by the user is bugs.

Writing input for WinBUGS - intended for internal use only

Description

Write files ‘inits1.txt’, ‘inits2.txt’, etc., in the working directory for WinBUGS to read - for internal use.

Usage

bugs.inits(inits, n.chains, digits,
    inits.files = paste("inits", 1:n.chains, ".txt", sep = ""))

Arguments

Value

Vector of names of inits.files; as a side effect, the inits files ‘inits*.txt’ are written

See Also

The main function to be called by the user is bugs.

Read data from WinBUGS logfile

Description

Read data such as summary statistics and DIC information from the WinBUGS logfile

Usage

bugs.log(file)

Arguments

Value

A list with components:

Author(s)

Jouni Kerman

See Also

The main function that generates the log file is bugs.

Plotting summary information - intended for internal use only

Description

Plotting summary information - intended for internal use

Usage

bugs.plot.summary(sims, ...)
bugs.plot.inferences(sims, display.parallel, ...)

Arguments

Details

bugs.plot.summary (left hand side of plot) and bugs.plot.inferences (right hand side of plot).

Value

Does not return anything, but prints and plots as side-effects.

See Also

The main function to be called by the user is plot, see plot.bugs for details.

Calling WinBUGS

Description

Updates the lengths of the adaptive phases in the WinBUGS registry (using bugs.update.settings), calls WinBUGS and runs it with ‘script.txt’ - intended for internal use

Usage

bugs.run(n.burnin, bugs.directory,
         useWINE=.Platform$OS.type != "windows", WINE=NULL,
         newWINE=TRUE, WINEPATH=NULL)

Arguments

Value

Nothing, but has side effects as documented in bugs.update.settings and calls WinBUGS.

See Also

The main function to be called by the user is bugs.

Writes script for running WinBUGS

Description

Write file ‘script.txt’ for WinBUGS to read - intended for internal use

Usage

bugs.script(parameters.to.save, n.chains, n.iter, n.burnin, n.thin,
    model.file, debug=FALSE, is.inits, bin, DIC=FALSE,
    useWINE=.Platform$OS.type != "windows", newWINE=TRUE, WINEPATH=NULL, 
    bugs.seed=NULL, summary.only=FALSE, save.history=TRUE, 
    bugs.data.file, bugs.inits.files, over.relax = FALSE)

Arguments

Value

Nothing, but as a side effect, the script file ‘script.txt’ is written

See Also

The main function to be called by the user is bugs.

WinBUGS output reader

Description

Reads simulations from WinBUGS into R or S-PLUS, formats them, monitors convergence, performs convergence checks, and computes medians and quantiles - intended for internal use.

Usage

bugs.sims(parameters.to.save, n.chains, n.iter, n.burnin, n.thin,
    DIC = TRUE)

Arguments

Value

Returns the same values as bugs.

See Also

The main function to be called by the user is bugs.

Adjusting WinBUGS registry

Description

Adjusts WinBUGS registry - intended for internal use

Usage

bugs.update.settings(n.burnin, bugs.directory)

Arguments

Details

Alter the adaptive phases in the WinBUGS updaters (in the ‘BUGS/System/Rsrc/Registry.odc’ file, where BUGS is map of installed WinBUGS) so that all adaptive updating is done during the burnin stage. Otherwise WinBUGS will not report results if the burnin is less than a minimum value such as 500 or 4000 (depending on the model). Write permission on above mentioned file is needed for this!

Value

Nothing, but as a side effect, the registry file ‘BUGS/System/Rsrc/Registry.odc’ is modified

See Also

The main function to be called by the user is bugs.

Decodes WinBUGS parameter names

Description

Decodes WinBUGS parameter names (e.g., beta[3,14] becomes beta with 2 indexes: 3 and 14) for use by the bugs.sims function - intended for internal use

Usage

decode.parameter.name(a)

Arguments

Value

list with elements:

given a == "beta[3, 14]"

See Also

The main function to be called by the user is bugs.

Special summary statistics

Description

Special summary statistics of the WinBUGS output.

Usage

monitor(a, n.chains = dim(a)[2], trans = NULL, keep.all = FALSE, Rupper.keep = FALSE)
conv.par(x, n.chains, Rupper.keep = TRUE)

Arguments

Details

conv.par is intended for internal use only.

Value

for monitor:

for conv.par a list with elements:

See Also

The main function to be called by the user is bugs.

Wrapper to run OpenBUGS

Description

The openbugs function takes data and starting values as input. It automatically calls the package BRugs and runs something similar to BRugsFit. Not available in S-PLUS.

Usage

openbugs(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) / n.sims)),
    n.sims = 1000,  DIC = TRUE, 
    bugs.directory = "c:/Program Files/OpenBUGS/",
    working.directory = NULL, digits = 5, over.relax = FALSE, seed=NULL)

Arguments

Value

A bugs object.

Note

By default, BRugs (and hence openbugs()) is quite verbose. This can be controlled for the whole BRugs package by the option ‘BRugsVerbose’ (see options) which is set to TRUE by default.

Author(s)

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

See Also

bugs and the BRugs 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))
}
## 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: 
## both write access in the working directory and package BRugs required:
schools.sim <- bugs(data, inits, parameters, model.file,
    n.chains = 3, n.iter = 5000,
    program = "openbugs", working.directory = NULL)
print(schools.sim)
plot(schools.sim)

## End(Not run)

Plotting a bugs object

Description

Plotting a bugs object

Usage

## S3 method for class 'bugs'
plot(x, display.parallel = FALSE, ...)

Arguments

See Also

bugs

Printing a bugs object

Description

Printing a bugs object

Usage

## S3 method for class 'bugs'
print(x, digits.summary = 1, ...)

Arguments

See Also

bugs

Read output files in CODA format

Description

This function reads Markov Chain Monte Carlo output in the CODA format produced by WinBUGS and returns an object of class mcmc.list for further output analysis using the coda package.

Usage

read.bugs(codafiles, ...)

Arguments

See Also

bugs, read.coda, mcmc.list

8 schools analysis

Description

8 schools analysis

Usage

data(schools)

Format

A data frame with 8 observations on the following 3 variables.

school

See Source.

estimate

See Source.

sd

See Source.

Source

Rubin, D.B. (1981): Estimation in Parallel Randomized Experiments. Journal of Educational Statistics 6(4), 377-400.

Section 5.5 of Gelman, A., Carlin, J.B., Stern, H.S., Rubin, D.B. (2003): Bayesian Data Analysis, 2nd edition, CRC Press.

Write data for WinBUGS

Description

Write data in files that can be read by WinBUGS - intended for internal use

Usage

write.datafile(datalist, towhere, fill = TRUE)
formatdata(datalist)

Arguments

Value

See Also

The main function to be called by the user is bugs.

Creating a WinBUGS model file

Description

Convert R / S-PLUS function to a WinBUGS model file

Usage

write.model(model, con = "model.bug", digits = 5)

Arguments

Details

BUGS models follow closely S syntax. It is therefore possible to write most BUGS models as R functions.

As a difference, BUGS syntax allows truncation specification like this: dnorm(...) I(...) but this is illegal in R and S-PLUS. To overcome this incompatibility, use dummy operator %_% before I(...): dnorm(...) %_% I(...). The dummy operator %_% will be removed before the BUGS code is saved.

In S-PLUS, a warning is generated when the model function is defined if the last statement in the model is an assignment. To avoid this warning, add the line "invisible()" to the end of the model definition. This line will be removed before the BUGS code is saved.

Value

Nothing, but as a side effect, the model file is written

Author(s)

original idea by Jouni Kerman, modified by Uwe Ligges

See Also

bugs

Examples

## Same "schoolsmodel" that is used in the examples in ?bugs:
schoolsmodel <- function(){
    for (j in 1:J){
        y[j] ~ dnorm (theta[j], tau.y[j])
        theta[j] ~ dnorm (mu.theta, tau.theta)
        tau.y[j] <- pow(sigma.y[j], -2)
    }
    mu.theta ~ dnorm (0.0, 1.0E-6)
    tau.theta <- pow(sigma.theta, -2)
    sigma.theta ~ dunif (0, 1000)
}

## some temporary filename:
filename <- file.path(tempdir(), "schoolsmodel.bug")


## write model file:
write.model(schoolsmodel, filename)
## and let's take a look:
file.show(filename)