mention prior predictive checking

advances #196

Author: jgabry

R/bayesplot-package.R

@@ -36,7 +36,8 @@
 #'   Monte Carlo (MCMC) simulations generated by *any* MCMC algorithm
 #'   as well as diagnostics. There are also additional functions specifically
 #'   for use with models fit using the [No-U-Turn Sampler (NUTS)][NUTS].
-#' * [__PPC__][PPC-overview]: Graphical posterior predictive checks (PPCs).
+#' * [__PPC__][PPC-overview]: Graphical prior and posterior predictive
+#'   checks (PPCs).
 #'
 #' In future releases modules will be added specifically for
 #' forecasting/out-of-sample prediction and other inference-related tasks.

R/pp_check.R

@@ -1,13 +1,13 @@
-#' Posterior predictive checks (S3 generic and default method)
+#' Posterior (or prior) predictive checks (S3 generic and default method)
 #'
 #' S3 generic with simple default method. The intent is to provide a generic so
 #' authors of other \R packages who wish to provide interfaces to the functions
-#' in **bayesplot** will be encouraged to include `pp_check()` methods in
-#' their package, preserving the same naming conventions for posterior
+#' in **bayesplot** will be encouraged to include `pp_check()` methods in their
+#' package, preserving the same naming conventions for posterior (and prior)
 #' predictive checking across many \R packages for Bayesian inference. This is
-#' for the convenience of both users and developers. See the **Details**
-#' and **Examples** sections, below, and the package vignettes for examples
-#' of defining `pp_check()` methods.
+#' for the convenience of both users and developers. See the **Details** and
+#' **Examples** sections, below, and the package vignettes for examples of
+#' defining `pp_check()` methods.
 #'
 #' @export
 #' @param object Typically a fitted model object. The default method, however,
@@ -56,8 +56,8 @@ pp_check <- function(object, ...) {
 #' @export
 #' @param yrep For the default method, a `yrep` matrix passed to `fun`.
 #' @param fun For the default method, the plotting function to call. Can be any
-#'   of the \link[=PPC]{PPC functions}. The `"ppc_"` prefix can optionally
-#'   be dropped if `fun` is specified as a string.
+#'   of the [PPC] functions. The `"ppc_"` prefix can optionally be dropped if
+#'   `fun` is specified as a string.
 #'
 pp_check.default <- function(object, yrep, fun, ...) {
   if (is.character(fun) && substr(fun, 1, 4) != "ppc_") {

R/ppc-overview.R

@@ -5,11 +5,11 @@
 #' @family PPCs
 #'
 #' @description
-#' The **bayesplot** PPC module provides various plotting functions for
-#' creating graphical displays comparing observed data to simulated data from
-#' the posterior predictive distribution. See below for a brief discussion of
-#' the ideas behind posterior predictive checking, a description of the
-#' structure of this package, and tips on providing an interface to
+#' The **bayesplot** PPC module provides various plotting functions for creating
+#' graphical displays comparing observed data to simulated data from the
+#' posterior (or prior) predictive distribution. See below for a brief
+#' discussion of the ideas behind posterior predictive checking, a description
+#' of the structure of this package, and tips on providing an interface to
 #' **bayesplot** from another package.
 #'
 #' @details
@@ -50,35 +50,45 @@
 #' For a more thorough discussion of posterior predictive checking see
 #' Chapter 6 of Gelman et. al. (2013).
 #' }
+#' \subsection{Prior predictive checking}{
+#' To use **bayesplot** for *prior* predictive checks you can simply use draws
+#' from the prior predictive distribution instead of the posterior predictive
+#' distribution. See Gabry et al. (2019) for more on prior predictive checking
+#' and when it is reasonable to compare the prior predictive distribution to the
+#' observed data. If you want to avoid using the observed data for prior
+#' predictive checks, then the `y` argument to the PPC plotting functions can be
+#' used to provide plausible or implausible `y` values that you want to compare
+#' to the prior predictive realizations.
+#' }
 #'
-#' @section PPC plotting functions: The plotting functions for posterior
-#'   predictive checking in this package are organized into several categories,
-#'   each with its own documentation:
+#' @section PPC plotting functions: The plotting functions for prior and
+#'   posterior predictive checking are organized into several categories, each
+#'   with its own documentation:
 #' * [__Distributions__][PPC-distributions]: Histograms, kernel density
 #'   estimates, boxplots, and other plots comparing the empirical distribution
-#'   of the observed data `y` to the distributions of individual replicated
-#'   datasets (rows) in `yrep`.
-#' * [__Statistics__][PPC-test-statistics]: The distribution of a statistic, or a
-#'   pair of statistics, over the replicated datasets (rows) in `yrep` compared
-#'   to value of the statistic(s) computed from `y`.
+#'   of data `y` to the distributions of individual simulated datasets (rows)
+#'   in `yrep`.
+#' * [__Statistics__][PPC-test-statistics]: The distribution of a statistic,
+#'   or a pair of statistics, over the simulated datasets (rows) in `yrep`
+#'   compared to value of the statistic(s) computed from `y`.
 #' * [__Intervals__][PPC-intervals]: Interval estimates of `yrep` with `y`
 #'   overlaid. The x-axis variable can be optionally specified by the user
 #'   (e.g. to plot against against a predictor variable or over time).
 #' * [__Predictive errors__][PPC-errors]: Plots of predictive errors
-#'   (`y - yrep`) computed from `y` and replicated datasets (rows) in `yrep`.
-#'   For binomial models binned error plots are also available.
+#'   (`y - yrep`) computed from `y` and eachc of the simulated datasets (rows)
+#'   in `yrep`. For binomial models binned error plots are also available.
 #' * [__Scatterplots__][PPC-scatterplots]: Scatterplots (and similar
-#'   visualizations) of the observed data `y` vs. individual replicated datasets
-#'   (rows) in `yrep`, or vs. the average value of the distributions of each data
-#'   point (columns) in `yrep`.
+#'   visualizations) of the data `y` vs. individual simuluted datasets
+#'   (rows) in `yrep`, or vs. the average value of the distributions of each
+#'   data point (columns) in `yrep`.
 #' * [__Plots for discrete outcomes__][PPC-discrete]: PPC functions that can
 #'   only be used if `y` and `yrep` are discrete. For example, rootograms for
 #'   count outcomes and bar plots for ordinal, categorical, and
 #'   multinomial outcomes.
 #' * [__LOO predictive checks__][PPC-loo]: PPC functions for predictive checks
 #'   based on (approximate) leave-one-out (LOO) cross-validation.
 #'
-#' @section Providing an interface for posterior predictive checking from another package:
+#' @section Providing an interface for predictive checking from another package:
 #'
 #' In addition to the various plotting functions, the **bayesplot** package
 #' provides the S3 generic [pp_check()]. Authors of \R packages for