diff --git a/NEWS.md b/NEWS.md index 50e0a0b8..be2a6061 100644 --- a/NEWS.md +++ b/NEWS.md @@ -1,5 +1,6 @@ # bayesplot (development version) +* Documentation added for `ppc_data()` and `ppc_loo_pit_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 diff --git a/R/ppc-distributions.R b/R/ppc-distributions.R index d86a8b4c..217ad315 100644 --- a/R/ppc-distributions.R +++ b/R/ppc-distributions.R @@ -22,6 +22,15 @@ #' #' @section Plot Descriptions: #' \describe{ +#' \item{`ppc_data()`}{ +#' This function prepares data for plotting with **ggplot2**. It is a +#' general-purpose data-preparation helper used by many `ppc_*()` plotting +#' functions, and users can call it directly to create custom PPC plots using +#' ggplot2. The function returns a data frame that can be used to build ggplot +#' objects. 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. +#' } #' \item{`ppc_hist(), ppc_freqpoly(), ppc_dens(), ppc_boxplot()`}{ #' A separate histogram, shaded frequency polygon, smoothed kernel density #' estimate, or box and whiskers plot is displayed for `y` and each diff --git a/R/ppc-loo.R b/R/ppc-loo.R index 88a6692c..e0f93039 100644 --- a/R/ppc-loo.R +++ b/R/ppc-loo.R @@ -23,10 +23,21 @@ #' `ppc_loo_ribbon()`, `alpha` and `size` are passed to #' [ggplot2::geom_ribbon()]. #' -#' @template return-ggplot +#' @template return-ggplot-or-data #' #' @section Plot Descriptions: #' \describe{ +#' \item{`ppc_loo_pit_data()`}{ +#' This function prepares LOO-PIT data for plotting with **ggplot2**. It is +#' the data-preparation back end for the LOO-PIT plotting functions +#' (`ppc_loo_pit_overlay()`, `ppc_loo_pit_qq()`, and `ppc_loo_pit_ecdf()`), +#' and users can call it directly to create custom LOO-PIT plots using +#' ggplot2. The function computes the leave-one-out probability integral +#' transform (LOO-PIT) values and returns a data frame that can be used to +#' build ggplot objects. This is useful when you want to create custom +#' visualizations of LOO-PIT values beyond what the built-in plotting +#' functions provide. +#' } #' \item{`ppc_loo_pit_overlay()`, `ppc_loo_pit_qq()`, `ppc_loo_pit_ecdf()`}{ #' The calibration of marginal predictions can be assessed using probability #' integral transformation (PIT) checks. LOO improves the check by avoiding the diff --git a/man/PPC-distributions.Rd b/man/PPC-distributions.Rd index ce0f264a..23841507 100644 --- a/man/PPC-distributions.Rd +++ b/man/PPC-distributions.Rd @@ -264,6 +264,15 @@ the input contains the "success" \emph{proportions} (not discrete \section{Plot Descriptions}{ \describe{ +\item{\code{ppc_data()}}{ +This function prepares data for plotting with \strong{ggplot2}. It is a +general-purpose data-preparation helper used by many \verb{ppc_*()} plotting +functions, and users can call it directly to create custom PPC plots using +ggplot2. The function returns a data frame that can be used to build ggplot +objects. 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. +} \item{\verb{ppc_hist(), ppc_freqpoly(), ppc_dens(), ppc_boxplot()}}{ A separate histogram, shaded frequency polygon, smoothed kernel density estimate, or box and whiskers plot is displayed for \code{y} and each diff --git a/man/PPC-loo.Rd b/man/PPC-loo.Rd index 555898d8..7e9ebe02 100644 --- a/man/PPC-loo.Rd +++ b/man/PPC-loo.Rd @@ -223,7 +223,10 @@ order of the observations. The alternative (\code{"median"}) arranges them by median value from smallest (left) to largest (right).} } \value{ -A ggplot object that can be further customized using the \strong{ggplot2} package. +The plotting functions return a ggplot object that can be further +customized using the \strong{ggplot2} package. The functions with suffix +\verb{_data()} return the data that would have been drawn by the plotting +function. } \description{ Leave-One-Out (LOO) predictive checks. See the \strong{Plot Descriptions} section, @@ -233,6 +236,17 @@ for details. \section{Plot Descriptions}{ \describe{ +\item{\code{ppc_loo_pit_data()}}{ +This function prepares LOO-PIT data for plotting with \strong{ggplot2}. It is +the data-preparation back end for the LOO-PIT plotting functions +(\code{ppc_loo_pit_overlay()}, \code{ppc_loo_pit_qq()}, and \code{ppc_loo_pit_ecdf()}), +and users can call it directly to create custom LOO-PIT plots using +ggplot2. The function computes the leave-one-out probability integral +transform (LOO-PIT) values and returns a data frame that can be used to +build ggplot objects. This is useful when you want to create custom +visualizations of LOO-PIT values beyond what the built-in plotting +functions provide. +} \item{\code{ppc_loo_pit_overlay()}, \code{ppc_loo_pit_qq()}, \code{ppc_loo_pit_ecdf()}}{ The calibration of marginal predictions can be assessed using probability integral transformation (PIT) checks. LOO improves the check by avoiding the