The tab_stubhead() function

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

car	year	hp	trq
GT	2017	647	550
458 Speciale	2015	597	398
458 Spider	2015	562	398
458 Italia	2014	562	398
488 GTB	2016	661	561

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

	year	hp	trq
GT	2017	647	550
458 Speciale	2015	597	398
458 Spider	2015	562	398
458 Italia	2014	562	398
488 GTB	2016	661	561

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

Country Code / Person		address	city	postcode
POL	CZERWINSKI, Stanisław	ul. Osinowa 129	Łódź	91-348
	MICHALSKA, Wiola	ul. Narwicka 103	Gdańsk	80-557
	ZAJĄC, Zdzisława	ul. Spokojna 139	Jastrzębie-Zdrój	44-336
	KUCHARSKA, Beatrycze	ul. Grochowa 59	Łódź	94-248
	OLSZEWSKI, Iwan	ul. Świętego Wawrzyńca 51	Poznań	60-541
DEU	KOENIG, Dieter	Fugger Strasse 76	Wesel	46485
	BRISETTE, Grégoire	Karl-Liebknecht-Strasse 88	Bruchhausen-Vilsen	27305
	BUI, Olger	Mellingburgredder 96	Erlangen	91014
	DIEDERICH, Simone	Alsterkrugchaussee 58	Leinburg	91225
	KLEIN, Daniela	Hollander Strasse 83	Netzbach	65623

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

Nitrophenol Compound	Rate constant at 298 K, in cm3 molecules−1 s−1
	OH	Cl
nitrobenzene	1.40 × 10−13	9.40 × 10−13
m-nitrotoluene	1.20 × 10−12	—
3-methyl-2-nitrophenol	3.70 × 10−12	1.40 × 10−10
2-methyl-6-nitrophenol	2.80 × 10−12	2.68 × 10−11
5-methyl-2-nitrophenol	6.70 × 10−12	1.94 × 10−11
4-methyl-2-nitrophenol	3.60 × 10−12	4.30 × 10−11
1-nitronaphthalene	7.45 × 10−12	—
2-nitronaphthalene	5.48 × 10−12	—
2-nitrophenol	—	6.80 × 10−12