pdil/usmapdata

🗺 Data repository for the usmap R package

🗺 usmapdata

You might be looking for the usmap package: CRAN | GitHub | Website

Purpose

usmapdata is a container package for the map data frame used in the usmap package. This data has been extracted to keep usmap small and easier to maintain, while allowing the ability to keep the US map data frame updated as often as possible (independently of usmap updates).

This package and repository will only contain functions and data relevant to the actual map and FIPS data used to draw the map in the usmap package. All other functions, including FIPS and mapping convenience functions, will be contained in the usmap repository.

Map Data

The map data files that we use to plot the maps in R are located in the inst/extdata folder. They are generated from shapefiles published by the US Census Bureau. Data files for maps and FIPS codes at both the state and county levels are included.

The Cartographic Boundary Files are used for mapping in usmap—specifically the 1:20m scale files. This low resolution allows for small file sizes while still allowing enough detail for simple choropleths. The file description can be read here.

Shapefiles are updated yearly by the US Census Bureau. This repository contains scripts which periodically check for new shapefiles and update the data in the package accordingly. For more details see the data-raw directory.

Installation

This package should only be installed if you intend to manipulate the US mapping data frame, which contains coordinates to draw the US state and county boundaries. If you're interested in plotting data on a US map, use the usmap package.

📦 To install from CRAN (recommended), run the following code in an R console:

install.packages("usmapdata")

Developer Build

⚠️ The developer build may be unstable and not function correctly, use with caution.

To install the package from this repository, run the following code in an R console:

# install.package("devtools")
devtools::install_github("pdil/usmapdata")

This method will provide the most recent developer build of usmapdata.

Usage

To begin using usmapdata, import the package using the library command:

library(usmapdata)

Additional Information

Coordinate System

usmap uses the US National Atlas Equal Area coordinate system:

sf::st_crs(9311)

```r
#> Coordinate Reference System:
#>   User input: EPSG:9311
#>   wkt:
#> PROJCRS["NAD27 / US National Atlas Equal Area",
#>     BASEGEOGCRS["NAD27",
#>         DATUM["North American Datum 1927",
#>             ELLIPSOID["Clarke 1866",6378206.4,294.978698213898,
#>                 LENGTHUNIT["metre",1]]],
#>         PRIMEM["Greenwich",0,
#>             ANGLEUNIT["degree",0.0174532925199433]],
#>         ID["EPSG",4267]],
#>     CONVERSION["US National Atlas Equal Area",
#>         METHOD["Lambert Azimuthal Equal Area (Spherical)",
#>             ID["EPSG",1027]],
#>         PARAMETER["Latitude of natural origin",45,
#>             ANGLEUNIT["degree",0.0174532925199433],
#>             ID["EPSG",8801]],
#>         PARAMETER["Longitude of natural origin",-100,
#>             ANGLEUNIT["degree",0.0174532925199433],
#>             ID["EPSG",8802]],
#>         PARAMETER["False easting",0,
#>             LENGTHUNIT["metre",1],
#>             ID["EPSG",8806]],
#>         PARAMETER["False northing",0,
#>             LENGTHUNIT["metre",1],
#>             ID["EPSG",8807]]],
#>     CS[Cartesian,2],
#>         AXIS["easting (X)",east,
#>             ORDER[1],
#>             LENGTHUNIT["metre",1]],
#>         AXIS["northing (Y)",north,
#>             ORDER[2],
#>             LENGTHUNIT["metre",1]],
#>     USAGE[
#>         SCOPE["Statistical analysis."],
#>         AREA["United States (USA) - onshore and offshore."],
#>         BBOX[15.56,167.65,74.71,-65.69]],
#>     ID["EPSG",9311]]
```

This coordinate reference system (CRS) can also be obtained with usmap::usmap_crs().

Acknowledgments

The code used to generate the map files was based on this blog post by Bob Rudis: Moving The Earth (well, Alaska & Hawaii) With R

usmapdata's Issues

Automated shapefile updates

Currently the process of updating shapefiles is only semi-automated. While there are scripts in the data-raw folder that will convert US Census Bureau shapefiles into data frames readable by usmapdata, it is still a process that requires manual checking of the census website and downloading the appropriate files.

In order to provide for more timely updates to shapefiles as new ones are released, it would be beneficial to create (or attempt to create) a fully automated process that can check the relevant website(s), download the files, and create the csv data files automatically.

GitHub Actions workflows can be used to facilitate this:

1. Scheduled monthly task to check US Census Bureau website for shapefile updates*
2. If update exists, download required files*
3. Process files and convert them to .csv files that are readable by usmapdata
4. Open a pull request with the changes and new files (possibly send a notification using Pushover)
5. Project maintainer(s) review the changes and ensure everything is correct, works, and tests pass
6. Changes are made manually to resolve any issues and then the pull request is merged

*Monitoring and download can be done with either shell, python, or R scripts - whichever is more ergonomic for the given task

Update `actions/setup-python` version in `update-map-data` workflow

The update-map-data workflow is currently using actions/setup-python@v4. This should be updated to @v5 to resolve this warning:

Node.js 16 actions are deprecated. Please update the following actions to use Node.js 20: actions/setup-python@v4. For more information see: https://github.blog/changelog/2023-09-22-github-actions-transitioning-from-node-16-to-node-20/.

Fix documentation in us_map function

Function and documentation were copied over straight from usmap package so some references are either broken or don't make sense

Remove the word "shapefiles" from `DESCRIPTION`

Replace with "map data files" as this is more general in case the underlying files change from shapefiles in the future (also it sometimes triggers a spelling error in R CMD check).

As part of this, check instances of this word in the documentation to see if "map data files" is more applicable or if "shapefiles" really is the best word to use.

Add `centroid_labels` parameter documentation

Builds are failing due to the lack of documentation for the regions parameter of centroid_labels:

Warning:   Undocumented arguments in documentation object 'centroid_labels'
Execution halted
    ‘regions’
  
  Functions with \usage entries need to have the appropriate \alias
  entries, and all their arguments documented.
  The \usage entries must correspond to syntactically valid R code.
  See chapter ‘Writing R documentation files’ in the ‘Writing R
  Extensions’ manual.

Update workflow actions to resolve deprecation warnings

The following workflows and actions are affected:

• lintr
  • actions/checkout@v3 ➡️ @v4
  • github/codeql-action/upload-sarif@v2 ➡️ @v3 (CodeQL deprecation)
• R-cmd-check
  • actions/checkout@v3 ➡️ @v4
• test-coverage
  • actions/checkout@v3 ➡️ @v4

actions/checkout@v3 is due to the Node.js 16 deprecation

See also related change: #23