rube {rube}R Documentation

Run an extended WinBUGS model

Description

Using the WinBUGS model extensions of rube, run a WinBUGS model using bugs() from R2WinBUGS. Extensions include WHAT=value type defaults, LC() for on-the-fly model formulas (linear combinations of parameters and data), FOR() for on-the-fly specification of priors based on a run-time data variable list. Other features check models, give feedback on model relationships, plot and modify output, and otherwise make using WinBUGS easier, more efficient, and less frustrating.

Usage

rube(model, data=NULL, inits=NULL, parameters.to.save=NULL,
     n.chains=ifelse(is.null(parameters.to.save),1,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, modelCheck=c("always","onFail","never"),
     cullData = TRUE, cullInits=TRUE, cullPts=TRUE,
     cullWarn = TRUE,
     DIC = TRUE, digits = 5, codaPkg = FALSE, 
     subs=NULL, cases=NULL, varList=list(),
     bugs.directory = ifelse(Sys.getenv("BUGSDIR")=="", 
                                        "c:/Program Files/WinBUGS14/",
                                        Sys.getenv("BUGSDIR")),
     useWINE = .Platform$OS.type != "windows", 
     WINE = NULL, newWINE = TRUE, WINEPATH = NULL,
     program = c("auto","WinBUGS", "OpenBUGS", "winbugs", "openbugs", "jags"),
     parallel = FALSE,
     progress.bar = c("gui","text","none"),
     RNGname = c("Wichmann-Hill", "Marsaglia-Multicarry", "Super-Duper", "Mersenne-Twister"),
     wd = ifelse(Sys.getenv("BUGSWD")=="", getwd(), Sys.getenv("BUGSWD")),
     bugs.seed=round(runif(1,1,2^31)), over.relax=FALSE,
     dataParams=list(), initsExtra=NULL, warnUseless=FALSE,
     modelFile="tempModel.txt", ignore=NULL)

Arguments

model

The name of the model declaration file or the model declaration itself as a newline-separated single string. The file will be be pre-processed to replace over-ridden defaults and expand LC(), FOR() and BASE() pseudofunctions.

data

A function that creates model data (as a named list) or a named list of such data.

inits

A function that creates a named list of initialization values, or a named list of such initializations.

parameters.to.save

A character vector of parameters to save upon return from WinBUGS.

n.chains

The nunber of separate MCMC chains to be run.

n.iter

see bugs() documentation

n.burnin

see bugs() documentation

n.thin

see bugs() documentation

n.sims

see bugs() documentation

bin

see bugs() documentation

debug

A logical flag where TRUE indicates that WinBUGS will stop in debug mode before returning to R.

modelCheck

Determines whether and when model checking is done if data, inits, and parameters.to.save are all supplied. If some are not supplied modelCheck is ignored and model checking is the only action taken. WARNING: if modelCheck is "never", culling cannot occur; perhaps you want "onFail".

cullData

If TRUE extraneous variables in "data" are dropped.

cullInits

If TRUE extraneous variables in "inits" are dropped.

cullPts

If TRUE extraneous variables in "parameters.to.save" are dropped.

cullWarn

FALSE/TRUE indicates that culling is silent vs. warned

DIC

see bugs() documentation

digits

see bugs() documentation

codaPkg

see bugs() documentation

subs

A named list of substitutions used to over-ride defaults.

cases

A character vector of items used to evaluate IFCASE() statements.

varList

A named list used for implementing LC(), FOR() and BASE().

bugs.directory

see bugs() documentation

useWINE

see bugs() documentation

WINE

see bugs() documentation

newWINE

see bugs() documentation

WINEPATH

see bugs() documentation

program

If program="auto" jags is chosen instead of WinBUGS if it is loaded

parallel

If program="jags", parallel runs jags in parallel

progress.bar

Progress indicator for jags (see R2jags documentation)

RNGname

Random number generator used for jags (see R2jags documentation)

wd

The working directory containing the model description and where results are stored.

bugs.seed

see bugs() documentation

over.relax

see bugs() documentation

dataParams

A named list of parameters to be used when calling the data generating function.

initsExtra

A named list of parameters to be used when calling the initalization function.

warnUseless

If TRUE, warn if useless CASEs are in cases.

modelFile

The name of the processed model file sent to WinBUGS.

ignore

If "all" or the start of one or more problem messages, this allows bugs() to run despite the problem(s).

Details

This is a wrapper for the R2WinBUGS function bugs(). It has better defaults, and incorporates model description file pre-processing.

Preprocessing includes:

  1. Use of the syntax WHAT=value, e.g, y[i] ~ dnorm(0, PREC=2) which will be replaced with y[i] ~ dnorm(0, 2) unless subs=list(...,PREC=3,...) is used as an argument to rube(), model(), or rube::selectText(), in which case, for this example, y[i] ~ dnorm(0, 3) is put into the final model description file. This is useful for simplifying code while allowing hyperprior sensitivity checks without modifying the model text.

  2. The pseudofunction LC(prefix, FORMULA, suffix, index) is useful for representing a linear combination of data values and parameters when the particular data columns and level of interaction are specified at run-time allowing maintenance of a single, simple model specification. The VALS string must be a named element of the varList to rube(), model(), etc. E.g., if the call is LC(B, COVARS, t, i) with varList equal to list(COVARS="a+(b+c)^2") then the substituted text is Bat*a[i] + Bbt*b[i] + Bct*c[i] + Bbct*b[i]*c[i]. Note that this will NOT WORK APPROPRIATELY if any of the variables are categorical variables with three or more levels.

  3. The pseudofunction FOR(prefix, FORMULA, suffix, codeText) is useful for defining prior distributions in tandem with LC(). Multiple WinBUGS model description lines will be generated, and they differ in that different parameter names are substituted for the special character "?" in the "codeText". For example, if the call is FOR(B, COVARS, t, ? ~ dnorm(0,1)) with varList equal to list(COVARS="a+(b+c)^2") then the substituted text is:

    Bat ~ dnorm(0,1) Bbt ~ dnorm(0,1) Bct ~ dnorm(0,1) Bbct ~ dnorm(0,1)

  4. The psuedofunction BASE(FORMULA, index) generates a product of one minus the indexed data values. E.g., isBase[i] <- BASE(VARS, i) when varList includes VARS=c("a+b*cd") will produce isBase <- (1-a[i])*(1-b[i])*(1-cd[i]) which is useful for specifiying a baseline group.

  5. Conditional processing of sections of model specification text. There are two forms. The inline form has text1 IFCASE(caseFormula) text2 ELSECASE text3 ENDCASE text4 and results in text1 text2 text4 if the caseFormula evaluates to TRUE or text1 text3 text4 otherwise. The case formula uses the cases= argument (in the several functions that define it) such that each listed element in the string vector is taken to be TRUE and undefined elements are FALSE. The formula can use "!" for NOT, "|" for OR, "&" for AND, plus parentheses. The multiline form has IFCASE(caseFormula) alone one a line, then any number of lines to be included if the case formula is TRUE, then ELSEIFCASE(caseFormula) with more subsequent lines repeated zero or more times, then ENDCASE.

Value

The bugs() object containing the WinBUGS results.

Author(s)

Howard J. Seltman <hseltman@stat.cmu.edu>

References

http://www.stat.cmu.edu/~hseltman/rube

See Also

check,model,showDefaults

Examples

  cat("Simple example needed\n")

[Package rube version 0.3-11 Index]