From 2dd1a7a8b0768483cc9ba35e0215fc6c773ebab2 Mon Sep 17 00:00:00 2001 From: Utkarsh Date: Thu, 26 Feb 2026 17:05:04 +0530 Subject: [PATCH 1/2] Add documentation for ppc_data and ppc_loo_pit_data Fixes #209 --- NEWS.md | 1 + R/ppc-distributions.R | 9 +++++++++ R/ppc-loo.R | 13 ++++++++++++- man/PPC-distributions.Rd | 9 +++++++++ man/PPC-loo.Rd | 16 +++++++++++++++- 5 files changed, 46 insertions(+), 2 deletions(-) diff --git a/NEWS.md b/NEWS.md index 25c323e3..5cc259c4 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) * New functions `mcmc_dots` and `mcmc_dots_by_chain` for dot plots of MCMC draws by @behramulukir (#402) * Default to `quantiles=100` for all dot plots by @behramulukir (#402) diff --git a/R/ppc-distributions.R b/R/ppc-distributions.R index d86a8b4c..fda798af 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 the +#' data-preparation back end for all the `ppc_*()` plotting functions, and +#' users can call it directly to create custom PPC plots using ggplot2. The +#' function returns a data frame (or list of data frames) 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 create entirely new types of PPC visualizations. +#' } #' \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 c31242e8..64bba2a3 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 the +data-preparation back end for all the \verb{ppc_*()} plotting functions, and +users can call it directly to create custom PPC plots using ggplot2. The +function returns a data frame (or list of data frames) 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 create entirely new types of PPC visualizations. +} \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 From a8260cf9e0f236bbaa76dd11194352f3e7b06c47 Mon Sep 17 00:00:00 2001 From: Utkarsh Date: Thu, 26 Feb 2026 17:20:42 +0530 Subject: [PATCH 2/2] Replaced all ppc_*() functions with many ppc_*() for accuracy, corrected the return type to data frame, and refined wording to avoid overclaiming functionality --- R/ppc-distributions.R | 14 +++++++------- man/PPC-distributions.Rd | 14 +++++++------- 2 files changed, 14 insertions(+), 14 deletions(-) diff --git a/R/ppc-distributions.R b/R/ppc-distributions.R index fda798af..217ad315 100644 --- a/R/ppc-distributions.R +++ b/R/ppc-distributions.R @@ -23,13 +23,13 @@ #' @section Plot Descriptions: #' \describe{ #' \item{`ppc_data()`}{ -#' This function prepares data for plotting with **ggplot2**. It is the -#' data-preparation back end for all the `ppc_*()` plotting functions, and -#' users can call it directly to create custom PPC plots using ggplot2. The -#' function returns a data frame (or list of data frames) 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 create entirely new types of PPC visualizations. +#' 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 diff --git a/man/PPC-distributions.Rd b/man/PPC-distributions.Rd index 64bba2a3..e1d6825d 100644 --- a/man/PPC-distributions.Rd +++ b/man/PPC-distributions.Rd @@ -265,13 +265,13 @@ the input contains the "success" \emph{proportions} (not discrete \describe{ \item{\code{ppc_data()}}{ -This function prepares data for plotting with \strong{ggplot2}. It is the -data-preparation back end for all the \verb{ppc_*()} plotting functions, and -users can call it directly to create custom PPC plots using ggplot2. The -function returns a data frame (or list of data frames) 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 create entirely new types of PPC visualizations. +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