Minor edits

* move doc of _data() functions below doc of plotting functions

Author: jgabry

R/mcmc-diagnostics.R

@@ -18,20 +18,13 @@
 #'
 #' @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
+#' \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_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

@@ -19,12 +19,6 @@
 #'
 #' @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.
 #'   }
@@ -54,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

@@ -38,13 +38,6 @@
 #'
 #' @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.
@@ -58,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

@@ -29,12 +29,6 @@
 #'
 #' @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
@@ -54,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

@@ -45,13 +45,6 @@
 #'
 #' @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.
@@ -79,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

@@ -37,11 +37,6 @@
 #'
 #' @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.
@@ -50,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

@@ -22,15 +22,6 @@
 #'
 #' @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
@@ -40,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
@@ -68,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

@@ -33,12 +33,6 @@
 #'
 #' @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
@@ -73,6 +67,12 @@
 #'    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-or-data

R/ppc-intervals.R

@@ -33,13 +33,6 @@
 #'
 #' @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
@@ -57,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

R/ppc-scatterplots.R

@@ -29,14 +29,6 @@
 #'
 #' @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
@@ -53,6 +45,14 @@
 #'    The same as `ppc_scatter_avg()`, but a separate plot is generated for
 #'    each level of a grouping variable.
 #'   }
+#'   \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 visualizations with **ggplot2**.
+#'   }
 #' }
 #'
 #' @examples