Title: Mapping Data for 'usmap' Package
Version: 0.6.0
Description: Provides a container for data used by the 'usmap' package. The data used by 'usmap' has been extracted into this package so that the file size of the 'usmap' package can be reduced greatly. The data in this package will be updated roughly once per year as new map data files are provided by the US Census Bureau.
Depends: R (≥ 3.5.0)
License: GPL (≥ 3)
Encoding: UTF-8
Language: en-US
URL: https://usmap.dev
BugReports: https://github.com/pdil/usmapdata/issues
Imports: rlang, sf
Suggests: covr, dplyr, spelling, testthat (≥ 3.0.0)
RoxygenNote: 7.3.2
Config/testthat/edition: 3
NeedsCompilation: no
Packaged: 2025-06-14 02:29:26 UTC; paolo
Author: Paolo Di Lorenzo [aut, cre]
Maintainer: Paolo Di Lorenzo <paolo@dilorenzo.org>
Repository: CRAN
Date/Publication: 2025-06-15 02:20:02 UTC

usmapdata: Mapping Data for usmap Package

Description

It is usually difficult or inconvenient to create US maps that include both Alaska and Hawaii in a convenient spot. All map data frames produced by this package use the US National Atlas Equal Area projection.

Map data frames

Alaska and Hawaii 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.

The function provides the ability to retrieve maps with either state borders or county borders using the regions parameter for convenience.

States (or counties) can be included such that all other states (or counties) are excluded using the include parameter.

Author(s)

Paolo Di Lorenzo

References

Rudis B (2014). “Moving The Earth (well, Alaska & Hawaii) With R.” https://rud.is/b/2014/11/16/moving-the-earth-well-alaska-hawaii-with-r/.

See Also

Helpful links:

Years for which US map data is available

Description

Years for which US map data is available

Usage

available_map_years()

Value

A numeric vector of available map data years, sorted in descending order.

Examples

available_map_years()

Retrieve centroid labels

Description

Retrieve centroid labels

Usage

centroid_labels(
  regions = c("states", "state", "counties", "county"),
  as_sf = TRUE,
  data_year = NULL
)

Arguments

regions

The region breakdown for the map, can be one of ("states", "state", "counties", "county"). The default is "states".

as_sf

Defunct, this parameter no longer has any effect and will be removed in the future.

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.

Value

An sf data frame of state or county centroid labels and positions relative to the coordinates returned by the us_map function.

Internal map creation tools

Description

create_us_map() creates the modified shapefiles used by the usmap package.

ea_crs() returns the US National Atlas Equal Area coordinate reference system (CRS) used by this package and usmap.

transform2D() computes a two dimensional affine transformation matrix for the provided rotation angle and scale factor.

transform_alaska() applies the appropriate transform for the Alaska polygons.

transform_hawaii() applies the appropriate transform for the Hawaii polygons.

compute_centroids() computes the modified centroids for each state or county polygon using a center-of-mass technique on the largest polygon in the region.

alaska_bbox() returns the bounding box of Alaska pre-transformation.

hawaii_bbox() returns the bounding box of Hawaii pre-transformation.

Usage

create_us_map(
  type = c("states", "counties"),
  input_file,
  output_dir,
  output_file
)

ea_crs()

transform2D(angle = 0, scale = 1)

transform_alaska(alaska)

transform_hawaii(hawaii)

compute_centroids(polygons, iterations = 3, initial_width_step = 10)

alaska_bbox()

hawaii_bbox()

Note

Using these functions externally is not recommended since they make certain undocumented assumptions that may not work with all inputs.

It is strongly recommend that the usmap package is used directly.

In some cases where the raw data is required, the us_map and centroid_labels functions located in this package can be used instead.

References

Gert (2017). “How to calculate polygon centroids in R (for non-contiguous shapes).” https://gis.stackexchange.com/a/265475.

Rudis B (2014). “Moving The Earth (well, Alaska & Hawaii) With R.” https://rud.is/b/2014/11/16/moving-the-earth-well-alaska-hawaii-with-r/.

Retrieve state and county FIPS codes

Description

Retrieve state and county FIPS codes

Usage

fips_data(
  regions = c("states", "state", "counties", "county"),
  as_sf = TRUE,
  data_year = NULL
)

Arguments

regions

The region breakdown for the map, can be one of ("states", "state", "counties", "county"). The default is "states".

as_sf

Defunct, this parameter no longer has any effect and will be removed in the future.

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.

Value

An data frame of FIPS codes of the desired regions.

Examples

str(fips_data())

state_fips <- fips_data()
county_fips <- fips_data(regions = "counties")

Select appropriate map data year from available years

Description

Select appropriate map data year from available years

Usage

select_map_year(data_year)

Arguments

data_year

The year for which to obtain usmap data. If the value is NULL, the most recent year is returned. If the provided year is not found from the available map data sets, the next most recent available year is returned.

Retrieve US map data

Description

Retrieve US map data

Usage

us_map(
  regions = c("states", "state", "counties", "county"),
  include = c(),
  exclude = c(),
  as_sf = TRUE,
  data_year = NULL
)

Arguments

regions

The region breakdown for the map, can be one of ("states", "state", "counties", "county"). The default is "states".

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.

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 include parameter are applied first and the exclude regions are then removed from the resulting map. Any excluded regions not present in the included regions will be ignored.

as_sf

Defunct, this parameter no longer has any effect and will be removed in the future.

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.

Value

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"))

excl_west_coast <- us_map(exclude = c("CA", "OR", "WA"))

ct_counties_as_of_2022 <- us_map(regions = "counties", include = "CT", data_year = 2022)