We can create a row group from a collection of rows with the
tab_row_group()
function. 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, use the row_group_order()
function.
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. To restore
labels for row groups not explicitly assigned a group,
tab_options(row_group.default_label = "")
can be used.
Arguments
- data
The gt table data object
obj:<gt_tbl>
// requiredThis is the gt table object that is commonly created through use of the
gt()
function.- label
Row group label text
scalar<character>
// requiredThe text to use for the row group label. We can optionally use the
md()
andhtml()
functions to style the text as Markdown or to retain HTML elements in the text.- rows
Rows to target
<row-targeting expression>
// requiredThe rows to be made components of the row group. The default
everything()
results in all rows incolumns
being formatted. Alternatively, we can supply a vector of row captions withinc()
, a vector of row indices, or a select helper function. Examples of select helper functions includestarts_with()
,ends_with()
,contains()
,matches()
,one_of()
,num_range()
, andeverything()
. 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 usingtab_style()
ortab_footnote()
) theid
value is used as the reference (and not thelabel
). If anid
is not explicitly provided here, it will be taken from thelabel
value. It is advisable to set an explicitid
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 anid
value you must ensure that it is unique across all ID values set for row groups (the function will stop ifid
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
.
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 the
tab_row_group()
function, 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, the row_group_order()
function can be
used for that.
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.
See also
Other part creation/modification functions:
tab_caption()
,
tab_footnote()
,
tab_header()
,
tab_info()
,
tab_options()
,
tab_source_note()
,
tab_spanner_delim()
,
tab_spanner()
,
tab_stub_indent()
,
tab_stubhead()
,
tab_style_body()
,
tab_style()