Add Puerto Rico support (#118)

* Add support for Puerto Rico based on `usmapdata 1.0.0`

closes #20

Author: pdil

.github/workflows/check.yaml

@@ -1,4 +1,3 @@
-
 name: check
 
 on:

.github/workflows/lint.yaml

@@ -1,4 +1,3 @@
-
 name: lint
 
 on:

.github/workflows/release.yaml

@@ -1,4 +1,3 @@
-
 name: release
 run-name: Release ${{ github.event.repository.name }} ${{ inputs.version }}
 

.github/workflows/test-coverage.yaml

@@ -1,4 +1,3 @@
-
 name: test-coverage
 
 on:

DESCRIPTION

@@ -16,7 +16,7 @@ URL: https://usmap.dev
 BugReports: https://github.com/pdil/usmap/issues
 Imports:
     rlang,
-    usmapdata (>= 0.6.0)
+    usmapdata (>= 1.0.0)
 Suggests:
     covr,
     ggplot2 (>= 3.5.0),
@@ -28,7 +28,8 @@ Suggests:
     sf,
     spelling,
     testthat (>= 3.0.0),
-    vdiffr
+    vdiffr,
+    withr
 RoxygenNote: 7.3.2
 Roxygen: list(markdown = TRUE)
 VignetteBuilder: knitr

NEWS.md

@@ -1,5 +1,20 @@
 # [unreleased]
 
+Introducing `usmap 1.0.0`! This week we celebrated 10 years since the [first commit](https://github.com/pdil/usmap/commit/1d6a950d54c8195507406d7042093041381b605c) to this project. It has been quite a ride and `usmap` has grown greatly over the years. To everyone who has supported the project in any way, either by reporting issues, contributing code, or just using the package in your work, thank you so much.
+
+I'm happy to announce that with this version we have finally added Puerto Rico! This addition has been [years](https://github.com/pdil/usmap/issues/20) in the making and its now available throughout `usmap`.
+
+### New Features
+* Add Puerto Rico support to all `usmap` functions (where relevant), see [Issue #20](https://github.com/pdil/usmap/issues/20).
+  * All included map years have been retroactively updated to include Puerto Rico, so any valid value of `data_year` will include Puerto Rico if desired.
+  * Functions now return Puerto Rico in their data sets and it can be included or excluded just like any state (using FIPS, full name, abbreviation, etc.).
+  * Puerto Rican municipalities will be shown when using `"county"` map variants.
+  * By default, Puerto Rico is not shown when using `plot_usmap()` unless it is specifically included with the `include` parameter. This default behavior can be changed by setting the environment variable `USMAP_DEFAULT_EXCLUDE_PR = FALSE`. Setting this parameter will include Puerto Rico by default when calling `plot_usmap()` unless specifically excluded with the `exclude` parameter.
+  * Special thanks [@dcaud](https://github.com/dcaud) who started this work [years ago](https://github.com/pdil/usmap/pull/34).
+
+### Improvements
+* Improve documentation and vignettes.
+
 # usmap 0.8.0
 Released Wednesday, May 28, 2025.
 
@@ -19,6 +34,11 @@ Released Wednesday, May 28, 2025.
 ### Improvements
 * Update package author email.
 
+### Removed
+* The `as_sf` parameter has been completely removed from `usmapdata`.
+  * Its usage was already removed from `usmap` but its removal is noted here as a final notice.
+  * Any existing code that sets it can safely delete it from `usmapdata` function calls.
+
 # usmap 0.7.1
 Released Thursday, March 21, 2024.
 

R/fips.R

@@ -19,7 +19,7 @@
 #'  the available map data sets, the next most recent year's data is used.
 #'  The default is NULL, i.e. the most recent available year is used.
 #'
-#' @note A \code{state} must be included when searching for \code{county},
+#' @note A `state` must be included when searching for `county`,
 #'  otherwise multiple results may be returned for duplicate county names.
 #'
 #' @details State and county FIPS (Federal Information Processing Standards) are
@@ -30,7 +30,7 @@
 #'   information for the 50 US states (and their associated counties and
 #'   census designated areas).
 #'
-#' @return The FIPS code(s) of given \code{state} or \code{county}.
+#' @return The FIPS code(s) of given `state` or `county`.
 #'
 #' If only states are entered, a vector of length equal to the number of states
 #' is returned. If any states are not found or are invalid, `NA` is returned in their place.

R/join-data.R

@@ -5,17 +5,17 @@
 #'   parameter should be a data frame consisting of two columns,
 #'   a fips code (2 characters for state, 5 characters for county)
 #'   and the value that should be associated with that region. The
-#'   columns of \code{data} \emph{must} be \code{fips} or \code{state} and
-#'   the value of the `values` parameter. If both \code{fips} and \code{state}
-#'   are provided, this function uses the \code{fips}.
+#'   columns of `data` _must_ be `fips` or `state` and
+#'   the value of the `values` parameter. If both `fips` and `state`
+#'   are provided, this function uses the `fips`.
 #' @param values The name of the column that contains the values to be associated
-#'   with a given region. The default is \code{"values"}.
+#'   with a given region. The default is `"values"`.
 #' @param na The value to be inserted for states or counties that don't have
-#'   a value in \code{data}. This value must be of the same type as the \code{value}
-#'   column of \code{data}.
+#'   a value in `data`. This value must be of the same type as the `value`
+#'   column of `data`.
 #'
 #' @return A data frame composed of the map data frame (from [us_map()]) except
-#'   an extra column containing the values in \code{data} is included.
+#'   an extra column containing the values in `data` is included.
 #'
 #'   The result can be plotted using [ggplot2::ggplot()] or [plot_usmap()].
 #'
@@ -69,7 +69,12 @@ map_with_data <- function(
   data$fips <- as.character(data$fips)
 
   region_type <- ifelse(nchar(data$fips[1]) <= 2, "state", "county")
-  map_df <- usmap::us_map(regions = region_type, include = include, exclude = exclude, data_year = data_year)
+  map_df <- usmap::us_map(
+    regions = region_type,
+    include = include,
+    exclude = exclude,
+    data_year = data_year
+  )
 
   # Remove columns in data that are already in map_df
   data$abbr <- NULL

R/plot-map.R

@@ -5,31 +5,36 @@
 #'   parameter should be a data frame consisting of two columns,
 #'   a FIPS code (2 characters for state, 5 characters for county)
 #'   and the value that should be associated with that region. The
-#'   columns of \code{data} \emph{must} be \code{fips} or \code{state} and
+#'   columns of `data` _must_ be `fips` or `state` and
 #'   the value of the `values` parameter.
 #' @param values The name of the column that contains the values to be associated
-#'   with a given region. The default is \code{"value"}.
+#'   with a given region. The default is `"value"`.
 #' @param theme The theme that should be used for plotting the map. The default
-#'   is \code{theme_map} from \href{https://github.com/jrnold/ggthemes}{ggthemes}.
+#'   is `theme_map` from [ggthemes](https://github.com/jrnold/ggthemes).
 #' @param labels Whether or not to display labels on the map. Labels are not displayed
 #'   by default.
-#' @param label_color The color of the labels to display. Corresponds to the \code{color}
-#'   option in the [ggplot2::aes()] mapping. The default is \code{"black"}.
-#'   \href{https://usmap.dev/docs/Rcolor.pdf}{Click here}
+#' @param label_color The color of the labels to display. Corresponds to the `color`
+#'   option in the [ggplot2::aes()] mapping. The default is `"black"`.
+#'   [Click here](https://usmap.dev/docs/Rcolor.pdf)
 #'   for more color options.
 #' @param ... Other arguments to pass to [ggplot2::aes()]. These are
-#'   often aesthetics, used to set an aesthetic to a fixed value, like \code{color = "red"}
-#'   or \code{linewidth = 3}. They affect the appearance of the polygons used to render
+#'   often aesthetics, used to set an aesthetic to a fixed value, like `color = "red"`
+#'   or `linewidth = 3`. They affect the appearance of the polygons used to render
 #'   the map (for example fill color, line color, line thickness, etc.). If any of
-#'   \code{color}/\code{colour}, \code{fill}, or \code{linewidth} are not specified they
-#'   are set to their default values of \code{color="black"}, \code{fill="white"},
-#'   and \code{linewidth=0.4}.
+#'   `color`/`colour`, `fill`, or `linewidth` are not specified they
+#'   are set to their default values of `color="black"`, `fill="white"`,
+#'   and `linewidth=0.4`.
 #'
 #' @return A [ggplot2::ggplot] object that contains a basic
-#'   US map with the described parameters. Since the result is a \code{ggplot}
+#'   US map with the described parameters. Since the result is a `ggplot`
 #'   object, it can be extended with more [ggplot2::Geom] layers, scales, labels,
 #'   themes, etc.
 #'
+#' @details
+#' By default, Puerto Rico is not plotted unless it is specifically included
+#' via `include = c("PR")` etc. The default behavior can be changed by setting
+#' the environment variable `USMAP_DEFAULT_EXCLUDE_PR = FALSE`.
+#'
 #' @seealso [usmap], [ggplot2::theme()]
 #'
 #' @examples
@@ -75,6 +80,12 @@ plot_usmap <- function(
 
   .data <- ggplot2::.data
 
+  # exclude PR by default if env variable is not `FALSE`
+  if (Sys.getenv("USMAP_DEFAULT_EXCLUDE_PR", unset = TRUE) == TRUE &&
+        !("PR" %in% include || "72" %in% include)) {
+    exclude <- unique(c(exclude, "PR", "72"))
+  }
+
   # parse parameters
   regions <- match.arg(regions)
   geom_args <- list(...)
@@ -113,14 +124,10 @@ plot_usmap <- function(
 
     centroid_labels <- usmapdata::centroid_labels(regions, data_year = data_year)
 
-    if (length(include) > 0) {
-      centroid_labels <- centroid_labels[
-        centroid_labels$full %in% include |
-          centroid_labels$abbr %in% include |
-          centroid_labels$fips %in% include,
-      ]
-    }
+    # remove excluded items that are in `include`
+    exclude <- setdiff(exclude, include)
 
+    # remove excludes
     if (length(exclude) > 0) {
       centroid_labels <- centroid_labels[!(
         centroid_labels$full %in% exclude |
@@ -130,6 +137,15 @@ plot_usmap <- function(
       ), ]
     }
 
+    # remove non-includes
+    if (length(include) > 0) {
+      centroid_labels <- centroid_labels[
+        centroid_labels$full %in% include |
+          centroid_labels$abbr %in% include |
+          centroid_labels$fips %in% include,
+      ]
+    }
+
     if (regions == "county" || regions == "counties") {
       label_layer <- ggplot2::geom_sf_text(
         data = centroid_labels,

R/transform.R

@@ -129,14 +129,22 @@ perform_transform <- function(data, ...) {
   hawaii <- sf::st_intersection(transformed, hi_bbox)
   hawaii <- usmapdata:::transform_hawaii(hawaii)
 
+  # Transform Hawaii points
+  pr_bbox <- usmapdata:::puerto_rico_bbox()
+  puerto_rico <- sf::st_intersection(transformed, pr_bbox)
+  puerto_rico <- usmapdata:::transform_puerto_rico(puerto_rico)
+
   # Re-combine all points
   transformed_excl_ak <- sf::st_difference(transformed, ak_bbox)
   sf::st_agr(transformed_excl_ak) <- "constant"
 
   transformed_excl_ak_hi <- sf::st_difference(transformed_excl_ak, hi_bbox)
   sf::st_agr(transformed_excl_ak_hi) <- "constant"
 
-  rbind(transformed_excl_ak_hi, alaska, hawaii)
+  transformed_excl_ak_hi_pr <- sf::st_difference(transformed_excl_ak_hi, pr_bbox)
+  sf::st_agr(transformed_excl_ak_hi_pr) <- "constant"
+
+  rbind(transformed_excl_ak_hi_pr, alaska, hawaii, puerto_rico)
 }
 
 #' usmap coordinate reference system