2. Creating gt tables

library(getACS)
library(dplyr)
library(gt)

One feature of the getACS package is support for building tables with the gt package. To demonstrate, we need data for a few different tables from the American Community Survey:

acs_data <- get_acs_tables(
  geography = "county",
  state = "MD",
  table = c("B01003", "B15003", "B25003"),
  quiet = TRUE
)

To start, we can use filter_acs() to filter one or more tables from the ACS data frame:

pop_tbl_data <- acs_data |>
  filter_acs(
    table = "B01003"
  ) |>
  slice_max(estimate, n = 5)

Then, you can use select_acs_cols() to select the estimate, percent estimate, name, and column title columns. In this example, setting column_title_col and perc_est_cols to NULL drops those columns from the data frame:

pop_tbl_data <- pop_tbl_data |>
  select_acs_cols(
    est_cols = "estimate",
    name_col = "NAME",
    column_title_col = NULL,
    perc_est_cols = NULL
  )

The main table building function is gt_acs() which is a wrapper for gt::gt(), gt::cols_label(), gt::cols_merge_uncert() and other gt functions. Based on the predictable structure of ACS data, this function can merge estimate and margin of error columns, format estimate and percent estimate columns, and set a source note with a survey and table attribution. Additional helpers can support common formatting tasks when working with American Community Survey data, such as fmt_acs_county() stripping the state name and trailing comma from the ACS data frame name column.

pop_tbl_data |>
  gt_acs(
    table = "B01003",
    est_cols = "estimate",
    est_col_label = "Population",
    name_col_label = "County"
  ) |>
  fmt_acs_county(
    state = "Maryland",
    pattern = "(County|), {state}"
  )

County	est_cols	moe
Montgomery	1057201	NA
Prince George's	957767	NA
Baltimore	850702	NA
Baltimore city	592211	NA
Anne Arundel	584064	NA
Source: 2017-2021 ACS 5-year Estimates, Table B01003.

Many helper functions are all built around tidyverse functions so additional parameters passed to filter_data() are passed to dplyr::filter() so subsetting data by indent, line_number, or other attributes is straightforward:

edu_tbl_data <- acs_data |>
  filter_acs(
    table = "B15003",
    indent > 0,
    line_number > 16,
    NAME == "Baltimore city, Maryland"
  )

Similarly, gt_acs() returns a gt_tbl object so it can be combined with other gt functions to add headers or customize tables in other ways:

edu_tbl_data |>
  select_acs_cols(name_col = NULL) |>
  gt_acs(
    table = edu_tbl_data$table_id[[1]],
    column_title_label = "Education",
    est_col_label = "Estimate",
    perc_col_label = "% of total"
  ) |>
  tab_header(
    edu_tbl_data$table_title[[1]],
    edu_tbl_data$NAME[[1]]
  )

Educational Attainment for the Population 25 Years and Over
Baltimore city, Maryland
Education	Estimate	% of total
Regular high school diploma	95,925 ± 2,657	23% ± 1%
GED or alternative credential	20,737 ± 1,380	5% ± 0%
Some college, less than 1 year	24,460 ± 1,264	6% ± 0%
Some college, 1 or more years, no degree	53,735 ± 2,074	13% ± 0%
Associate's degree	21,425 ± 1,109	5% ± 0%
Bachelor's degree	71,550 ± 1,819	17% ± 0%
Master's degree	46,701 ± 1,643	11% ± 0%
Professional school degree	13,160 ± 837	3% ± 0%
Doctorate degree	10,519 ± 733	3% ± 0%
Source: 2017-2021 ACS 5-year Estimates, Table B15003.

This flexibility makes it easy to quickly produce useful tables:

tenure_tbl_data <- acs_data |>
  filter_acs(
    table = "B25003",
    NAME == "Baltimore city, Maryland"
  )

tenure_tbl_data |>
  select_acs_cols(name_col = NULL) |>
  gt_acs(
    rowname_col = "column_title",
    est_col_label = "Units",
    table = tenure_tbl_data$table_id[[1]]
  ) |>
  tab_header(
    tenure_tbl_data$table_title[[1]],
    "Baltimore City, Maryland"
  )

Tenure
Baltimore City, Maryland
	Units	% share
Total	244,893 ± 1,599	100% ± 1%
Owner occupied	117,377 ± 1,910	48% ± 1%
Renter occupied	127,516 ± 2,368	52% ± 1%
Source: 2017-2021 ACS 5-year Estimates, Table B25003.

Helpers such as join_acs_geography_ratio() support additional features such as calculating a ratio between an estimate and the estimate for a reference geography:

comparison_data <- get_acs_geographies(
  geography = c("county", "metropolitan statistical area/micropolitan statistical area", "state"),
  county = "Baltimore city",
  state = "MD",
  msa = "Baltimore-Columbia-Towson, MD Metro Area",
  table = "B25105"
)

comparison_data |>
  join_acs_geography_ratio(
    geography = "county"
  ) |>
  select_acs_cols(
    name_col = "NAME",
    perc_est_cols = NULL,
    column_title_col = NULL,
    starts_with("ratio_")
  ) |>
  gt_acs() |>
  cols_merge_uncert_ext(
    c("ratio_estimate", "ratio_moe")
  )

NAME	Est.	ratio_estimate
Baltimore city, Maryland	1,184 ± 11	1.00 ± 0.01
Baltimore-Columbia-Towson, MD Metro Area	1,510 ± 8	1.28 ± 0.01
Maryland	1,605 ± 4	1.36 ± 0.01
Source: 2017-2021 ACS 5-year Estimates.