R: Add label text to the stubhead

tab_stubhead {gt}

R Documentation

Add label text to the stubhead

Description

We can add a label to the stubhead of a gt table with tab_stubhead(). The stubhead is the lone part of the table that is positioned left of the column labels, and above the stub. If a stub does not exist, then there is no stubhead (so no visible change will be made when using this function in that case). We have the flexibility to use Markdown formatting for the stubhead label via the md() helper function. Furthermore, if the table is intended for HTML output, we can use HTML inside of html() for the stubhead label.

Usage

tab_stubhead(data, label)

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

Stubhead label text

⁠scalar<character>⁠ // required

The text to be used as the stubhead label. We can optionally use md() or html() to style the text as Markdown or to retain HTML elements in the text.

Value

An object of class gt_tbl.

Examples

Using a small subset of the gtcars dataset, we can create a gt table with row labels. Since we have row labels in the stub (via use of rowname_col = "model" in the gt() function call) we have a stubhead, so, let's add a stubhead label ("car") with tab_stubhead() to describe what's in the stub.

gtcars |>
  dplyr::select(model, year, hp, trq) |>
  dplyr::slice(1:5) |>
  gt(rowname_col = "model") |>
  tab_stubhead(label = "car")

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

The stuhead can contain all sorts of interesting content. How about an icon for a car? We can make this happen with help from the fontawesome package.

gtcars |>
  dplyr::select(model, year, hp, trq) |>
  dplyr::slice(1:5) |>
  gt(rowname_col = "model") |>
  tab_stubhead(label = fontawesome::fa("car"))

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

If the stub is two columns wide (made possible by using row_group_as_column = TRUE in the gt() statement), the stubhead will be a merged cell atop those two stub columns representing the row group and the row label. Here's an example of that type of situation in a table that uses the peeps dataset.

peeps |>
  dplyr::filter(country %in% c("POL", "DEU")) |>
  dplyr::group_by(country) |>
  dplyr::filter(dplyr::row_number() %in% 1:5) |>
  dplyr::ungroup() |>
  dplyr::mutate(name = paste0(toupper(name_family), ", ", name_given)) |>
  dplyr::select(name, address, city, postcode, country) |>
  gt(
    rowname_col = "name",
    groupname_col = "country",
    row_group_as_column = TRUE
  ) |>
  tab_stubhead(label = "Country Code / Person") |>
  tab_style(
    style = cell_text(transform = "capitalize"),
    locations = cells_column_labels()
  )

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

The stubhead cell and its text can be styled using tab_style() with cells_stubhead(). In this example, using the reactions dataset, we style the stubhead label so that it is vertically centered with text that is highly emboldened.

reactions |>
  dplyr::filter(cmpd_type == "nitrophenol") |>
  dplyr::select(cmpd_name, OH_k298, Cl_k298) |>
  dplyr::filter(!(is.na(OH_k298) & is.na(Cl_k298))) |>
  gt(rowname_col = "cmpd_name") |>
  tab_spanner(
    label = "Rate constant at 298 K, in {{cm^3 molecules^-1 s^-1}}",
    columns = ends_with("k298")
  ) |>
  tab_stubhead(label = "Nitrophenol Compound") |>
  fmt_scientific() |>
  sub_missing() |>
  cols_label_with(fn = function(x) sub("_k298", "", x)) |>
  cols_width(everything() ~ px(200)) |>
  tab_style(
    style = cell_text(v_align = "middle", weight = "800"),
    locations = cells_stubhead()
  )

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

Function ID

2-5

Function Introduced

v0.2.0.5 (March 31, 2020)