Make clipping configurable. Closes #2536 (#2539)

* Make clipping configurable. Closes #2536

* panel clip settings should not be applied to facet strips.

* reference user name and github issue

* Move news statement to the correct news file. NEWS is not in use anymore, NEWS.md is current.

* Add visual tests for clipping

* update documentation for clipping option

* Simplify visual tests to just two, fix documentation bug

* rebase and fix visual tests

Author: clauswilke

NEWS.md

@@ -318,6 +318,9 @@ up correct aspect ratio, and draws a graticule.
 
 ### Other
 
+* Clipping to the plot panel is now configurable, through a `clip` argument
+  to coordinate systems, e.g. `coord_cartesian(clip = "off")`. (@clauswilke, #2536)
+
 * `fortify()` gains a method for tbls (@karawoo, #2218)
 
 * `ggplot` gains a method for `grouped_df`s that adds a `.group` variable,

R/coord-.r

@@ -35,6 +35,10 @@ Coord <- ggproto("Coord",
   # Is this the default coordinate system?
   default = FALSE,
 
+  # should drawing be clipped to the extent of the plot panel?
+  # "on" = yes, "off" = no
+  clip = "on",
+
   aspect = function(ranges) NULL,
 
   labels = function(panel_params) panel_params,

R/coord-cartesian-.r

@@ -10,6 +10,14 @@
 #'   the limits to ensure that data and axes don't overlap. If `FALSE`,
 #'   limits are taken exactly from the data or `xlim`/`ylim`.
 #' @param default Is this the default coordinate system? If `FALSE`
+#' @param clip Should drawing be clipped to the extent of the plot panel? A
+#'   setting of `"on"` (the default) means yes, and a setting of `"off"`
+#'   means no. In most cases, the default of `"on"` should not be changed,
+#'   as setting `clip = "off"` can cause unexpected results. It allows
+#'   drawing of data points anywhere on the plot, including in the plot margins. If
+#'   limits are set via `xlim` and `ylim` and some data points fall outside those
+#'   limits, then those data points may show up in places such as the axes, the
+#'   legend, the plot title, or the plot margins.
 #' @export
 #' @examples
 #' # There are two ways of zooming the plot display: with scales or
@@ -49,11 +57,12 @@
 #' # displayed bigger
 #' d + coord_cartesian(xlim = c(0, 1))
 coord_cartesian <- function(xlim = NULL, ylim = NULL, expand = TRUE,
-                            default = FALSE) {
+                            default = FALSE, clip = "on") {
   ggproto(NULL, CoordCartesian,
     limits = list(x = xlim, y = ylim),
     expand = expand,
-    default = default
+    default = default,
+    clip = clip
   )
 }
 

R/coord-fixed.r

@@ -22,11 +22,12 @@
 #' p + coord_fixed(xlim = c(15, 30))
 #'
 #' # Resize the plot to see that the specified aspect ratio is maintained
-coord_fixed <- function(ratio = 1, xlim = NULL, ylim = NULL, expand = TRUE) {
+coord_fixed <- function(ratio = 1, xlim = NULL, ylim = NULL, expand = TRUE, clip = "on") {
   ggproto(NULL, CoordFixed,
     limits = list(x = xlim, y = ylim),
     ratio = ratio,
-    expand = expand
+    expand = expand,
+    clip = clip
   )
 }
 

R/coord-flip.r

@@ -25,10 +25,11 @@
 #' ggplot(df, aes(x, y)) +
 #'   geom_area()
 #' last_plot() + coord_flip()
-coord_flip <- function(xlim = NULL, ylim = NULL, expand = TRUE) {
+coord_flip <- function(xlim = NULL, ylim = NULL, expand = TRUE, clip = "on") {
   ggproto(NULL, CoordFlip,
     limits = list(x = xlim, y = ylim),
-    expand = expand
+    expand = expand,
+    clip = clip
   )
 }
 

R/coord-map.r

@@ -30,6 +30,9 @@
 #'   [mapproj::mapproject()] for more information.
 #' @param xlim,ylim Manually specific x/y limits (in degrees of
 #'   longitude/latitude)
+#' @param clip Should drawing be clipped to the extent of the plot panel? A
+#'   setting of `"on"` (the default) means yes, and a setting of `"off"`
+#'   means no. For details, please see [`coord_cartesian()`].
 #' @export
 #' @examples
 #' if (require("maps")) {
@@ -85,7 +88,7 @@
 #' # Centered on New York (currently has issues with closing polygons)
 #' worldmap + coord_map("ortho", orientation = c(41, -74, 0))
 #' }
-coord_map <- function(projection="mercator", ..., parameters = NULL, orientation = NULL, xlim = NULL, ylim = NULL) {
+coord_map <- function(projection="mercator", ..., parameters = NULL, orientation = NULL, xlim = NULL, ylim = NULL, clip = "on") {
   if (is.null(parameters)) {
     params <- list(...)
   } else {
@@ -96,7 +99,8 @@ coord_map <- function(projection="mercator", ..., parameters = NULL, orientation
     projection = projection,
     orientation = orientation,
     limits = list(x = xlim, y = ylim),
-    params = params
+    params = params,
+    clip = clip
   )
 }
 

R/coord-polar.r

@@ -6,6 +6,9 @@
 #' @param theta variable to map angle to (`x` or `y`)
 #' @param start offset of starting point from 12 o'clock in radians
 #' @param direction 1, clockwise; -1, anticlockwise
+#' @param clip Should drawing be clipped to the extent of the plot panel? A
+#'   setting of `"on"` (the default) means yes, and a setting of `"off"`
+#'   means no. For details, please see [`coord_cartesian()`].
 #' @export
 #' @examples
 #' # NOTE: Use these plots with caution - polar coordinates has
@@ -54,15 +57,16 @@
 #' doh + geom_bar(width = 0.9, position = "fill") + coord_polar(theta = "y")
 #' }
 #' }
-coord_polar <- function(theta = "x", start = 0, direction = 1) {
+coord_polar <- function(theta = "x", start = 0, direction = 1, clip = "on") {
   theta <- match.arg(theta, c("x", "y"))
   r <- if (theta == "x") "y" else "x"
 
   ggproto(NULL, CoordPolar,
     theta = theta,
     r = r,
     start = start,
-    direction = sign(direction)
+    direction = sign(direction),
+    clip = clip
   )
 }
 

R/coord-quickmap.R

@@ -1,10 +1,11 @@
 #' @inheritParams coord_cartesian
 #' @export
 #' @rdname coord_map
-coord_quickmap <- function(xlim = NULL, ylim = NULL, expand = TRUE) {
+coord_quickmap <- function(xlim = NULL, ylim = NULL, expand = TRUE, clip = "on") {
   ggproto(NULL, CoordQuickmap,
     limits = list(x = xlim, y = ylim),
-    expand = expand
+    expand = expand,
+    clip = clip
   )
 }
 

R/coord-transform.r

@@ -12,6 +12,9 @@
 #' @param xtrans,ytrans Deprecated; use `x` and `y` instead.
 #' @param limx,limy limits for x and y axes. (Named so for backward
 #'    compatibility)
+#' @param clip Should drawing be clipped to the extent of the plot panel? A
+#'   setting of `"on"` (the default) means yes, and a setting of `"off"`
+#'   means no. For details, please see [`coord_cartesian()`].
 #' @export
 #' @examples
 #' \donttest{
@@ -75,7 +78,7 @@
 #' plot + coord_trans(x = "log10")
 #' plot + coord_trans(x = "sqrt")
 #' }
-coord_trans <- function(x = "identity", y = "identity", limx = NULL, limy = NULL,
+coord_trans <- function(x = "identity", y = "identity", limx = NULL, limy = NULL, clip = "on",
   xtrans, ytrans)
 {
   if (!missing(xtrans)) {
@@ -99,7 +102,8 @@ coord_trans <- function(x = "identity", y = "identity", limx = NULL, limy = NULL
 
   ggproto(NULL, CoordTrans,
     trans = list(x = x, y = y),
-    limits = list(x = limx, y = limy)
+    limits = list(x = limx, y = limy),
+    clip = clip
   )
 }
 

R/facet-grid-.r

@@ -374,7 +374,7 @@ FacetGrid <- ggproto("FacetGrid", Facet,
     }
 
     panel_table <- gtable_matrix("layout", panel_table,
-      panel_widths, panel_heights, respect = respect, clip = "on", z = matrix(1, ncol = ncol, nrow = nrow))
+      panel_widths, panel_heights, respect = respect, clip = coord$clip, z = matrix(1, ncol = ncol, nrow = nrow))
     panel_table$layout$name <- paste0('panel-', rep(seq_len(ncol), nrow), '-', rep(seq_len(nrow), each = ncol))
 
     panel_table <- gtable_add_col_space(panel_table,

R/facet-null.r

@@ -63,7 +63,7 @@ FacetNull <- ggproto("FacetNull", Facet,
     grob_widths <- unit.c(grobWidth(axis_v$left), unit(1, "null"), grobWidth(axis_v$right))
     grob_heights <- unit.c(grobHeight(axis_h$top), unit(aspect_ratio, "null"), grobHeight(axis_h$bottom))
     grob_names <- c("spacer", "axis-l", "spacer", "axis-t", "panel", "axis-b", "spacer", "axis-r", "spacer")
-    grob_clip <- c("off", "off", "off", "off", "on", "off", "off", "off", "off")
+    grob_clip <- c("off", "off", "off", "off", coord$clip, "off", "off", "off", "off")
 
     layout <- gtable_matrix("layout", all,
       widths = grob_widths, heights = grob_heights,

R/facet-wrap.r

@@ -259,7 +259,7 @@ FacetWrap <- ggproto("FacetWrap", Facet,
     empties <- apply(panel_table, c(1,2), function(x) is.zero(x[[1]]))
     panel_table <- gtable_matrix("layout", panel_table,
      widths = unit(rep(1, ncol), "null"),
-     heights = unit(rep(aspect_ratio, nrow), "null"), respect = respect, clip = "on", z = matrix(1, ncol = ncol, nrow = nrow))
+     heights = unit(rep(aspect_ratio, nrow), "null"), respect = respect, clip = coord$clip, z = matrix(1, ncol = ncol, nrow = nrow))
     panel_table$layout$name <- paste0('panel-', rep(seq_len(ncol), nrow), '-', rep(seq_len(nrow), each = ncol))
 
     panel_table <- gtable_add_col_space(panel_table,
@@ -332,7 +332,7 @@ FacetWrap <- ggproto("FacetWrap", Facet,
         strip_pad <- axis_height_bottom
       }
       strip_height <- unit(apply(strip_mat, 1, max_height), "cm")
-      panel_table <- weave_tables_row(panel_table, strip_mat, placement, strip_height, strip_name, 2, "on")
+      panel_table <- weave_tables_row(panel_table, strip_mat, placement, strip_height, strip_name, 2, coord$clip)
       if (!inside) {
         strip_pad[unclass(strip_pad) != 0] <- strip_padding
         panel_table <- weave_tables_row(panel_table, row_shift = placement, row_height = strip_pad)
@@ -348,7 +348,7 @@ FacetWrap <- ggproto("FacetWrap", Facet,
       }
       strip_pad[unclass(strip_pad) != 0] <- strip_padding
       strip_width <- unit(apply(strip_mat, 2, max_width), "cm")
-      panel_table <- weave_tables_col(panel_table, strip_mat, placement, strip_width, strip_name, 2, "on")
+      panel_table <- weave_tables_col(panel_table, strip_mat, placement, strip_width, strip_name, 2, coord$clip)
       if (!inside) {
         strip_pad[unclass(strip_pad) != 0] <- strip_padding
         panel_table <- weave_tables_col(panel_table, col_shift = placement, col_width = strip_pad)