fmt_chem()

The new fmt_chem() function makes it easy to format chemical formulas or even chemical reactions in the table body. You might have single compounds that need formatting (e.g., "C2H4O", for acetaldehyde), or, there could be a need to format chemical reactions (e.g., ⁠"2CH3OH -> CH3OCH3 + H2O"⁠). There’s a lot that fmt_chem() does to make chemistry look its best in a table! Here’s an example using the new photolysis dataset:

photolysis |>
    dplyr::filter(cmpd_name %in% c(
        "hydrogen peroxide", "nitrogen dioxide",
        "nitric acid", "acetaldehyde", "methyl peroxide",
        "methyl ethyl ketone", "methacrolein", "methyl vinyl ketone",
        "n-butyraldehyde", "i-butyraldehyde"
  )) |>
  dplyr::mutate(reaction = paste(cmpd_formula, products)) |>
  dplyr::select(cmpd_name, reaction, quantum_yield) |>
  gt() |>
  tab_header(title = "Photolysis pathways of selected VOCs") |>
  fmt_chem(columns = reaction) |>
  cols_label(
    cmpd_name = "VOC",
    reaction = "Photolysis Pathway",
    quantum_yield = "Quantum Yield, {{:Phi:}}"
  ) |>
  opt_align_table_header(align = "left") |>
  sub_missing(missing_text = "unknown") |>
  tab_source_note(
    source_note = md(
        "Quantum yield is defined as: 
        $\\Phi = {\\frac {\\rm {\\#\\ molecules\\ decomposed}}
        {\\rm {\\#\\ photons\\ absorbed}}}$"
    )
  )

The upgrades to chemistry notation in gt allow for beautiful tables with chemical data formatted to the conventions of the field. And there is much more beyond this, including:

• expression of charges with terminating "+" or "-" characters (e.g., "H+", "[AgCl2]-", "Y^{99+}", etc.)

• use of stoichiometric values (e.g., "2H2O2", "1/2 H2O", etc.)

• styling to fit conventions (e.g., "NO_x", "x Na(NH4)HPO4", "*n*-C5H12", etc.)

• formatting of chemical isotopes like this: "^{227}_{90}Th", "^{0}_{-1}n^{-}", and "^0_-1n-"

• a variety of reaction arrows: (1) "A -> B", (2) "A <- B", (3) "A <-> B", (4) "A <--> B", (5) "A <=> B", (6) "A <=>> B", or (7) "A <<=> B"

• center dots for addition compounds can be added by using a single "." or "*" as in "KCr(SO4)2 . 12 H2O" or "KCr(SO4)2 * 12 H2O"

• single and double bonds with "-" or "=" between adjacent characters; two examples: "C6H5-CHO" and "CH3CH=CH2"

• inclusion of Greek letters by surrounding the letter name with colons; here’s an example that describes the delta value of carbon-13: ":delta: ^13C"

Here’s how that all looks in a reference table:

If you have a need to include chemistry in your gt table, please try out this new functionality!

fmt_email()

While fmt_url() is a suitable function for creating links from URLs, there wasn’t a comparable formatting function for handling email addresses. We added the fmt_email() function for this task and the rendered email addresses can now interact properly with email clients on the user system.

Let’s take ten rows from the peeps dataset and create a table of contact information with mailing addresses and email addresses. With the column that contains email addresses (email_addr), we can use fmt_email() to generate ‘mailto:’ links. Clicking any of these formatted email addresses should result in new message creation (though this can depend on the OS integration with an email client).

peeps |>
  dplyr::filter(country == "AUS") |>
  dplyr::select(
    starts_with("name"),
    address, city, state_prov, postcode, country, email_addr
  ) |>
  dplyr::mutate(city = toupper(city)) |>
  gt(rowname_col = "name_family") |>
  tab_header(title = "Our Contacts in Australia") |>
  tab_stubhead(label = "Name") |>
  fmt_email(columns = email_addr) |>
  fmt_country(columns = country) |>
  cols_merge(
    columns = c(address, city, state_prov, postcode, country),
    pattern = "{1}<br>{2} {3} {4}<br>{5}"
  ) |>
  cols_merge(
    columns = c(name_family, name_given),
    pattern = "{1},<br>{2}"
  ) |>
  cols_label(
    address = "Mailing Address",
    email_addr = "Email"
  ) |>
  tab_style(
    style = cell_text(size = "x-small"),
    locations = cells_body(columns = address)
  ) |>
  opt_align_table_header(align = "left")

There are also many possibilities for further display customization like displaying the names of the email recipients instead of the email addresses (by using the from_column() helper in the display_name argument). Check out the documentation in ?fmt_email for many such examples!

fmt_country()

Tables that have data split across countries often need to have the country name included. While this seems like a fairly simple task, it really is not. Being consistent with country names can be fraught with difficulty.

This is where fmt_country() comes in. This new formatting function will supply a well-crafted country name based on a 2- or 3-letter ISO 3166-1 country code in the input. The resulting country names have been obtained from the Unicode CLDR, which is a good source since all country names are agreed upon by consensus. Furthermore, the country names can be localized/translated to any of 574 different locales via the function’s locale argument.

Let’s look at an example that uses the new films dataset. Here, fmt_country() resolves country codes in the countries_of_origin column and the function can handle multiple country codes per cell so long as they’re delimited by commas (as they are here).

films |>
  dplyr::filter(year == 1959) |>
  dplyr::select(
    title, run_time, director, countries_of_origin, imdb_url
  ) |>
  gt() |>
  tab_header(title = "Feature Films in Competition at the 1959 Festival") |>
  fmt_country(columns = countries_of_origin, sep = ", ") |>
  fmt_url(
    columns = imdb_url,
    label = fontawesome::fa("imdb", fill = "black")
  ) |>
  cols_merge(
    columns = c(title, imdb_url),
    pattern = "{1} {2}"
  ) |>
  cols_label(
    title = "Film",
    run_time = "Length",
    director = "Director",
    countries_of_origin = "Country"
  ) |>
  opt_vertical_padding(scale = 0.5) |>
  opt_horizontal_padding(scale = 2.5) |>
  opt_table_font(stack = "classical-humanist", weight = "bold") |>
  opt_stylize(style = 1, color = "gray") |>
  tab_options(heading.title.font.size = px(26))

The fmt_country() function is super powerful and can even resolve countries that no longer exist! Historical country codes like "SU" (‘USSR’), "CS" (‘Czechoslovakia’), and "YU" (‘Yugoslavia’) are resolved, which is a nice touch.

fmt_tf()

It completely escaped us that tables may contain TRUE/FALSE values (i.e., logical values) that are in need of formatting. That situation is remedied in v0.11.0 of gt with the new fmt_tf() function. With this formatter we let you resolve logicals to a number of preset (yet customizable) combinations of words or symbols.

Let’s have a look at two examples. The first is of a table of small towny towns/villages/hamlets. There are two TRUE/FALSE columns: (1) does this tiny place have a website? and (2) has the population increased? Each of these fmt_tf() calls will either produce "yes"/"no" or "up"/"down" strings (set via the tf_style option).

towny |>
  dplyr::arrange(population_2021) |>
  dplyr::mutate(website = !is.na(website))  |>
  dplyr::mutate(pop_dir = population_2021 > population_1996) |>
  dplyr::select(name, website, population_1996, population_2021, pop_dir) |>
  dplyr::slice_head(n = 10) |>
  gt(rowname_col = "name") |>
  tab_spanner(
    label = "Population",
    columns = starts_with("pop")
  ) |>
  tab_stubhead(label = "Town") |>
  fmt_tf(
    columns = website,
    tf_style = "yes-no",
    auto_align = FALSE
  ) |>
  fmt_tf(
    columns = pop_dir,
    tf_style = "up-down",
    pattern = "It's {x}."
  ) |>
  cols_label_with(
    columns = starts_with("population"),
    fn = function(x) sub("population_", "", x)
  ) |>
  cols_label(
    website = md("Has a  \n website?"),
    pop_dir = "Pop. direction?"
  ) |>
  opt_horizontal_padding(scale = 2)

Like the fmt_country() function (and many others previously added), fmt_tf() has a locale argument for localizing any word-based formatting outputs to a wide range of languages.

Here’s another example, this time using up and down arrow icons. The premise is that a logical value could denote whether something increased or decreased. In the case of this sp500 data, it’ll be shown whether the daily close price was higher than the open price. We can even assign colors to the arrows through the colors argument (super useful).

sp500 |>
  dplyr::filter(date >= "2013-01-07" & date <= "2013-01-12") |>
  dplyr::arrange(date) |>
  dplyr::select(-c(adj_close, volume, high, low)) |>
  gt(rowname_col = "date") |>
  cols_add(dir = close > open, .after = open) |>
  fmt_tf(
    columns = dir,
    tf_style = "arrows",
    colors = c("green", "red")
  ) |>
  fmt_currency(columns = c(open, close)) |>
  cols_label(
    open = "Opening",
    close = "Closing",
    dir = ""
  )

This type of formatting can help provide quicker insights into the data and we’re hoping you’ll find it useful for some of your table-making tasks.

In closing

There’s so much great new stuff in gt so try out v0.11.0 and let us know what you think! Talk with us by filing an issue, or ask us anything in the GitHub Discussions.

You can keep up with us by following the engaging @gt_package account on X/Twitter! There’s also a Discord server, and we do like to talk tables there, so join us!