Changelog

Source: NEWS.md

bayesplot (development version)

• Unified density-control argument defaults (bw, adjust, kernel, n_dens) to use NULL with internal fallbacks. No change in user-facing behavior.
• prepare_mcmc_array() now warns instead of erroring on NAs in the input.
• Fixed validate_chain_list() colnames check to compare all chains, not just the first two.
• Added test verifying legend_move("none") behaves equivalently to legend_none().
• Added singleton-dimension edge-case tests for exported _data() functions.
• Validate empty list and zero-row matrix inputs in nuts_params.list().
• Validate user-provided pit values in ppc_loo_pit_data() and ppc_loo_pit_qq(), rejecting non-numeric inputs, missing values, and values outside [0, 1].
• New show_marginal argument to ppd_*() functions to show the PPD - the marginal predictive distribution by @mattansb (#425)
• ppc_ecdf_overlay(), ppc_ecdf_overlay_grouped(), and ppd_ecdf_overlay() now always use geom_step(). The discrete argument is deprecated.
• Fixed missing drop = FALSE in nuts_params.CmdStanMCMC().
• Replace apply() with storage.mode() for integer-to-numeric matrix conversion in validate_predictions().
• Fixed is_chain_list() to correctly reject empty lists instead of silently returning TRUE.
• Added unit tests for mcmc_areas_ridges_data(), mcmc_parcoord_data(), and mcmc_trace_data().
• Added unit tests for ppc_error_data() and ppc_loo_pit_data() covering output structure, argument handling, and edge cases.
• Added vignette sections demonstrating *_data() companion functions for building custom ggplot2 visualizations (#435)
• Extract drop_singleton_values() helper in mcmc_nuts_treedepth() to remove duplicated filtering logic.
• Eliminate redundant data processing in mcmc_areas_data() by reusing the prepared MCMC array for both interval and density computation.
• Validate equal chain lengths in validate_df_with_chain(), reject missing chain labels, and renumber data-frame chain labels internally when converting to arrays.
• Added unit tests for previously untested edge cases in param_range(), param_glue(), and tidyselect_parameters() (no-match, partial-match, and negation behavior).
• Bumped minimum version for rstantools from >= 1.5.0 to >= 2.0.0 .
• Use rlang::warn() and rlang::inform() for selected PPC user messages instead of base warning() and message().
• Standardize input validation errors in ppc_km_overlay() and interpolation helpers to use rlang::abort() for consistent error handling.
• Fix assignment-in-call bug in mcmc_rank_ecdf() (#).
• Replaced deprecated dplyr and tidyselect functions (top_n, one_of, group_indices) with their modern equivalents to ensure future compatibility. (#431)
• Documentation added for all exported *_data() functions (#209)
• Improved documentation for binwidth, bins, and breaks arguments to clarify they are passed to ggplot2::geom_area() and ggdist::stat_dots() in addition to ggplot2::geom_histogram()
• Improved documentation for freq argument to clarify it applies to frequency polygons in addition to histograms
• Fixed test in test-ppc-distributions.R that incorrectly used ppc_dens() instead of ppd_dens() when testing PPD functions
• New functions mcmc_dots and mcmc_dots_by_chain for dot plots of MCMC draws by @behramulukir (#402)
• Default to quantiles=100 for all dot plots by @behramulukir (#402)
• Use "neff_ratio" consistently in diagnostic color scale helpers to avoid relying on partial matching of "neff".
• Replace expand = c(mult, add) with ggplot2::expansion() helper in scale functions for consistency with ggplot2 >= 3.3.0 style.
• Replace uses of geom_bar(stat = "identity") with the more idiomatic ggplot2 form geom_col()
• New function ppc_rootogram_grouped for grouped rootogram plots by @behramulukir and @jgabry (#419)

bayesplot 1.15.0

CRAN release: 2025-12-12

• Add shape argument to mcmc_scatter by @behramulukir (#375)
• Restore pre ggplot2 v4.0 behavior of bayesplot theme setting by @jgabry (#385)
• New pkgdown theme by @VisruthSK in (#378)
• Testthat 3e by @VisruthSK (#397)
• Update loo PIT visual tests by @jgabry (#374)
• Update SVGs for visual tests for ggplot2 v4.0 by @jgabry (#379)
• Bumped roxygen and fixed linking note by @VisruthSK (#382)
• Fix height/width attributes in Rd files for CRAN by @jgabry (#387)

bayesplot 1.14.0

CRAN release: 2025-08-31

• PPC “avg” functions (ppc_scatter_avg(), ppc_error_scatter_avg(), etc.) gain a stat argument to set the averaging function. (Suggestion of #348, @kruschke).
• ppc_error_scatter_avg_vs_x(x = some_expression) labels the x axis with some_expression.
• New quantile dot plot functions ppc_dots() and ppd_dots() by @behramulukir (#357)
• Add x argument to ppc_error_binned() to control x axis by @behramulukir (#359)
• Add x argument to ppc_error_scatter_avg() to control x axis by @behramulukir (#367)
• Add discrete style to ppc_rootogram() by @behramulukir (#362)
• Add discrete argument to ppc_stat() and ppd_stat() to support discrete stats by @behramulukir (#369)

bayesplot 1.13.0

CRAN release: 2025-06-18

• Add ppc_loo_pit_ecdf() by @TeemuSailynoja (#345)
• Add possibility for left-truncation to ppc_km_overlay() and ppc_km_overlay_grouped() by @Sakuski (#347)
• Give user control over extrapolation in ppc_km_overlay() and ppc_km_overlay_grouped() by @Sakuski (#353)
• Allow passing moment_match via ... for loo functions by @n-kall (#351)
• Skip some tests when missing Suggests by @MichaelChirico (#344)
• Remove a test that will fail with next ggplot2 release (#356)

bayesplot 1.12.0

CRAN release: 2025-04-10

• Expand checking workflows to more platforms by @andrjohns (#324)
• Skip tests depending on Suggested dependency rstantools if not installed by @MichaelChirico (#325)
• Skip tests depending on Suggested dependency gridExtra if not installed by @MichaelChirico (#326)
• Fix missing legends for unobserved levels in rhat and neff plots (#328)
• Document problems with ppc_stat with stat="mean" (#329)
• Ensure rank overlay plot starts at 0 even if not all bins present, thanks @sims1253 (#332)
• Compatibility with ggplot2 3.6.0 by @teunbrand (#337)
• Update GitHub actions workflows (#338)
• Remove deprecated functions from available_ppc() (#340)
• Fix missing counts in ppc_bars_data() by @TeemuSailynoja, thanks @famuvie (#342)

bayesplot 1.11.1

CRAN release: 2024-02-15

• Limit maximum number of evaluation points in ppc_pit_ecdf functions by default to 1000. by @TeemuSailynoja in #318

bayesplot 1.11.0

CRAN release: 2024-01-30

• Update for new ggplot2 release by @teunbrand in #309
• Add bins argument to many histogram plots by 2 in #300
• Follow ggplot2 updates on facet_grid() and facet_wrap() by @heavywatal in #305
• Better ppc_loo_pit_qq plots by @avehtari in #307
• Check prob is numeric for intervals plots by @tony-stone in #299
• Add bins and breaks arguments to more histogram and hex plots by @heavywatal in #313
• Replace size argument with linewidth for geom_line and geom_ridgeline by @heavywatal in #314
• All LOO plots now accept psis_object argument by @jgabry in #311
• ppc_pit_ecdf() and ppc_pit_ecdf_grouped() now support discrete variables, and their default method for selecting the number of ECDF evaluation points has been updated. by @TeemuSailynoja in #316

bayesplot 1.10.0

CRAN release: 2022-11-16

• New function mcmc_rank_ecdf() for rank ecdf plots with confidence bands for assessing if two or more chains sample the same distribution (#282, @TeemuSailynoja)
• New functions ppc_pit_ecdf(), ppc_pit_ecdf_grouped(), PIT ecdf plots with confidence bands to assess if y and yrep contain samples from the same distribution. (#282, @TeemuSailynoja)
• Several ppc and ppd functions now accept the new linewidth argument introduced in ggplot2 3.4.0: ppc_bars(), ppc_bars_grouped(), ppc_intervals(), ppc_intervals_grouped(), ppd_intervals(), ppd_intervals_grouped().
• Fix bug in how mcmc_pairs() detected hitting max_treedepth, thanks to @dmphillippo. (#281)
• Fix failing tests due to changes in ggplot2 3.4.0 (#289)

bayesplot 1.9.0

CRAN release: 2022-03-10

• New module PPD (posterior/prior predictive distribution) with a lot of new plotting functions with ppd_ prefix. These functions plot draws from the prior or posterior predictive distributions (PPD) without comparing to observed data (i.e., no y argument). Because these are not “checks” against the observed data we use PPD instead of PPC. These plots are essentially the same as the corresponding PPC plots but without showing any observed data (e.g., ppd_intervals() is like ppc_intervals() but without plotting y). See help("PPD-overview") for details. (#151, #222)

• All PPC categories now have one or more _data() functions that return the data frame used for plotting (#97, #222). Many of these have already been in previous releases, but the new ones in this release are:

  • ppc_bars_data()
  • ppc_error_data()
  • ppc_error_binnned_data()
  • ppc_scatter_data()
  • ppc_scatter_avg_data()
  • ppc_stat_data()

• Many functions gain an argument facet_args for controlling ggplot2 faceting (many other functions have had this argument for a long time). The ones that just now got the argument are:

  • ppc_scatter()
  • ppc_scatter_avg_grouped()
  • ppc_error_hist()
  • ppc_error_hist_grouped()
  • ppc_error_scatter()
  • ppc_error_binned()

• New plotting function ppc_km_overlay_grouped(), the grouped variant of ppc_km_overlay(). (#260, @fweber144)

• ppc_scatter(), ppc_scatter_avg(), and ppc_scatter_avg_grouped() gain an argument ref_line, which can be set to FALSE to turn off the x=y line drawn behind the scatterplot.

• ppc_ribbon() and ppc_ribbon_grouped() gain argument y_draw that specifies whether the observed y should be plotted using a point, line, or both. (#257, @charlesm93)

• mcmc_*() functions now support all draws formats from the posterior package. (#277, @Ozan147)

• mcmc_dens() and mcmc_dens_overlay() gain arguments for controlling the the density calculation. (#258)

• mcmc_hist() and mcmc_dens() gain argument alpha for controlling transparency. (#244)

• mcmc_areas() and mcmc_areas_ridges() gain an argument border_size for controlling the thickness of the ridgelines. (#224)

bayesplot 1.8.1

CRAN release: 2021-06-14

• Fix R cmd check error on linux for CRAN

bayesplot 1.8.0

CRAN release: 2021-01-10

Bug fixes

• mcmc_areas() tries to use less vertical blank space. (#218, #230)

• Fix bug in color_scheme_view() minimal theme (#213).

• Fix error in mcmc_acf() for certain input types. (#244, #245, @hhau)

New features

• New plotting functions ppc_dens_overlay_grouped() and ppc_ecdf_overlay_grouped() for plotting density and cumulative distributions of the posterior predictive distribution (versus observed data) by group. (#212)

• New plotting function ppc_km_overlay() for outcome variables that are
  right-censored. Empirical CCDF estimates of yrep are compared with the Kaplan-Meier estimate of y. (#233, #234, @fweber144)

• ppc_loo_pit_overlay() now uses a boundary correction for an improved kernel density estimation. The new argument boundary_correction defaults to TRUE but can be set to FALSE to recover the old version of the plot. (#171, #235,

• CmdStanMCMC objects (from CmdStanR) can now be used with extractor functions nuts_params(), log_posterior(), rhat(), and neff_ratio(). (#227)

• On the y axis, ppc_loo_pit_qq(..., compare = "normal") now plots standard normal quantiles calculated from the PIT values (instead of the standardized PIT values). (#240, #243, @fweber144)

• mcmc_rank_overlay() gains argument facet_args. (#221, @hhau)

• For mcmc_intervals() the sizeof the points and interval lines can be set withmcmc_intervals(…, outer_size, inner_size, point_size)`. (#215, #228, #229)

bayesplot 1.7.2

CRAN release: 2020-05-28

Compatibility with dplyr 1.0.0 (#219)

bayesplot 1.7.1

CRAN release: 2019-12-01

Release requested by CRAN to fix errors at https://cran.r-project.org/web/checks/check_results_bayesplot.html due to matrices also inheriting from “array” in R 4.0.

bayesplot 1.7.0

CRAN release: 2019-05-23

(GitHub issue/PR numbers in parentheses)

• The pars argument of all MCMC plotting functions now supports tidy variable selection. See help("tidy-params", package="bayesplot") for details and examples. (#161, #183, #188)

• Two new plots have been added for inspecting the distribution of ranks. Rank histograms were introduced by the Stan team’s new paper on MCMC diagnostics. (#178, #179)

  mcmc_rank_hist(): A traditional traceplot (mcmc_trace()) visualizes how sampled values the MCMC chains mix over the course of sampling. A rank histogram (mcmc_rank_hist()) visualizes how the ranks of values from the chains mix together. An ideal plot would show the ranks mixing or overlapping in a uniform distribution.

  mcmc_rank_overlay(): Instead of drawing each chain’s histogram in a separate panel, this plot draws the top edge of the chains’ histograms in a single panel.

• Added mcmc_trace_data(), which returns the data used for plotting the trace plots and rank histograms. (Advances #97)

• ColorBrewer palettes are now available as color schemes via color_scheme_set(). For example, color_scheme_set("brewer-Spectral") will use the Spectral palette. (#177, #190)

• MCMC plots now also accept objects with an as.array method as input (e.g., stanfit objects). (#175, #184)

• mcmc_trace() gains an argument iter1 which can be used to label the traceplot starting from the first iteration after warmup. (#14, #155, @mcol)

• mcmc_areas() gains an argument area_method which controls how to draw the density curves. The default "equal area" constrains the heights so that the curves have the same area. As a result, a narrow interval will appear as a spike of density, while a wide, uncertain interval is spread thin over the x axis. Alternatively "equal height" will set the maximum height on each curve to the same value. This works well when the intervals are about the same width. Otherwise, that wide, uncertain interval will dominate the visual space compared to a narrow, less uncertain interval. A compromise between the two is "scaled height" which scales the curves from "equal height" using height * sqrt(height). (#163, #169)

• mcmc_areas() correctly plots density curves where the point estimate does not include the highest point of the density curve. (#168, #169, @jtimonen)

• mcmc_areas_ridges() draws the vertical line at x = 0 over the curves so that it is always visible.

• mcmc_intervals() and mcmc_areas() raise a warning if prob_outer is ever less than prob. It sorts these two values into the correct order. (#138)

• MCMC parameter names are now always converted to factors prior to plotting. We use factors so that the order of parameters in a plot matches the order of the parameters in the original MCMC data. This change fixes a case where factor-conversion failed. (#162, #165, @wwiecek)

• The examples in ?ppc_loo_pit_overlay() now work as expected. (#166, #167)

• Added "viridisD" as an alternative name for "viridis" to the supported colors.

• Added "viridisE" (the cividis version of viridis) to the supported colors.

• ppc_bars() and ppc_bars_grouped() now allow negative integers as input. (#172, @jeffpollock9)

bayesplot 1.6.0

CRAN release: 2018-08-02

(GitHub issue/PR numbers in parentheses)

• Loading bayesplot no longer overrides the ggplot theme! Rather, it sets a theme specific for bayesplot. Some packages using bayesplot may still override the default ggplot theme (e.g., rstanarm does but only until next release), but simply loading bayesplot itself will not. There are new functions for controlling the ggplot theme for bayesplot that work like their ggplot2 counterparts but only affect plots made using bayesplot. Thanks to Malcolm Barrett. (#117, #149).

  • bayesplot_theme_set()
  • bayesplot_theme_get()
  • bayesplot_theme_update()
  • bayesplot_theme_replace()

• The Visual MCMC Diagnostics vignette has been reorganized and has a lot of useful new content thanks to Martin Modrák. (#144, #153)

• The LOO predictive checks now require loo version >= 2.0.0. (#139)

• Histogram plots gain a breaks argument that can be used as an alternative to binwidth. (#148)

• mcmc_pairs() now has an argument grid_args to provide a way of passing optional arguments to gridExtra::arrangeGrob(). This can be used to add a title to the plot, for example. (#143)

• ppc_ecdf_overlay() gains an argument discrete, which is FALSE by default, but can be used to make the Geom more appropriate for discrete data. (#145)

• PPC intervals plots and LOO predictive checks now draw both an outer and an inner probability interval, which can be controlled through the new argument prob_outer and the already existing prob. This is consistent with what is produced by mcmc_intervals(). (#152, #154, @mcol)

bayesplot 1.5.0

CRAN release: 2018-03-30

(GitHub issue/PR numbers in parentheses)

• New package documentation website: https://mc-stan.org/bayesplot/

• Two new plots that visualize posterior density using ridgelines. These work well when parameters have similar values and similar densities, as in hierarchical models. (#104)

  • mcmc_dens_chains() draws the kernel density of each sampling chain.
  • mcmc_areas_ridges() draws the kernel density combined across chains.
  • Both functions have a _data() function to return the data plotted by each function.

• mcmc_intervals() and mcmc_areas() have been rewritten. (#103)

  • They now use a discrete y-axis. Previously, they used a continuous scale with numeric breaks relabelled with parameter names; this design
    caused some unexpected behavior when customizing these plots.
  • mcmc_areas() now uses geoms from the ggridges package to draw density curves.

• Added mcmc_intervals_data() and mcmc_areas_data() that return data plotted by mcmc_intervals() and mcmc_areas(). (Advances #97)

• New ppc_data() function returns the data plotted by many of the PPC plotting functions. (Advances #97)

• Added ppc_loo_pit_overlay() function for a better LOO PIT predictive check. (#123)

• Started using vdiffr to add visual unit tests to the existing PPC unit tests. (#137)

bayesplot 1.4.0

CRAN release: 2017-09-12

(GitHub issue/PR numbers in parentheses)

• New plotting function mcmc_parcoord() for parallel coordinates plots of MCMC draws (optionally including HMC/NUTS diagnostic information). (#108)

• mcmc_scatter gains an np argument for specifying NUTS parameters, which allows highlighting divergences in the plot. (#112)

• New functions with names ending with suffix _data don’t make the plots, they just return the data prepared for plotting (more of these to come in future releases):

  • ppc_intervals_data() (#101)
  • ppc_ribbon_data() (#101)
  • mcmc_parcoord_data() (#108)
  • mcmc_rhat_data() (#110)
  • mcmc_neff_data() (#110)

• ppc_stat_grouped(), ppc_stat_freqpoly_grouped() gain a facet_args argument for controlling ggplot2 faceting (many of the mcmc_ functions already have this).

• The divergences argument to mcmc_trace() has been deprecated in favor of np (NUTS parameters) to match the other functions that have an np argument.

• Fixed an issue where duplicated rhat values would break mcmc_rhat() (#105).

bayesplot 1.3.0

CRAN release: 2017-08-07

(GitHub issue/PR numbers in parentheses)

• bayesplot::theme_default() is now set as the default ggplot2 plotting theme when bayesplot is loaded, which makes changing the default theme using ggplot2::theme_set() possible. Thanks to @gavinsimpson. (#87)

• mcmc_hist() and mcmc_hist_by_chain() now take a freq argument that defaults to TRUE (behavior is like freq argument to R’s hist function).

• Using a ts object for y in PPC plots no longer results in an error. Thanks to @helske. (#94)

• mcmc_intervals() doesn’t use round lineends anymore as they slightly exaggerate the width of the intervals. Thanks to @tjmahr. (#96)

bayesplot 1.2.0

CRAN release: 2017-04-12

A lot of new stuff in this release. (GitHub issue/PR numbers in parentheses)

Fixes

• Avoid error in some cases when divergences is specified in call to mcmc_trace() but there are not actually any divergent transitions.

• The merge_chains argument to mcmc_nuts_energy() now defaults to FALSE.

New features in existing functions

• For mcmc_*() functions, transformations are recycled if transformations argument is specified as a single function rather than a named list. Thanks to @tklebel. (#64)

• For ppc_violin_grouped() there is now the option of showing y as a violin, points, or both. Thanks to @silberzwiebel. (#74)

• color_scheme_get() now has an optional argument i for selecting only a subset of the colors.

• New color schemes: darkgray, orange, viridis, viridisA, viridisB, viridisC. The viridis schemes are better than the other schemes for trace plots (the colors are very distinct from each other).

New functions

• mcmc_pairs(), which is essentially a ggplot2+grid implementation of rstan’s pairs.stanfit() method. (#67)

• mcmc_hex(), which is similar to mcmc_scatter() but using geom_hex() instead of geom_point(). This can be used to avoid overplotting. (#67)

• overlay_function() convenience function. Example usage: add a Gaussian (or any distribution) density curve to a plot made with mcmc_hist().

• mcmc_recover_scatter() and mcmc_recover_hist(), which are similar to mcmc_recover_intervals() and compare estimates to “true” values used to simulate data. (#81, #83)

• New PPC category Discrete with functions:

  • ppc_rootogram() for use with models for count data. Thanks to
    2. (#28)
  • ppc_bars(), ppc_bars_grouped() for use with models for ordinal, categorical and multinomial data. Thanks to @silberzwiebel. (#73)

• New PPC category LOO (thanks to suggestions from @avehtari) with functions:

  • ppc_loo_pit() for assessing the calibration of marginal predictions. (#72)
  • ppc_loo_intervals(), ppc_loo_ribbon() for plotting intervals of the LOO predictive distribution. (#72)

bayesplot 1.1.0

CRAN release: 2016-12-20

(GitHub issue/PR numbers in parentheses)

Fixes

• Images in vignettes should now render properly using png device. Thanks to TJ Mahr. (#51)

• xaxis_title(FALSE) and yaxis_title(FALSE) now set axis titles to NULL rather than changing theme elements to element_blank(). This makes it easier to add axis titles to plots that don’t have them by default. Thanks to Bill Harris. (#53)

New features in existing functions

• Add argument divergences to mcmc_trace() function. For models fit using HMC/NUTS this can be used to display divergences as a rug at the bottom of the trace plot. (#42)

• The stat argument for all ppc_stat_*() functions now accepts a function instead of only the name of a function. (#31)

New functions

• ppc_error_hist_grouped() for plotting predictive errors by level of a grouping variable. (#40)

• mcmc_recover_intervals)( for comparing MCMC estimates to “true” parameter values used to simulate the data. (#56)

• bayesplot_grid() for juxtaposing plots and enforcing shared axis limits. (#59)

bayesplot 1.0.0

CRAN release: 2016-11-18

Initial CRAN release