MCMCscatterplots.Rd
Scatterplots, hexagonal heatmaps, and pairs plots from MCMC draws. See the Plot Descriptions section, below, for details.
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(), ..., 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)
x  A 3D array, matrix, list of matrices, or data frame of MCMC draws.
The MCMCoverview page provides details on how to specify each these
allowed inputs. It is also possible to use an object with an


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

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()
.
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 the np
,
and np_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
, and np_style
arguments. If np
is specified (and
condition
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 both
np
and max_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. The
np_style
argument can be used with the pairs_style_np()
convenience function to change the appearance of these overlaid points.
See the Examples section.
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)
Other MCMC: MCMCcombos
,
MCMCdiagnostics
,
MCMCdistributions
,
MCMCintervals
, MCMCnuts
,
MCMCoverview
, MCMCparcoord
,
MCMCrecover
, MCMCtraces
library("ggplot2") # some parameter draws to use for demonstration x < example_mcmc_draws(params = 6) dimnames(x)#> $Iteration #> NULL #> #> $Chain #> [1] "chain:1" "chain:2" "chain:3" "chain:4" #> #> $Parameter #> [1] "alpha" "sigma" "beta[1]" "beta[2]" "beta[3]" "beta[4]" #># 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 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))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)))### 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 )#> Warning: There were 56 divergent transitions after warmup. Increasing adapt_delta above 0.9 may help. See #> http://mcstan.org/misc/warnings.html#divergenttransitionsafterwarmup#> Warning: Examine the pairs() plot to diagnose sampling problems#> Warning: Bulk Effective Samples Size (ESS) is too low, indicating posterior means and medians may be unreliable. #> Running the chains for more iterations may help. See #> http://mcstan.org/misc/warnings.html#bulkessposterior < 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__"])) )