Package 'R2jags'

Attach/detach elements of ‘JAGS’ objects to search path

Description

These are wraper functions for attach.bugs and detach.bugs, which attach or detach three-way-simulation array of bugs object to the search path. See attach.all for details.

Usage

attach.jags(x, overwrite = NA)

Arguments

x	An rjags object.
overwrite	If TRUE, objects with identical names in the Workspace (.GlobalEnv) that are masking objects in the database to be attached will be deleted. If NA (the default) and an interactive session is running, a dialog box asks the user whether masking objects should be deleted. In non-interactive mode, behaviour is identical to overwrite=FALSE, i.e. nothing will be deleted.

Details

See attach.bugs for details

Author(s)

Yu-Sung Su [email protected],

References

Sibylle Sturtz and Uwe Ligges and Andrew Gelman. (2005). “R2WinBUGS: A Package for Running WinBUGS from R.” Journal of Statistical Software 3 (12): 1–6.

Examples

# See the example in ?jags for the usage.

---

Function for auto-updating ‘JAGS’ until the model converges

Description

The autojags takes a rjags object as input. autojags will update the model until it converges.

Usage

autojags(
  object,
  n.iter = 1000,
  n.thin = 1,
  Rhat = 1.1,
  n.update = 2,
  refresh = n.iter/50,
  progress.bar,
  ...
)

Arguments

object	an object of rjags class.
n.iter	number of total iterations per chain, default=1000
n.thin	thinning rate. Must be a positive integer, default=1
Rhat	converegence criterion, default=1.1.
n.update	the max number of updates, default=2.
refresh	refresh frequency for progress bar, default is n.iter/50
progress.bar	type of progress bar. Possible values are “text”, “gui”, and “none”. Type “text” is displayed on the R console. Type “gui” is a graphical progress bar in a new window. The progress bar is suppressed if progress.bar is “none”
...	further arguments pass to or from other methods.

Author(s)

Yu-Sung Su [email protected]

References

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

Examples

# see ?jags for an example.

---

Retrives the information from the JAGS compilation

Description

Retrives the information from the JAGS compilation

Usage

count_nodes(x, ...)

Arguments

x	A 'rjags' object (obtained from running R2jags::jags) or a 'jags' object (resulting from running rjags::jags.samples.
...	Additional parameters that can be passed

Value

A vector with the number of observed, unobserved and total nodes included in the DAG resulting from the model assumptions encoded by the code

Author(s)

Gianluca Baio

Examples

# An example model file is given in:
model.file <- system.file(package="R2jags", "model", "schools.txt")
#=================# 
# initialization  #
#=================#
# data
J <- 8.0
y <- c(28.4,7.9,-2.8,6.8,-0.6,0.6,18.0,12.2)
sd <- c(14.9,10.2,16.3,11.0,9.4,11.4,10.4,17.6)
jags.data <- list("y","sd","J")
jags.params <- c("mu","sigma","theta")
jags.inits <- function(){
 list("mu"=rnorm(1),"sigma"=runif(1),"theta"=rnorm(J))
}
jagsfit <- jags(data=list("y","sd","J"), inits=jags.inits, jags.params,
             n.iter=10, model.file=model.file)
count_nodes(jagsfit)

---

Run ‘JAGS’ from R

Description

The jags function takes data and starting values as input. It automatically writes a jags script, calls the model, and saves the simulations for easy access in R.

Usage

jags(
  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.iter - n.burnin)/1000)),
  DIC = TRUE,
  pD = FALSE,
  n.iter.pd = NULL,
  n.adapt = 100,
  working.directory = NULL,
  jags.seed = 123,
  refresh = n.iter/50,
  progress.bar,
  digits = 5,
  RNGname = c("Wichmann-Hill", "Marsaglia-Multicarry", "Super-Duper", "Mersenne-Twister"),
  jags.module = c("glm", "dic"),
  quiet,
  checkMissing = FALSE
)

jags2(
  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.iter - n.burnin)/1000)),
  DIC = TRUE,
  jags.path = "",
  working.directory = NULL,
  clearWD = TRUE,
  refresh = n.iter/50
)

jags.parallel(
  data,
  inits,
  parameters.to.save,
  model.file = "model.bug",
  n.chains = 2,
  n.iter = 2000,
  n.burnin = floor(n.iter/2),
  n.thin = max(1, floor((n.iter - n.burnin)/1000)),
  n.cluster = n.chains,
  DIC = TRUE,
  working.directory = NULL,
  jags.seed = 123,
  digits = 5,
  RNGname = c("Wichmann-Hill", "Marsaglia-Multicarry", "Super-Duper", "Mersenne-Twister"),
  jags.module = c("glm", "dic"),
  export_obj_names = NULL,
  envir = .GlobalEnv
)

Arguments

data	(1) a vector or list of the names of the data objects used by the model, (2) a (named) list of the data objects themselves, or (3) the name of a "dump" format file containing the data objects, which must end in ".txt", see example below for details.
inits	a list with n.chains elements; each element of the list is itself a list of starting values for the BUGS model, or a function creating (possibly random) initial values. If inits is NULL, JAGS will generate initial values for parameters.
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 BUGS code. Alternatively, as in R2WinBUGS, 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. If n.burnin is 0, jags() will run 100 iterations for adaption.
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.
DIC	logical; if TRUE (default), compute deviance, pD, and DIC. The rule pD=var(deviance) / 2 is used.
pD	logical; if TRUE and DIC is also TRUE, then adds the computation of 'pD', using 'rjags::dic.samples()'. Defaults to FALSE.
n.iter.pd	number of iterations to feed 'rjags::dic.samples()' to compute 'pD'. Defaults at 1000.
n.adapt	number of iterations for which to run the adaptation, when creating the model object. Defaults at 100.
working.directory	sets working directory during execution of this function; This should be the directory where model file is.
jags.seed	random seed for JAGS, default is 123. This function is used for jags.parallell() and does not work for jags(). Use set.seed() instead if you want to produce identical result with jags()
refresh	refresh frequency for progress bar, default is n.iter/50
progress.bar	type of progress bar. Possible values are “text”, “gui”, and “none”. Type “text” is displayed on the R console. Type “gui” is a graphical progress bar in a new window. The progress bar is suppressed if progress.bar is “none”. Default set globally to “text”
digits	as in write.model in the R2WinBUGS package: number of significant digits used for BUGS input, see formatC. Only used if specifying a BUGS model as an R function.
RNGname	the name for random number generator used in JAGS. There are four RNGS supplied by the base moduale in JAGS: Wichmann-Hill, Marsaglia-Multicarry, Super-Duper, Mersenne-Twister
jags.module	the vector of jags modules to be loaded. Default are “glm” and “dic”. Input NULL if you don't want to load any jags module.
quiet	Logical, whether to suppress stdout in jags.model(). Default set globally to “FALSE”
checkMissing	Default: FALSE. When TRUE, checks for missing data in categorical parameters and returns a sim.list with NA values if detected. It's recommended to supply jags() with complete data.
jags.path	directory that contains the JAGS executable. The default is “”.
clearWD	indicating whether the files ‘data.txt’, ‘inits[1:n.chains].txt’, ‘codaIndex.txt’, ‘jagsscript.txt’, and ‘CODAchain[1:nchains].txt’ should be removed after jags has finished, default=TRUE.
n.cluster	number of clusters to use to run parallel chains. Default equals n.chains.
export_obj_names	character vector of objects to export to the clusters.
envir	default is .GlobalEnv

Details

To run:

1. Write a JAGS model in an ASCII file.

2. Go into R.

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

4. The model will now run in JAGS. It might take awhile. You will see things happening in the R console.

Author(s)

Yu-Sung Su [email protected], Masanao Yajima [email protected], Gianluca Baio [email protected]

References

Plummer, Martyn (2003) “JAGS: A program for analysis of Bayesian graphical models using Gibbs sampling.” https://www.r-project.org/conferences/DSC-2003/Proceedings/Plummer.pdf.

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

Sibylle Sturtz and Uwe Ligges and Andrew Gelman. (2005). “R2WinBUGS: A Package for Running WinBUGS from R.” Journal of Statistical Software 3 (12): 1–6.

Examples

# Can set global options for some of the features of R2jags. For example
# running the command
options(r2j.pb="none")
# before launching jags shuts down the progress bar. Or running the command
options(r2j.quiet=FALSE)
# forces jags to not show the compilation summary. Or running the command
options(r2j.print.progam=FALSE)
# modifies the print method and prevents R2jags from printing the name of 
# software used to run the MCMC analysis. These options may be helpful 
# when using Rmarkdown or quarto to help formtting the output.
#
# An example model file is given in:
model.file <- system.file(package="R2jags", "model", "schools.txt")
# Let's take a look:
file.show(model.file)

#=================#
# Initialization  #
#=================#

# Data
J <- 8.0
y <- c(28.4, 7.9, -2.8, 6.8, -0.6, 0.6, 18.0, 12.2)
sd <- c(14.9, 10.2, 16.3, 11.0, 9.4, 11.4, 10.4, 17.6)

jags.data <- list(y = y, sd = sd, J = J)
jags.params <- c("mu", "sigma", "theta")
jags.inits <- function() {
  list(mu = rnorm(1), sigma = runif(1), theta = rnorm(J))
}

## You can input data in 4 ways:

# 1) Data as a list of character strings
jagsfit <- jags(data = list("y", "sd", "J"), inits = jags.inits, 
                parameters.to.save = jags.params, 
                n.iter = 10, model.file = model.file)

# 2) Data as a character vector of names
jagsfit <- jags(data = c("y", "sd", "J"), inits = jags.inits, 
                parameters.to.save = jags.params, 
                n.iter = 10, model.file = model.file)

# 3) Data as a named list
jagsfit <- jags(data = list(y = y, sd = sd, J = J), inits = jags.inits, 
                parameters.to.save = jags.params, 
                n.iter = 10, model.file = model.file)

# 4) Data from a file
fn <- "tmpbugsdata.txt"
dump(c("y", "sd", "J"), file = fn)
jagsfit <- jags(data = fn, inits = jags.inits, 
                parameters.to.save = jags.params, 
                n.iter = 10, model.file = model.file)
unlink("tmpbugsdata.txt")

## Writing a BUGS model as an R function
schoolsmodel <- function() {
  for (j in 1:J) {
    y[j] ~ dnorm(theta[j], tau.y[j])  # Likelihood
    tau.y[j] <- pow(sd[j], -2)        # Precision
  }
  for (j in 1:J) {
    theta[j] ~ dnorm(mu, tau)         # Hierarchical model
  }
  tau <- pow(sigma, -2)
  mu ~ dnorm(0.0, 1.0E-6)
  sigma ~ dunif(0, 1000)
}

jagsfit <- jags(data = jags.data, inits = jags.inits, 
                parameters.to.save = jags.params, 
                n.iter = 10, model.file = schoolsmodel)

#=================================#
# Running JAGS and postprocessing #
#=================================#

jagsfit <- jags(data = jags.data, inits = jags.inits, 
                parameters.to.save = jags.params, 
                n.iter = 5000, model.file = model.file)

## Computing DIC with pD
## Not run: 
jagsfit.pD <- jags(data = jags.data, inits = jags.inits, 
                   parameters.to.save = jags.params, 
                   n.iter = 5000, model.file = model.file, pD = TRUE)

## End(Not run)

## Running JAGS in parallel
## Not run: 
jagsfit.p <- jags.parallel(data = jags.data, inits = jags.inits, 
                            parameters.to.save = jags.params, 
                            n.iter = 5000, model.file = model.file)
print(jagsfit.p,digits=3,interval=c(0.025,0.975))
plot(jagsfit.p)

## End(Not run)

## Checking model convergence
## Not run: 
traceplot(jagsfit)
traceplot(jagsfit.p)

## End(Not run)

## Updating JAGS if the model does not converge
## Not run: 
jagsfit.upd <- update(jagsfit, n.iter = 100)
print(jagsfit.upd)
plot(jagsfit.upd)

## End(Not run)

## Auto-updating until convergence
## Not run: 
jagsfit.upd <- autojags(jagsfit)
jagsfit.upd <- autojags(jagsfit.p)

## End(Not run)

## Obtaining DIC separately
## Not run: 
dic.samples(jagsfit.upd$model, n.iter = 1000, type = "pD")

## End(Not run)

## Attaching and detaching JAGS results
## Not run: 
attach.jags(jagsfit.upd)
mu  # View parameter estimates
detach.jags()

## End(Not run)

## Picking up the last saved session
## Not run: 
recompile(jagsfit)
jagsfit.upd <- update(jagsfit, n.iter = 100)

## End(Not run)

---

Read jags output files in CODA format

Description

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

Usage

jags2bugs(
  path = getwd(),
  parameters.to.save,
  n.chains = 3,
  n.iter = 2000,
  n.burnin = 1000,
  n.thin = 2,
  DIC = TRUE
)

Arguments

path	sets working directory during execution of this function; This should be the directory where CODA files are.
parameters.to.save	character vector of the names of the parameters to save which should be monitored.
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, default is 2
DIC	logical; if TRUE (default), compute deviance, pD, and DIC. The rule pD=var(deviance) / 2 is used.

Author(s)

Yu-Sung Su [email protected], Masanao Yajima [email protected]

---

Function for recompiling rjags object

Description

The recompile takes a rjags object as input. recompile will re-compile the previous saved rjags object.

Usage

recompile(object, n.iter, refresh, progress.bar)

Arguments

object	an object of rjags class.
n.iter	number of iteration for adapting, default is 100
refresh	refresh frequency for progress bar, default is n.iter/50
progress.bar	type of progress bar. Possible values are “text”, “gui”, and “none”. Type “text” is displayed on the R console. Type “gui” is a graphical progress bar in a new window. The progress bar is suppressed if progress.bar is “none”

Author(s)

Yu-Sung Su [email protected]

Examples

# see ?jags for an example.

---

Trace plot of bugs object

Description

Displays a plot of iterations vs. sampled values for each variable in the chain, with a separate plot per variable.

Usage

traceplot(x,...)

## S4 method for signature 'rjags'
traceplot(
  x,
  mfrow = c(1, 1),
  varname = NULL,
  match.head = TRUE,
  ask = TRUE,
  col = rainbow(x$n.chains),
  lty = 1,
  lwd = 1,
  ...
)

Arguments

x	A bugs object
mfrow	graphical parameter (see par)
varname	vector of variable names to plot
match.head	matches the variable names by the beginning of the variable names in bugs object
ask	logical; if TRUE, the user is asked before each plot, see par(ask=.).
col	graphical parameter (see par)
lty	graphical parameter (see par)
lwd	graphical parameter (see par)
...	further graphical parameters

Author(s)

Masanao Yajima [email protected].

See Also

densplot, plot.mcmc, traceplot

---