jagsUI (version 1.3.7)

jags: Call JAGS from R

Description

The jags function is a basic user interface for running JAGS analyses via package rjags inspired by similar packages like R2WinBUGS, R2OpenBUGS, and R2jags. The user provides a model file, data, initial values (optional), and parameters to save. The function compiles the information and sends it to JAGS, then consolidates and summarizes the MCMC output in an object of class jagsUI.

Usage

jags(data, inits, parameters.to.save, model.file,
  n.chains, n.adapt=100, n.iter, n.burnin=0, n.thin=1,
  modules=c('glm'), parallel=FALSE, DIC=TRUE, store.data=FALSE,
  codaOnly=FALSE,seed=floor(runif(1,1,10000)), bugs.format=FALSE, verbose=TRUE)

Arguments

data

A named list of the data objects required by the model, or a character vector containing the names of the data objects required by the model.

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,

parameters.to.save

Character vector of the names of the parameters in the model which should be monitored.

model.file

Path to file containing the model written in BUGS code

n.chains

Number of Markov chains to run.

n.adapt

Number of iterations to run in the JAGS adaptive phase. Sometimes JAGS chooses not to run these iterations; therefore they are separated from the burn-in in this package.

n.iter

Total number of iterations per chain (including burn-in).

n.burnin

Number of iterations at the beginning of the chain to discard (i.e., the burn-in). Does not include the adaptive phase iterations.

n.thin

Thinning rate. Must be a positive integer.

modules

List of JAGS modules to load before analysis. By default only module 'glm' is loaded (in addition to 'basemod' and 'bugs'). To force no additional modules to load, set modules=NULL.

parallel

If TRUE, run MCMC chains in parallel on multiple CPU cores. Each chain is assigned to a different core, so n.chains must be

DIC

Option to report DIC and the estimated number of parameters (pD). Defaults to TRUE.

store.data

Option to store the input dataset and initial values in the output object for future use. Defaults to FALSE.

codaOnly

Optional character vector of parameter names for which you do NOT want to calculate detailed statistics. This may be helpful when you have many output parameters (e.g., predicted values) and you want to save time. For these parameters, only the mean value

seed

Set a custom seed for the R random number generator and JAGS. The current state of the random number generator is saved in the output object.

bugs.format

Option to print JAGS output in classic R2WinBUGS format. Default is FALSE.

verbose

If set to FALSE, all text output in the console will be suppressed as the function runs (including most warnings).

Value

• An object of class jagsUI. Notable elements in the output object include:
• sims.list
  A list of values sampled from the posterior distributions of each monitored parameter.
• summary
  A summary of various statistics calculated based on model output, in matrix form.
• samples
  The original output object from the rjags package, as class mcmc.list.
• model
  The rjags model object; this will contain multiple elements if parallel=TRUE.

Details

Basic analysis steps:

1. Collect and package data
2. Write a model file in BUGS language
3. Set initial values
4. Specify parameters to monitor
5. Set MCMC variables and run analysis
6. Optionally, generate more posterior samples using theupdatemethod.

See example below.

Examples

#Analyze Longley economic data in JAGS
  
#Number employed as a function of GNP
  
######################################
##   1. Collect and Package Data    ##
######################################
  
#Load data (built into R)
  
data(longley)
head(longley)
  
#Separate data objects
  
gnp <- longley$GNP
employed <- longley$Employed
n <- length(employed)

#Input data objects must be numeric, and must be
#scalars, vectors, matrices, or arrays.
  
#Package together: several possible ways
  
#1. A named list of the objects
data <- list(gnp=gnp,employed=employed,n=n)
  
#2. A character vector of the names of the objects
data <- c('gnp','employed','n')
  
#3. A list of names of the objects
data <- list('gnp','employed','n')
  
######################################
##      2. Write model file         ##
######################################

#Write a model in the BUGS language

#Generate model file directly in R
#(could also read in existing model file)

writeLines("model{

  #Likelihood
  for (i in 1:n){ 

    employed[i] ~ dnorm(mu[i], tau)     
    mu[i] <- alpha + beta*gnp[i]

  }
    
  #Priors
  alpha ~ dnorm(0, 0.00001)
  beta ~ dnorm(0, 0.00001)
  sigma ~ dunif(0,1000)
  tau <- pow(sigma,-2)

}
", con="model.txt")

#Identify filepath of model file;
#in this case in the working directory
modfile <- 'model.txt'
  
######################################
##    3. Initialize Parameters      ##
######################################
  
#Best to generate initial values using function

inits <- function(){  
  list(alpha=rnorm(1,0,1),beta=rnorm(1,0,1),sigma=runif(1,0,3))  
}
  
#In many cases, JAGS can pick initial values automatically;
#you can leave argument inits=NULL to allow this.

######################################
##  4. Set parameters to monitor    ##
######################################

#Choose parameters you want to save output for
#Only parameters in this list will appear in output object
#(deviance is added automatically if DIC=TRUE)

#List must be specified as a character vector

params <- c('alpha','beta','sigma')

######################################
##        5. Run Analysis           ##
######################################

#Call jags function; specify number of chains, number of adaptive iterations,
#the length of the burn-in period, total iterations, and the thin rate.

out <- jags(data = data,
            inits = inits,
            parameters.to.save = params,
            model.file = modfile,
            n.chains = 3,
            n.adapt = 100,
            n.iter = 1000,
            n.burnin = 500,
            n.thin = 2)

#Arguments will be passed to JAGS; you will see progress bars
#and other information

#Examine output summary

out

#Look at output object elements
names(out)

#Plot traces and posterior densities
plot(out)

#Plot traces
traceplot(out)

#Update model another 1000 iterations
out <- update(out,n.iter = 1000)