Update documentation for geom_map()

R/coord-map.r

@@ -1,13 +1,24 @@
 #' Map projections
 #'
+#' @description
+#' `r lifecycle::badge("superseded")`
+#'
 #' `coord_map()` projects a portion of the earth, which is approximately
 #' spherical, onto a flat 2D plane using any projection defined by the
 #' `mapproj` package. Map projections do not, in general, preserve straight
 #' lines, so this requires considerable computation. `coord_quickmap()` is a
 #' quick approximation that does preserve straight lines. It works best for
 #' smaller areas closer to the equator.
 #'
-#' In general, map projections must account for the fact that the actual length
+#' Both `coord_map()` and `coord_quickmap()`
+#' are superseded by [`coord_sf()`], and should no longer be used in new
+#' code. All regular (non-sf) geoms can be used with `coord_sf()` by
+#' setting the default coordinate system via the `default_crs` argument.
+#' See also the examples for [`annotation_map()`] and [`geom_map()`].
+#'
+#' @details
+#'
+#' Map projections must account for the fact that the actual length
 #' (in km) of one degree of longitude varies between the equator and the pole.
 #' Near the equator, the ratio between the lengths of one degree of latitude and
 #' one degree of longitude is approximately 1. Near the pole, it tends

R/geom-map.r

@@ -3,7 +3,11 @@ NULL
 
 #' Polygons from a reference map
 #'
-#' This is pure annotation, so does not affect position scales.
+#' Display polygons as a map. This is meant as annotation, so it does not
+#' affect position scales. Note that this function predates the [`geom_sf()`]
+#' framework and does not work with sf geometry columns as input. However,
+#' it can be used in conjunction with `geom_sf()` layers and/or
+#' [`coord_sf()`] (see examples).
 #'
 #' @eval rd_aesthetics("geom", "map")
 #' @export
@@ -14,10 +18,12 @@ NULL
 #' @inheritParams layer
 #' @inheritParams geom_point
 #' @examples
-#' # When using geom_polygon, you will typically need two data frames:
-#' # one contains the coordinates of each polygon (positions),  and the
-#' # other the values associated with each polygon (values).  An id
-#' # variable links the two together
+#' # First, a made-up example containing a few polygons, to explain
+#' # how `geom_map()` works. It requires two data frames:
+#' # One contains the coordinates of each polygon (`positions`), and is
+#' # provided via the `map` argument. The other contains the
+#' # other the values associated with each polygon (`values`).  An id
+#' # variable links the two together.
 #'
 #' ids <- factor(c("1.1", "2.1", "1.2", "2.2", "1.3", "2.3"))
 #'
@@ -44,7 +50,7 @@ NULL
 #'   geom_map(aes(map_id = id), map = positions) +
 #'   expand_limits(positions) + ylim(0, 3)
 #'
-#' # Better example
+#' # Now some examples with real maps
 #' if (require(maps)) {
 #'
 #'   crimes <- data.frame(state = tolower(rownames(USArrests)), USArrests)
@@ -56,15 +62,32 @@ NULL
 #'   crimes_long <- do.call("rbind", vars)
 #'
 #'   states_map <- map_data("state")
+#'
+#'   # without geospatial coordinate system, the resulting plot
+#'   # looks weird
 #'   ggplot(crimes, aes(map_id = state)) +
 #'     geom_map(aes(fill = Murder), map = states_map) +
 #'     expand_limits(x = states_map$long, y = states_map$lat)
 #'
-#'   last_plot() + coord_map()
-#'   ggplot(crimes_long, aes(map_id = state)) +
-#'     geom_map(aes(fill = value), map = states_map) +
-#'     expand_limits(x = states_map$long, y = states_map$lat) +
-#'     facet_wrap( ~ variable)
+#'   # in combination with `coord_sf()` we get an appropriate result
+#'   ggplot(crimes, aes(map_id = state)) +
+#'     geom_map(aes(fill = Murder), map = states_map) +
+#'     # crs = 5070 is a Conus Albers projection for North America,
+#'     #   see: https://epsg.io/5070
+#'     # default_crs = 4326 tells coord_sf() that the input map data
+#'     #   are in longitude-latitude format
+#'     coord_sf(
+#'       crs = 5070, default_crs = 4326,
+#'       xlim = c(-125, -70), ylim = c(25, 52)
+#'     )
+#'
+#'  ggplot(crimes_long, aes(map_id = state)) +
+#'    geom_map(aes(fill = value), map = states_map) +
+#'    coord_sf(
+#'      crs = 5070, default_crs = 4326,
+#'      xlim = c(-125, -70), ylim = c(25, 52)
+#'    ) +
+#'    facet_wrap(~variable)
 #' }
 geom_map <- function(mapping = NULL, data = NULL,
                      stat = "identity",