Merge pull request #357 from stan-dev/qdotplot

add quantile dot plot functions

Author: jgabry

DESCRIPTION

@@ -41,6 +41,7 @@ Imports:
     tidyselect,
     utils
 Suggests:
+    ggdist,
     ggfortify,
     gridExtra (>= 2.2.1),
     hexbin,

NAMESPACE

@@ -123,6 +123,7 @@ export(ppc_data)
 export(ppc_dens)
 export(ppc_dens_overlay)
 export(ppc_dens_overlay_grouped)
+export(ppc_dots)
 export(ppc_ecdf_overlay)
 export(ppc_ecdf_overlay_grouped)
 export(ppc_error_binned)
@@ -170,6 +171,7 @@ export(ppd_boxplot)
 export(ppd_data)
 export(ppd_dens)
 export(ppd_dens_overlay)
+export(ppd_dots)
 export(ppd_ecdf_overlay)
 export(ppd_freqpoly)
 export(ppd_freqpoly_grouped)

R/ppc-distributions.R

@@ -15,7 +15,7 @@
 #' @template args-pit-ecdf
 #' @param size,alpha Passed to the appropriate geom to control the appearance of
 #'   the predictive distributions.
-#' @param ... Currently unused.
+#' @param ... For dot plots, optional additional arguments to pass to [ggdist::stat_dots()].
 #'
 #' @template details-binomial
 #' @template return-ggplot-or-data
@@ -28,14 +28,19 @@
 #'    dataset (row) in `yrep`. For these plots `yrep` should therefore
 #'    contain only a small number of rows. See the **Examples** section.
 #'   }
+#'   \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.
+#'    }
 #'   \item{`ppc_freqpoly_grouped()`}{
 #'    A separate frequency polygon is plotted for each level of a grouping
 #'    variable for `y` and each dataset (row) in `yrep`. For this plot
 #'    `yrep` should therefore contain only a small number of rows. See the
 #'    **Examples** section.
 #'   }
-#'   \item{`ppc_ecdf_overlay(), ppc_dens_overlay(),
-#'          ppc_ecdf_overlay_grouped(), ppc_dens_overlay_grouped()`}{
+#'   \item{`ppc_ecdf_overlay()`, `ppc_dens_overlay()`,
+#'          `ppc_ecdf_overlay_grouped()`, `ppc_dens_overlay_grouped()`}{
 #'    Kernel density or empirical CDF estimates of each dataset (row) in
 #'    `yrep` are overlaid, with the distribution of `y` itself on top
 #'    (and in a darker shade). When using `ppc_ecdf_overlay()` with discrete
@@ -80,7 +85,7 @@
 #' ppc_pit_ecdf(y, yrep, prob = 0.99, plot_diff = TRUE)
 #' }
 #'
-#' # for ppc_hist,dens,freqpoly,boxplot definitely use a subset yrep rows so
+#' # for ppc_hist,dens,freqpoly,boxplot,dots definitely use a subset yrep rows so
 #' # only a few (instead of nrow(yrep)) histograms are plotted
 #' ppc_hist(y, yrep[1:8, ])
 #' \donttest{
@@ -90,6 +95,9 @@
 #' # wizard hat plot
 #' color_scheme_set("blue")
 #' ppc_dens(y, yrep[200:202, ])
+#'
+#' # dot plot
+#' ppc_dots(y, yrep[1:8, ])
 #' }
 #'
 #' \donttest{
@@ -507,6 +515,45 @@ ppc_boxplot <-
       xaxis_title(FALSE)
   }
 
+#' @rdname PPC-distributions
+#' @export
+#' @template args-dots
+ppc_dots <-
+  function(y,
+           yrep,
+           ...,
+           binwidth = NA,
+           quantiles = NA,
+           freq = TRUE) {
+    check_ignored_arguments(..., ok_args = c("dotsize", "layout", "stackratio", "overflow"))
+
+    suggested_package("ggdist")
+
+    data <- ppc_data(y, yrep)
+
+    ggplot(data, mapping = set_hist_aes(
+      freq = freq,
+      fill = .data$is_y_label,
+      color = .data$is_y_label
+    )) +
+      ggdist::stat_dots(
+        binwidth = binwidth,
+        quantiles = quantiles,
+        ...
+      ) +
+      scale_fill_ppc() +
+      scale_color_ppc() +
+      facet_wrap_parsed("rep_label") +
+      force_axes_in_facets() +
+      bayesplot_theme_get() +
+      space_legend_keys() +
+      yaxis_text(FALSE) +
+      yaxis_title(FALSE) +
+      yaxis_ticks(FALSE) +
+      xaxis_title(FALSE) +
+      facet_text(FALSE) +
+      facet_bg(FALSE)
+  }
 
 #' @rdname PPC-distributions
 #' @export

R/ppd-distributions.R

@@ -187,6 +187,43 @@ ppd_hist <-
       facet_text(FALSE)
   }
 
+#' @rdname PPD-distributions
+#' @export
+ppd_dots <-
+  function(ypred,
+           ...,
+           binwidth = NA,
+           quantiles = NA,
+           freq = TRUE) {
+    check_ignored_arguments(..., ok_args = c("dotsize", "layout", "stackratio", "overflow"))
+
+    suggested_package("ggdist")
+
+    data <- ppd_data(ypred)
+    ggplot(data, mapping = set_hist_aes(
+      freq,
+      color = "ypred",
+      fill = "ypred"
+    )) +
+      ggdist::stat_dots(
+        binwidth = binwidth,
+        quantiles = quantiles,
+        ...
+      ) +
+      scale_color_ppd() +
+      scale_fill_ppd() +
+      bayesplot_theme_get() +
+      facet_wrap_parsed("rep_label") +
+      force_axes_in_facets() +
+      dont_expand_y_axis() +
+      legend_none() +
+      yaxis_text(FALSE) +
+      yaxis_title(FALSE) +
+      yaxis_ticks(FALSE) +
+      xaxis_title(FALSE) +
+      facet_text(FALSE)
+  }
+
 
 #' @rdname PPD-distributions
 #' @export

man-roxygen/args-dots.R

@@ -0,0 +1,4 @@
+#' @param quantiles For dot plots, an optional integer passed to
+#'   [ggdist::stat_dots()] specifying the number of quantiles to use for a
+#'   quantile dot plot. If `quantiles` is `NA` (the default) then all data
+#'   points are plotted.