bugs {R2WinBUGS} | R Documentation |
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.
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)
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 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. |
To run:
write.model
).
bugs
function and run it (see
Example section).
debug=TRUE
.
BUGS version support:
program="OpenBUGS"
Operation system support:
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
.
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 |
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.
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.
print.bugs
, plot.bugs
, as well as
coda and BRugs packages
# 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: ## 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)