diff --git a/NEWS.md b/NEWS.md index 5dd86c77..b5b642f4 100644 --- a/NEWS.md +++ b/NEWS.md @@ -1,10 +1,9 @@ # bayesplot (development version) +* 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. +* 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()`. diff --git a/vignettes/graphical-ppcs.Rmd b/vignettes/graphical-ppcs.Rmd index db649f42..fc860ab2 100644 --- a/vignettes/graphical-ppcs.Rmd +++ b/vignettes/graphical-ppcs.Rmd @@ -314,6 +314,45 @@ See Figure 8 in [Gabry et al. (2019)](#gabry2019) for another example of using
+## Using `*_data()` functions for custom plots + +Many bayesplot plotting functions have a companion `*_data()` function that +returns the pre-processed data as a tidy data frame instead of a plot. This is +useful when you want to build a fully custom ggplot2 visualization using the +same summary statistics that bayesplot computes internally. + +For example, `ppc_intervals_data()` returns the quantile summaries that +`ppc_intervals()` uses: + +```{r data_intervals, eval=params$EVAL} +d <- ppc_intervals_data(y, yrep_nb, prob = 0.5, prob_outer = 0.9) +head(d) +``` + +You can then use this data to create your own plot: + +```{r data_intervals_custom, eval=params$EVAL} +ggplot(d, aes(x = x, y = m)) + + geom_linerange(aes(ymin = ll, ymax = hh), color = "skyblue", linewidth = 0.6) + + geom_linerange(aes(ymin = l, ymax = h), color = "steelblue", linewidth = 1.2) + + geom_point(aes(y = y_obs), shape = 21, fill = "red", size = 1.5) + + labs(title = "Custom interval plot from ppc_intervals_data()", + x = "Observation", y = "Value") + + theme_minimal() +``` + +Similarly, `ppc_stat_data()` returns the computed test statistics: + +```{r data_stat, eval=params$EVAL, message=FALSE} +stat_d <- ppc_stat_data(y, yrep_nb, stat = "median") +head(stat_d) +``` + +See `available_ppc(plots_only = FALSE)` and `available_mcmc(plots_only = FALSE)` +for a full list of data-preparation functions. + +
+ ## Providing an interface to bayesplot PPCs from another package The **bayesplot** package provides the S3 generic function `pp_check`. Authors of diff --git a/vignettes/plotting-mcmc-draws.Rmd b/vignettes/plotting-mcmc-draws.Rmd index 0ed21f62..4dbd8b38 100644 --- a/vignettes/plotting-mcmc-draws.Rmd +++ b/vignettes/plotting-mcmc-draws.Rmd @@ -367,6 +367,23 @@ mcmc_trace_highlight(posterior, pars = "sigma", highlight = 3) ``` +
+ +## Using `*_data()` functions for custom plots + +As with PPC functions, many MCMC plotting functions have `*_data()` companions +that return the underlying data instead of a plot. For example, +`mcmc_intervals_data()` returns the quantiles used by `mcmc_intervals()`: + +```{r data_intervals_mcmc} +d <- mcmc_intervals_data(posterior, pars = c("(Intercept)", "sigma")) +d +``` + +This can be used to build fully custom ggplot2 visualizations using the same +summary statistics that bayesplot computes internally. See +`available_mcmc(plots_only = FALSE)` for a full list of `*_data()` functions. +
## References