Rename borders() to annotation_borders() (#6399)

* extract borders function

* rename `borders()` -> `annotation_borders()`

* propagate name change

* deprecate `borders()`

* document

* remove unrelated example

* adjust pkgdown index

* use `annotate()` to avoid propagating labels

* add test

* add news bullet

Author: teunbrand

DESCRIPTION

@@ -93,6 +93,7 @@ Collate:
     'compat-plyr.R'
     'utilities.R'
     'aes.R'
+    'annotation-borders.R'
     'utilities-checks.R'
     'legend-draw.R'
     'geom-.R'

NAMESPACE

@@ -297,6 +297,7 @@ export(after_scale)
 export(after_stat)
 export(alpha)
 export(annotate)
+export(annotation_borders)
 export(annotation_custom)
 export(annotation_logticks)
 export(annotation_map)

NEWS.md

@@ -1,5 +1,7 @@
 # ggplot2 (development version)
 
+* `annotation_borders()` replaces the now-deprecated `borders()` 
+  (@teunbrand, #6392)
 * New `make_constructor()` function that builds a standard constructor for
   Geom and Stat classes (@teunbrand, #6142).
 * In continuous scales, when `breaks` is a function and `n.breaks` is set, the 

R/annotation-borders.R

@@ -0,0 +1,51 @@
+#' Create a layer of map borders
+#'
+#' This is a quick and dirty way to get map data (from the \pkg{maps} package)
+#' onto your plot. This is a good place to start if you need some crude
+#' reference lines, but you'll typically want something more sophisticated
+#' for communication graphics.
+#'
+#' @param database map data, see [maps::map()] for details
+#' @param regions map region
+#' @param fill fill colour
+#' @param colour border colour
+#' @param xlim,ylim latitudinal and longitudinal ranges for extracting map
+#'   polygons, see [maps::map()] for details.
+#' @inheritDotParams geom_polygon
+#' @export
+#' @examples
+#' if (require("maps")) {
+#' data(us.cities)
+#' capitals <- subset(us.cities, capital == 2)
+#' ggplot(capitals, aes(long, lat)) +
+#'   annotation_borders("state") +
+#'   geom_point(aes(size = pop)) +
+#'   scale_size_area() +
+#'   coord_quickmap()
+#' }
+#'
+#' if (require("maps")) {
+#' # Same map, with some world context
+#' ggplot(capitals, aes(long, lat)) +
+#'   annotation_borders("world", xlim = c(-130, -60), ylim = c(20, 50)) +
+#'   geom_point(aes(size = pop)) +
+#'   scale_size_area() +
+#'   coord_quickmap()
+#' }
+annotation_borders <- function(database = "world", regions = ".", fill = NA,
+                               colour = "grey50", xlim = NULL, ylim = NULL, ...) {
+  df <- map_data(database, regions, xlim = xlim, ylim = ylim)
+  annotate(
+    geom = "polygon",
+    x = df$long, y = df$lat, group = df$group,
+    fill = fill, colour = colour, ...
+  )
+}
+
+#' @export
+#' @rdname annotation_borders
+#' @usage borders(...) # Deprecated
+borders <- function(...) {
+  deprecate_soft0("4.0.0", "borders()", "annotation_borders()")
+  annotation_borders(...)
+}

R/fortify-map.R

@@ -7,7 +7,7 @@
 #' plotted with ggplot2.
 #'
 #' @export
-#' @seealso [map_data()] and [borders()]
+#' @seealso [map_data()] and [annotation_borders()]
 #' @param model map object
 #' @param data not used by this method
 #' @param ... not used by this method
@@ -108,57 +108,3 @@ map_data <- function(map, region = ".", exact = FALSE, ...) {
   df[names(names)] <- vec_slice(names, df$group)
   vec_slice(df, stats::complete.cases(df$lat, df$long))
 }
-
-#' Create a layer of map borders
-#'
-#' This is a quick and dirty way to get map data (from the \pkg{maps} package)
-#' onto your plot. This is a good place to start if you need some crude
-#' reference lines, but you'll typically want something more sophisticated
-#' for communication graphics.
-#'
-#' @param database map data, see [maps::map()] for details
-#' @param regions map region
-#' @param fill fill colour
-#' @param colour border colour
-#' @param xlim,ylim latitudinal and longitudinal ranges for extracting map
-#'   polygons, see [maps::map()] for details.
-#' @inheritDotParams geom_polygon
-#' @export
-#' @examples
-#' if (require("maps")) {
-#'
-#' ia <- map_data("county", "iowa")
-#' mid_range <- function(x) mean(range(x))
-#' seats <- do.call(rbind, lapply(split(ia, ia$subregion), function(d) {
-#'   data.frame(lat = mid_range(d$lat), long = mid_range(d$long), subregion = unique(d$subregion))
-#' }))
-#'
-#' ggplot(ia, aes(long, lat)) +
-#'   geom_polygon(aes(group = group), fill = NA, colour = "grey60") +
-#'   geom_text(aes(label = subregion), data = seats, size = 2, angle = 45)
-#' }
-#'
-#' if (require("maps")) {
-#' data(us.cities)
-#' capitals <- subset(us.cities, capital == 2)
-#' ggplot(capitals, aes(long, lat)) +
-#'   borders("state") +
-#'   geom_point(aes(size = pop)) +
-#'   scale_size_area() +
-#'   coord_quickmap()
-#' }
-#'
-#' if (require("maps")) {
-#' # Same map, with some world context
-#' ggplot(capitals, aes(long, lat)) +
-#'   borders("world", xlim = c(-130, -60), ylim = c(20, 50)) +
-#'   geom_point(aes(size = pop)) +
-#'   scale_size_area() +
-#'   coord_quickmap()
-#' }
-borders <- function(database = "world", regions = ".", fill = NA,
-                    colour = "grey50", xlim = NULL, ylim = NULL, ...) {
-  df <- map_data(database, regions, xlim = xlim, ylim = ylim)
-  geom_polygon(aes(.data$long, .data$lat, group = .data$group), data = df,
-    fill = fill, colour = colour, ..., inherit.aes = FALSE)
-}

R/geom-segment.R

@@ -98,7 +98,7 @@ GeomSegment <- ggproto(
 #' ggplot(seals, aes(long, lat)) +
 #'   geom_segment(aes(xend = long + delta_long, yend = lat + delta_lat),
 #'     arrow = arrow(length = unit(0.1,"cm"))) +
-#'   borders("state")
+#'   annotation_borders("state")
 #' }
 #'
 #' # Use lineend and linejoin to change the style of the segments

R/layer.R

@@ -64,7 +64,7 @@
 #' @param inherit.aes If `FALSE`, overrides the default aesthetics,
 #'   rather than combining with them. This is most useful for helper functions
 #'   that define both data and aesthetics and shouldn't inherit behaviour from
-#'   the default plot specification, e.g. [borders()].
+#'   the default plot specification, e.g. [annotation_borders()].
 #' @param check.aes,check.param If `TRUE`, the default, will check that
 #'   supplied parameters and aesthetics are understood by the `geom` or
 #'   `stat`. Use `FALSE` to suppress the checks.

_pkgdown.yml

@@ -92,7 +92,7 @@ reference:
   - annotation_logticks
   - annotation_map
   - annotation_raster
-  - borders
+  - annotation_borders
 
 - title: Aesthetics
   desc: >