Merge pull request #222 from stan-dev/ppd-functions

Add new PPD module for plots without `y` variable

.Rbuildignore

@@ -13,5 +13,5 @@ images/*
 book/*
 docs/*
 Rplots.pdf
-tests/figs/*
 ^\.github$
+^tests/testthat/_snaps$

DESCRIPTION

@@ -7,18 +7,18 @@ Authors@R: c(person("Jonah", "Gabry", role = c("aut", "cre"), email = "jsg2201@c
              person("Tristan", "Mahr", role = "aut"),
              person("Paul-Christian", "Bürkner", role = "ctb"),
              person("Martin", "Modrák", role = "ctb"),
-             person("Malcolm", "Barrett", role = "ctb"), 
+             person("Malcolm", "Barrett", role = "ctb"),
              person("Frank", "Weber", role = "ctb"),
              person("Eduardo", "Coronado Sroka", role = "ctb"),
              person("Aki", "Vehtari", role = "ctb"))
 Maintainer: Jonah Gabry <[email protected]>
 Description: Plotting functions for posterior analysis, MCMC diagnostics,
-    prior and posterior predictive checks, and other visualizations 
+    prior and posterior predictive checks, and other visualizations
     to support the applied Bayesian workflow advocated in
     Gabry, Simpson, Vehtari, Betancourt, and Gelman (2019) <doi:10.1111/rssa.12378>.
-    The package is designed not only to provide convenient functionality 
-    for users, but also a common set of functions that can be easily used by 
-    developers working on a variety of R packages for Bayesian modeling, 
+    The package is designed not only to provide convenient functionality
+    for users, but also a common set of functions that can be easily used by
+    developers working on a variety of R packages for Bayesian modeling,
     particularly (but not exclusively) packages interfacing with 'Stan'.
 License: GPL (>= 3)
 URL: https://mc-stan.org/bayesplot/
@@ -35,10 +35,10 @@ Imports:
     reshape2,
     rlang (>= 0.3.0),
     stats,
-    tibble,
+    tibble (>= 2.0.0),
     tidyselect,
     utils
-Suggests: 
+Suggests:
     ggfortify,
     gridExtra (>= 2.2.1),
     hexbin,
@@ -53,7 +53,7 @@ Suggests:
     shinystan (>= 2.3.0),
     survival,
     testthat (>= 2.0.0),
-    vdiffr
+    vdiffr (>= 1.0.2)
 RoxygenNote: 7.1.2
 VignetteBuilder: knitr
 Encoding: UTF-8

NAMESPACE

@@ -24,6 +24,7 @@ S3method(rhat,stanreg)
 export(abline_01)
 export(available_mcmc)
 export(available_ppc)
+export(available_ppd)
 export(bayesplot_grid)
 export(bayesplot_theme_get)
 export(bayesplot_theme_replace)
@@ -99,6 +100,7 @@ export(parcoord_style_np)
 export(plot_bg)
 export(pp_check)
 export(ppc_bars)
+export(ppc_bars_data)
 export(ppc_bars_grouped)
 export(ppc_boxplot)
 export(ppc_data)
@@ -108,10 +110,12 @@ export(ppc_dens_overlay_grouped)
 export(ppc_ecdf_overlay)
 export(ppc_ecdf_overlay_grouped)
 export(ppc_error_binned)
+export(ppc_error_data)
 export(ppc_error_hist)
 export(ppc_error_hist_grouped)
 export(ppc_error_scatter)
 export(ppc_error_scatter_avg)
+export(ppc_error_scatter_avg_grouped)
 export(ppc_error_scatter_avg_vs_x)
 export(ppc_freqpoly)
 export(ppc_freqpoly_grouped)
@@ -133,12 +137,36 @@ export(ppc_ribbon_grouped)
 export(ppc_rootogram)
 export(ppc_scatter)
 export(ppc_scatter_avg)
+export(ppc_scatter_avg_data)
 export(ppc_scatter_avg_grouped)
+export(ppc_scatter_data)
 export(ppc_stat)
 export(ppc_stat_2d)
+export(ppc_stat_data)
+export(ppc_stat_freqpoly)
 export(ppc_stat_freqpoly_grouped)
 export(ppc_stat_grouped)
 export(ppc_violin_grouped)
+export(ppd_boxplot)
+export(ppd_data)
+export(ppd_dens)
+export(ppd_dens_overlay)
+export(ppd_ecdf_overlay)
+export(ppd_freqpoly)
+export(ppd_freqpoly_grouped)
+export(ppd_hist)
+export(ppd_intervals)
+export(ppd_intervals_data)
+export(ppd_intervals_grouped)
+export(ppd_ribbon)
+export(ppd_ribbon_data)
+export(ppd_ribbon_grouped)
+export(ppd_stat)
+export(ppd_stat_2d)
+export(ppd_stat_data)
+export(ppd_stat_freqpoly)
+export(ppd_stat_freqpoly_grouped)
+export(ppd_stat_grouped)
 export(rhat)
 export(scatter_style_np)
 export(theme_default)
@@ -156,8 +184,10 @@ import(ggplot2)
 import(rlang)
 import(stats)
 importFrom(dplyr,"%>%")
+importFrom(dplyr,across)
 importFrom(dplyr,arrange)
 importFrom(dplyr,count)
+importFrom(dplyr,full_join)
 importFrom(dplyr,group_by)
 importFrom(dplyr,inner_join)
 importFrom(dplyr,left_join)

NEWS.md

@@ -2,6 +2,42 @@
 
 # bayesplot 1.8.1.9000
 
+* New module PPD (posterior/prior predictive distribution) with a lot of new
+plotting functions with `ppd_` prefix. These functions plot draws from the prior
+or posterior predictive distributions (PPD) without comparing to observed data
+(i.e., no `y` argument). Because these are not "checks" against the observed
+data we use PPD instead of PPC. These plots are essentially the same as the
+corresponding PPC plots but without showing any observed data (e.g.,
+`ppd_intervals()` is like `ppc_intervals()` but without plotting `y`). See
+`help("PPD-overview")` for details. (#151, #222)
+
+* All PPC categories now have one or more `_data()` functions that return the
+data frame used for plotting (#97, #222). Many of these have already been in
+previous releases, but the new ones in this release are:
+   - `ppc_bars_data()`
+   - `ppc_error_data()`
+   - `ppc_error_binnned_data()`
+   - `ppc_scatter_data()`
+   - `ppc_scatter_avg_data()`
+   - `ppc_stat_data()`
+
+* Many functions gain an argument `facet_args` for controlling ggplot2 faceting
+  (many other functions have had this argument for a long time).
+  The ones that just now got the argument are:
+   - `ppc_scatter()`
+   - `ppc_scatter_avg_grouped()`
+   - `ppc_error_hist()`
+   - `ppc_error_hist_grouped()`
+   - `ppc_error_scatter()`
+   - `ppc_error_binned()`
+
+* New plotting function `ppc_km_overlay_grouped()`, the grouped variant of
+  `ppc_km_overlay()`. (#260, @fweber144)
+
+* `ppc_scatter()`, `ppc_scatter_avg()`, and `ppc_scatter_avg_grouped()` gain an
+  argument `ref_line`, which can be set to `FALSE` to turn off the `x=y` line
+  drawn behind the scatterplot.
+
 * `mcmc_*()` functions now support all draws formats from the **posterior** package. (#277, @Ozan147)
 
 * `mcmc_dens()` and `mcmc_dens_overlay()` gain arguments for controlling the
@@ -12,9 +48,6 @@
 * `mcmc_areas()` and `mcmc_areas_ridges()` gain an argument `border_size` for
 controlling the thickness of the ridgelines. (#224)
 
-* New plotting function `ppc_km_overlay_grouped()`, the grouped variant of
-  `ppc_km_overlay()`. (#260, @fweber144)
-
 # bayesplot 1.8.1
 
 * Fix R cmd check error on linux for CRAN

R/available-module-functions.R

@@ -1,36 +1,82 @@
-#' Get or view the names of available plotting functions
+#' Get or view the names of available plotting or data functions
 #'
 #' @export
 #' @param pattern,fixed,invert Passed to [base::grep()].
+#' @param plots_only If `TRUE` (the default) only plotting functions are
+#'   searched for. If `FALSE` then functions that return data for plotting
+#'   (functions ending in `_data()`) are also included.
 #' @return A possibly empty character vector of function names with several
 #'   additional attributes (for use by a custom print method). If `pattern`
 #'   is missing then the returned object contains the names of all available
-#'   plotting functions in the [MCMC] or [PPC] module, depending on
+#'   plotting functions in the [MCMC], [PPC], or [PPD] module, depending on
 #'   which function is called. If `pattern` is specified then a subset of
 #'   function names is returned.
 #'
 #' @examples
 #' available_mcmc()
 #' available_mcmc("nuts")
 #' available_mcmc("rhat|neff")
+#'
+#' available_ppc()
 #' available_ppc("grouped")
 #' available_ppc("grouped", invert = TRUE)
 #'
-available_ppc <- function(pattern = NULL, fixed = FALSE, invert = FALSE) {
-  .list_module_functions("ppc",
-                         .pattern = pattern,
-                         fixed = fixed,
-                         invert = invert)
-}
+#' available_ppd()
+#' available_ppd("grouped")
+#'
+#' # can also see which functions that return data are available
+#' available_ppc(plots_only = FALSE)
+#'
+#' # only show the _data functions
+#' available_ppc("_data", plots_only = FALSE)
+#' available_ppd("_data", plots_only = FALSE)
+#' available_mcmc("_data", plots_only = FALSE)
+#'
+available_ppc <-
+  function(pattern = NULL,
+           fixed = FALSE,
+           invert = FALSE,
+           plots_only = TRUE) {
+    .list_module_functions(
+      .module = "ppc",
+      .pattern = pattern,
+      fixed = fixed,
+      invert = invert,
+      plots_only = plots_only
+    )
+  }
 
 #' @rdname available_ppc
 #' @export
-available_mcmc <- function(pattern = NULL, fixed = FALSE, invert = FALSE) {
-  .list_module_functions("mcmc",
-                         .pattern = pattern,
-                         fixed = fixed,
-                         invert = invert)
-}
+available_ppd <-
+  function(pattern = NULL,
+           fixed = FALSE,
+           invert = FALSE,
+           plots_only = TRUE) {
+    .list_module_functions(
+      .module = "ppd",
+      .pattern = pattern,
+      fixed = fixed,
+      invert = invert,
+      plots_only = plots_only
+    )
+  }
+
+#' @rdname available_ppc
+#' @export
+available_mcmc <-
+  function(pattern = NULL,
+           fixed = FALSE,
+           invert = FALSE,
+           plots_only = TRUE) {
+    .list_module_functions(
+      .module = "mcmc",
+      .pattern = pattern,
+      fixed = fixed,
+      invert = invert,
+      plots_only = plots_only
+    )
+  }
 
 #' @export
 print.bayesplot_function_list <- function(x, ...) {
@@ -48,10 +94,11 @@ print.bayesplot_function_list <- function(x, ...) {
 
 # internal ----------------------------------------------------------------
 .list_module_functions <-
-  function(.module = c("ppc", "mcmc"),
+  function(.module = c("ppc", "ppd", "mcmc"),
            .pattern,
            fixed = FALSE,
-           invert = FALSE) {
+           invert = FALSE,
+           plots_only = TRUE) {
 
     .module <- match.arg(.module)
 
@@ -62,6 +109,17 @@ print.bayesplot_function_list <- function(x, ...) {
     )
     return_funs <- sort(all_funs)
 
+    if (plots_only) {
+      # drop _data() functions
+      return_funs <-
+        grep(
+          pattern = "_data()",
+          x = return_funs,
+          invert = TRUE,
+          value = TRUE
+        )
+    }
+
     if (!is.null(.pattern)) {
       return_funs <- grep(
         pattern = .pattern,
@@ -71,6 +129,7 @@ print.bayesplot_function_list <- function(x, ...) {
         invert = invert
       )
     }
+
     structure(
       return_funs,
       class = c("bayesplot_function_list", "character"),

R/bayesplot-colors.R

@@ -203,8 +203,11 @@ plot.bayesplot_scheme <- function(x, ...) {
 
 # internal -----------------------------------------------------------------
 
-# plot color scheme
-# @param scheme A string (length 1) naming a scheme
+#' Plot color scheme
+#' @noRd
+#' @param scheme A string (length 1) naming a scheme. If `NULL` the current
+#'   scheme is used.
+#' @return A ggplot object.
 plot_scheme <- function(scheme = NULL) {
   if (is.null(scheme)) {
     x <- color_scheme_get()
@@ -248,9 +251,8 @@ scheme_level_names <- function() {
 }
 
 #' Return a color scheme based on `scheme` argument specified as a string
-#'
 #' @noRd
-#' @param scheme A string (length 1) naming a scheme
+#' @param scheme A string (length 1) naming a scheme.
 scheme_from_string <- function(scheme) {
   if (identical(substr(scheme, 1, 4), "mix-")) {
     # user specified a mixed scheme (e.g., "mix-blue-red")
@@ -300,8 +302,8 @@ is_mixed_scheme <- function(x) {
 
 #' Access a subset of the current scheme colors
 #' @noRd
-#' @param level A character vector of level names in `scheme_level_names()`.
-#'   The abbreviations "l", "lh", "m", "mh", "d", and "dh" can also be used
+#' @param levels A character vector of level names in `scheme_level_names()`.
+#'   The abbreviations `"l", "lh", "m", "mh", "d", "dh"` can also be used
 #'   instead of the full names.
 #' @return A character vector of color values.
 #'

R/bayesplot-ggplot-themes.R

@@ -129,6 +129,9 @@ theme_default <-
 #' bayesplot_theme_set(theme_dark())
 #' mcmc_hist(x) + panel_bg(fill = "black")
 #'
+#' # reset
+#' bayesplot_theme_set()
+#'
 bayesplot_theme_get <- function() {
   if (!identical(.bayesplot_theme_env$gg_current, ggplot2::theme_get())) {
     .bayesplot_theme_env$current <- ggplot2::theme_get()