mcmcplots (version 0.2)

caterplot: Caterpillar Plots of MCMC Output

Description

Creates plots of credible intervals for parameters from an MCMC simulation. Because these types of plots have been called "caterpillar" plots by other Bayesian software (like WinBUGS), this function is called caterplot, where the "cat" is pronounced as in caterpillar and not as in the word "cater".)

Usage

caterplot(mcmcout, parms = NULL, regex = NULL, random = NULL, quantiles = list(), collapse = TRUE, labels = NULL, labels.loc = "axis", cex.labels = NULL, horizontal=TRUE, val.lim = NULL, lab.lim = NULL, lwd = c(1, 2), pch = 19, col = mcmcplotsPalette(nchains), style=c("gray", "plain"), ...)

Arguments

mcmcout

a matrix, bugs, mcmc, or mcmc.list object. All objects will be coerced to mcmc.list.

parms

a vector of character strings that identifies which variables in mcmcout should be plotted. If parms and regex are both NULL, all parameter will be plotted.

regex

a vector of character strings with regular expressions that identify which variables in mcmcout should be plotted.

random

integer specifying how many parameters from each group will be randomly selected for plotting. This argument is useful when mcmcout has a large number of parameters (e.g., from a hierarchical model). If NULL, all parameters wil

quantiles

list with two elements outer and inner. The outer element of the list should contain the quantiles of the posterior draws that will be plotted as the longer, thinner line. The inner element of the list

collapse

if TRUE, all parallel chains are collapsed into one chain before plotting. If FALSE, parallel chains are plotted nearly on top of each other with colors as specified in col.

labels

labels for the individual "caterpillars." If NULL, parameter names in mcmcout are used.

labels.loc

if 'axis,' then parameter labels (the names of the parameters) will be plotted on the axis. If 'above,' then variable names will be plotted above the means for each 'caterplot.' If any other value, no names will be plotted.

cex.labels

character expansion factor for the plot labels. If names of parameters will not be plotted, this argument is ignored.

horizontal

logical indicating whether intervals should be plotted parallel to the x-axis (so horizontal lines) or parallel to the y axis.

val.lim

a vector containing the upper and lower limits for the "value" axis (which is the x axis if horizontal=TRUE). If NULL, the minimum and maximum values found by outer quantiles are used.

lab.lim

a vector containing the upper and lower limits for the "label" axis (which is the y axis if horizontal=TRUE). If NULL, limits are automatically selected to contain all the labels of the plotted intervals.

col

a single value or a vector of values specifying the colors to be used in plotting.

lwd

a vector of length 2 of line weights used for plotting the inner and outer caterpillars.

pch

plot character to use in plotting the medians of the intervals.

style

if "gray", then the plotting region is printed with a gray background, otherwise the default plotting region is used.

...

further arguments passed to the plotting function.

Value

• Invisibly returns a character vector with the names of the parameters that were plotted. This can be useful when the option random is specified and not all of the parameters are plotted. See caterpoints for an example of how to use the return value.

Details

The caterplot function uses the internal function parms2plot to match the strings in the parms argument to the names of the variables in mcmcout. Quantiles, as specified in the quantiles argument, are computed for the posterior draws of each variable returned by the call to parms2plot. The quantiles are then used to create plots of the posterior intervals of each matched variable. Medians are also plotted as points. This function produces a plot similar to the plots produced by the coefplot function in the R package arm and the caterpillar plots in the WinBUGS software.

References

None.

See Also

caterpoints, mcmcplot

Examples

## Create fake MCMC output
nc <- 10; nr <- 1000
pnames <- c(paste("alpha[", 1:5, "]", sep=""), paste("gamma[", 1:5, "]", sep=""))
means <- rpois(10, 20)
fakemcmc <- as.mcmc.list(lapply(1:3, function(i) mcmc(matrix(rnorm(nc*nr, rep(means, each=nr)), nrow=nr, dimnames=list(NULL,pnames)))))

## caterplot plots of the fake MCMC output
par(mfrow=c(2,2))
caterplot(fakemcmc, "alpha", collapse=FALSE)
caterplot(fakemcmc, "gamma", collapse=FALSE)
caterplot(fakemcmc, "alpha", labels.loc="axis", col="blue")
caterplot(fakemcmc, "gamma", labels.loc="above", col="red")

caterplot(fakemcmc, "alpha", collapse=FALSE, style="plain")
caterplot(fakemcmc, "gamma", collapse=FALSE, style="plain")
caterplot(fakemcmc, "alpha", labels.loc="axis")
caterplot(fakemcmc, "gamma", labels.loc="above")

caterplot(fakemcmc, "alpha", horizontal=FALSE)
caterplot(fakemcmc, horizontal=FALSE)
caterpoints(rnorm(10, 21, 2), horizontal=FALSE, pch="x", col="red")

## caterplot works on bugs objects too
library(R2WinBUGS)
example("openbugs", "R2WinBUGS")
## from the help file for openbugs:
schools.sim <- bugs(data, inits, parameters, model.file,
                    n.chains = 3, n.iter = 5000,
                    program = "openbugs", working.directory = NULL)
caterplot(schools.sim, "theta")