Skip to content

Rename borders() to annotation_borders() #6399

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Merged
merged 11 commits into from
May 19, 2025
Merged
Changes from all commits
Commits
File filter

Filter by extension

Filter by extension

Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
1 change: 1 addition & 0 deletions DESCRIPTION
Original file line number Diff line number Diff line change
@@ -93,6 +93,7 @@ Collate:
'compat-plyr.R'
'utilities.R'
'aes.R'
'annotation-borders.R'
'utilities-checks.R'
'legend-draw.R'
'geom-.R'
1 change: 1 addition & 0 deletions NAMESPACE
Original file line number Diff line number Diff line change
@@ -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)
2 changes: 2 additions & 0 deletions NEWS.md
Original file line number Diff line number Diff line change
@@ -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
51 changes: 51 additions & 0 deletions R/annotation-borders.R
Original file line number Diff line number Diff line change
@@ -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(...)
}
56 changes: 1 addition & 55 deletions R/fortify-map.R
Original file line number Diff line number Diff line change
@@ -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)
}
2 changes: 1 addition & 1 deletion R/geom-segment.R
Original file line number Diff line number Diff line change
@@ -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
2 changes: 1 addition & 1 deletion R/layer.R
Original file line number Diff line number Diff line change
@@ -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.
2 changes: 1 addition & 1 deletion _pkgdown.yml
Original file line number Diff line number Diff line change
@@ -92,7 +92,7 @@ reference:
- annotation_logticks
- annotation_map
- annotation_raster
- borders
- annotation_borders

- title: Aesthetics
desc: >
28 changes: 9 additions & 19 deletions man/borders.Rd → man/annotation_borders.Rd

Some generated files are not rendered by default. Learn more about how customized files appear on GitHub.

2 changes: 1 addition & 1 deletion man/fortify.map.Rd

Some generated files are not rendered by default. Learn more about how customized files appear on GitHub.

2 changes: 1 addition & 1 deletion man/geom_bar.Rd

Some generated files are not rendered by default. Learn more about how customized files appear on GitHub.

2 changes: 1 addition & 1 deletion man/geom_bin_2d.Rd

Some generated files are not rendered by default. Learn more about how customized files appear on GitHub.

2 changes: 1 addition & 1 deletion man/geom_blank.Rd

Some generated files are not rendered by default. Learn more about how customized files appear on GitHub.

2 changes: 1 addition & 1 deletion man/geom_boxplot.Rd

Some generated files are not rendered by default. Learn more about how customized files appear on GitHub.

2 changes: 1 addition & 1 deletion man/geom_contour.Rd

Some generated files are not rendered by default. Learn more about how customized files appear on GitHub.

2 changes: 1 addition & 1 deletion man/geom_count.Rd

Some generated files are not rendered by default. Learn more about how customized files appear on GitHub.

2 changes: 1 addition & 1 deletion man/geom_density.Rd

Some generated files are not rendered by default. Learn more about how customized files appear on GitHub.

2 changes: 1 addition & 1 deletion man/geom_density_2d.Rd

Some generated files are not rendered by default. Learn more about how customized files appear on GitHub.

2 changes: 1 addition & 1 deletion man/geom_dotplot.Rd

Some generated files are not rendered by default. Learn more about how customized files appear on GitHub.

2 changes: 1 addition & 1 deletion man/geom_function.Rd

Some generated files are not rendered by default. Learn more about how customized files appear on GitHub.

2 changes: 1 addition & 1 deletion man/geom_hex.Rd

Some generated files are not rendered by default. Learn more about how customized files appear on GitHub.

2 changes: 1 addition & 1 deletion man/geom_histogram.Rd

Some generated files are not rendered by default. Learn more about how customized files appear on GitHub.

2 changes: 1 addition & 1 deletion man/geom_jitter.Rd

Some generated files are not rendered by default. Learn more about how customized files appear on GitHub.

2 changes: 1 addition & 1 deletion man/geom_linerange.Rd

Some generated files are not rendered by default. Learn more about how customized files appear on GitHub.

2 changes: 1 addition & 1 deletion man/geom_map.Rd

Some generated files are not rendered by default. Learn more about how customized files appear on GitHub.

2 changes: 1 addition & 1 deletion man/geom_path.Rd

Some generated files are not rendered by default. Learn more about how customized files appear on GitHub.

2 changes: 1 addition & 1 deletion man/geom_point.Rd

Some generated files are not rendered by default. Learn more about how customized files appear on GitHub.

Loading
Oops, something went wrong.