Discarding boxplot outliers (#5379)

* Add `outliers` param to boxplot

* Add test

* Redocument

* Add news bullet

Author: teunbrand

NEWS.md

@@ -1,5 +1,10 @@
 # ggplot2 (development version)
 
+* `geom_boxplot()` gains an `outliers` argument to switch outliers on or off,
+  in a manner that does affects the scale range. For hiding outliers that does
+  not affect the scale range, you can continue to use `outlier.shape = NA` 
+  (@teunbrand, #4892).
+
 * Binned scales now treat `NA`s in limits the same way continuous scales do 
   (#5355).
 
@@ -9,6 +14,7 @@
   deprecated. The `hjust` setting of the `legend.text` and `legend.title` 
   elements continues to fulfil the role of text alignment (@teunbrand, #5347).
 
+
 * Integers are once again valid input to theme arguments that expect numeric
   input (@teunbrand, #5369)
 

R/geom-boxplot.R

@@ -33,19 +33,19 @@
 #' @inheritParams geom_bar
 #' @param geom,stat Use to override the default connection between
 #'   `geom_boxplot()` and `stat_boxplot()`.
+#' @param outliers Whether to display (`TRUE`) or discard (`FALSE`) outliers
+#'   from the plot. Hiding or discarding outliers can be useful when, for
+#'   example, raw data points need to be displayed on top of the boxplot.
+#'   By discarding outliers, the axis limits will adapt to the box and whiskers
+#'   only, not the full data range. If outliers need to be hidden and the axes
+#'   needs to show the full data range, please use `outlier.shape = NA` instead.
 #' @param outlier.colour,outlier.color,outlier.fill,outlier.shape,outlier.size,outlier.stroke,outlier.alpha
 #'   Default aesthetics for outliers. Set to `NULL` to inherit from the
 #'   aesthetics used for the box.
 #'
 #'   In the unlikely event you specify both US and UK spellings of colour, the
 #'   US spelling will take precedence.
 #'
-#'   Sometimes it can be useful to hide the outliers, for example when overlaying
-#'   the raw data points on top of the boxplot. Hiding the outliers can be achieved
-#'   by setting `outlier.shape = NA`. Importantly, this does not remove the outliers,
-#'   it only hides them, so the range calculated for the y-axis will be the
-#'   same with outliers shown and outliers hidden.
-#'
 #' @param notch If `FALSE` (default) make a standard box plot. If
 #'   `TRUE`, make a notched box plot. Notches are used to compare groups;
 #'   if the notches of two boxes do not overlap, this suggests that the medians
@@ -109,6 +109,7 @@
 geom_boxplot <- function(mapping = NULL, data = NULL,
                          stat = "boxplot", position = "dodge2",
                          ...,
+                         outliers = TRUE,
                          outlier.colour = NULL,
                          outlier.color = NULL,
                          outlier.fill = NULL,
@@ -133,6 +134,7 @@ geom_boxplot <- function(mapping = NULL, data = NULL,
       position$preserve <- "single"
     }
   }
+  check_bool(outliers)
 
   layer(
     data = data,
@@ -143,6 +145,7 @@ geom_boxplot <- function(mapping = NULL, data = NULL,
     show.legend = show.legend,
     inherit.aes = inherit.aes,
     params = list2(
+      outliers = outliers,
       outlier.colour = outlier.color %||% outlier.colour,
       outlier.fill = outlier.fill,
       outlier.shape = outlier.shape,
@@ -167,7 +170,7 @@ GeomBoxplot <- ggproto("GeomBoxplot", Geom,
 
   # need to declare `width` here in case this geom is used with a stat that
   # doesn't have a `width` parameter (e.g., `stat_identity`).
-  extra_params = c("na.rm", "width", "orientation"),
+  extra_params = c("na.rm", "width", "orientation", "outliers"),
 
   setup_params = function(data, params) {
     params$flipped_aes <- has_flipped_aes(data, params)
@@ -180,6 +183,10 @@ GeomBoxplot <- ggproto("GeomBoxplot", Geom,
     data$width <- data$width %||%
       params$width %||% (resolution(data$x, FALSE) * 0.9)
 
+    if (isFALSE(params$outliers)) {
+      data$outliers <- NULL
+    }
+
     if (!is.null(data$outliers)) {
       suppressWarnings({
         out_min <- vapply(data$outliers, min, numeric(1))

man/geom_boxplot.Rd

@@ -8,6 +8,15 @@ test_that("geom_boxplot range includes all outliers", {
 
   expect_true(miny <= min(dat$y))
   expect_true(maxy >= max(dat$y))
+
+  # Unless specifically directed not to
+  p <- ggplot_build(ggplot(dat, aes(x, y)) + geom_boxplot(outliers = FALSE))
+
+  miny <- p$layout$panel_params[[1]]$y.range[1]
+  maxy <- p$layout$panel_params[[1]]$y.range[2]
+
+  expect_lte(maxy, max(dat$y))
+  expect_gte(miny, min(dat$y))
 })
 
 test_that("geom_boxplot works in both directions", {