MCMCscatterplots {bayesplot}  R Documentation 
Scatterplots of MCMC draws
Description
Scatterplots, hexagonal heatmaps, and pairs plots from MCMC draws. See the Plot Descriptions section, below, for details.
Usage
mcmc_scatter(
x,
pars = character(),
regex_pars = character(),
transformations = list(),
...,
size = 2.5,
alpha = 0.8,
np = NULL,
np_style = scatter_style_np()
)
mcmc_hex(
x,
pars = character(),
regex_pars = character(),
transformations = list(),
...,
bins = 30,
binwidth = NULL
)
mcmc_pairs(
x,
pars = character(),
regex_pars = character(),
transformations = list(),
...,
diag_fun = c("hist", "dens"),
off_diag_fun = c("scatter", "hex"),
diag_args = list(),
off_diag_args = list(),
condition = pairs_condition(),
lp = NULL,
np = NULL,
np_style = pairs_style_np(),
max_treedepth = NULL,
grid_args = list(),
save_gg_objects = TRUE
)
scatter_style_np(
div_color = "red",
div_shape = 16,
div_size = 2.5,
div_alpha = 1
)
pairs_style_np(
div_color = "red",
div_shape = 4,
div_size = 1,
div_alpha = 1,
td_color = "yellow2",
td_shape = 3,
td_size = 1,
td_alpha = 1
)
pairs_condition(chains = NULL, draws = NULL, nuts = NULL)
Arguments
x 
An object containing MCMC draws:

pars 
An optional character vector of parameter names. If neither

regex_pars 
An optional regular expression to use for
parameter selection. Can be specified instead of 
transformations 
Optionally, transformations to apply to parameters
before plotting. If Note: due to partial argument matching 
... 
Currently ignored. 
size , alpha 
For 
np 
Optionally, a data frame of NUTS sampler parameters, either created
by 
np_style 
If 
bins , binwidth 
For 
diag_fun , off_diag_fun 
For 
diag_args , off_diag_args 
For 
condition 
For 
lp 
For 
max_treedepth 
For 
grid_args , save_gg_objects 
For 
div_color , div_shape , div_size , div_alpha , td_color , td_shape , td_size , td_alpha 
Optional arguments to the 
chains , draws , nuts 
Optional arguments to the

Value
mcmc_scatter()
and mcmc_hex()
return a ggplot object that
can be further customized using the ggplot2 package.
mcmc_pairs()
returns many ggplot objects organized into a grid via
bayesplot_grid()
.
Plot Descriptions
mcmc_scatter()

Bivariate scatterplot of posterior draws. If using a very large number of posterior draws then
mcmc_hex()
may be preferable to avoid overplotting. For models fit using NUTS thenp
, andnp_style
arguments can be used to add additional information in the plot (in this case the approximate location of divergences). For more on why the scatter plot with divergences is a useful diagnostic tool see Gabry et al. (2019). mcmc_hex()

Hexagonal heatmap of 2D bin counts. This plot is useful in cases where the posterior sample size is large enough that
mcmc_scatter()
suffers from overplotting. mcmc_pairs()

A square plot matrix with univariate marginal distributions along the diagonal (as histograms or kernel density plots) and bivariate distributions off the diagonal (as scatterplots or hex heatmaps).
For the offdiagonal plots, the default is to split the chains so that (roughly) half are displayed above the diagonal and half are below (all chains are always merged together for the plots along the diagonal). Other possibilities are available by setting the
condition
argument.Additionally, extra diagnostic information for models fit using NUTS can be added to the pairs plot using the
lp
,np
, andnp_style
arguments. Ifnp
is specified (andcondition
is not"divergent__"
), then points (red, by default) will be superimposed onto the offdiagonal plots indicating which (if any) iterations encountered a divergent transition. Also, if bothnp
andmax_treedepth
are specified then points (yellow, by default) will be superimposed to indicate a transition that hit the maximum treedepth rather than terminated its evolution normally. Thenp_style
argument can be used with thepairs_style_np()
convenience function to change the appearance of these overlaid points. See the Examples section.
References
Gabry, J. , Simpson, D. , Vehtari, A. , Betancourt, M. and Gelman, A. (2019), Visualization in Bayesian workflow. J. R. Stat. Soc. A, 182: 389402. doi:10.1111/rssa.12378. (journal version, arXiv preprint, code on GitHub)
See Also
Other MCMC:
MCMCcombos
,
MCMCdiagnostics
,
MCMCdistributions
,
MCMCintervals
,
MCMCnuts
,
MCMCoverview
,
MCMCparcoord
,
MCMCrecover
,
MCMCtraces
Examples
library("ggplot2")
# some parameter draws to use for demonstration
x < example_mcmc_draws(params = 6)
dimnames(x)
# scatterplot of alpha vs log(sigma)
color_scheme_set("teal")
(p < mcmc_scatter(x, pars = c("alpha", "sigma"),
transform = list(sigma = "log")))
p +
labs(
title = "Insert your own headlinegrabbing title",
subtitle = "with a provocative subtitle",
caption = "and a controversial caption",
x = expression(alpha),
y = expression(log(sigma))
)
# add ellipse
p + stat_ellipse(level = 0.9, color = "gray20", size = 1)
# add contour
color_scheme_set("red")
p2 < mcmc_scatter(x, pars = c("alpha", "sigma"), size = 3.5, alpha = 0.25)
p2 + stat_density_2d(color = "black", size = .5)
# can also add lines/smooths
color_scheme_set("pink")
(p3 < mcmc_scatter(x, pars = c("alpha", "beta[3]"), alpha = 0.25, size = 3))
p3 + geom_smooth(method = "lm", se = FALSE, color = "gray20",
size = .75, linetype = 2)
if (requireNamespace("hexbin", quietly = TRUE)) {
# hexagonal heatmap
color_scheme_set("brightblue")
(p < mcmc_hex(x, pars = c("sigma", "alpha"), transform = list(sigma = "log")))
p + plot_bg(fill = "gray95")
p + plot_bg(fill = "gray95") + panel_bg(fill = "gray70")
}
color_scheme_set("purple")
# pairs plots
# default of condition=NULL implies splitting chains between upper and lower panels
mcmc_pairs(x, pars = "alpha", regex_pars = "beta\\[[1,4]\\]",
off_diag_args = list(size = 1, alpha = 0.5))
# change to density plots instead of histograms and hex plots instead of
# scatterplots
mcmc_pairs(x, pars = "alpha", regex_pars = "beta\\[[1,4]\\]",
diag_fun = "dens", off_diag_fun = "hex")
# plot chain 1 above diagonal and chains 2, 3, and 4 below
color_scheme_set("brightblue")
mcmc_pairs(x, pars = "alpha", regex_pars = "beta\\[[1,4]\\]",
diag_fun = "dens", off_diag_fun = "hex",
condition = pairs_condition(chains = list(1, 2:4)))
## Not run:
### Adding NUTS diagnostics to scatterplots and pairs plots
# examples using rstanarm package
library(rstanarm)
# for demonstration purposes, intentionally fit a model that
# will (almost certainly) have some divergences
fit < stan_glm(
mpg ~ ., data = mtcars,
iter = 1000, refresh = 0,
# this combo of prior and adapt_delta should lead to some divergences
prior = hs(),
adapt_delta = 0.9
)
posterior < as.array(fit)
np < nuts_params(fit)
# mcmc_scatter with divergences highlighted
color_scheme_set("brightblue")
mcmc_scatter(posterior, pars = c("wt", "sigma"), np = np)
color_scheme_set("darkgray")
div_style < scatter_style_np(div_color = "green", div_shape = 4, div_size = 4)
mcmc_scatter(posterior, pars = c("sigma", "(Intercept)"),
np = np, np_style = div_style)
# split the draws according to above/below median accept_stat__
# and show approximate location of divergences (red points)
color_scheme_set("brightblue")
mcmc_pairs(
posterior,
pars = c("wt", "cyl", "sigma"),
off_diag_args = list(size = 1, alpha = 1/3),
condition = pairs_condition(nuts = "accept_stat__"),
np = np
)
# more customizations:
#  transform sigma to log(sigma)
#  median logposterior as 'condition'
#  hex instead of scatter for offdiagonal plots
#  show points where max treedepth hit in blue
color_scheme_set("darkgray")
mcmc_pairs(
posterior,
pars = c("wt", "cyl", "sigma"),
transform = list(sigma = "log"),
off_diag_fun = "hex",
condition = pairs_condition(nuts = "lp__"),
lp = log_posterior(fit),
np = np,
np_style = pairs_style_np(div_color = "firebrick",
td_color = "blue",
td_size = 2),
# for demonstration purposes, set max_treedepth to a value that will
# result in at least a few max treedepth warnings
max_treedepth = with(np, 1 + max(Value[Parameter == "treedepth__"]))
)
## End(Not run)