Running OpenBUGS from R

Description

R2OpenBUGS Call a BUGS model, summarize inferences and convergence in a table and graph, and save the simulations in arrays for easy access in R. The main command is bugs.

Details

The following are sources of information on R2OpenBUGS 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 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="R2OpenBUGS")
# 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: 
## See ?bugs if the following fails:
schools.sim <- bugs(data, inits, parameters, model.file,
    n.chains = 3, n.iter = 1000,
    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 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

Details

To run:

1. Write a BUGS model in an ASCII file (hint: use write.model).

2. Go into R.

3. Prepare the inputs for the bugs function and run it (see Example section).

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

5. 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”).

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:

Author(s)

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

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

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

## End(Not run)

Writing input for OpenBUGS

Description

Write file for OpenBUGS to read.

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 OpenBUGS

Description

Write files ‘inits1.txt’, ‘inits2.txt’, etc., in the working directory for OpenBUGS to read

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

Description

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

Usage

bugs.log(file)

Arguments

Details

Returns the OpenBUGS summary statistics and DIC extracted directly from the log file.

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 OpenBUGS

Description

Calls OpenBUGS and runs it with ‘script.txt’ - intended for internal use

Usage

bugs.run(n.burnin, OpenBUGS.pgm, debug=FALSE, 
         useWINE=FALSE, WINE=NULL,
         newWINE=TRUE, WINEPATH=NULL)

Arguments

Value

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

See Also

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

Writes script for running OpenBUGS

Description

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

Usage

bugs.script(parameters.to.save, n.chains, n.iter, n.burnin,
           n.thin, saveExec, restart, model.file.bug,
           model.file, debug=FALSE, is.inits, 
           DIC=FALSE, useWINE=FALSE,
           newWINE=TRUE, WINEPATH=NULL, bugs.seed=NULL, summary.only=FALSE,
           save.history=(.Platform$OS.type == "windows" | useWINE==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.

OpenBUGS output reader

Description

Reads simulations from OpenBUGS into R, 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 OpenBUGS registry

Description

Adjusts OpenBUGS registry - intended for internal use

Usage

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

Arguments

Details

Alter the adaptive phases in the OpenBUGS updaters (in the ‘BUGS/System/Rsrc/Registry.odc’ file, where BUGS is map of installed OpenBUGS) so that all adaptive updating is done during the burnin stage. Otherwise OpenBUGS 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 OpenBUGS parameter names

Description

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

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

Compare OpenBUGS/R2OpenBUGS execution to results supplied with OpenBUGS

Description

A selected subset of the examples from the OpenBUGS manual is executed and compared to results supplied with the package to validate installation.

Usage

validateInstallOpenBUGS(
    OpenBUGS.pgm=NULL,
    useWINE=FALSE, WINE=NULL,
    newWINE=TRUE, WINEPATH=NULL
    )

Arguments

Details

Operation system support:

• MS Windows Yes

• Linux, intel processors Yes, but GUI display and graphics not available.

• Mac OS X and Unix 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”).

Value

No data returned. Prints match/no match result to console for each example.

Author(s)

Neal Thomas based on BRugs examples created by Chris Jackaon.

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

bugs

Write data for OpenBUGS

Description

Write data in files that can be read by OpenBUGS - 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 OpenBUGS model file

Description

Convert R function to a OpenBUGS 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. To overcome this incompatibility, use dummy operator %_% before I(...): dnorm(...) %_% I(...). The dummy operator %_% 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)