🗺 usmapdata

Build Status codecov

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 data frame 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.

Shape Files

The shape files that we use to plot the maps in R are located in the data-raw folder. For more information refer to the US Census Bureau. Maps at both the state and county levels are included for convenience (zip code maps may be included in the future).

Updating Shape Files

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.

Follow these steps to update the files used within the project (click to expand)
  1. Go to https://www.census.gov/geographies/mapping-files/time-series/geo/cartographic-boundary.html and select the most recent year available.
  2. In the Cartographic Boundary Files by Geography section, download the following files to the data-raw folder:
  3. Refer to the county changes documentation and make any relevant updates to county-fips.csv
  4. Delete the folders from older years (e.g. cb_2017_us_county_20m)
  5. Run create-map-df.R
  6. Run format-map-df.R
  7. Copy the following files to inst/extdata:
After applying these changes, open a pull request and await review.

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

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

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

Installing using devtools::install_github will provide the most recent developer build of usmapdata.

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

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

library(usmapdata)

Additional Information

Projection

usmap uses an Albers equal-area conic projection, with arguments as follows:

usmap::usmap_crs()

    #> Coordinate Reference System:
    #> Deprecated Proj.4 representation:
    #>  +proj=laea +lat_0=45 +lon_0=-100 +x_0=0 +y_0=0 +ellps=sphere
    #> +units=m +no_defs 
    #> WKT2 2019 representation:
    #> PROJCRS["unknown",
    #>     BASEGEOGCRS["unknown",
    #>         DATUM["unknown",
    #>             ELLIPSOID["Normal Sphere (r=6370997)",6370997,0,
    #>                 LENGTHUNIT["metre",1,
    #>                     ID["EPSG",9001]]]],
    #>         PRIMEM["Greenwich",0,
    #>             ANGLEUNIT["degree",0.0174532925199433],
    #>             ID["EPSG",8901]]],
    #>     CONVERSION["unknown",
    #>         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["(E)",east,
    #>             ORDER[1],
    #>             LENGTHUNIT["metre",1,
    #>                 ID["EPSG",9001]]],
    #>         AXIS["(N)",north,
    #>             ORDER[2],
    #>             LENGTHUNIT["metre",1,
    #>                 ID["EPSG",9001]]]] 
    ```
</details>

This is the same projection used by the [US National Atlas](https://epsg.io/2163).

To obtain the projection used by `usmap`, use `usmap_crs()`.

Alternatively, the CRS ([coordinate reference system](https://www.nceas.ucsb.edu/sites/default/files/2020-04/OverviewCoordinateReferenceSystems.pdf)) can be created manually with the following command:
```r
sp::CRS(paste("+proj=laea +lat_0=45 +lon_0=-100 +x_0=0 +y_0=0",
              "+a=6370997 +b=6370997 +units=m +no_defs"))

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