MCMCplot: Caterpillar plots of posterior distributions from MCMC output

Description Usage Arguments Details Notes References Examples

View source: R/MCMCplot.R

Description

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

Usage

1
2
3
4
5
6
MCMCplot(object, params = "all", excl = NULL, ISB = TRUE, ref = 0,
  ref_ovl = FALSE, col = "black", rank = FALSE, horiz = TRUE, xlim,
  ylim, xlab, ylab, main, labels, labels_sz = 1.2, med_sz = 1.5,
  thick_sz = 5, thin_sz = 2, ax_sz = 3, axis_text_sz = 1.3,
  tick_text_sz = 1.2, main_text_sz = 1.2, tick_pos, mar = c(5.1, 4.1, 4.1,
  2.1))

Arguments

object

Object containing MCMC output. See DETAILS below.

params

Character string (or vector of character strings) denoting parameters to be plotted.

Default 'all' plots posteriors for all parameters. See VALUE below.

excl

Character string (or vector of character strings) denoting parameters to exclude. Used in conjunction with params argument to select parameters of interest.

ISB

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.

ref

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.

ref_ovl

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.

col

Character string 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.

rank

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.

horiz

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

xlim

Numerical vector of length 2, indicating range of x-axis. Only applicable if horiz = TRUE.

ylim

Numerical vector of length 2, indicating range of y-axis. Only applicable if horiz = FALSE.

xlab

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.

ylab

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.

main

Character string indicating title of plot.

labels

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.

labels_sz

Number specifying size of text for parameter labels on axis.

med_sz

Number specifying size of points represents posterior medians.

thick_sz

Number specifying thickness of 50 percent CI line (thicker line).

thin_sz

Number specifying thickness of 95 percent CI line (thinner line).

ax_sz

Number specifying thickness of axis and ticks.

axis_text_sz

Number specifying size of text for axis label.

tick_text_sz

Number specifying size of text for tick labels on axis.

main_text_sz

Number specifying size of text for main title.

tick_pos

Numeric vector specifying where ticks on axis should be placed.

mar

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.

Details

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.

object argument can be a stanfit object (rstan 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.

Notes

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.

References

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.

Examples

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
#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)

MCMCvis documentation built on May 22, 2018, 9:03 a.m.