R/get_decennial_metro.R

In nmmarquez/censeg: Calculate Segregation Measures from Census Data

#' A wrapper function of get_decennial which gets data for 50 states plus DC
#'
#' @description get_decennial_metro uses the census api to download data for all
#' 50 states plus DC for "on spine" geographies county and below. This method
#' will associate those geographies with a CBSA as well.
#'
#' @param geography unit for which to pull data
#' @param variables Character string or vector of character strings of
#' variable IDs.
#' @param table The Census table for which you would like to request all
#' variables. Uses lookup tables to identify the variables; performs faster
#' when variable table already exists through load_variables(cache = TRUE).
#' Only one table may be requested per call.
#' @param cache_table Whether or not to cache table names for faster future
#' access. Defaults to FALSE; if TRUE, only needs to be called once per dataset.
#' If variables dataset is already cached via the load_variables function,
#' this can be bypassed.
#' @param year The year for which you are requesting data.
#' 1990, 2000, and 2010 are available.
#' @param sumfile The Census summary file. Defaults to sf1;
#' the function will look in sf3 if it cannot find a variable in sf1.
#' @param output One of "tidy" (the default) in which each row represents an
#' enumeration unit-variable combination, or "wide" in which each row
#' represents an enumeration unit and the variables are in the columns.
#' @param summary_var Character string of a "summary variable" from the
#' decennial Census to be included in your output. Usually a variable
#' (e.g. total population) that you'll want to use as a denominator.
#' @param key Your Census API key. Obtain one at
#' http://api.census.gov/data/key_signup.html
#' @param show_call if TRUE, display call made to Census API. This can be very
#' useful in debugging and determining if error messages returned are due to
#' tidycensus or the Census API. Copy to the API call into a browser and see
#' what is returned by the API directly. Defaults to FALSE.
#' @param ... Other argumenets to pass to get_decennial.
#'
#' @return data frame with census info and adjoined cbsa location
#'
#' @examples
#' \dontrun{
#' # get Korean population for all tracts in US with appropriate metro info
#' get_decennial_metro("tract", c(Korean = "PCT005012"))
#' }
#'
#' @export

get_decennial_metro <- function(
    geography,
    variables = NULL,
    table = NULL,
    cache_table = FALSE,
    year = 2010,
    sumfile = "sf1",
    output = "tidy",
    summary_var = NULL,
    key = NULL,
    show_call = FALSE,
    ...){

    all_df <- as.data.table(rbindlist(lapply(c(state.abb, "DC"), function(s){
        get_decennial(
            geography = geography,
            variables = variables,
            table = table,
            cache_table = cache_table,
            year = year,
            sumfile = sumfile,
            state = s,
            county = NULL,
            geometry = FALSE,
            output = output,
            keep_geo_vars = FALSE,
            shift_geo = FALSE,
            summary_var = summary_var,
            key = key,
            show_call = show_call,
            ...
        )
    })))

    all_df[,STATE := substr(GEOID, 1, 2)]
    all_df[,COUNTY := substr(GEOID, 3, 5)]

    merge(
        all_df, cbsa_county_df, all.x = TRUE, by = c("STATE", "COUNTY"))
}