Create a gt table with formatted ACS estimate and percent estimate columns

Create or format a gt table with an estimate and margin of error and (optionally) percent estimate and margin of error value. Use in combination with the select_acs_cols() helper function to prep data before creating a table.

Usage

gt_acs(
  data,
  rownames_to_stub = FALSE,
  row_group_as_column = FALSE,
  ...,
  est_cols = c("estimate", "moe"),
  est_col_label = "Est.",
  perc_cols = c("perc_estimate", "perc_moe"),
  perc_col_label = "% share",
  est_spanner = NULL,
  perc_spanner = NULL,
  combined_spanner = NULL,
  decimals = 0,
  column_title_col = "column_title",
  column_title_label = NULL,
  name_col = "NAME",
  name_col_label = NULL,
  source_note = NULL,
  append_note = FALSE,
  drop_geometry = TRUE,
  hide_na_cols = TRUE,
  survey = "acs5",
  year = 2021,
  table = NULL,
  prefix = "Source: ",
  end = "."
)

Arguments

data

Input data table

obj:<data.frame>|obj:<tbl_df> // required

A data.frame object or a tibble (tbl_df).

rownames_to_stub

Use data frame row labels in the stub

scalar<logical> // default: FALSE

An option to take rownames from the input data table (should they be available) as row labels in the display table stub.

row_group_as_column

Mode for displaying row group labels in the stub

scalar<logical> // default: FALSE

An option that alters the display of row group labels. By default this is FALSE and row group labels will appear in dedicated rows above their respective groups of rows. If TRUE row group labels will occupy a secondary column in the table stub.

...

Additional parameters passed to gt::fmt_number() by fmt_acs_estimate() or to gt::fmt_percent() by fmt_acs_percent().

est_cols, est_col_label, est_spanner

Passed to columns, col_labels, and spanner parameter for fmt_acs_estimate()

perc_cols, perc_col_label, perc_spanner

Passed to columns, col_labels, and spanner parameter for fmt_acs_percent()

combined_spanner

If not NULL, combined_spanner is passed to label parameter of gt::tab_spanner() using both est_cols and perc_cols as the columns parameter.

decimals

Number of decimal places

scalar<numeric|integer>(val>=0) // default: 2

This corresponds to the exact number of decimal places to use. A value such as 2.34 can, for example, be formatted with 0 decimal places and it would result in "2". With 4 decimal places, the formatted value becomes "2.3400". The trailing zeros can be removed with drop_trailing_zeros = TRUE. If you always need decimals = 0, the fmt_integer() function should be considered.

column_title_col, column_title_label

Column title and label. If column_title_label is a string, column_title_col is required. column_title_label can also be a named vector in the format of c("label" = "column"). column_title_col defaults to "column_title"

name_col, name_col_label

Place name column and label. name_col_label can be a string or a named vector (similar to column_title_label). name_col defaults to "NAME"

source_note

Source note text

scalar<character> // required

Text to be used in the source note. We can optionally use the md() and html() functions to style the text as Markdown or to retain HTML elements in the text.

append_note

If TRUE, add source_note to the end of the generated ACS data label. If FALSE, any supplied source_note will be used instead of an ACS label.

drop_geometry

If TRUE (default) and data is an sf object, drop geometry before turning the data frame into a table.

hide_na_cols

If TRUE (default), hide columns where all values are NA.

survey

ACS survey, "acs5", "acs3", or "acs1".

year

Based on the year and survey, acs_survey_ts() returns a vector of years for non-overlapping ACS samples to allow comparison.

table

One or more table IDs to include in label or source note.

prefix

Text to insert before ACS survey label.

end

A character string appended to the end of the full label. Defaults to ".".

See also

Other gt table: fmt_acs_estimate(), tab_acs_source_note()

Examples

if (FALSE) {
if (interactive()) {
  data <- get_acs_tables(
    geography = "county",
    county = "Baltimore city",
    state = "MD",
    table = "B08134"
  )

  tbl_data <- filter_acs(data, indent == 1, line_number <= 10)
  tbl_data <- select_acs_cols(tbl_data)

  gt_acs(
    tbl_data,
    column_title_label = "Commute time",
    table = "B08134"
  )
}
}