Improve documentation

Author: arcresu

NEWS.md

@@ -1,7 +1,5 @@
 # ggmapinset 0.3.0
 
-* Added `transform_to_inset()` helper for applying the inset transformation to
-  arbitrary geometries.
 * Replaced the confusing `inset_clip` and `inset_copy` parameters of
   `geom_sf_inset()` with the new `map_base` and `map_inset` parameters.
 * Inset frame aesthetics can now be specified consistently.
@@ -11,6 +9,8 @@
   coordinate limits and computes some inset-related variables for downstream use.
 * The new `stat_sf_coordinates_inset()`, `stat_sf_text_inset()`, and
   `stat_sf_label_inset()` labels complete the coverage of sf-related layers.
+* Added `transform_to_inset()` helper for applying the inset transformation to
+  arbitrary geometries (for extension developers).
 
 # ggmapinset 0.2.3
 

R/coord_sf_inset.R

@@ -8,6 +8,7 @@
 #' @param inset Inset configuration; see [configure_inset()].
 #' @param ... Arguments passed to [ggplot2::coord_sf()]
 #'
+#' @returns A ggplot coordinate object to be added to a plot.
 #' @seealso [geom_sf_inset()]
 #' @export
 #'

README.Rmd

@@ -38,16 +38,27 @@ install.packages('ggmapinset', repos = c('https://cidm-ph.r-universe.dev', 'http
 
 ## Replacing 'ggplot2' sf layers
 
-`{ggmapinset}` provides replacements for each of the sf-related layers from
-`{ggplot2}` with the suffix `_inset` added to the names.
-For the most part they work the same way as the standard layers, but they can
-understand the inset configuration and make small adjustments accordingly such as
-expanding axes to fit the inset frame or duplicating the layer and transforming it
-to fit into the inset viewport.
+`{ggmapinset}` provides drop-in replacements for each of the `{sf}`-related layers
+from `{ggplot2}`:
+
+| ‘ggplot2’ function      | ‘ggmapinset’ replacement      |
+|:------------------------|:------------------------------|
+| `geom_sf()`             | `geom_sf_inset()`             |
+| `geom_sf_text()`        | `geom_sf_text_inset()`        |
+| `geom_sf_label()`       | `geom_sf_label_inset()`       |
+| `stat_sf()`             | `stat_sf_inset()`             |
+| `stat_sf_coordinates()` | `stat_sf_coordinates_inset()` |
+| `coord_sf()`            | `coord_sf_inset()`            |
+
+The replacements work the same as their normal versions but copy, zoom, and clip
+the layers to make the inset work. The stats can be used to add inset support to
+geoms from third-party packages. For extension developers, tools are provided to
+make `{sf}`-based layers inset-aware (see `{ggautomap}` for examples).
+
 
 ## Example
 
-This example adds an inset to the first example from `ggplot2::geom_sf`.
+This example adds an inset to the first example from `ggplot2::geom_sf()`.
 The inset area is defined as a circle centred on the named county, with radius
 50 miles. The inset is enlarged by a factor of 2 and shifted to an empty part
 of the map.
@@ -56,20 +67,31 @@ of the map.
 library(ggmapinset)
 library(ggplot2)
 
+# load the North Carolina map example shipped with sf
 nc <- sf::st_read(system.file("shape/nc.shp", package = "sf"), quiet = TRUE)
 
-# The basic ggplot example:
-# ggplot(nc) +
-#   geom_sf(aes(fill = AREA)) +
-#   coord_sf()
+# find the centroid of the specified county
+inset_centre <- sf::st_centroid(sf::st_geometry(nc)[nc$NAME == "Yancey"])
 
-# Adding an inset means replacing geom_sf(...) -> geom_sf_inset(...) and
-# coord_sf(...) -> coord_sf_inset(..., inset = configure_inset(...))
+# pick some counties to label
+labelled_counties <- sample(nc$NAME, 10)
+
+# the basic ggplot example:
+base_plot <- ggplot(nc) +
+  geom_sf(aes(fill = AREA)) +
+  geom_sf_label(aes(label = NAME), data = ~dplyr::filter(.x, NAME %in% labelled_counties)) +
+  coord_sf()
+
+# the same plot with an inset zooming in on one area:
 ggplot(nc) +
+  # replace sf layers with their `_inset` versions
   geom_sf_inset(aes(fill = AREA)) +
+  # add the inset frame (the two circles with the connecting lines)
   geom_inset_frame() +
-  geom_sf_label_inset(aes(label = NAME), data = ~dplyr::slice_sample(.x, n = 10)) +
-  coord_sf_inset(inset = configure_inset(
-    centre = sf::st_centroid(sf::st_geometry(nc)[nc$NAME == "Yancey"]),
-    scale = 2, translation = c(70, -180), radius = 50, units = "mi"))
+  geom_sf_label_inset(aes(label = NAME), data = ~dplyr::filter(.x, NAME %in% labelled_counties)) +
+  # configure the inset in the coordinate system so that all layers can see it
+  coord_sf_inset(inset = configure_inset(centre = inset_centre, scale = 2, units = "mi",
+                                         translation = c(70, -180), radius = 50))
 ```
+
+For more information, see the [online documentation](https://cidm-ph.github.io/ggmapinset/) and `vignette("ggmapinset")`.

README.md

@@ -27,40 +27,64 @@ install.packages('ggmapinset', repos = c('https://cidm-ph.r-universe.dev', 'http
 
 ## Replacing ‘ggplot2’ sf layers
 
-`{ggmapinset}` provides replacements for each of the sf-related layers
-from `{ggplot2}` with the suffix `_inset` added to the names. For the
-most part they work the same way as the standard layers, but they can
-understand the inset configuration and make small adjustments
-accordingly such as expanding axes to fit the inset frame or duplicating
-the layer and transforming it to fit into the inset viewport.
+`{ggmapinset}` provides drop-in replacements for each of the
+`{sf}`-related layers from `{ggplot2}`:
+
+| ‘ggplot2’ function      | ‘ggmapinset’ replacement      |
+|:------------------------|:------------------------------|
+| `geom_sf()`             | `geom_sf_inset()`             |
+| `geom_sf_text()`        | `geom_sf_text_inset()`        |
+| `geom_sf_label()`       | `geom_sf_label_inset()`       |
+| `stat_sf()`             | `stat_sf_inset()`             |
+| `stat_sf_coordinates()` | `stat_sf_coordinates_inset()` |
+| `coord_sf()`            | `coord_sf_inset()`            |
+
+The replacements work the same as their normal versions but copy, zoom,
+and clip the layers to make the inset work. The stats can be used to add
+inset support to geoms from third-party packages. For extension
+developers, tools are provided to make `{sf}`-based layers inset-aware
+(see `{ggautomap}` for examples).
 
 ## Example
 
-This example adds an inset to the first example from `ggplot2::geom_sf`.
-The inset area is defined as a circle centred on the named county, with
-radius 50 miles. The inset is enlarged by a factor of 2 and shifted to
-an empty part of the map.
+This example adds an inset to the first example from
+`ggplot2::geom_sf()`. The inset area is defined as a circle centred on
+the named county, with radius 50 miles. The inset is enlarged by a
+factor of 2 and shifted to an empty part of the map.
 
 ``` r
 library(ggmapinset)
 library(ggplot2)
 
+# load the North Carolina map example shipped with sf
 nc <- sf::st_read(system.file("shape/nc.shp", package = "sf"), quiet = TRUE)
 
-# The basic ggplot example:
-# ggplot(nc) +
-#   geom_sf(aes(fill = AREA)) +
-#   coord_sf()
+# find the centroid of the specified county
+inset_centre <- sf::st_centroid(sf::st_geometry(nc)[nc$NAME == "Yancey"])
 
-# Adding an inset means replacing geom_sf(...) -> geom_sf_inset(...) and
-# coord_sf(...) -> coord_sf_inset(..., inset = configure_inset(...))
+# pick some counties to label
+labelled_counties <- sample(nc$NAME, 10)
+
+# the basic ggplot example:
+base_plot <- ggplot(nc) +
+  geom_sf(aes(fill = AREA)) +
+  geom_sf_label(aes(label = NAME), data = ~dplyr::filter(.x, NAME %in% labelled_counties)) +
+  coord_sf()
+
+# the same plot with an inset zooming in on one area:
 ggplot(nc) +
+  # replace sf layers with their `_inset` versions
   geom_sf_inset(aes(fill = AREA)) +
+  # add the inset frame (the two circles with the connecting lines)
   geom_inset_frame() +
-  geom_sf_label_inset(aes(label = NAME), data = ~dplyr::slice_sample(.x, n = 10)) +
-  coord_sf_inset(inset = configure_inset(
-    centre = sf::st_centroid(sf::st_geometry(nc)[nc$NAME == "Yancey"]),
-    scale = 2, translation = c(70, -180), radius = 50, units = "mi"))
+  geom_sf_label_inset(aes(label = NAME), data = ~dplyr::filter(.x, NAME %in% labelled_counties)) +
+  # configure the inset in the coordinate system so that all layers can see it
+  coord_sf_inset(inset = configure_inset(centre = inset_centre, scale = 2, units = "mi",
+                                         translation = c(70, -180), radius = 50))
 ```
 
 <img src="man/figures/README-example-1.png" width="100%" />
+
+For more information, see the [online
+documentation](https://cidm-ph.github.io/ggmapinset/) and
+`vignette("ggmapinset")`.

man/coord_sf_inset.Rd

@@ -64,3 +64,30 @@ ggplot(nc) +
     translation = c(100, -120), radius = 50, units = "mi"))
 ```
 
+## Multiple insets
+For multiple insets, the appropriate inset configuration just needs to be passed to each
+layer separately. It's probably clearer to avoid providing an inset to the coordinate
+system in this case.
+
+Since the inset-aware layers will duplicate themselves for the base and inset maps,
+you will probably want to disable that behaviour with `map_base = "none"` to avoid
+having multiple identical copies of the base map.
+```{r multiple, fig.width=7, fig.height=5}
+inset1 <- configure_inset(
+  centre = sf::st_centroid(sf::st_geometry(nc)[nc$NAME == "Bladen"]), scale = 1.5,
+  translation = c(150, -50), radius = 50, units = "mi")
+inset2 <- configure_inset(
+  centre = sf::st_centroid(sf::st_geometry(nc)[nc$NAME == "Orange"]), scale = 3,
+  translation = c(30, 120), radius = 30, units = "mi")
+
+ggplot(nc) +
+  # base map
+  geom_sf_inset() +
+  # inset 1
+  geom_sf_inset(map_base = "none", inset = inset1) +
+  geom_inset_frame(inset = inset1, colour = "red") +
+  # inset 2
+  geom_sf_inset(map_base = "none", inset = inset2) +
+  geom_inset_frame(inset = inset2, colour = "blue")
+```
+