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".)
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.
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. 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.
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.
Note
None.
Author(s)
S. McKay Curtis
References
Jackson, C. H. (2008) “Displaying uncertainty with shading”. The American Statistician, 62(4):340-347.