cells_body: Location helper for targeting data cells in the table body

Description

The cells_body() function is used to target the data cells in the table body. The function can be used to apply a footnote with tab_footnote(), to add custom styling with tab_style(), or the transform the targeted cells with text_transform(). The function is expressly used in each of those functions' locations argument. The 'body' location is present by default in every gt table.

Usage

cells_body(columns = everything(), rows = everything())

Value

A list object with the classes cells_body and location_cells.

Arguments

columns: The names of the columns that are to be targeted.
rows: The names of the rows that are to be targeted.

Overview of location helper functions

Location helper functions can be used to target cells with virtually any function that has a locations argument. Here is a listing of all of the location helper functions, with locations corresponding roughly from top to 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_spanners(): targets the spanner column labels with the spanners argument; spanner column labels appear above the column labels.
cells_column_labels(): targets the column labels with its columns argument.
cells_row_groups(): 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_body(): 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
cells_stub_summary(): targets summary row labels in the table stub using the groups and rows arguments.
cells_stub_grand_summary(): targets grand summary row labels in the table stub using the rows argument.
cells_footnotes(): targets all footnotes in the table footer (cannot be used with tab_footnote()).
cells_source_notes(): targets all source notes in the table footer (cannot be used with tab_footnote()).

When using any of the location helper functions with an appropriate function that has a locations argument (e.g., tab_style()), multiple locations can be targeted by enclosing several cells_*() helper functions in a list() (e.g., list(cells_body(), cells_grand_summary())).

Targeting cells with <code>columns</code> and <code>rows</code>

Targeting of values is done through columns and additionally by rows (if nothing is provided for rows then entire columns are selected). The columns argument allows us to target a subset of cells contained in the resolved columns. We say resolved because aside from declaring column names in c() (with bare column names or names in quotes) we can use tidyselect-style expressions. This can be as basic as supplying a select helper like starts_with(), or, providing a more complex incantation like

where(~ is.numeric(.x) && max(.x, na.rm = TRUE) > 1E6)

which targets numeric columns that have a maximum value greater than 1,000,000 (excluding any NAs from consideration).

Once the columns are targeted, we may also target the rows within those columns. This can be done in a variety of ways. If a stub is present, then we potentially have row identifiers. Those can be used much like column names in the columns-targeting scenario. We can use simpler tidyselect-style expressions (the select helpers should work well here) and we can use quoted row identifiers in c(). It's also possible to use row indices (e.g., c(3, 5, 6)) though these index values must correspond to the row numbers of the input data (the indices won't necessarily match those of rearranged rows if row groups are present). One more type of expression is possible, an expression that takes column values (can involve any of the available columns in the table) and returns a logical vector.

Examples

Use gtcars to create a gt table. Add a footnote that targets a single data cell with tab_footnote(), using cells_body() in locations (rows = hp == max(hp) will target a single row in the hp column).

gtcars |>
  dplyr::filter(ctry_origin == "United Kingdom") |>
  dplyr::select(mfr, model, year, hp) |>
  gt() |>
  tab_footnote(
    footnote = "Highest horsepower.",
    locations = cells_body(
      columns = hp,
      rows = hp == max(hp)
    )
  ) |>
  opt_footnote_marks(marks = c("*", "+"))

This image of a table was generated from the first code example in the `cells_body()` help file.

Function ID

8-12

Function Introduced

v0.2.0.5 (March 31, 2020)