diff --git a/DESCRIPTION b/DESCRIPTION index 82266c740f..a681bc838a 100644 --- a/DESCRIPTION +++ b/DESCRIPTION @@ -93,6 +93,7 @@ Collate: 'compat-plyr.R' 'utilities.R' 'aes.R' + 'annotation-borders.R' 'utilities-checks.R' 'legend-draw.R' 'geom-.R' diff --git a/NAMESPACE b/NAMESPACE index 088da2ba6c..c3b3a9b77a 100644 --- a/NAMESPACE +++ b/NAMESPACE @@ -294,6 +294,7 @@ export(after_scale) export(after_stat) export(alpha) export(annotate) +export(annotation_borders) export(annotation_custom) export(annotation_logticks) export(annotation_map) diff --git a/NEWS.md b/NEWS.md index 363a20cc28..bac421e27d 100644 --- a/NEWS.md +++ b/NEWS.md @@ -1,5 +1,7 @@ # ggplot2 (development version) +* `annotation_borders()` replaces the now-deprecated `borders()` + (@teunbrand, #6392) * `position_fill()` avoids stacking observations of zero (@teunbrand, #6338) * New `layer(layout)` argument to interact with facets (@teunbrand, #3062) * New `stat_connect()` to connect points via steps or other shapes diff --git a/R/annotation-borders.R b/R/annotation-borders.R new file mode 100644 index 0000000000..5f725d80a1 --- /dev/null +++ b/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(...) +} diff --git a/R/fortify-map.R b/R/fortify-map.R index 19b58a04bf..26cfc9b8d9 100644 --- a/R/fortify-map.R +++ b/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) -} diff --git a/R/geom-segment.R b/R/geom-segment.R index fb00f0481d..91c8439825 100644 --- a/R/geom-segment.R +++ b/R/geom-segment.R @@ -42,7 +42,7 @@ #' 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 diff --git a/R/layer.R b/R/layer.R index cb81e84b58..af2f57ba9a 100644 --- a/R/layer.R +++ b/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. diff --git a/_pkgdown.yml b/_pkgdown.yml index 5b0505afd8..add2a2e296 100644 --- a/_pkgdown.yml +++ b/_pkgdown.yml @@ -92,7 +92,7 @@ reference: - annotation_logticks - annotation_map - annotation_raster - - borders + - annotation_borders - title: Aesthetics desc: > diff --git a/man/borders.Rd b/man/annotation_borders.Rd similarity index 87% rename from man/borders.Rd rename to man/annotation_borders.Rd index 2f5e9f6841..184cc67a1a 100644 --- a/man/borders.Rd +++ b/man/annotation_borders.Rd @@ -1,10 +1,11 @@ % Generated by roxygen2: do not edit by hand -% Please edit documentation in R/fortify-map.R -\name{borders} +% Please edit documentation in R/annotation-borders.R +\name{annotation_borders} +\alias{annotation_borders} \alias{borders} \title{Create a layer of map borders} \usage{ -borders( +annotation_borders( database = "world", regions = ".", fill = NA, @@ -13,6 +14,8 @@ borders( ylim = NULL, ... ) + +borders(...) # Deprecated } \arguments{ \item{database}{map data, see \code{\link[maps:map]{maps::map()}} for details} @@ -85,7 +88,7 @@ but unobserved levels are omitted.} \item{\code{inherit.aes}}{If \code{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. \code{\link[=borders]{borders()}}.} +the default plot specification, e.g. \code{\link[=annotation_borders]{annotation_borders()}}.} \item{\code{na.rm}}{If \code{FALSE}, the default, missing values are removed with a warning. If \code{TRUE}, missing values are silently removed.} }} @@ -97,24 +100,11 @@ reference lines, but you'll typically want something more sophisticated for communication graphics. } \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") + + annotation_borders("state") + geom_point(aes(size = pop)) + scale_size_area() + coord_quickmap() @@ -123,7 +113,7 @@ ggplot(capitals, aes(long, lat)) + if (require("maps")) { # Same map, with some world context ggplot(capitals, aes(long, lat)) + - borders("world", xlim = c(-130, -60), ylim = c(20, 50)) + + annotation_borders("world", xlim = c(-130, -60), ylim = c(20, 50)) + geom_point(aes(size = pop)) + scale_size_area() + coord_quickmap() diff --git a/man/fortify.map.Rd b/man/fortify.map.Rd index ba1c5fbc63..0eae5e818b 100644 --- a/man/fortify.map.Rd +++ b/man/fortify.map.Rd @@ -35,6 +35,6 @@ ggplot(tx, aes(long, lat)) + } } \seealso{ -\code{\link[=map_data]{map_data()}} and \code{\link[=borders]{borders()}} +\code{\link[=map_data]{map_data()}} and \code{\link[=annotation_borders]{annotation_borders()}} } \keyword{internal} diff --git a/man/geom_bar.Rd b/man/geom_bar.Rd index 1d19ff8f90..759ec40557 100644 --- a/man/geom_bar.Rd +++ b/man/geom_bar.Rd @@ -129,7 +129,7 @@ but unobserved levels are omitted.} \item{inherit.aes}{If \code{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. \code{\link[=borders]{borders()}}.} +the default plot specification, e.g. \code{\link[=annotation_borders]{annotation_borders()}}.} \item{geom, stat}{Override the default connection between \code{geom_bar()} and \code{stat_count()}. For more information about overriding these connections, diff --git a/man/geom_bin_2d.Rd b/man/geom_bin_2d.Rd index 16b0fa4dad..f55b0e6aa8 100644 --- a/man/geom_bin_2d.Rd +++ b/man/geom_bin_2d.Rd @@ -111,7 +111,7 @@ but unobserved levels are omitted.} \item{inherit.aes}{If \code{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. \code{\link[=borders]{borders()}}.} +the default plot specification, e.g. \code{\link[=annotation_borders]{annotation_borders()}}.} \item{geom, stat}{Use to override the default connection between \code{geom_bin_2d()} and \code{stat_bin_2d()}. For more information about overriding diff --git a/man/geom_blank.Rd b/man/geom_blank.Rd index a8d4a2613d..51606bb14b 100644 --- a/man/geom_blank.Rd +++ b/man/geom_blank.Rd @@ -100,7 +100,7 @@ but unobserved levels are omitted.} \item{inherit.aes}{If \code{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. \code{\link[=borders]{borders()}}.} +the default plot specification, e.g. \code{\link[=annotation_borders]{annotation_borders()}}.} } \description{ The blank geom draws nothing, but can be a useful way of ensuring common diff --git a/man/geom_boxplot.Rd b/man/geom_boxplot.Rd index d96c576da0..7f065bb239 100644 --- a/man/geom_boxplot.Rd +++ b/man/geom_boxplot.Rd @@ -178,7 +178,7 @@ but unobserved levels are omitted.} \item{inherit.aes}{If \code{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. \code{\link[=borders]{borders()}}.} +the default plot specification, e.g. \code{\link[=annotation_borders]{annotation_borders()}}.} \item{geom, stat}{Use to override the default connection between \code{geom_boxplot()} and \code{stat_boxplot()}. For more information about diff --git a/man/geom_contour.Rd b/man/geom_contour.Rd index 2336ec973f..57b5a1f335 100644 --- a/man/geom_contour.Rd +++ b/man/geom_contour.Rd @@ -176,7 +176,7 @@ but unobserved levels are omitted.} \item{inherit.aes}{If \code{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. \code{\link[=borders]{borders()}}.} +the default plot specification, e.g. \code{\link[=annotation_borders]{annotation_borders()}}.} \item{geom}{The geometric object to use to display the data for this layer. When using a \verb{stat_*()} function to construct a layer, the \code{geom} argument diff --git a/man/geom_count.Rd b/man/geom_count.Rd index 753ec70728..a5848b8720 100644 --- a/man/geom_count.Rd +++ b/man/geom_count.Rd @@ -103,7 +103,7 @@ but unobserved levels are omitted.} \item{inherit.aes}{If \code{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. \code{\link[=borders]{borders()}}.} +the default plot specification, e.g. \code{\link[=annotation_borders]{annotation_borders()}}.} \item{geom, stat}{Use to override the default connection between \code{geom_count()} and \code{stat_sum()}. For more information about overriding diff --git a/man/geom_density.Rd b/man/geom_density.Rd index 1cb1b80b07..25ce560324 100644 --- a/man/geom_density.Rd +++ b/man/geom_density.Rd @@ -117,7 +117,7 @@ but unobserved levels are omitted.} \item{inherit.aes}{If \code{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. \code{\link[=borders]{borders()}}.} +the default plot specification, e.g. \code{\link[=annotation_borders]{annotation_borders()}}.} \item{outline.type}{Type of the outline of the area; \code{"both"} draws both the upper and lower lines, \code{"upper"}/\code{"lower"} draws the respective lines only. diff --git a/man/geom_density_2d.Rd b/man/geom_density_2d.Rd index 18e423d60e..b771b0e290 100644 --- a/man/geom_density_2d.Rd +++ b/man/geom_density_2d.Rd @@ -145,7 +145,7 @@ but unobserved levels are omitted.} \item{inherit.aes}{If \code{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. \code{\link[=borders]{borders()}}.} +the default plot specification, e.g. \code{\link[=annotation_borders]{annotation_borders()}}.} \item{geom, stat}{Use to override the default connection between \code{geom_density_2d()} and \code{stat_density_2d()}. For more information at diff --git a/man/geom_dotplot.Rd b/man/geom_dotplot.Rd index b8b68c2146..1cfc1ce0fe 100644 --- a/man/geom_dotplot.Rd +++ b/man/geom_dotplot.Rd @@ -138,7 +138,7 @@ but unobserved levels are omitted.} \item{inherit.aes}{If \code{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. \code{\link[=borders]{borders()}}.} +the default plot specification, e.g. \code{\link[=annotation_borders]{annotation_borders()}}.} } \description{ In a dot plot, the width of a dot corresponds to the bin width diff --git a/man/geom_function.Rd b/man/geom_function.Rd index be0a23541d..7b1d47c2fc 100644 --- a/man/geom_function.Rd +++ b/man/geom_function.Rd @@ -107,7 +107,7 @@ but unobserved levels are omitted.} \item{inherit.aes}{If \code{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. \code{\link[=borders]{borders()}}.} +the default plot specification, e.g. \code{\link[=annotation_borders]{annotation_borders()}}.} \item{geom}{The geometric object to use to display the data for this layer. When using a \verb{stat_*()} function to construct a layer, the \code{geom} argument diff --git a/man/geom_hex.Rd b/man/geom_hex.Rd index bbe58dd8f5..6fd4b278aa 100644 --- a/man/geom_hex.Rd +++ b/man/geom_hex.Rd @@ -106,7 +106,7 @@ but unobserved levels are omitted.} \item{inherit.aes}{If \code{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. \code{\link[=borders]{borders()}}.} +the default plot specification, e.g. \code{\link[=annotation_borders]{annotation_borders()}}.} \item{geom, stat}{Override the default connection between \code{geom_hex()} and \code{stat_bin_hex()}. For more information about overriding these connections, diff --git a/man/geom_histogram.Rd b/man/geom_histogram.Rd index f0532d8b25..556f479393 100644 --- a/man/geom_histogram.Rd +++ b/man/geom_histogram.Rd @@ -128,7 +128,7 @@ but unobserved levels are omitted.} \item{inherit.aes}{If \code{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. \code{\link[=borders]{borders()}}.} +the default plot specification, e.g. \code{\link[=annotation_borders]{annotation_borders()}}.} \item{binwidth}{The width of the bins. Can be specified as a numeric value or as a function that takes x after scale transformation as input and diff --git a/man/geom_jitter.Rd b/man/geom_jitter.Rd index afcb05e39e..7e9b0c9fb8 100644 --- a/man/geom_jitter.Rd +++ b/man/geom_jitter.Rd @@ -115,7 +115,7 @@ but unobserved levels are omitted.} \item{inherit.aes}{If \code{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. \code{\link[=borders]{borders()}}.} +the default plot specification, e.g. \code{\link[=annotation_borders]{annotation_borders()}}.} } \description{ The jitter geom is a convenient shortcut for diff --git a/man/geom_linerange.Rd b/man/geom_linerange.Rd index e5208dce61..09e925e033 100644 --- a/man/geom_linerange.Rd +++ b/man/geom_linerange.Rd @@ -183,7 +183,7 @@ but unobserved levels are omitted.} \item{inherit.aes}{If \code{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. \code{\link[=borders]{borders()}}.} +the default plot specification, e.g. \code{\link[=annotation_borders]{annotation_borders()}}.} } \description{ Various ways of representing a vertical interval defined by \code{x}, diff --git a/man/geom_map.Rd b/man/geom_map.Rd index 561a297161..b4a3723c49 100644 --- a/man/geom_map.Rd +++ b/man/geom_map.Rd @@ -96,7 +96,7 @@ but unobserved levels are omitted.} \item{inherit.aes}{If \code{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. \code{\link[=borders]{borders()}}.} +the default plot specification, e.g. \code{\link[=annotation_borders]{annotation_borders()}}.} } \description{ Display polygons as a map. This is meant as annotation, so it does not diff --git a/man/geom_path.Rd b/man/geom_path.Rd index 6d0f30ec8d..d295359a35 100644 --- a/man/geom_path.Rd +++ b/man/geom_path.Rd @@ -147,7 +147,7 @@ but unobserved levels are omitted.} \item{inherit.aes}{If \code{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. \code{\link[=borders]{borders()}}.} +the default plot specification, e.g. \code{\link[=annotation_borders]{annotation_borders()}}.} \item{orientation}{The orientation of the layer. The default (\code{NA}) automatically determines the orientation from the aesthetic mapping. In the diff --git a/man/geom_point.Rd b/man/geom_point.Rd index ea7975762d..cb7dfb6f0b 100644 --- a/man/geom_point.Rd +++ b/man/geom_point.Rd @@ -104,7 +104,7 @@ but unobserved levels are omitted.} \item{inherit.aes}{If \code{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. \code{\link[=borders]{borders()}}.} +the default plot specification, e.g. \code{\link[=annotation_borders]{annotation_borders()}}.} } \description{ The point geom is used to create scatterplots. The scatterplot is most diff --git a/man/geom_polygon.Rd b/man/geom_polygon.Rd index 1c76e21995..073c15c653 100644 --- a/man/geom_polygon.Rd +++ b/man/geom_polygon.Rd @@ -110,7 +110,7 @@ but unobserved levels are omitted.} \item{inherit.aes}{If \code{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. \code{\link[=borders]{borders()}}.} +the default plot specification, e.g. \code{\link[=annotation_borders]{annotation_borders()}}.} } \description{ Polygons are very similar to paths (as drawn by \code{\link[=geom_path]{geom_path()}}) diff --git a/man/geom_qq.Rd b/man/geom_qq.Rd index 7915f29e47..aad48d91b0 100644 --- a/man/geom_qq.Rd +++ b/man/geom_qq.Rd @@ -163,7 +163,7 @@ but unobserved levels are omitted.} \item{inherit.aes}{If \code{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. \code{\link[=borders]{borders()}}.} +the default plot specification, e.g. \code{\link[=annotation_borders]{annotation_borders()}}.} } \description{ \code{geom_qq()} and \code{stat_qq()} produce quantile-quantile plots. \code{geom_qq_line()} and diff --git a/man/geom_quantile.Rd b/man/geom_quantile.Rd index 495e6b22cd..7a97d3a6cf 100644 --- a/man/geom_quantile.Rd +++ b/man/geom_quantile.Rd @@ -116,7 +116,7 @@ but unobserved levels are omitted.} \item{inherit.aes}{If \code{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. \code{\link[=borders]{borders()}}.} +the default plot specification, e.g. \code{\link[=annotation_borders]{annotation_borders()}}.} \item{geom, stat}{Use to override the default connection between \code{geom_quantile()} and \code{stat_quantile()}. For more information about diff --git a/man/geom_ribbon.Rd b/man/geom_ribbon.Rd index 256e821e6b..89f2d464dd 100644 --- a/man/geom_ribbon.Rd +++ b/man/geom_ribbon.Rd @@ -137,7 +137,7 @@ but unobserved levels are omitted.} \item{inherit.aes}{If \code{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. \code{\link[=borders]{borders()}}.} +the default plot specification, e.g. \code{\link[=annotation_borders]{annotation_borders()}}.} \item{outline.type}{Type of the outline of the area; \code{"both"} draws both the upper and lower lines, \code{"upper"}/\code{"lower"} draws the respective lines only. diff --git a/man/geom_rug.Rd b/man/geom_rug.Rd index e77826c7e9..3d66a043c8 100644 --- a/man/geom_rug.Rd +++ b/man/geom_rug.Rd @@ -115,7 +115,7 @@ but unobserved levels are omitted.} \item{inherit.aes}{If \code{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. \code{\link[=borders]{borders()}}.} +the default plot specification, e.g. \code{\link[=annotation_borders]{annotation_borders()}}.} } \description{ A rug plot is a compact visualisation designed to supplement a 2d display diff --git a/man/geom_segment.Rd b/man/geom_segment.Rd index 8cddae4dc2..da25a6bc96 100644 --- a/man/geom_segment.Rd +++ b/man/geom_segment.Rd @@ -135,7 +135,7 @@ but unobserved levels are omitted.} \item{inherit.aes}{If \code{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. \code{\link[=borders]{borders()}}.} +the default plot specification, e.g. \code{\link[=annotation_borders]{annotation_borders()}}.} \item{curvature}{A numeric value giving the amount of curvature. Negative values produce left-hand curves, positive values @@ -197,7 +197,7 @@ if (requireNamespace('maps', quietly = TRUE)) { 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 diff --git a/man/geom_smooth.Rd b/man/geom_smooth.Rd index 4a02999e73..0129703bf9 100644 --- a/man/geom_smooth.Rd +++ b/man/geom_smooth.Rd @@ -147,7 +147,7 @@ but unobserved levels are omitted.} \item{inherit.aes}{If \code{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. \code{\link[=borders]{borders()}}.} +the default plot specification, e.g. \code{\link[=annotation_borders]{annotation_borders()}}.} \item{geom, stat}{Use to override the default connection between \code{geom_smooth()} and \code{stat_smooth()}. For more information about overriding diff --git a/man/geom_spoke.Rd b/man/geom_spoke.Rd index ffebfbe589..6486812cd2 100644 --- a/man/geom_spoke.Rd +++ b/man/geom_spoke.Rd @@ -105,7 +105,7 @@ but unobserved levels are omitted.} \item{inherit.aes}{If \code{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. \code{\link[=borders]{borders()}}.} +the default plot specification, e.g. \code{\link[=annotation_borders]{annotation_borders()}}.} } \description{ This is a polar parameterisation of \code{\link[=geom_segment]{geom_segment()}}. It is diff --git a/man/geom_text.Rd b/man/geom_text.Rd index 4293217066..7b07eaad34 100644 --- a/man/geom_text.Rd +++ b/man/geom_text.Rd @@ -150,7 +150,7 @@ but unobserved levels are omitted.} \item{inherit.aes}{If \code{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. \code{\link[=borders]{borders()}}.} +the default plot specification, e.g. \code{\link[=annotation_borders]{annotation_borders()}}.} \item{check_overlap}{If \code{TRUE}, text that overlaps previous text in the same layer will not be plotted. \code{check_overlap} happens at draw time and in diff --git a/man/geom_tile.Rd b/man/geom_tile.Rd index d0638772b5..3f7a18a421 100644 --- a/man/geom_tile.Rd +++ b/man/geom_tile.Rd @@ -140,7 +140,7 @@ but unobserved levels are omitted.} \item{inherit.aes}{If \code{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. \code{\link[=borders]{borders()}}.} +the default plot specification, e.g. \code{\link[=annotation_borders]{annotation_borders()}}.} \item{linejoin}{Line join style (round, mitre, bevel).} } diff --git a/man/geom_violin.Rd b/man/geom_violin.Rd index 590ebface6..1495f7b294 100644 --- a/man/geom_violin.Rd +++ b/man/geom_violin.Rd @@ -146,7 +146,7 @@ but unobserved levels are omitted.} \item{inherit.aes}{If \code{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. \code{\link[=borders]{borders()}}.} +the default plot specification, e.g. \code{\link[=annotation_borders]{annotation_borders()}}.} \item{geom, stat}{Use to override the default connection between \code{geom_violin()} and \code{stat_ydensity()}. For more information about diff --git a/man/ggsf.Rd b/man/ggsf.Rd index f7790f5abb..3343c6bbdc 100644 --- a/man/ggsf.Rd +++ b/man/ggsf.Rd @@ -244,7 +244,7 @@ override the default legend.} \item{inherit.aes}{If \code{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. \code{\link[=borders]{borders()}}.} +the default plot specification, e.g. \code{\link[=annotation_borders]{annotation_borders()}}.} \item{...}{Other arguments passed on to \code{\link[=layer]{layer()}}'s \code{params} argument. These arguments broadly fall into one of 4 categories below. Notably, further diff --git a/man/layer.Rd b/man/layer.Rd index 79d9afbe57..f4b9bfb13f 100644 --- a/man/layer.Rd +++ b/man/layer.Rd @@ -85,7 +85,7 @@ to use \code{position_jitter()}, give the position as \code{"jitter"}. \item{inherit.aes}{If \code{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. \code{\link[=borders]{borders()}}.} +the default plot specification, e.g. \code{\link[=annotation_borders]{annotation_borders()}}.} \item{check.aes, check.param}{If \code{TRUE}, the default, will check that supplied parameters and aesthetics are understood by the \code{geom} or diff --git a/man/layer_sf.Rd b/man/layer_sf.Rd index a10dfa8805..e9a11604e8 100644 --- a/man/layer_sf.Rd +++ b/man/layer_sf.Rd @@ -82,7 +82,7 @@ to use \code{position_jitter()}, give the position as \code{"jitter"}. \item{inherit.aes}{If \code{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. \code{\link[=borders]{borders()}}.} +the default plot specification, e.g. \code{\link[=annotation_borders]{annotation_borders()}}.} \item{check.aes, check.param}{If \code{TRUE}, the default, will check that supplied parameters and aesthetics are understood by the \code{geom} or diff --git a/man/stat_connect.Rd b/man/stat_connect.Rd index d62ba610a5..a8b1668e6f 100644 --- a/man/stat_connect.Rd +++ b/man/stat_connect.Rd @@ -121,18 +121,18 @@ but unobserved levels are omitted.} \item{inherit.aes}{If \code{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. \code{\link[=borders]{borders()}}.} +the default plot specification, e.g. \code{\link[=annotation_borders]{annotation_borders()}}.} } \description{ Connect successive points with lines of different shapes. } \section{Aesthetics}{ -\code{stat_connect()} understands the following aesthetics (required aesthetics are in bold): -\itemize{ -\item \strong{\code{\link[=aes_position]{x}} \emph{or} \code{\link[=aes_position]{xmin}} \emph{or} \code{\link[=aes_position]{xmax}}} -\item \strong{\code{\link[=aes_position]{y}} \emph{or} \code{\link[=aes_position]{ymin}} \emph{or} \code{\link[=aes_position]{ymax}}} -\item \code{\link[=aes_group_order]{group}} +\code{stat_connect()} understands the following aesthetics. Required aesthetics are displayed in bold and defaults are displayed for optional aesthetics: +\tabular{rll}{ +• \tab \strong{\code{\link[=aes_position]{x}} \emph{or} \code{\link[=aes_position]{xmin}} \emph{or} \code{\link[=aes_position]{xmax}}} \tab \cr\cr +• \tab \strong{\code{\link[=aes_position]{y}} \emph{or} \code{\link[=aes_position]{ymin}} \emph{or} \code{\link[=aes_position]{ymax}}} \tab \cr\cr +• \tab \code{\link[=aes_group_order]{group}} \tab → inferred \cr\cr } Learn more about setting these aesthetics in \code{vignette("ggplot2-specs")}. } diff --git a/man/stat_ecdf.Rd b/man/stat_ecdf.Rd index a341ce6543..94a91b5b79 100644 --- a/man/stat_ecdf.Rd +++ b/man/stat_ecdf.Rd @@ -112,7 +112,7 @@ but unobserved levels are omitted.} \item{inherit.aes}{If \code{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. \code{\link[=borders]{borders()}}.} +the default plot specification, e.g. \code{\link[=annotation_borders]{annotation_borders()}}.} } \description{ The empirical cumulative distribution function (ECDF) provides an alternative diff --git a/man/stat_ellipse.Rd b/man/stat_ellipse.Rd index fa4ecc9b05..4b0d13d0ef 100644 --- a/man/stat_ellipse.Rd +++ b/man/stat_ellipse.Rd @@ -119,7 +119,7 @@ but unobserved levels are omitted.} \item{inherit.aes}{If \code{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. \code{\link[=borders]{borders()}}.} +the default plot specification, e.g. \code{\link[=annotation_borders]{annotation_borders()}}.} } \description{ The method for calculating the ellipses has been modified from diff --git a/man/stat_identity.Rd b/man/stat_identity.Rd index f5dd6e1a5d..5cf31b868a 100644 --- a/man/stat_identity.Rd +++ b/man/stat_identity.Rd @@ -100,7 +100,7 @@ but unobserved levels are omitted.} \item{inherit.aes}{If \code{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. \code{\link[=borders]{borders()}}.} +the default plot specification, e.g. \code{\link[=annotation_borders]{annotation_borders()}}.} } \description{ The identity statistic leaves the data unchanged. diff --git a/man/stat_manual.Rd b/man/stat_manual.Rd index de64b21a31..374c57bafc 100644 --- a/man/stat_manual.Rd +++ b/man/stat_manual.Rd @@ -112,7 +112,7 @@ but unobserved levels are omitted.} \item{inherit.aes}{If \code{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. \code{\link[=borders]{borders()}}.} +the default plot specification, e.g. \code{\link[=annotation_borders]{annotation_borders()}}.} } \description{ \code{stat_manual()} takes a function that computes a data transformation for diff --git a/man/stat_sf_coordinates.Rd b/man/stat_sf_coordinates.Rd index 1a8aef4440..3173fa8e86 100644 --- a/man/stat_sf_coordinates.Rd +++ b/man/stat_sf_coordinates.Rd @@ -79,7 +79,7 @@ but unobserved levels are omitted.} \item{inherit.aes}{If \code{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. \code{\link[=borders]{borders()}}.} +the default plot specification, e.g. \code{\link[=annotation_borders]{annotation_borders()}}.} \item{fun.geometry}{A function that takes a \code{sfc} object and returns a \code{sfc_POINT} with the same length as the input. If \code{NULL}, \code{function(x) sf::st_point_on_surface(sf::st_zm(x))} diff --git a/man/stat_summary.Rd b/man/stat_summary.Rd index 20326b840f..25fcd57915 100644 --- a/man/stat_summary.Rd +++ b/man/stat_summary.Rd @@ -168,7 +168,7 @@ but unobserved levels are omitted.} \item{inherit.aes}{If \code{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. \code{\link[=borders]{borders()}}.} +the default plot specification, e.g. \code{\link[=annotation_borders]{annotation_borders()}}.} \item{fun.ymin, fun.y, fun.ymax}{\ifelse{html}{\href{https://lifecycle.r-lib.org/articles/stages.html#deprecated}{\figure{lifecycle-deprecated.svg}{options: alt='[Deprecated]'}}}{\strong{[Deprecated]}} Use the versions specified above instead.} diff --git a/man/stat_summary_2d.Rd b/man/stat_summary_2d.Rd index da62dd0a15..76b530f415 100644 --- a/man/stat_summary_2d.Rd +++ b/man/stat_summary_2d.Rd @@ -147,7 +147,7 @@ but unobserved levels are omitted.} \item{inherit.aes}{If \code{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. \code{\link[=borders]{borders()}}.} +the default plot specification, e.g. \code{\link[=annotation_borders]{annotation_borders()}}.} } \description{ \code{stat_summary_2d()} is a 2d variation of \code{\link[=stat_summary]{stat_summary()}}. diff --git a/man/stat_unique.Rd b/man/stat_unique.Rd index 717b49e36c..f42da84f6b 100644 --- a/man/stat_unique.Rd +++ b/man/stat_unique.Rd @@ -104,7 +104,7 @@ but unobserved levels are omitted.} \item{inherit.aes}{If \code{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. \code{\link[=borders]{borders()}}.} +the default plot specification, e.g. \code{\link[=annotation_borders]{annotation_borders()}}.} } \description{ Remove duplicates diff --git a/tests/testthat/_snaps/annotate/annotation-borders-utah.svg b/tests/testthat/_snaps/annotate/annotation-borders-utah.svg new file mode 100644 index 0000000000..4a64ae21b9 --- /dev/null +++ b/tests/testthat/_snaps/annotate/annotation-borders-utah.svg @@ -0,0 +1,60 @@ + + + + + + + + + + + + + + + + + + + + + + + + + +37 +38 +39 +40 +41 +42 + + + + + + + + + + + + +-114 +-113 +-112 +-111 +-110 +-109 +annotation_borders utah + + diff --git a/tests/testthat/test-annotate.R b/tests/testthat/test-annotate.R index a0200a82d3..df8b648831 100644 --- a/tests/testthat/test-annotate.R +++ b/tests/testthat/test-annotate.R @@ -115,3 +115,9 @@ test_that("annotation_custom() and annotation_raster() adhere to scale transform expect_equal(as.numeric(ann$height), 8/10) }) + +test_that("annotation_borders() can create a map", { + skip_if_not_installed("maps") + lifecycle::expect_deprecated(utah <- borders("state", "utah")) + expect_doppelganger("annotation_borders utah", ggplot() + utah) +})