R: Add a row group to a *gt* table

tab_row_group {gt}

R Documentation

Add a row group to a gt table

Description

We can create a row group from a collection of rows with tab_row_group(). This requires specification of the rows to be included, either by supplying row labels, row indices, or through use of a select helper function like starts_with(). To modify the order of row groups, we can use row_group_order().

To set a default row group label for any rows not formally placed in a row group, we can use a separate call to ⁠tab_options(row_group.default_label = <label>)⁠. If this is not done and there are rows that haven't been placed into a row group (where one or more row groups already exist), those rows will be automatically placed into a row group without a label.

Usage

tab_row_group(data, label, rows, id = label, others_label = NULL, group = NULL)

Arguments

`data`	The gt table data object `⁠obj:<gt_tbl>⁠` // required This is the gt table object that is commonly created through use of the `gt()` function.
`label`	Row group label text `⁠scalar<character>⁠` // required The text to use for the row group label. We can optionally use `md()` or `html()` to style the text as Markdown or to retain HTML elements in the text.
`rows`	Rows to target `⁠<row-targeting expression>⁠` // required The rows to be made components of the row group. We can supply a vector of row ID values within `c()`, a vector of row indices, or use select helpers (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⁠`).
`id`	Row group ID `⁠scalar<character>⁠` // default: `label` The ID for the row group. When accessing a row group through `cells_row_groups()` (when using `tab_style()` or `tab_footnote()`) the `id` value is used as the reference (and not the `label`). If an `id` is not explicitly provided here, it will be taken from the `label` value. It is advisable to set an explicit `id` value if you plan to access this cell in a later function call and the label text is complicated (e.g., contains markup, is lengthy, or both). Finally, when providing an `id` value you must ensure that it is unique across all ID values set for row groups (the function will stop if `id` isn't unique).
`others_label`	Deprecated Label for default row group `⁠scalar<character>⁠` // default: `NULL` (`optional`) This argument is deprecated. Instead use `⁠tab_options(row_group.default_label = <label>)⁠`.
`group`	Deprecated The group label `⁠scalar<character>⁠` // default: `NULL` (`optional`) This argument is deprecated. Instead use `label`.

Value

An object of class gt_tbl.

Examples

Using a subset of the gtcars dataset, let's create a simple gt table with row labels (from the model column) inside of a stub. This eight-row table begins with no row groups at all but with a single use of tab_row_group(), we can specify a row group that will contain any rows where the car model begins with a number.

gtcars |>
  dplyr::select(model, year, hp, trq) |>
  dplyr::slice(1:8) |>
  gt(rowname_col = "model") |>
  tab_row_group(
    label = "numbered",
    rows = matches("^[0-9]")
  )

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

This actually makes two row groups since there are row labels that don't begin with a number. That second row group is a catch-all NA group, and it doesn't display a label at all. Rather, it is set off from the other group with a double line. This may be a preferable way to display the arrangement of one distinct group and an 'others' or default group. If that's the case but you'd like the order reversed, you can use row_group_order().

gtcars |>
  dplyr::select(model, year, hp, trq) |>
  dplyr::slice(1:8) |>
  gt(rowname_col = "model") |>
  tab_row_group(
    label = "numbered",
    rows = matches("^[0-9]")
  ) |>
  row_group_order(groups = c(NA, "numbered"))

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

Two more options include: (1) setting a default label for the 'others' group (done through tab_options()), and (2) creating row groups until there are no more unaccounted for rows. Let's try the first option in the next example:

gtcars |>
  dplyr::select(model, year, hp, trq) |>
  dplyr::slice(1:8) |>
  gt(rowname_col = "model") |>
  tab_row_group(
    label = "numbered",
    rows = matches("^[0-9]")
  ) |>
  row_group_order(groups = c(NA, "numbered")) |>
  tab_options(row_group.default_label = "others")

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

The above use of the row_group.default_label in tab_options() gets the job done and provides a default label. One drawback is that the default/NA group doesn't have an ID, so it can't as easily be styled with tab_style(); however, row groups have indices and the index for the "others" group here is 1.

gtcars |>
  dplyr::select(model, year, hp, trq) |>
  dplyr::slice(1:8) |>
  gt(rowname_col = "model") |>
  tab_row_group(
    label = "numbered",
    rows = matches("^[0-9]")
  ) |>
  row_group_order(groups = c(NA, "numbered")) |>
  tab_options(row_group.default_label = "others") |>
  tab_style(
    style = cell_fill(color = "bisque"),
    locations = cells_row_groups(groups = 1)
  ) |>
  tab_style(
    style = cell_fill(color = "lightgreen"),
    locations = cells_row_groups(groups = "numbered")
  )

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

Now let's try using tab_row_group() with our gtcars-based table such that all rows are formally assigned to different row groups. We'll define two row groups with the (Markdown-infused) labels "**Powerful Cars**" and "**Super Powerful Cars**". The distinction between the groups is whether hp is lesser or greater than 600 (and this is governed by the expressions provided to the rows argument).

gtcars |>
  dplyr::select(model, year, hp, trq) |>
  dplyr::slice(1:8) |>
  gt(rowname_col = "model") |>
  tab_row_group(
    label = md("**Powerful Cars**"),
    rows = hp < 600,
    id = "powerful"
  ) |>
  tab_row_group(
    label = md("**Super Powerful Cars**"),
    rows = hp >= 600,
    id = "v_powerful"
  ) |>
  tab_style(
    style = cell_fill(color = "gray85"),
    locations = cells_row_groups(groups = "powerful")
  ) |>
  tab_style(
    style = list(
      cell_fill(color = "gray95"),
      cell_text(size = "larger")
    ),
    locations = cells_row_groups(groups = "v_powerful")
  )

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

Setting the id values for each of the row groups makes things easier since you will have clean, markup-free ID values to reference in later calls (as was done with the tab_style() invocations in the example above). The use of the md() helper function makes it so that any Markdown provided for the label of a row group is faithfully rendered.

Function ID

2-4

Function Introduced

v0.2.0.5 (March 31, 2020)