Add vignette sections for *_data() companion functions

NEWS.md

@@ -1,5 +1,7 @@
 # bayesplot (development version)
 
+* Added vignette sections demonstrating `*_data()` companion functions for
+  building custom ggplot2 visualizations (#435)
 * 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

vignettes/graphical-ppcs.Rmd

@@ -314,6 +314,45 @@ See Figure 8 in [Gabry et al. (2019)](#gabry2019) for another example of using
 
 <br>
 
+## 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, 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, 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.
+
+<br>
+
 ## Providing an interface to bayesplot PPCs from another package
 
 The **bayesplot** package provides the S3 generic function `pp_check`. Authors of

vignettes/plotting-mcmc-draws.Rmd

@@ -367,6 +367,23 @@ mcmc_trace_highlight(posterior, pars = "sigma", highlight = 3)
 ```
 
 
+<br>
+
+## 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.
+
 <br>
 
 ## References