RcensusPkg (version 0.1.5)

tiger_states_sf: tiger_states_sf

Description

This function performs three tasks:

1. Download to an output directory a zip file from the TIGER/Line Shapefiles database.

2. Unzip the zip file and locate the shape file of interest.

3. Read and convert the shape file to a simple feature object.

Usage

tiger_states_sf(
  output_dir = tempdir(),
  delete_files = TRUE,
  vintage = 2020,
  general = FALSE,
  resol = "500k",
  set_crs = NULL,
  transform_crs = NULL,
  sf_info = FALSE,
  do_progress = FALSE,
  shapefile = NULL,
  datafile = NULL,
  datafile_key = NULL,
  sf_key = "GEOID",
  express = NULL,
  check_na = FALSE
)

Value

A data frame object of class sf (simple feature)

Arguments

output_dir

A full directory path where the shapefile and its associated files will be downloaded. The default is the directory defined by the value returned by tempdir().

delete_files

A logical which if TRUE will delete the shapefile and associated files in 'output_dir'. The default is TRUE.

vintage

A numeric that sets the vintage of interest. The default is 2020.

general

A logical which if TRUE will download a less detailed, more generalized version of the state geometries.

resol

If general is TRUE, then the resolution to return. Acceptable values are strings "500k", "5m", "20m".

set_crs

A numeric or character string which if non-NULL calls sf::st_crs() to set the crs of the geometries and transforms them.

transform_crs

A numeric or character string which if non-NULL calls sf::st_transform() to perform a crs transform of the geometries. Note that the crs of the shapefile must not be NA.

sf_info

A logical which if TRUE displays info on the resulting simple feature object.

do_progress

A logical which if TRUE displays a progress bar during the download.

shapefile

A full file path to a shapefile folder with its unzipped files to be processed instead of downloading.

datafile

A dataframe containing data that should be joined with this function's resultant simple feature object.

datafile_key

The column name from 'datafile' dataframe used to key with the 'sf_key' column of the resultant simple feature dataframe.

sf_key

The column from the resultant sf dataframe used to key with the 'datafile' dataframe.

express

A logical expression object used to filter the resultant simple feature dataframe. For example, one of the columns of the resultant simple feature dataframe is "STATEFP". If you wanted to return just the geometries for Florida (which has a fips code of "12"), then you assign 'express' equal to: expression(STATEFP == "12"). The expression will be evaluated and only the geometries for Florida will be returned.

check_na

A logical which if TRUE will remove rows that have missing values for any of the columns. The default is to not check the columns for NA values.

Details

Returns simple feature (sf) of state boundary related geometric polygons, provided by the US Census Bureau's TIGER/Line Shapefiles database. See Simple Features for R for more information on simple features. Along with the geometries, additional state related variables are provided. See Appendix P-5. Record Layout: State and Equivalent Entity National Shapefile) for a description of state related variables of the sf file. For further information on the Census Bureau's shape files see About the 2021 TIGER/Line Shapefiles. From Chapter 4.17 States and State Equivalent Entities -- "States and equivalent entities are the primary governmental divisions of the United States. In addition to the fifty states, the Census Bureau treats the District of Columbia, Puerto Rico, and the Island Areas (American Samoa, the Commonwealth of the Northern Mariana Islands, Guam, and the U.S. Virgin Islands) as statistical equivalents of states for the purpose of data presentation."

A more generalized, recognizable version of the state geometries that has less download size is also available. For more information on cartographic boundary files see Cartographic Boundary File Description. These files are available for vintages greater than 2013 with resolution 1:500k, 1:5m, 1:20m meters.

The function returns the simple feature object which can easily be mapped (see RplotterPkg::create_sf_plot()) or joined with US Census Bureau demographic data. To help incorporate data files, this function has a 'datafile' parameter which will be joined with the resultant simple feature object. The only requirement is that a common "key" for joining exist between the data dataframe and the simple feature dataframe.

Some earlier vintages may have NA for the crs so you may need to specify the 'crs_transform' to 3426. Also you may be interested in using a state level crs. See epsg.io to search worldwide for crs.

Examples

library(usmap)
library(sf)
library(data.table)
library(downloader)
library(withr)
library(RcensusPkg)

# Get the fips code for Florida
florida_fips <- usmap::fips(state = "florida")
#
# Define an expression that will filter out Florida from
#   the simple feature obtained from the downloaded/converted
#   tiger states shapefile.
express <- parse(text = paste0("STATEFP == ", '"', florida_fips, '"'))
#
# Define a temporary output folder for the downloaded shapefiles
output_dir <- withr::local_tempdir()
if(!dir.exists(output_dir)){
  dir.create(output_dir)
}

# Download, convert, and filter the states shapefile for Florida
#   using the expression.
florida_general_sf <- RcensusPkg::tiger_states_sf(
  general = TRUE,
  express = express,
  output_dir = output_dir,
  delete_files = FALSE
)