gt (version 0.1.0)

location_cells: Helpers for targeting multiple cells in different locations

Description

These helper functions are used to target individual cells in different locations (e.g., the stub, the column labels, the title, etc.). They can be used in any of these functions (which all have a locations argument): tab_footnote(), tab_style(), and text_transform(). Furthermore, multiple locations can be targeted by enclosing several cells_*() helper functions in a list().

Usage

cells_title(groups = c("title", "subtitle"))
cells_stubhead()
cells_column_spanners(spanners)
cells_column_labels(columns)
cells_group(groups = TRUE)
cells_stub(rows = TRUE)
cells_data(columns = TRUE, rows = TRUE)
cells_summary(groups = TRUE, columns = TRUE, rows = TRUE)
cells_grand_summary(columns = TRUE, rows = TRUE)

Arguments

groups

Used in the cells_title(), cells_group(), and cells_summary() functions to specify which groups to target.

spanners

Used in the cells_column_spanners() function to indicate which spanners to target.

columns, rows

Either a vector of names, a vector of indices, values provided by vars(), values provided by c(), or a select helper function (see Details for information on these functions).

Value

a list object of class location_cells.

Figures

Details

The following helper functions can be used to target cells (roughly in order from the top to the bottom of a table):

• cells_title(): targets the table title or the table subtitle depending on the value given to the groups argument ("title" or "subtitle").

• cells_stubhead(): targets the stubhead location, a cell of which is only available when there is a stub; a label in that location can be created by using the tab_stubhead() function.

• cells_column_labels(): targets the column labels.

• cells_column_spanners(): targets the spanner column labels, which appear above the column labels.

• cells_group(): targets the row group labels in any available row groups using the groups argument.

• cells_stub(): targets row labels in the table stub using the rows argument.

• cells_data(): targets data cells in the table body using intersections of columns and rows.

• cells_summary(): targets summary cells in the table body using the groups argument and intersections of columns and rows.

• cells_grand_summary(): targets cells of the table's grand summary using intersections of columns and rows

Examples

# NOT RUN {
library(tidyr)

# Use `sp500` to create a gt table; add
# a header (with a title and a subtitle),
# and then add a footnote to the subtitle
# with `tab_footnote()` and `cells_title()`
# in `locations`
tab_1 <-
  sp500 %>%
  dplyr::filter(
    date >= "2015-01-05" &
      date <="2015-01-10"
  ) %>%
  dplyr::select(
    -c(adj_close, volume, high, low)
  ) %>%
  gt() %>%
  tab_header(
    title = "S&P 500",
    subtitle = "Open and Close Values"
  ) %>%
  tab_footnote(
    footnote = "All values in USD.",
    locations = cells_title(
      groups = "subtitle")
  )

# Use `sza` to create a gt table; add a
# header and then add footnotes to the
# column labels with `tab_footnote()` and
# `cells_column_labels()` in `locations`
tab_2 <-
  sza %>%
  dplyr::filter(
    latitude == 20 & month == "jan" &
      !is.na(sza)
  ) %>%
  dplyr::select(-latitude, -month) %>%
  gt() %>%
  tab_footnote(
    footnote = "True solar time.",
    locations = cells_column_labels(
      columns = vars(tst))
  ) %>%
  tab_footnote(
    footnote = "Solar zenith angle.",
    locations = cells_column_labels(
      columns = vars(sza))
  )

# Use `pizzaplace` to create a gt table
# with grouped data; add a summary with the
# `summary_rows()` function and then add a
# footnote to the "peppr_salami" row group
# label with `tab_footnote()` and with
# `cells_group()` in `locations`
tab_3 <-
  pizzaplace %>%
  dplyr::filter(
    name %in% c("soppressata", "peppr_salami")
  ) %>%
  dplyr::group_by(name, size) %>%
  dplyr::summarize(
    `Pizzas Sold` = dplyr::n()
  ) %>%
  gt(rowname_col = "size") %>%
  summary_rows(
    groups = TRUE,
    columns = vars("Pizzas Sold"),
    fns = list(TOTAL = "sum"),
    formatter = fmt_number,
    decimals = 0,
    use_seps = TRUE
  ) %>%
  tab_footnote(
    footnote = "The Pepper-Salami.",
    cells_group(groups = "peppr_salami")
  )

# Use `sza` to create a gt table; color
# all of the `month` values in the table
# stub with `tab_style()`, using `cells_stub()`
# in `locations` (`rows = TRUE` targets
# all stub rows)
tab_4 <-
  sza %>%
  dplyr::filter(
    latitude == 20 & tst <= "1000") %>%
  dplyr::select(-latitude) %>%
  dplyr::filter(!is.na(sza)) %>%
  tidyr::spread(key = "tst", value = sza) %>%
  gt(rowname_col = "month") %>%
  fmt_missing(
    columns = TRUE,
    missing_text = ""
  ) %>%
  tab_style(
    style = list(
      cell_fill(color = "darkblue"),
      cell_text(color = "white")
      ),
    locations = cells_stub(rows = TRUE)
  )

# Use `gtcars` to create a gt table; add
# a footnote that targets a single data cell
# with `tab_footnote()`, using `cells_data()`
# in `locations` (`rows = hp == max(hp)` will
# target a single row in the `hp` column)
tab_5 <-
  gtcars %>%
  dplyr::filter(ctry_origin == "United Kingdom") %>%
  dplyr::select(mfr, model, year, hp) %>%
  gt() %>%
  tab_footnote(
    footnote = "Highest horsepower.",
    locations = cells_data(
      columns = vars(hp),
      rows = hp == max(hp))
  ) %>%
  opt_footnote_marks(marks = "*")

# Use `countrypops` to create a gt table; add
# some styling to the summary data cells with
# with `tab_style()`, using `cells_summary()`
# in `locations`
tab_6 <-
  countrypops %>%
  dplyr::filter(
    country_name == "Japan",
    year < 1970) %>%
  dplyr::select(-contains("country")) %>%
  dplyr::mutate(
    decade = paste0(substr(year, 1, 3), "0s")
  ) %>%
  dplyr::group_by(decade) %>%
  gt(
    rowname_col = "year",
    groupname_col = "decade"
  ) %>%
  fmt_number(
    columns = vars(population),
    decimals = 0
  ) %>%
  summary_rows(
    groups = "1960s",
    columns = vars(population),
    fns = list("min", "max"),
    formatter = fmt_number,
    decimals = 0
  ) %>%
  tab_style(
    style = list(
      cell_text(style = "italic"),
      cell_fill(color = "lightblue")
      ),
    locations = cells_summary(
      groups = "1960s",
      columns = vars(population),
      rows = 1)
  ) %>%
  tab_style(
    style = list(
      cell_text(style = "italic"),
      cell_fill(color = "lightgreen")
      ),
    locations = cells_summary(
      groups = "1960s",
      columns = vars(population),
      rows = 2)
  )

# }