The gt package – gt-cols

The `cols_label()` function

Use countrypops to create a gt table. Relabel all the table’s columns with the cols_label() function to improve its presentation. In this simple case we are supplying the name of the column on the left-hand side, and the label text on the right-hand side.

countrypops |>
  dplyr::select(-contains("code")) |>
  dplyr::filter(country_name == "Mongolia") |>
  tail(5) |>
  gt() |>
  cols_label(
    country_name = "Name",
    year = "Year",
    population = "Population"
  )

Name	Year	Population
Mongolia	2017	3096030
Mongolia	2018	3163991
Mongolia	2019	3232430
Mongolia	2020	3294335
Mongolia	2021	3347782

Using countrypops again to create a gt table, we label columns just as before but this time make the column labels bold through Markdown formatting (with the md() helper function). It’s possible here to use either a = or a ~ between the column name and the label text.

countrypops |>
  dplyr::select(-contains("code")) |>
  dplyr::filter(country_name == "Mongolia") |>
  tail(5) |>
  gt() |>
  cols_label(
    country_name = md("**Name**"),
    year = md("**Year**"),
    population ~ md("**Population**")
  )

Name	Year	Population
Mongolia	2017	3096030
Mongolia	2018	3163991
Mongolia	2019	3232430
Mongolia	2020	3294335
Mongolia	2021	3347782

With the metro dataset, let’s create a small gt table with three columns. We’d like to provide column labels that have line breaks. For that, we can use <br> to indicate where the line breaks should be. We also need to use the md() helper function to signal to gt that this text should be interpreted as Markdown. Instead of calling md() on each of labels as before, we can more conveniently use the .fn argument and provide the bare function there (it will be applied to each label).

metro |>
  dplyr::select(name, lines, passengers, connect_other) |>
  dplyr::arrange(desc(passengers)) |>
  dplyr::slice_head(n = 10) |>
  gt() |>
  cols_hide(columns = passengers) |>
  cols_label(
    name = "Name of<br>Metro Station",
    lines = "Metro<br>Lines",
    connect_other = "Train<br>Services",
    .fn = md
  )

Name of Metro Station	Metro Lines	Train Services
Gare du Nord	4, 5	TGV, TER, Thalys, Eurostar
Saint-Lazare	3, 12, 13, 14	TGV, TER, Intercités
Gare de Lyon	1, 14	TGV, TGV Lyria, Renfe-SNCF, OUIGO, Frecciarossa
Montparnasse—Bienvenüe	4, 6, 12, 13	TGV, TER, Intercités, OUIGO
Gare de l'Est	4, 5, 7	TGV, TER, OUIGO, Nightjet
Bibliothèque François Mitterrand	14	NA
République	3, 5, 8, 9, 11	NA
Les Halles	4	NA
La Défense	1	NA
Châtelet	1, 4, 7, 11, 14	NA

Using towny, we can create an interesting gt table. First, only certain columns are selected from the dataset, some filtering of rows is done, rows are sorted, and then only the first 10 rows are kept. When introduced to gt(), we apply some spanner column labels through two calls of tab_spanner() all the table’s columns. Below those spanners, we want to label the columns by the years of interest. Using cols_label() and select expressions on the left side of the formulas, we can easily relabel multiple columns with common label text. Note that we cannot use an = sign in any of the expressions within cols_label(); because the left-hand side is not a single column name, we must use formula syntax (i.e., with the ~).

towny |>
  dplyr::select(
    name, ends_with("2001"), ends_with("2006"), matches("2001_2006")
  ) |>
  dplyr::filter(population_2001 > 100000) |>
  dplyr::arrange(desc(pop_change_2001_2006_pct)) |>
  dplyr::slice_head(n = 10) |>
  gt() |>
  fmt_integer() |>
  fmt_percent(columns = matches("change"), decimals = 1) |>
  tab_spanner(label = "Population", columns = starts_with("population")) |>
  tab_spanner(label = "Density", columns = starts_with("density")) |>
  cols_label(
    ends_with("01") ~ "2001",
    ends_with("06") ~ "2006",
    matches("change") ~ md("Population Change,<br>2001 to 2006")
  ) |>
  cols_width(everything() ~ px(120))

name	Population		Density		Population Change, 2001 to 2006
name	2001	2006	2001	2006	Population Change, 2001 to 2006
Brampton	325,428	433,806	1,224	1,632	33.3%
Vaughan	182,022	238,866	668	877	31.2%
Markham	208,615	261,573	989	1,240	25.4%
Barrie	103,710	128,430	1,047	1,297	23.8%
Richmond Hill	132,030	162,704	1,310	1,614	23.2%
Oakville	144,738	165,613	1,042	1,192	14.4%
Mississauga	612,925	668,599	2,094	2,284	9.1%
Cambridge	110,372	120,371	977	1,065	9.1%
Burlington	150,836	164,415	810	883	9.0%
Guelph	106,170	114,943	1,214	1,315	8.3%

The cols_label() function

The `cols_label()` function