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

In rstudio/gt: Easily Create Presentation-Ready Display Tables

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 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"))

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")

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")
  )

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")
  )

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)

See Also

Other part creation/modification functions: tab_caption(), tab_footnote(), tab_header(), tab_info(), tab_options(), tab_source_note(), tab_spanner(), tab_spanner_delim(), tab_stub_indent(), tab_stubhead(), tab_style(), tab_style_body()

rstudio/gt documentation built on Dec. 2, 2024, 11:05 a.m.