Download ACS estimates for the census tracts of one state

Downloads American Community Survey (ACS) 5-year estimates for the census tracts of one state, with the tract boundaries, using tidycensus::get_acs(). Each estimate comes with the margin of error published with it, the half-width of its 90 percent confidence interval. The function removes water tracts unless drop_water_tracts = FALSE, and it returns negative margins of error as NA whatever the other arguments are (see the "Water tracts" and "Missing estimates and margins of error" sections). Unless the cache is turned off, the result is also saved in the cache folder and reused by later calls with the same request (see the "Cache behavior" section).

Usage

cacs_acs_prefetch(
  state,
  year = 2023L,
  variables = NULL,
  survey = "acs5",
  geography = "tract",
  cache_dir = NULL,
  write_gpkg = FALSE,
  force_refresh = FALSE,
  drop_water_tracts = TRUE,
  verbose = TRUE
)

Arguments

state: A string giving one state, the District of Columbia, or Puerto Rico, as a two-letter USPS abbreviation (such as "AL") or a two-digit FIPS code (such as "01"). A vector of states, or a lowercase code such as "al", gives an error.
year: A single whole number giving the last year of the ACS 5-year estimates, from 2009 to 2024; the default is 2023 (the 2019-2023 estimates).
variables: A character vector of ACS variable codes, or NULL (the default) for cacs_acs_default_vars. Each code must have the form of "B19013_001" (the letter B, five digits, an underscore, and three digits); other codes, such as "B01001A_001" or "C17002_001", give an error. "core" and "extended" select the same variables as NULL. For codes that are not in the ACS variable list for year, see the "Downloading from the Census Bureau" section. The Details of cacs_intersect_weight() say how each code is combined; a median or per-person value from a table other than B19013, B25077, or B19301 is added up like a count.
survey: A string giving the survey. Only "acs5" (the default), the ACS 5-year estimates, is accepted.
geography: A string giving the geographic level. Only "tract" (the default), census tracts, is accepted.
cache_dir: A path to the cache folder, or NULL (the default) to use cacs_cache_dir(); see the "Cache behavior" section. A folder outside the temporary folder of the R session is tidied as described in cacs_cache_dir(). cacs_clear_cache() clears only the folder that cacs_cache_dir() returns.
write_gpkg: A logical value, FALSE (the default) or TRUE. If TRUE, a downloaded result is also written to a GeoPackage file (.gpkg) in the acs folder of the cache folder (cache_dir, or cacs_cache_dir() when cache_dir is NULL), for use in other GIS software. The file is written even when the cache is turned off, but not when a saved result is read. It is named after the cache key, attr(result, "cacs_provenance")$cache_key, with the extension .gpkg. By default the cache folder is inside the temporary folder of the R session, so the file is deleted when the session ends; in a cache folder that lasts between sessions it is deleted together with the saved result (see cacs_cache_dir()), and cacs_clear_cache() also deletes it. To keep a copy, write the result with sf::st_write().
force_refresh: A logical value. If TRUE, the data are downloaded even when a saved result exists, and the new result replaces it unless the cache is turned off. With FALSE (the default), a saved result is read when there is one; see the "Cache behavior" section.
drop_water_tracts: A logical value. If TRUE (the default), tracts numbered 9900 or higher and tracts whose boundary has no area are removed; if FALSE, they are kept unless they were already removed from a saved result. See the "Water tracts" section.
verbose: A logical value. With TRUE (the default), the function shows a message before the download and a summary line when it finishes, and other messages report reading a saved result, writing files, and removing water tracts. FALSE turns off these messages; warnings are still given. See the "Progress messages" section of cacs_run() for how to turn the summary line off.

Value

An sf data frame with one row for each tract and variable, and the columns GEOID (the 11-digit tract identifier: two digits for the state, three for the county, and six for the tract), NAME (the tract name), variable (the ACS variable code), estimate, moe (the margin of error), and geometry (the tract boundary, in NAD83, EPSG:4269).

The attributes cacs_provenance and cacs_acs_provenance hold the same list, a record of how the result was produced. It gives the request: the state, the year, the survey, the geography, and the variable codes. It counts the variables, tracts, rows, missing estimates, and margins of error set to NA. It also holds the cache key, the time the result was created (in UTC), and the tidycensus and sf versions. A result read from the cache keeps the list from the original download. The attribute cacs_schema_version is the version label ("1.0") of the column layout.

Downloading from the Census Bureau

Reading a saved result needs neither a Census API key nor an internet connection. The data are downloaded when no saved result is found or when force_refresh = TRUE. A download needs a Census API key in the CENSUS_API_KEY environment variable, which tidycensus::census_api_key() can set; if it is missing or empty, the function stops before any request is made. Variable codes that are not in the ACS variable list for the year are skipped with a warning, and the function stops if none is left. A failed download is tried up to three times, except that an HTTP 4xx error, such as a bad request, stops the function at once. The downloaded table is checked with the same rules as cacs_acs_validate().

Water tracts

When drop_water_tracts = TRUE (the default), two kinds of tracts are removed right after the download. The first are tracts numbered 9900 or higher (a GEOID whose last six digits begin with 99), which the package treats as water or special-purpose tracts. The second are tracts whose boundary has zero, negative, or non-finite area, such as an empty boundary, because an area weight cannot be computed for them. A message lists the removed GEOIDs (the first five, followed by the number of others) unless verbose = FALSE.

The same rule is applied again when a saved result is read from the cache, but tracts removed before the result was saved stay removed even with drop_water_tracts = FALSE. They come back only with force_refresh = TRUE or after the saved result is deleted, for example with cacs_clear_cache(). With drop_water_tracts = FALSE, cacs_intersect_weight() skips tracts with zero area, with a warning.

Missing estimates and margins of error

Negative values in the margin-of-error column, which the Census Bureau's data API uses as codes rather than margins of error, are returned as NA; the function does not change estimates. For example, -555555555 means that a margin of error is not appropriate because the estimate is controlled to an independent population or housing estimate (U.S. Census Bureau, "Notes on ACS Estimate and Annotation Values"). A warning is given when more than 10 percent of the rows have a missing estimate, and another when more than 10 percent have -555555555 in place of a margin of error. Step 5 in the Details of cacs_intersect_weight() describes how these NA values carry into the estimates for the drive-time areas.

Cache behavior

By default the result is saved in the acs folder of the cache folder (cache_dir, or cacs_cache_dir() when cache_dir is NULL), with a small checksum file next to it. The default cache folder lasts only for the R session; cacs_cache_dir() says how to keep saved results between sessions and how long they are kept. A later call reads the saved result when it asks for the same state value, year, survey, geography, and variables (in any order) and the installed versions of R, catchmentACS, tidycensus, tigris, and sf have not changed. Otherwise the data are downloaded again (state = "AL" and state = "01", for example, are saved separately). A saved result that fails its checksum check is deleted and downloaded again.

A saved result that is read back with fewer than 1,000 rows gives a warning that it may be incomplete, once per session and only for copies with at least six variables (the catchmentACS.stale_min_variables option). The row limit is set with the option catchmentACS.stale_threshold_rows (0 turns the check off) or for one state value with an option such as catchmentACS.stale_threshold_WY.

Examples

library(sf)
#> Linking to GEOS 3.12.1, GDAL 3.8.4, PROJ 9.4.0; sf_use_s2() is TRUE
# The rows of 60 census tracts around a site in Birmingham, Alabama, taken
# from the 2019-2023 estimates that cacs_acs_prefetch() downloaded for the
# state and kept in a file that comes with the package: one row for each
# tract and variable
acs_bhm <- readRDS(system.file("extdata", "visual_walkthrough_fixture.rds",
                               package = "catchmentACS"))$acs_sf
head(acs_bhm)
#> Simple feature collection with 6 features and 5 fields
#> Geometry type: MULTIPOLYGON
#> Dimension:     XY
#> Bounding box:  xmin: -86.87313 ymin: 33.50507 xmax: -86.84912 ymax: 33.52091
#> Geodetic CRS:  NAD83
#>         GEOID                                          NAME   variable estimate
#> 1 01073003001 Census Tract 30.01; Jefferson County; Alabama B01003_001     3408
#> 2 01073003001 Census Tract 30.01; Jefferson County; Alabama B11001_001      715
#> 3 01073003001 Census Tract 30.01; Jefferson County; Alabama B17001_001     1331
#> 4 01073003001 Census Tract 30.01; Jefferson County; Alabama B17001_002      166
#> 5 01073003001 Census Tract 30.01; Jefferson County; Alabama B19013_001    56917
#> 6 01073003001 Census Tract 30.01; Jefferson County; Alabama B19056_001      715
#>     moe                       geometry
#> 1   403 MULTIPOLYGON (((-86.87246 3...
#> 2   193 MULTIPOLYGON (((-86.87246 3...
#> 3   399 MULTIPOLYGON (((-86.87246 3...
#> 4   121 MULTIPOLYGON (((-86.87246 3...
#> 5 26119 MULTIPOLYGON (((-86.87246 3...
#> 6   193 MULTIPOLYGON (((-86.87246 3...

# Downloads the estimates for every tract in Alabama, which needs a Census
# API key.
if (FALSE) { # \dontrun{
al <- cacs_acs_prefetch(state = "AL", year = 2023)
} # }