Document all *_data() functions (#209)

Author: utkarshpawade

NEWS.md

@@ -1,6 +1,6 @@
 # bayesplot (development version)
 
-* Documentation added for `ppc_data()` and `ppc_loo_pit_data()` functions (#209)
+* 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,20 @@
 #'
 #' @section Plot Descriptions:
 #' \describe{
+#' \item{`mcmc_rhat_data()`}{
+#'   Data-preparation back end for `mcmc_rhat()` and `mcmc_rhat_hist()`.
+#'   Users can call `mcmc_rhat_data()` directly to obtain the data frame of
+#'   Rhat values with rating labels and create custom Rhat diagnostic
+#'   visualizations with **ggplot2**.
+#' }
+#'
+#' \item{`mcmc_neff_data()`}{
+#'   Data-preparation back end for `mcmc_neff()` and `mcmc_neff_hist()`.
+#'   Users can call `mcmc_neff_data()` directly to obtain the data frame of
+#'   effective-sample-size ratios with rating labels and create custom Neff
+#'   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,10 +15,16 @@
 #' @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{
+#'   \item{`mcmc_dens_chains_data()`}{
+#'    Data-preparation back end for `mcmc_dens_chains()`. Users can call
+#'    `mcmc_dens_chains_data()` directly to obtain the prepared long-format
+#'    data frame of MCMC draws (with chain information retained) and create
+#'    custom ridgeline density visualizations with **ggplot2**.
+#'   }
 #'   \item{`mcmc_hist()`}{
 #'    Histograms of posterior draws with all chains merged.
 #'   }

R/mcmc-intervals.R

@@ -38,6 +38,13 @@
 #'
 #' @section Plot Descriptions:
 #' \describe{
+#'   \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**.
+#'   }
 #'   \item{`mcmc_intervals()`}{
 #'    Plots of uncertainty intervals computed from posterior draws with all
 #'    chains merged.

R/mcmc-parcoord.R

@@ -29,6 +29,12 @@
 #'
 #' @section Plot Descriptions:
 #' \describe{
+#'   \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 parallel coordinates visualizations with **ggplot2**.
+#'   }
 #'   \item{`mcmc_parcoord()`}{
 #'    [Parallel coordinates plot](https://en.wikipedia.org/wiki/Parallel_coordinates)
 #'    of MCMC draws. There is one dimension per parameter along the horizontal

R/mcmc-traces.R

@@ -45,6 +45,13 @@
 #'
 #' @section Plot Descriptions:
 #' \describe{
+#'   \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**.
+#'   }
 #'   \item{`mcmc_trace()`}{
 #'    Standard trace plots of MCMC draws. For models fit using [NUTS],
 #'    the `np` argument can be used to also show divergences on the trace plot.

R/ppc-discrete.R

@@ -37,6 +37,11 @@
 #'
 #' @section Plot Descriptions:
 #' \describe{
+#' \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 bar chart visualizations with **ggplot2**.
+#' }
 #' \item{`ppc_bars()`}{
 #'   Bar plot of `y` with `yrep` medians and uncertainty intervals
 #'   superimposed on the bars.

R/ppc-errors.R

@@ -33,6 +33,12 @@
 #'
 #' @section Plot descriptions:
 #' \describe{
+#'   \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**.
+#'   }
 #'   \item{`ppc_error_hist()`}{
 #'    A separate histogram is plotted for the predictive errors computed from
 #'    `y` and each dataset (row) in `yrep`. For this plot `yrep` should have
@@ -69,7 +75,7 @@
 #'   }
 #' }
 #'
-#' @template return-ggplot
+#' @template return-ggplot-or-data
 #'
 #' @templateVar bdaRef (Ch. 6)
 #' @template reference-bda

R/ppc-intervals.R

@@ -33,6 +33,13 @@
 #'
 #' @section Plot Descriptions:
 #' \describe{
+#'   \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**.
+#'   }
 #'   \item{`ppc_intervals(), ppc_ribbon()`}{
 #'    `100*prob`% central intervals for `yrep` at each `x`
 #'    value. `ppc_intervals()` plots intervals as vertical bars with points

R/ppc-scatterplots.R

@@ -29,6 +29,14 @@
 #'
 #' @section Plot Descriptions:
 #' \describe{
+#'   \item{`ppc_scatter_data()`, `ppc_scatter_avg_data()`}{
+#'    Data-preparation back ends for the `ppc_scatter*()` family of plotting
+#'    functions. `ppc_scatter_data()` returns a data frame with one row per
+#'    observation per `yrep` draw, while `ppc_scatter_avg_data()` returns a
+#'    data frame with one row per observation summarising `yrep` draws with
+#'    the chosen `stat`. Users can call these functions directly to create
+#'    custom scatterplot visualizations with **ggplot2**.
+#'   }
 #'   \item{`ppc_scatter()`}{
 #'    For each dataset (row) in `yrep` a scatterplot is generated showing `y`
 #'    against that row of `yrep`. For this plot `yrep` should only contain a