Merge pull request #426 from utkarshpawade/fix-209-ppc-data-docs

Add documentation for ppc_data and ppc_loo_pit_data

Author: jgabry

NEWS.md

@@ -1,5 +1,6 @@
 # bayesplot (development version)
 
+* 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

R/mcmc-diagnostics.R

@@ -18,6 +18,13 @@
 #'
 #' @section Plot Descriptions:
 #' \describe{
+#' \item{`mcmc_rhat_data()`, `mcmc_neff_data()`}{
+#'   Data-preparation back ends for the R-hat and effective sample size plots.
+#'   Users can call these functions directly to obtain the data frame of
+#'   diagnostic values with rating labels and create custom diagnostic
+#'   visualizations with **ggplot2**.
+#' }
+#'
 #' \item{`mcmc_rhat()`, `mcmc_rhat_hist()`}{
 #'   Rhat values as either points or a histogram. Values are colored using
 #'   different shades (lighter is better). The chosen thresholds are somewhat

R/mcmc-distributions.R

@@ -15,7 +15,7 @@
 #' @param ... For dot plots, optional additional arguments to pass to [ggdist::stat_dots()].
 #' @param alpha Passed to the geom to control the transparency.
 #'
-#' @template return-ggplot
+#' @template return-ggplot-or-data
 #'
 #' @section Plot Descriptions:
 #' \describe{
@@ -48,6 +48,12 @@
 #'    appear in separate facets; in `mcmc_dens_chains()` they appear in the
 #'    same panel and can overlap vertically.
 #'   }
+#'   \item{`mcmc_dens_chains_data()`}{
+#'    Data-preparation back end for `mcmc_dens_chains()`. Users can call this
+#'    function directly to obtain the prepared long-format data frame of MCMC
+#'    draws (with chain information retained) and create custom visualizations
+#'    with **ggplot2**.
+#'   }
 #' }
 #'
 #' @examples

R/mcmc-intervals.R

@@ -51,6 +51,13 @@
 #'    ridgelines. This plot provides a compact display of (hierarchically)
 #'    related distributions.
 #'   }
+#'   \item{`mcmc_intervals_data()`, `mcmc_areas_data()`, `mcmc_areas_ridges_data()`}{
+#'    Data-preparation back ends for `mcmc_intervals()`, `mcmc_areas()`, and
+#'    `mcmc_areas_ridges()`, respectively. Users can call these functions
+#'    directly to obtain the prepared data frames of posterior interval
+#'    summaries and create custom interval or density-area visualizations
+#'    with **ggplot2**.
+#'   }
 #' }
 #'
 #' @examples

R/mcmc-parcoord.R

@@ -48,6 +48,12 @@
 #'    when specifying the `transformations` argument to
 #'    `mcmc_parcoord`. See the **Examples** section for how to do this.
 #'   }
+#'   \item{`mcmc_parcoord_data()`}{
+#'    Data-preparation back end for `mcmc_parcoord()`. Users can call
+#'    `mcmc_parcoord_data()` directly to obtain the prepared long-format data
+#'    frame of MCMC draws (with optional NUTS diagnostic information) and
+#'    create custom visualizations with **ggplot2**.
+#'   }
 #' }
 #'
 #' @template reference-vis-paper

R/mcmc-traces.R

@@ -72,6 +72,13 @@
 #'    ECDFs and the theoretical expectation for samples originating from the
 #'    same distribution is drawn. See Säilynoja et al. (2021) for details.
 #'   }
+#'   \item{`mcmc_trace_data()`}{
+#'    Data-preparation back end for `mcmc_trace()`, `mcmc_trace_highlight()`,
+#'    `mcmc_rank_hist()`, `mcmc_rank_overlay()`, and `mcmc_rank_ecdf()`. The
+#'    returned data frame contains columns for both the original draw values
+#'    and their within-parameter ranks, so it can be used to build both trace
+#'    and rank-based visualizations with **ggplot2**.
+#'   }
 #' }
 #'
 #' @template reference-improved-rhat

R/ppc-discrete.R

@@ -45,6 +45,11 @@
 #'   Same as `ppc_bars()` but a separate plot (facet) is generated for each
 #'   level of a grouping variable.
 #' }
+#' \item{`ppc_bars_data()`}{
+#'   Data-preparation back end for `ppc_bars()` and `ppc_bars_grouped()`.
+#'   Users can call `ppc_bars_data()` directly to obtain the prepared data
+#'   frame and create custom visualizations with **ggplot2**.
+#' }
 #' \item{`ppc_rootogram()`}{
 #'   Rootograms allow for diagnosing problems in count data models such as
 #'   overdispersion or excess zeros. In `standing`, `hanging`, and `suspended`

R/ppc-distributions.R

@@ -31,7 +31,7 @@
 #'   \item{`ppc_dots()`}{
 #'    A dot plot plot is displayed for `y` and each dataset (row) in `yrep`.
 #'    For these plots `yrep` should therefore contain only a small number of rows.
-#'    See the **Examples** section. This function requires [ggdist::stat_dots] to be installed.
+#'    See the **Examples** section.
 #'    }
 #'   \item{`ppc_freqpoly_grouped()`}{
 #'    A separate frequency polygon is plotted for each level of a grouping
@@ -59,7 +59,16 @@
 #'    confidence intervals are provided to asses if `y` and `yrep` originate
 #'    from the same distribution. The PIT values can also be provided directly
 #'    as `pit`.
-#'    See Säilynoja et al. (2021) for more details.}
+#'    See Säilynoja et al. (2021) for more details.
+#'   }
+#'   \item{`ppc_data()`}{
+#'    This function prepares data for plotting with **ggplot2** and doesn't
+#'    itself make any plots. Users can call it directly to obtain the underlying
+#'    data frame that (in most cases) is passed to **ggplot2**. This is useful
+#'    when you want to customize the appearance of PPC plots beyond what the
+#'    built-in plotting functions allow, or when you want to construct new types
+#'    of PPC visualizations based on the same underlying data.
+#'   }
 #' }
 #'
 #' @template reference-vis-paper

R/ppc-errors.R

@@ -67,9 +67,15 @@
 #'    this plot `y` and `yrep` should contain proportions rather than counts,
 #'    and `yrep` should have only a small number of rows.
 #'   }
+#'   \item{`ppc_error_data()`}{
+#'    Data-preparation back end for the `ppc_error_*()` family of plotting
+#'    functions. Users can call `ppc_error_data()` directly to obtain the
+#'    data frame of predictive errors (`y - yrep`) and create custom error
+#'    visualizations with **ggplot2**.
+#'   }
 #' }
 #'
-#' @template return-ggplot
+#' @template return-ggplot-or-data
 #'
 #' @templateVar bdaRef (Ch. 6)
 #' @template reference-bda

R/ppc-intervals.R

@@ -50,6 +50,13 @@
 #'    Same as `ppc_intervals()` and `ppc_ribbon()`, respectively, but a
 #'    separate plot (facet) is generated for each level of a grouping variable.
 #'   }
+#'   \item{`ppc_intervals_data()`, `ppc_ribbon_data()`}{
+#'    Data-preparation back end for `ppc_intervals()`, `ppc_ribbon()`, and
+#'    their grouped variants. `ppc_ribbon_data()` is an alias for
+#'    `ppc_intervals_data()`. Users can call either function directly to
+#'    obtain the prepared data frame and create custom interval or ribbon
+#'    visualizations with **ggplot2**.
+#'   }
 #' }
 #'
 #' @examples