Title:	Making Census Data More Usable
Version:	0.0.5
Date:	2022-11-19
URL:	https://christophertkenny.com/censable/, https://github.com/christopherkenny/censable
BugReports:	https://github.com/christopherkenny/censable/issues
Description:	Creates a common framework for organizing, naming, and gathering population, age, race, and ethnicity data from the Census Bureau. Accesses the API https://www.census.gov/data/developers/data-sets.html. Provides tools for adding information to existing data to line up with Census data.
License:	MIT + file LICENSE
Encoding:	UTF-8
LazyData:	true
RoxygenNote:	7.2.1
Suggests:	roxygen2, spelling, testthat (≥ 3.0.0)
Imports:	magrittr, dplyr (≥ 1.0.4), rlang (≥ 0.4.11), sf (≥ 1.0.0), tibble, stringr, memoise, purrr, censusapi, methods, tinytiger
Depends:	R (≥ 2.10)
Config/testthat/edition:	3
Language:	en-US
NeedsCompilation:	no
Packaged:	2022-11-19 18:43:32 UTC; chris
Author:	Christopher T. Kenny [aut, cre]
Maintainer:	Christopher T. Kenny <christopherkenny@fas.harvard.edu>
Repository:	CRAN
Date/Publication:	2022-11-19 21:20:02 UTC

Pipe operator

Description

See magrittr::%>% for details.

Usage

lhs %>% rhs

Arguments

Value

The result of calling rhs(lhs).

Add Entry to Renviron

Description

Adds a value to the Renvironment of the form name=value. Designed for flexibly adding API keys for future sessions. Defaults are set up for entering a Census API key to work with tidycensus. By default this key will be configured to work with tidycensus. Package internally allows this key to work with censusapi when used through censable.

Usage

add_r_environ(
  value,
  name = "CENSUS_API_KEY",
  overwrite = FALSE,
  install = FALSE
)

Arguments

Value

value, invisibly

Examples

## Not run: 
add_r_environ('1234', 'SECRET_API_KEY')

## End(Not run)

Breakdown Census GEOID into Components

Description

Breakdown Census GEOID into Components

Usage

breakdown_geoid(.data, GEOID = "GEOID", area_type = "spine")

Arguments

Value

.data with added identifying columns based on area_type

Examples

data(mt_county)
mt_county <- mt_county %>% breakdown_geoid()

Build Data from the Decennial Census

Description

Creates a dataset, using the decennial census information, with the standard variables used for redistricting. Creates a stable base for getting data from censusapi for common calls in redistricting.

#' # Output columns are:

• GEOID: Geographic Identifier

• NAME: Name of County

• pop: total population

• pop_white: total population, Non-Hispanic White

• pop_black: total population, Non-Hispanic Black

• pop_hisp: total population, Hispanic

• pop_aian: total population, Non-Hispanic American Indian and Alaskan Native

• pop_asian: total population, Non-Hispanic Asian

• pop_nhpi: total population, Non-Hispanic Native Hawaiian and Pacific Islander

• pop_other: total population, Non-Hispanic Other

• pop_two: total population, Non-Hispanic Two Plus Races

• vap: voting age population

• vap_white: voting age population, Non-Hispanic White

• vap_black: voting age population, Non-Hispanic Black

• vap_hisp: voting age population, Hispanic

• vap_aian: voting age population, Non-Hispanic American Indian and Alaskan Native

• vap_asian: voting age population, Non-Hispanic Asian

• vap_nhpi: voting age population, Non-Hispanic Native Hawaiian and Pacific Islander

• vap_other: voting age population, Non-Hispanic Other

• vap_two: voting age population, Non-Hispanic Two Plus Races

• geometry: sf geometry

Arguments for geography are not checked, so will error if invalid. This is by design to avoid blocking usage that could become valid.

Currently valid options for geography:

• 'state'

• 'county'

• 'tract'

• 'block group'

• 'block'

• 'county subdivision'

• 'zcta'

• 'congressional district'

• 'state legislative district (upper chamber)'

• 'state legislative district (lower chamber)'

• 'school district (unified)'

• 'school district (elementary)'

• 'school district (secondary)'

Usage

build_acs(
  geography,
  state,
  county = NULL,
  geometry = TRUE,
  year = 2020,
  survey = "acs5",
  groups = "all"
)

mem_build_acs(
  geography,
  state,
  county = NULL,
  geometry = TRUE,
  year = 2020,
  survey = "acs5",
  groups = "all"
)

Arguments

Value

tibble with observations for each observation of the geography in the state or county. Data includes up to 3 sets of columns for each race or ethnicity category: population (pop), voting age population (vap), and citizen voting age population (cvap)

Examples

## Not run: 
# uses the Census API
tb <- build_acs(geography = 'tract', state = 'NY', county = 'Rockland', geometry = TRUE)

## End(Not run)

Build Data from the Decennial Census

Description

Creates a dataset, using the decennial census information, with the standard variables used for redistricting. Creates a stable base for getting data from censusapi for common calls in redistricting.

Usage

build_dec(
  geography,
  state,
  county = NULL,
  geometry = TRUE,
  year = 2020,
  groups = "all"
)

mem_build_dec(
  geography,
  state,
  county = NULL,
  geometry = TRUE,
  year = 2020,
  groups = "all"
)

Arguments

Value

tibble with observations for each observation of the geography in the state or county. Data includes up to 2 sets of columns for each race or ethnicity category: population (pop) and voting age population (vap)

Default output columns are:

• GEOID: Geographic Identifier

• NAME: Name of County

• pop: total population

• pop_white: total population, Non-Hispanic White

• pop_black: total population, Non-Hispanic Black

• pop_hisp: total population, Hispanic

• pop_aian: total population, Non-Hispanic American Indian and Alaskan Native

• pop_asian: total population, Non-Hispanic Asian

• pop_nhpi: total population, Non-Hispanic Native Hawaiian and Pacific Islander

• pop_other: total population, Non-Hispanic Other

• pop_two: total population, Non-Hispanic Two Plus Races

• vap: voting age population

• vap_white: voting age population, Non-Hispanic White

• vap_black: voting age population, Non-Hispanic Black

• vap_hisp: voting age population, Hispanic

• vap_aian: voting age population, Non-Hispanic American Indian and Alaskan Native

• vap_asian: voting age population, Non-Hispanic Asian

• vap_nhpi: voting age population, Non-Hispanic Native Hawaiian and Pacific Islander

• vap_other: voting age population, Non-Hispanic Other

• vap_two: voting age population, Non-Hispanic Two Plus Races

• geometry: sf geometry

Arguments for geography are not checked, so will error if invalid. This is by design, to avoid blocking usage that could become valid.

Currently valid options for geography:

• 'state'

• 'county'

• 'tract'

• 'block group'

• 'block'

• 'county subdivision'

• 'zcta'

• 'congressional district'

• 'state legislative district (upper chamber)'

• 'state legislative district (lower chamber)'

• 'school district (unified)'

• 'school district (elementary)'

• 'school district (secondary)'

• 'voting district' may also work, though seems to be less reliable

Examples

## Not run: 
# uses the Census API
tb <- build_dec(geography = 'block', state = 'NY', county = 'Rockland', geometry = TRUE)

## End(Not run)

Collapse Full Race Categories into 4 Categories

Description

Collapses Other, AIAN, Asian, NHPI, and Two+ into other, by prefix.

Usage

collapse4(.data, prefix)

Arguments

Value

.data with columns collapsed

Examples

data(mt_county)
mt_county <- mt_county %>% collapse4(prefix = c('pop_', 'vap_'))

Collapse Population Race Categories into 4 Categories

Description

Collapses Other, AIAN, Asian, NHPI, and Two+ into other.

Usage

collapse4_pop(.data, prefix = "pop_")

Arguments

Value

.data with columns collapsed

Examples

data(mt_county)
mt_county <- mt_county %>% collapse4_pop()

Collapse Voting Age Population Race Categories into 4 Categories

Description

Collapses Other, AIAN, Asian, NHPI, and Two+ into other.

Usage

collapse4_vap(.data, prefix = "vap_")

Arguments

Value

.data with columns collapsed

Examples

data(mt_county)
mt_county <- mt_county %>% collapse4_vap()

Collapse Full Race Categories into 5 Categories

Description

Collapses Other, AIAN, NHPI, and Two+ into Other, by prefix.

Usage

collapse5(.data, prefix)

Arguments

Value

.data with columns collapsed

Examples

data(mt_county)
mt_county <- mt_county %>% collapse5(prefix = c('pop_', 'vap_'))

Collapse Population Race Categories into 5 Categories

Description

Collapses Other, AIAN, NHPI, and Two+ into other.

Usage

collapse5_pop(.data, prefix = "pop_")

Arguments

Value

.data with columns collapsed

Examples

data(mt_county)
mt_county <- mt_county %>% collapse5_pop()

Collapse Voting Age Population Race Categories into 5 Categories

Description

Collapses Other, AIAN, NHPI, and Two+ into other.

Usage

collapse5_vap(.data, prefix = "vap_")

Arguments

Value

.data with columns collapsed

Examples

data(mt_county)
mt_county <- mt_county %>% collapse5_vap()

Create GEOID from Default Columns

Description

Create GEOID from Default Columns

Usage

construct_geoid(
  .data,
  area_type,
  state = "state",
  county = "county",
  tract = "tract",
  block_group = "block group",
  block = "block",
  cd = "cd",
  shd = "shd",
  ssd = "ssd",
  zcta = "zcta"
)

Arguments

Value

.data with new column GEOID

Examples

data(mt_county)
mt_county <- mt_county %>% breakdown_geoid()
mt_county <- mt_county %>% dplyr::select(-dplyr::all_of('GEOID'))
mt_county <- mt_county %>% construct_geoid()

Create a GEOID from Columns

Description

Create a GEOID from Columns

Usage

custom_geoid(.data, ...)

Arguments

Value

.data with new column GEOID

Examples

data(mt_county)
mt_county <- mt_county %>% custom_geoid(GEOID)

Counties FIPS 2000

Description

Contains three columns:

• state: state FIPS

• county: county FIPS

• name: county name

Usage

data('fips_2000')

Value

tibble

Examples

data('fips_2000')

Counties FIPS 2010

Description

Contains three columns:

• state: state FIPS

• county: county FIPS

• name: county name

Usage

data('fips_2010')

Value

tibble

Examples

data('fips_2010')

Counties FIPS 2020

Description

Contains three columns:

• state: state FIPS

• county: county FIPS

• name: county name

Usage

data('fips_2020')

Value

tibble

Examples

data('fips_2020')

Join Abb by ANSI

Description

Adds a column with state abbreviation joining by a column with state ansi

Usage

join_abb_ansi(.data, .ansi)

Arguments

Value

.data with column .ansi replaced with state abbreviation

Examples

data('stata')
stata %>% join_abb_ansi(ansi)

Join Abb by FIPS

Description

Adds a column with state abbreviation joining by a column with state fips

Usage

join_abb_fips(.data, .fips)

Arguments

Value

.data with column .fips replaced with state abb

Examples

data('stata')
stata %>% join_abb_fips(fips)

Join Abb by Name

Description

Adds a column with state abbs joining by a column with state names

Usage

join_abb_name(.data, .name)

Arguments

Value

.data with column .name replaced with abbreviation

Examples

data('stata')
stata %>% join_abb_name(name)

Join ANSI by Abb

Description

Adds a column with state ansi joining by a column with state abbreviation

Usage

join_ansi_abb(.data, .abb)

Arguments

Value

.data with column .abb replaced with state ansi

Examples

data('stata')
stata %>% join_ansi_abb(abb)

Join ANSI by FIPS

Description

Adds a column with state ansi joining by a column with state fips

Usage

join_ansi_fips(.data, .fips)

Arguments

Value

.data with column .fips replaced with state ansi

Examples

data('stata')
stata %>% join_ansi_fips(fips)

Join ANSI by Name

Description

Adds a column with state ansi joining by a column with state name

Usage

join_ansi_name(.data, .name)

Arguments

Value

.data with column .name replaced with ansi

Examples

data('stata')
stata %>% join_ansi_name(name)

Join FIPS by Abb

Description

Adds a column with state fips joining by a column with state abbreviation

Usage

join_fips_abb(.data, .abb)

Arguments

Value

.data with column .abb replaced with state name

Examples

data('stata')
stata %>% join_fips_abb(abb)

Join FIPS by ANSI

Description

Adds a column with state fips joining by a column with state ansi

Usage

join_fips_ansi(.data, .ansi)

Arguments

Value

.data with column .ansi replaced with state fips

Examples

data('stata')
stata %>% join_fips_ansi(ansi)

Join FIPS by Name

Description

Adds a column with state fips joining by a column with state name

Usage

join_fips_name(.data, .name)

Arguments

Value

.data with column .name replaced with fips

Examples

data('stata')
stata %>% join_fips_name(name)

Join Name by Abb

Description

Adds a column with state name joining by a column with state abbreviation

Usage

join_name_abb(.data, .abb)

Arguments

Value

.data with column .abb replaced with state name

Examples

data('stata')
stata %>% join_name_abb(abb)

Join Name by ANSI

Description

Adds a column with state name joining by a column with state ansi

Usage

join_name_ansi(.data, .ansi)

Arguments

Value

.data with column .ansi replaced with state name

Examples

data('stata')
stata %>% join_name_ansi(name)

Join Name by FIPS

Description

Adds a column with state name joining by a column with state fips

Usage

join_name_fips(.data, .fips)

Arguments

Value

.data with column .fips replaced with state name

Examples

data('stata')
stata %>% join_name_fips(fips)

Check or Get Census API Key

Description

Check or Get Census API Key

Usage

has_census_key()

get_census_key(key = "")

Arguments

Value

logical if has, key if get

Examples

has_census_key()

Try to Match to State Abbreviation

Description

Searches for an exact match and offers the best match if no exact match

Usage

match_abb(state)

Arguments

Value

Abbreviation if a match is found or character(0) if no match is found

Examples

match_abb('NY')
match_abb('01')

Try to Match to State ANSI

Description

Searches for an exact match and offers the best match if no exact match

Usage

match_ansi(state)

Arguments

Value

ANSI if a match is found or character(0) if no match is found

Examples

match_ansi('NY')
match_ansi('01')

Try to Match to State FIPS

Description

Searches for an exact match and offers the best match if no exact match

Usage

match_fips(state)

Arguments

Value

FIPS code if a match is found or character(0) if no match is found

Examples

match_fips('NY')
match_fips('01')

Try to Match to State Name

Description

Searches for an exact match and offers the best match if no exact match

Usage

match_name(state)

Arguments

Value

Name if a match is found or character(0) if no match is found

Examples

match_name('NY')
match_name('01')

Montana County Data

Description

• GEOID: Geographic Identifier

• NAME: Name of County

• pop: total population

• pop_white: total population, Non-Hispanic White

• pop_black: total population, Non-Hispanic Black

• pop_hisp: total population, Hispanic

• pop_aian: total population, Non-Hispanic American Indian and Alaskan Native

• pop_asian: total population, Non-Hispanic Asian

• pop_nhpi: total population, Non-Hispanic Native Hawaiian and Pacific Islander

• pop_other: total population, Non-Hispanic Other

• pop_two: total population, Non-Hispanic Two Plus Races

• vap: voting age population

• vap_white: voting age population, Non-Hispanic White

• vap_black: voting age population, Non-Hispanic Black

• vap_hisp: voting age population, Hispanic

• vap_aian: voting age population, Non-Hispanic American Indian and Alaskan Native

• vap_asian: voting age population, Non-Hispanic Asian

• vap_nhpi: voting age population, Non-Hispanic Native Hawaiian and Pacific Islander

• vap_other: voting age population, Non-Hispanic Other

• vap_two: voting age population, Non-Hispanic Two Plus Races

• geometry: sf geometry

Usage

data('mt_county')

Value

sf tibble with one observation for each county in Montana

Examples

data('mt_county')

Recode Abb by ANSI

Description

Replaces state ansi with state abbreviation

Usage

recode_abb_ansi(.data, .ansi)

Arguments

Value

.data with column .ansi replaced with state abbreviation

Examples

data('stata')
stata %>% recode_abb_ansi(ansi)

Recode Abb by FIPS

Description

Replaces state fips with state abb

Usage

recode_abb_fips(.data, .fips)

Arguments

Value

.data with column .fips replaced with state abb

Examples

data('stata')
stata %>% recode_abb_fips(fips)

Recode Abb by Name

Description

Replaces state name with state abbreviation

Usage

recode_abb_name(.data, .name)

Arguments

Value

.data with column .name replaced with abbreviation

Examples

data('stata')
stata %>% recode_abb_name(name)

Recode ANSI by Abb

Description

Replaces state abbreviation with state ansi

Usage

recode_ansi_abb(.data, .abb)

Arguments

Value

.data with column .abb replaced with state ansi

Examples

data('stata')
stata %>% recode_ansi_abb(abb)

Recode ANSI by FIPS

Description

Replaces state fips with state ansi

Usage

recode_ansi_fips(.data, .fips)

Arguments

Value

.data with column .fips replaced with state ansi

Examples

data('stata')
stata %>% recode_ansi_fips(fips)

Recode ANSI by Name

Description

Replaces state name with state ansi

Usage

recode_ansi_name(.data, .name)

Arguments

Value

.data with column .name replaced with ansi

Examples

data('stata')
stata %>% recode_ansi_name(name)

Recode FIPS by Abb

Description

Replaces state abbreviation with state fips

Usage

recode_fips_abb(.data, .abb)

Arguments

Value

.data with column .abb replaced with state name

Examples

data('stata')
stata %>% recode_fips_abb(abb)

Recode FIPS by ANSI

Description

Replaces state ansi with state fips

Usage

recode_fips_ansi(.data, .ansi)

Arguments

Value

.data with column .ansi replaced with state fips

Examples

data('stata')
stata %>% recode_fips_ansi(ansi)

Recode FIPS by Name

Description

Replaces state name with state fips

Usage

recode_fips_name(.data, .name)

Arguments

Value

.data with column .name replaced with fips

Examples

data('stata')
stata %>% recode_fips_name(name)

Recode Name by Abb

Description

Replaces state abbreviation with state name

Usage

recode_name_abb(.data, .abb)

Arguments

Value

.data with column .abb replaced with state name

Examples

data('stata')
stata %>% recode_name_abb(abb)

Recode Name by ANSI

Description

Replaces state ansi with state name

Usage

recode_name_ansi(.data, .ansi)

Arguments

Value

.data with column .ansi replaced with state name

Examples

data('stata')
stata %>% recode_name_ansi(name)

Recode Name by FIPS

Description

Replaces state fips with state name

Usage

recode_name_fips(.data, .fips)

Arguments

Value

.data with column .fips replaced with state name

Examples

data('stata')
stata %>% recode_name_fips(fips)

stata (State Data)

Description

tibble with columns:

• fips: Federal Information Processing Standards codes

• abb: two letter postal abbreviations

• name: title case state name

• ansi: American National Standards Institute codes

• region: Census Regions (for 50 states and D.C.)

• division: Census Divisions (for 50 states and D.C.)

Usage

data('stata')

Value

tibble with state identifying information

Examples

data('stata')

Tidy eval helpers

Description

This page lists the tidy eval tools reexported in this package from rlang. To learn about using tidy eval in scripts and packages at a high level, see the dplyr programming vignette and the ggplot2 in packages vignette. The Metaprogramming section of Advanced R may also be useful for a deeper dive.

• The tidy eval operators ⁠{{⁠, ⁠!!⁠, and ⁠!!!⁠ are syntactic constructs which are specially interpreted by tidy eval functions. You will mostly need ⁠{{⁠, as ⁠!!⁠ and ⁠!!!⁠ are more advanced operators which you should not have to use in simple cases.

  The curly-curly operator ⁠{{⁠ allows you to tunnel data-variables passed from function arguments inside other tidy eval functions. ⁠{{⁠ is designed for individual arguments. To pass multiple arguments contained in dots, use ... in the normal way.

  my_function <- function(data, var, ...) {
    data %>%
      group_by(...) %>%
      summarise(mean = mean({{ var }}))
  }
  

• enquo() and enquos() delay the execution of one or several function arguments. The former returns a single expression, the latter returns a list of expressions. Once defused, expressions will no longer evaluate on their own. They must be injected back into an evaluation context with ⁠!!⁠ (for a single expression) and ⁠!!!⁠ (for a list of expressions).

  my_function <- function(data, var, ...) {
    # Defuse
    var <- enquo(var)
    dots <- enquos(...)
  
    # Inject
    data %>%
      group_by(!!!dots) %>%
      summarise(mean = mean(!!var))
  }
  

  In this simple case, the code is equivalent to the usage of ⁠{{⁠ and ... above. Defusing with enquo() or enquos() is only needed in more complex cases, for instance if you need to inspect or modify the expressions in some way.

• The .data pronoun is an object that represents the current slice of data. If you have a variable name in a string, use the .data pronoun to subset that variable with [[.

  my_var <- "disp"
  mtcars %>% summarise(mean = mean(.data[[my_var]]))
  

• Another tidy eval operator is ⁠:=⁠. It makes it possible to use glue and curly-curly syntax on the LHS of =. For technical reasons, the R language doesn't support complex expressions on the left of =, so we use ⁠:=⁠ as a workaround.

  my_function <- function(data, var, suffix = "foo") {
    # Use `{{` to tunnel function arguments and the usual glue
    # operator `{` to interpolate plain strings.
    data %>%
      summarise("{{ var }}_mean_{suffix}" := mean({{ var }}))
  }
  

• Many tidy eval functions like dplyr::mutate() or dplyr::summarise() give an automatic name to unnamed inputs. If you need to create the same sort of automatic names by yourself, use as_label(). For instance, the glue-tunnelling syntax above can be reproduced manually with:

  my_function <- function(data, var, suffix = "foo") {
    var <- enquo(var)
    prefix <- as_label(var)
    data %>%
      summarise("{prefix}_mean_{suffix}" := mean(!!var))
  }
  

  Expressions defused with enquo() (or tunnelled with ⁠{{⁠) need not be simple column names, they can be arbitrarily complex. as_label() handles those cases gracefully. If your code assumes a simple column name, use as_name() instead. This is safer because it throws an error if the input is not a name as expected.