multi_geo_decennial: Fetch a decennial census table with multiple geography levels

In CT-Data-Haven/cwi: Prep for DataHaven's Community Wellbeing Index

Fetch a decennial census table with multiple geography levels

Description

Fetch a data table from the decennial census via tidycensus with your choice of geographies at multiple levels. For geographies made of aggregates, i.e. neighborhoods made of tracts or regions made of towns, the returned table will have estimates summed for the whole area. Any geographic levels that are null will be excluded.

Usage

multi_geo_decennial(
  table,
  year = 2020,
  towns = "all",
  regions = NULL,
  counties = "all",
  state = "09",
  neighborhoods = NULL,
  tracts = NULL,
  blockgroups = NULL,
  msa = FALSE,
  us = FALSE,
  new_england = TRUE,
  nhood_name = "name",
  nhood_geoid = NULL,
  nhood_weight = "weight",
  sumfile = c("dhc", "sf1", "sf3", "pl"),
  verbose = TRUE,
  key = NULL,
  sleep = 0,
  ...
)

Arguments

table	A string giving the decennial census table number. These are generally formatted as one or more letters, 3 numbers, and optionally a letter.
year	The year of the census table; currently defaults 2020.
towns	A character vector of towns to include; "all" (default) for all towns optionally filtered by county; or NULL to not fetch town-level table.
regions	A named list of regions with their town names (defaults NULL).
counties	A character vector of counties to include; "all" (default) for all counties in the state; or NULL to not fetch county-level table.
state	A string: either name or two-digit FIPS code of a US state. Required; defaults "09" (Connecticut).
neighborhoods	A data frame with columns for neighborhood name, GEOID of tracts, and weight, e.g. share of each tract assigned to a neighborhood. If included, weighted sums will be returned for neighborhoods. Unlike multi_geo_acs, this doesn't take block groups.
tracts	A character vector of 11-digit FIPS codes of tracts to include, or "all" for all tracts optionally filtered by county. Defaults NULL.
blockgroups	A character vector of 12-digit FIPS codes of block groups to include, or "all" for all block groups optionally filtered by county. Defaults NULL.
msa	Logical: whether to fetch New England states' metropolitan statistical areas. Defaults FALSE.
us	Logical: whether to fetch US-level table. Defaults FALSE.
new_england	Logical: if TRUE (the default), limits metro areas to just New England states.
nhood_name	String giving the name of the column in the data frame neighborhoods that contains neighborhood names. Previously this was a bare column name, but for consistency with changes to COG-based FIPS codes, this needs to be a string. Only relevant if a neighborhood weight table is being used. Defaults "name" to match the neighborhood lookup datasets.
nhood_geoid	String giving the name of the column in neighborhoods that contains neighborhood GEOIDs, either tracts or block groups. Only relevant if a neighborhood weight table is being used. Because of changes to FIPS codes, this no longer has a default.
nhood_weight	String giving the name of the column in neighborhoods that contains weights between neighborhood names and tract/block groups. Only relevant if a neighborhood weight table is being used. Defaults "weight" to match the neighborhood lookup datasets.
sumfile	A string giving the summary file to pull from. Note that codes have changed between 2010 and 2020. Now that default year is 2020, default sumfile is "dhc". For 2010, should be either "sf1", or less commonly "sf3". Use "pl" for 2020 redistricting data.
verbose	Logical: whether to print summary of geographies included. Defaults TRUE.
key	String: Census API key. If NULL (default), takes the value from Sys.getenv("CENSUS_API_KEY").
sleep	Number of seconds, if any, to sleep before each API call. This might help with the Census API's tendency to crash, but for many geographies, it could add a sizable about of time. Probably don't add more than a few seconds.
...	Additional arguments to pass on to tidycensus::get_acs

Details

This function essentially calls tidycensus::get_decennial() multiple times, depending on geographic levels chosen, and does minor cleaning, filtering, and aggregation. Note that the underlying tidycensus::get_decennial() requires a Census API key. As is the case with other tidycensus functions, multi_geo_decennial assumes this key is stored as CENSUS_API_KEY in your .Renviron. See tidycensus::census_api_key() for installation.

Be advised that decennial table numbers may change from year to year, so if you're looking at trends, check FactFinder or another source to make sure the tables have the same meaning. Setting verbose = TRUE is helpful for this as well.

Value

A tibble with GEOID, name, variable code, estimate, moe, geography level, state, and year, as applicable, for the chosen table.

See Also

tidycensus::census_api_key(), tidycensus::get_decennial()

Examples

## Not run: 
multi_geo_decennial("P1", 2020, sumfile = "dhc",
  towns = "all",
  regions = list(inner_ring = c("Hamden", "East Haven", "West Haven")),
  counties = "New Haven County")

## End(Not run)

CT-Data-Haven/cwi documentation built on July 1, 2024, 7:45 a.m.