caterplot: Caterpillar Plots of MCMC Output
In mcmcplots: Create Plots from MCMC Output

Description Usage Arguments Details Value Note Author(s) References See Also Examples

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".)

caterplot(mcmcout, parms = NULL, regex = NULL, random = NULL,
leaf.marker = "[\\[_]", quantiles = list(), collapse = TRUE,
reorder = collapse, denstrip = FALSE, add = FALSE, labels = NULL,
labels.loc = "axis", las = NULL, cex.labels = NULL, greek = FALSE,
horizontal=TRUE, val.lim = NULL, lab.lim = NULL, lwd = c(1, 2),
pch = 16, eps = 0.1, width = NULL, col = NULL, cat.shift=0,
style=c("gray", "plain"), ...)

`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 will be plotted.
`leaf.marker`	a regular expression with a character class that marks the beginning of the “leaf” portion of a parameter name. The default character class includes `[` and `_`
`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 should contain the quantiles of posterior draws that will be plotted as the shorter, thicker line. If missing, the default is to use `list(outer=c(0.025,0.975),inner=c(0.16,0.84))`, which corresponds to 95% and 68% credible intervals.
`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`.
`reorder`	if `TRUE`, caterpillars will be ordered according to their medians. This option only works when `collapse=TRUE`.
`denstrip`	if `TRUE`, then density strips will be plotted rather than quantile line plots.
`add`	if `TRUE`, output will be added to the existing plot.
`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.
`las`	controls the rotation of the labels on the label axis. See documentation for `par` for more information.
`cex.labels`	character expansion factor for the plot labels. If names of parameters will not be plotted, this argument is ignored.
`greek`	if `TRUE`, the names of greek letters in the `labels` will be displayed as greek characters on the plot.
`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. Default is `mcmcplotsPalette(nchains)`
`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.
`eps`	controls the spacing between parallel caterpillars when `collapse=FALSE`
`width`	width of the density strips.
`cat.shift`	if greater than 0, "caterpillars" are translated up (left) by the amount `cat.shift`. If less than 0, "caterpillars" are translated down (right) by the amount `cat.shift`.
`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.

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. If the option denstrip is set to TRUE, then density strips are plotted instead of quantile lines. (See Jackson, 2008.)

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.

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.

None.

S. McKay Curtis

Jackson, C. H. (2008) “Displaying uncertainty with shading”. The American Statistician, 62(4):340-347.

caterpoints, mcmcplot, denstrip, parms2plot

## Create fake MCMC output
nc <- 10; nr <- 1000
pnames <- c(paste("alpha[1,", 1:5, "]", sep=""), paste("gamma[", 1:5, "]", sep=""))
means <- rpois(10, 20)
fakemcmc <- coda::as.mcmc.list(
    lapply(1:3,
           function(i)
               coda::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", greek=TRUE, col="blue")
caterplot(fakemcmc, "gamma", labels.loc="above", greek=TRUE, col="red")

caterplot(fakemcmc, "alpha", collapse=FALSE, denstrip=TRUE)
caterplot(fakemcmc, "gamma", collapse=FALSE, denstrip=TRUE)
caterplot(fakemcmc, "alpha", labels.loc="axis", col="blue", denstrip=TRUE)
caterplot(fakemcmc, "gamma", labels.loc="above", col="red", denstrip=TRUE)

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(fakemcmc, horizontal=FALSE, denstrip=TRUE, col="blue", pch=NA)
caterplot(fakemcmc, horizontal=FALSE, col="red", pch=19, add=TRUE)
caterplot(fakemcmc, denstrip=TRUE, col="blue", pch=NA)
caterplot(fakemcmc, col="purple", pch=19, add=TRUE)

## Overlay caterplots
caterplot(fakemcmc, "alpha", collapse=TRUE)
caterplot(fakemcmc, "gamma", collapse=TRUE, add=TRUE, cat.shift=-0.3)

## What happens with NULL varnames?
coda::varnames(fakemcmc) <- NULL
caterplot(fakemcmc)
caterplot(fakemcmc, collapse=FALSE)

## Not run: 
## 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")

## End(Not run)