Add Puerto Rico support

.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

R/us-map.R

@@ -1,38 +1,40 @@
 #' Retrieve US map data
 #'
 #' @param regions The region breakdown for the map, can be one of
-#'   (\code{"states"}, \code{"state"}, \code{"counties"}, \code{"county"}).
-#'   The default is \code{"states"}.
-#' @param include The regions to include in the resulting map. If \code{regions} is
-#'  \code{"states"}/\code{"state"}, the value can be either a state name, abbreviation or FIPS code.
+#'   (`"states"`, `"state"`, `"counties"`, `"county"`).
+#'   The default is `"states"`.
+#' @param include The regions to include in the resulting map. If `regions` is
+#'  `"states"`/`"state"`, the value can be either a state name, abbreviation or FIPS code.
 #'  For counties, the FIPS must be provided as there can be multiple counties with the
 #'  same name. If states are provided in the county map, only counties in the included states
 #'  will be returned.
-#' @param exclude The regions to exclude in the resulting map. If \code{regions} is
-#'  \code{"states"}/\code{"state"}, the value can be either a state name, abbreviation or FIPS code.
+#' @param exclude The regions to exclude in the resulting map. If `regions` is
+#'  `"states"`/`"state"`, the value can be either a state name, abbreviation or FIPS code.
 #'  For counties, the FIPS must be provided as there can be multiple counties with the
-#'  same name. The regions listed in the \code{include} parameter are applied first and the
-#'  \code{exclude} regions are then removed from the resulting map. Any excluded regions
-#'  not present in the included regions will be ignored.
-#' @param data_year The year for which to obtain map data. If the value is NULL,
-#'  the most recent year's data is used. If the provided year is not found from
-#'  the available map data sets, the next most recent year's data is used.
-#'  This can be used if an older data set is being plotted on the US map so that
-#'  the data matches the map more accurately. Therefore, the provided value should
-#'  match the year of the plotted data set. The default is NULL, i.e. the most
-#'  recent available year is used.
+#'  same name. The regions listed in the `include` parameter take precedence over
+#'  regions listed in `exclude`. If both parameters include the same region(s) they
+#'  will be included in the map.
+#' @param data_year The year for which to obtain map data.
+#'  If the value is `NULL`, the most recent year's data is used. If the
+#'  provided year is not found from the available map data sets, the next most
+#'  recent year's data is used. This can be used if an older data set is being
+#'  plotted on the US map so that the data matches the map more accurately.
+#'  Therefore, the provided value should match the year of the plotted data set.
+#'  The default is `NULL`, i.e. the most recent available year is used.
 #'
 #' @seealso [usmapdata::us_map()] of which this function is a wrapper for.
 #'
-#' @return A data frame of US map coordinates divided by the desired \code{regions}.
+#' @return An `sf` data frame of US map coordinates divided by the desired `regions`.
 #'
 #' @examples
 #' str(us_map())
 #'
 #' df <- us_map(regions = "counties")
 #' west_coast <- us_map(include = c("CA", "OR", "WA"))
 #'
-#' south_atl_excl_FL <- us_map(include = .south_atlantic, exclude = "FL")
+#' excl_west_coast <- us_map(exclude = c("CA", "OR", "WA"))
+#'
+#' ct_counties_as_of_2022 <- us_map(regions = "counties", include = "CT", data_year = 2022)
 #' @export
 us_map <- function(
   regions = c("states", "state", "counties", "county"),

R/usmap-package.R

@@ -2,12 +2,12 @@
 #'
 #' @description
 #' It is usually difficult or inconvenient to create US maps that
-#'   include both Alaska and Hawaii in a convenient spot. All map
-#'   data presented in this package uses the US National Atlas Equal Area
+#'   include Alaska, Hawaii, and even Puerto Rico in a convenient spot. All map
+#'   data frames produced by this package use the US National Atlas Equal Area
 #'   projection.
 #'
 #' @section Map data:
-#' Alaska and Hawaii have been manually moved to a new location so that
+#' Alaska, Hawaii, and Puerto Rico have been manually moved to a new location so that
 #' their new coordinates place them to the bottom-left corner of
 #' the map. These maps can be accessed by using the [us_map()] function.
 #'
@@ -31,7 +31,7 @@
 #' @section Plot US map data:
 #' A convenience function [plot_usmap()] has been included which
 #' takes similar parameters to [us_map()] and returns a [ggplot2::ggplot2]
-#' object. Since the output is a \code{ggplot} object, other layers can be
+#' object. Since the output is a `ggplot` object, other layers can be
 #' added such as scales, themes, and labels. Including data in the function call
 #' will color the map according to the values in the data, creating a choropleth.
 #'

README.Rmd

@@ -34,7 +34,7 @@ citypop_t <- usmap_transform(citypop)
 citypop_t_west <- citypop_t[(citypop_t$abbr %in% .west_region) & (citypop_t$abbr != "AK") & (citypop_t$abbr != "HI"), ]
 
 west_county_citypop_map <-
-  plot_usmap("counties", include = .west_region, exclude = c("AK", "HI"), color = "blue", fill = "lightblue") +
+  plot_usmap("counties", include = setdiff(.west_region, c("AK", "HI")), color = "blue", fill = "lightblue") +
   geom_sf(data = citypop_t_west, aes(size = city_pop), color = "red", alpha = 0.7) +
   scale_size_continuous(range = c(2, 15), guide = "none") +
   ggrepel::geom_label_repel(