Visualize posterior distributions from MCMC output for specific parameters of interest using caterpillar plots. Color of median dot represents the overlap of the posterior distribution with 0 (or other specified value).
MCMCplot(object, object2 = NULL, params = "all", excl = NULL,
ISB = TRUE, ref = 0, ref_ovl = FALSE, col = "black",
col2 = "red", offset = 0.1, rank = FALSE, horiz = TRUE, xlim,
ylim, xlab, ylab, main, labels, guide_lines = FALSE,
guide_axis = TRUE, sz_labels = 1.2, sz_med = 1.5, sz_thick = 5,
sz_thin = 2, sz_ax = 3, sz_ax_txt = 1.3, sz_tick_txt = 1.2,
sz_main_txt = 1.2, pos_tick, mar = c(5.1, 4.1, 4.1, 2.1))Object containing MCMC output. See DETAILS below.
Optional second object containing MCMC output. If specified, parameter estimates from each model will be displayed in a paired manner. Parameter names for 'object' and 'object2' must be identical. See DETAILS below.
Character string (or vector of character strings) denoting parameters to be plotted.
Default 'all' plots posteriors for all parameters. See VALUE below.
Character string (or vector of character strings) denoting parameters to exclude. Used in conjunction with params argument to select parameters of interest.
Ignore Square Brackets (ISB). Logical specifying whether square brackets should be ignored in the params and excl arguments. If TRUE, square brackets are ignored - input from params and excl are otherwise matched exactly. If FALSE, square brackets are not ignored - input from params and excl are matched using grep, which can take arguments in regular expression format. This allows partial names to be used when specifying parameters of interest.
Value indicating where vertical reference line should be created and what value to use a reference for caterpillar median coloration.
Default is ref = 0.
Argument NULL will plot no reference line.
Logical specifying whether the style/color of plotted median dots and CI should be changed based on whether the 50 % and 95 % credible intervals overlap the reference line. See DETAILS for more information.
Character string (or vector of character strings) specifying which color to render estimates on plot. When ref_ovl = TRUE, this argument has no effect and colors plotted will be based on the credible intervals and reference line. Number of specified colors must equal the number of specified parameters or one.
Character string (or vector of character strings) specifying which color to render estimates on plot for object2 (if specified). Number of specified colors must equal the number of specified parameters or one. Red by default.
Value indicating how much to offset plotted posteriors when object2 is specified (i.e., control the amount of space between the two plotted posteriors for each parameter). The distance from one set of parameters to another corresponds to a value of 1.
Logical specifying whether output should be ranked. If TRUE posteriors will be ranked in decreasing order (based on specified measure of centrality) from top down.
Logical specifying orientation of plot. If TRUE posteriors will be plotted running horizontally (parallel to the x-axis). If FALSE posteriors will be plotted running vertically (perpendicular to the x-axis).
Numerical vector of length 2, indicating range of x-axis. Only applicable if horiz = TRUE.
Numerical vector of length 2, indicating range of y-axis. Only applicable if horiz = FALSE.
Character string labeling x-axis. Only applicable if horiz = TRUE.
Default label is 'Parameter Estimate'. Option NULL will return plot with no label on x-axis.
Character string labeling y-axis. Only applicable if horiz = FALSE.
Default label is 'Parameter Estimate'. Option NULL will return plot with no label on y-axis.
Character string indicating title of plot.
Character string (or vector of character strings if plotting > 1 parameter) labeling parameter estimates along y-axis (if horiz = FALSE) or x-axis (if horiz = TRUE).
Default option will use parameter names from object.
Option NULL will return plot with no labels on axis.
Logical specifying whether to plot reference lines for each parameter in order to better visualize which parameter names correspond to each posterior.
Logical specifying whether a second axis should be plotted (x-axis if HORIZ = TRUE, y-axis if HORIZ = FALSE) to help interpret values on plot.
Number specifying size of text for parameter labels on axis.
Number specifying size of points represents posterior medians.
Number specifying thickness of 50 percent CI line (thicker line).
Number specifying thickness of 95 percent CI line (thinner line).
Number specifying thickness of axis and ticks.
Number specifying size of text for axis label.
Number specifying size of text for tick labels on axis.
Number specifying size of text for main title.
Numeric vector specifying where ticks on axis should be placed.
Numerical vector of length 4 specifying plot margins - (BOTTOM, LEFT, TOP, RIGHT). Changes to the margin should be made within the function rather than using the par call.
Default is c(5.1, 4.1, 4.1, 2.1) - the R plot default.
When specifying rank = TRUE and specifying labels for labels, labels will be applied to parameters before they are ranked.
Thanks to Cinner et al. 2016, whose Fig. 1 inspired this plot.
Points represent posterior medians. Parameters where 50% credible intervals overlap 0 (or other specified value) are indicated by 'open' circles. Parameters where 50 percent credible intervals DO NOT overlap 0 AND 95 percent credible intervals DO overlap 0 (or other specified value) are indicated by 'closed' gray circles. Parameters where 95 percent credible intervals DO NOT overlap 0 (or other specified value) are indicated by 'closed' black circles. Thick lines represent 50 percent credible intervals while thin lines represent 95 % credible intervals. ref_ovl = TRUE can be used to enable this feature.
When object2 is specified, paired caterpillar plots of each parameter are produced. For this reason, parameter names of object and object2 specified with the params argument must be identical (to be used for comparing posterior estimates of similar models). col and col2 arguments can be specified to change the color of output from object and object2, respectively. By default, output from object is plotted in black and object2 is plotted in red. The ref_ovl argument can also be specified.
object argument can be a stanfit object (rstan package), a stanreg object (rstanarm package), a brmsfit object (brms package), an mcmc.list object (coda package), an R2jags model object (R2jags package), a jagsUI model object (jagsUI package), or a matrix containing MCMC chains (each column representing MCMC output for a single parameter, rows representing iterations in the chain). The function automatically detects the object type and proceeds accordingly.
Cinner, J. E., C. Huchery, M. A. MacNeil, N. A. J. Graham, T. R. McClanahan, J. Maina, E. Maire, J. N. Kittinger, C. C. Hicks, C. Mora, E. H. Allison, S. D'Agata, A. Hoey, D. A. Feary, L. Crowder, I. D. Williams, M. Kulbicki, L. Vigliola, L. Wantiez, G. Edgar, R. D. Stuart-Smith, S. A. Sandin, A. L. Green, M. J. Hardt, M. Beger, A. Friedlander, S. J. Campbell, K. E. Holmes, S. K. Wilson, E. Brokovich, A. J. Brooks, J. J. Cruz-Motta, D. J. Booth, P. Chabanet, C. Gough, M. Tupper, S. C. A. Ferse, U. R. Sumaila, and D. Mouillot. 2016. Bright spots among the world's coral reefs. Nature 535:416-419.
# NOT RUN {
#Load data
data(MCMC_data)
#Plot MCMC output
MCMCplot(MCMC_data, labels = NULL)
#Just 'beta' parameters
MCMCplot(MCMC_data, params = 'beta')
#Just 'beta[1]', 'beta[4]', and 'alpha[3]'
#'params' takes regular expressions when ISB = FALSE, square brackets must be escaped with '\\'
MCMCplot(MCMC_data, params = c('beta\\[1\\]', 'beta\\[4\\]', 'alpha\\[3\\]'), ISB = FALSE)
#Rank parameters by posterior mean
MCMCplot(MCMC_data, params = 'beta', rank = TRUE)
#Create vertical plot
MCMCplot(MCMC_data, params = 'beta', horiz = FALSE)
# }
Run the code above in your browser using DataCamp Workspace