---
title: "Creating gt tables"
output: rmarkdown::html_vignette
vignette: >
  %\VignetteIndexEntry{Creating gt tables}
  %\VignetteEngine{knitr::rmarkdown}
  %\VignetteEncoding{UTF-8}
---

```{r, include = FALSE}
knitr::opts_chunk$set(
  collapse = TRUE,
  message = FALSE,
  comment = "#>"
)
```

```{r setup}
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:

```{r}
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:

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

Then, you can use `select_acs()` 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:

```{r}
pop_tbl_data <- pop_tbl_data |>
  select_acs(
    .value_col = "estimate",
    .name_col = "NAME",
    .column_title_col = NULL,
    .perc_prefix = 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.

```{r}
pop_tbl_data |>
  gt_acs(
    table = "B01003",
    value_label = "Population",
    name_label = "County",
    perc = FALSE
  ) |>
  fmt_acs_county(
    state = "Maryland",
    pattern = "(County|), {state}"
  )
```

Additional helpers can support common formatting tasks when working with American Community Survey data. For example, the function `fmt_acs_county()`  strips the state name and trailing comma from the ACS data frame name column.

Many helper functions are 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:

```{r}
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:

```{r}
edu_tbl_data |>
  select_acs(.name_col = NULL) |>
  gt_acs(
    table = edu_tbl_data$table_id,
    column_title_label = "Education",
    value_label = "Estimate",
    perc_value_label = "% of total"
  ) |>
  tab_header(
    edu_tbl_data$table_title[[1]],
    edu_tbl_data$NAME[[1]]
  )
```

This flexibility makes it easy to quickly produce useful tables:

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

tenure_tbl_data |>
  select_acs(.name_col = NULL) |>
  gt_acs(
    rowname_col = "column_title",
    value_label = "Units",
    # Only unique table values are used to append to the source note
    table = tenure_tbl_data$table_id
  ) |>
  tab_header(
    title = unique(tenure_tbl_data$table_title),
    subtitle = "Baltimore City, Maryland"
  )
```

Helpers such as `pivot_acs_wider()` can also be helpful even without the `gt_acs_compare()` variant:

```{r}
geo_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",
  quiet = TRUE
)

geo_comparison_data |>
  select_acs(
    .name_col = "NAME",
    .perc = FALSE
  ) |>
  pivot_acs_wider() |>
  gt_acs(
    value_label = NULL,
    column_title_label = "",
    currency_value = TRUE
  ) |>
  cols_label_with(
    fn = function(x) {
      stringr::str_remove(x, "^estimate_")
    }
  )
```

The `gt_acs_compare()` calls `pivot_acs_wider()` and handles the process of renaming column titles for a similar effect:

```{r}
geo_comparison_data |>
  gt_acs_compare(
    id_cols = "column_title",
    column_title_label = "",
    currency_value = TRUE
  )
```

Note that, if you encounter warning or error messages, you may need to set a value for `id_cols` to resolve the issue.