Location helper for targeting group summary cells

cells_summary() is used to target the cells in a group summary and it is useful when applying a footnote with tab_footnote() or adding a custom style with tab_style(). The function is expressly used in each of those functions' locations argument. The 'summary' location is generated by summary_rows().

Usage

cells_summary(
  groups = everything(),
  columns = everything(),
  rows = everything()
)

Arguments

groups

Specification of row group IDs

<row-group-targeting expression> // default: everything()

The row groups to which targeting operations are constrained. This aids in targeting the summary rows that reside in certain row groups. Can either be a series of row group ID values provided in c() or a select helper function (e.g. starts_with(), ends_with(), contains(), matches(), num_range(), and everything().

columns

Columns to target

<column-targeting expression> // default: everything()

The columns to which targeting operations are constrained. Can either be a series of column names provided in c(), a vector of column indices, or a select helper function (e.g. starts_with(), ends_with(), contains(), matches(), num_range(), and everything()).

rows

Rows to target

<row-targeting expression> // default: everything()

In conjunction with columns, we can specify which of their rows should form a constraint for targeting operations. The default everything() results in all rows in columns being formatted. Alternatively, we can supply a vector of row IDs within c(), a vector of row indices, or a select helper function (e.g. starts_with(), ends_with(), contains(), matches(), num_range(), and everything()). We can also use expressions to filter down to the rows we need (e.g., [colname_1] > 100 & [colname_2] < 50).

Value

A list object with the classes cells_summary and location_cells.

Targeting cells with `columns`, `rows`, and `groups`

Targeting of summary cells is done through the groups, columns, and rows arguments. By default groups is set to everything(), which means that all available groups will be considered. Providing the ID values (in quotes) of row groups in c() will serve to constrain the targeting to that subset of groups.

The columns argument allows us to target a subset of summary 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 groups and columns are targeted, we may also target the rows of the summary. Summary cells in the stub will have ID values that 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)) that correspond to the row number of a summary row in a row group (numbering restarts with every row group).

Examples

Use a portion of the countrypops dataset to create a gt table. Add some styling to the summary data cells with tab_style(), using cells_summary() in the locations argument.

countrypops |>
  dplyr::filter(country_name == "Japan", year < 1970) |>
  dplyr::select(-contains("country")) |>
  dplyr::mutate(decade = paste0(substr(year, 1, 3), "0s")) |>
  gt(
    rowname_col = "year",
    groupname_col = "decade"
  ) |>
  fmt_number(
    columns = population,
    decimals = 0
  ) |>
  summary_rows(
    groups = "1960s",
    columns = population,
    fns = list("min", "max"),
    fmt = ~ fmt_integer(.)
  ) |>
  tab_style(
    style = list(
      cell_text(style = "italic"),
      cell_fill(color = "lightblue")
    ),
    locations = cells_summary(
      groups = "1960s",
      columns = population,
      rows = 1
    )
  ) |>
  tab_style(
    style = list(
      cell_text(style = "italic"),
      cell_fill(color = "lightgreen")
    ),
    locations = cells_summary(
      groups = "1960s",
      columns = population,
      rows = 2
    )
  )

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

Function ID

8-19

Function Introduced

v0.2.0.5 (March 31, 2020)