3  Publication design

Tables are common is scientific publications but usually rather minimalist design is preferred. Such tables are not only easy to read but also easy to create with the {gt} package - a perfect occasion for the first table of this tutorial. For the demonstration purposes, we will summarize δ13C measurement by families and countries.

veg_summarized <- dat_vegetation |> 
    group_by(family, country, type) |>
    summarize(
      n_plants = n(), # number of underlying measurements
      mean_d = mean(delta),
      sd_d = sd(delta),
      ) |> 
    ungroup()

3.1 Simplest table

Displaying a data frame as a gt table is a straightforward process and the default design is pleasing. However, our table will require some additional formatting to satisfy taxonomical and scietific conventions given by the data.

tbl_plain <- veg_summarized |> 
  gt() |> 
  tab_options(table.width = px(800))
family country type n_plants mean_d sd_d
Acanthaceae Kenya C<sub>3</sub> 1 -27.00000 NA
Amaranthaceae Kenya C<sub>3</sub> 1 -29.90000 NA
Asclepiadaceae Kenya C<sub>3</sub> 1 -28.10000 NA
Balinitaceae Kenya C<sub>3</sub> 2 -28.60000 0.8485281
Bignoniaceae Kenya C<sub>3</sub> 1 -28.90000 NA
Boraginaceae Kenya C<sub>3</sub> 2 -25.50000 0.8485281
Burseraceae Kenya C<sub>3</sub> 3 -28.70000 1.9157244
Caesalpiniaceae Democratic Republic of the Congo C<sub>3</sub> 2 -32.35000 1.9091883
Capparaceae Kenya C<sub>3</sub> 4 -27.67500 2.2276669
Combretaceae Kenya C<sub>3</sub> 1 -25.90000 NA
Connaraceae Democratic Republic of the Congo C<sub>3</sub> 1 -34.50000 NA
Cucurbitaceae Kenya C<sub>3</sub> 1 -27.50000 NA
Cyperaceae Mongolia C<sub>3</sub> 1 -27.60000 NA
Ebenaceae Democratic Republic of the Congo C<sub>3</sub> 1 -32.10000 NA
Euphorbiaceae Democratic Republic of the Congo C<sub>3</sub> 1 -33.40000 NA
Euphorbiaceae Kenya C<sub>3</sub> 2 -27.25000 0.2121320
Flacourtiaceae Democratic Republic of the Congo C<sub>3</sub> 2 -34.85000 0.7778175
Flacourtiaceae Kenya C<sub>3</sub> 1 -26.30000 NA
Gramineae Argentina C<sub>3</sub> 24 -27.61667 1.8438303
Gramineae Democratic Republic of the Congo C<sub>3</sub> 1 -32.20000 NA
Gramineae Kenya C<sub>4</sub> 55 -12.10545 1.0700326
Gramineae Mongolia C<sub>3</sub> 5 -24.82000 1.6006249
Labiatae Kenya C<sub>3</sub> 1 -28.30000 NA
Leguminosae Kenya C<sub>3</sub> 16 -27.03125 1.6886755
Malvaceae Kenya C<sub>3</sub> 2 -26.85000 1.7677670
Maranthaceae Democratic Republic of the Congo C<sub>3</sub> 2 -36.35000 0.2121320
Palmae Kenya C<sub>3</sub> 2 -25.90000 1.5556349
Papilionaceae Kenya C<sub>3</sub> 1 -28.60000 NA
Pedaliaceae Kenya C<sub>3</sub> 1 -28.10000 NA
Rhamnaceae Kenya C<sub>3</sub> 2 -27.40000 1.9798990
Rubiaceae Democratic Republic of the Congo C<sub>3</sub> 1 -33.00000 NA
Rubiaceae Kenya C<sub>3</sub> 1 -27.90000 NA
Salvadoraceae Kenya C<sub>3</sub> 6 -27.15000 1.3546217
Solanaceae Kenya C<sub>3</sub> 2 -27.50000 0.5656854
Sterculiaceae Democratic Republic of the Congo C<sub>3</sub> 1 -36.00000 NA
Tiliaceae Kenya C<sub>3</sub> 1 -27.50000 NA
Urticaceae Democratic Republic of the Congo C<sub>3</sub> 1 -34.90000 NA
Urticaceae Kenya C<sub>3</sub> 1 -28.20000 NA
Violaceae Democratic Republic of the Congo C<sub>3</sub> 1 -34.40000 NA

3.2 Scientific and other formatting

We will choose if there are any columns we would like to hide - here the n_plants which we introduced as helper column to control conditional formatting (in Section 3.4). We take advantage of sub_missing() function which helps us to handle missing values (NAs) according to our preference without the need to modify the input data directly or by introducing a helper column.

With tab_style() we can easily italicize an entire column and with cols_label() we can turn existing variable names into a meaningful and appealing column labels. When setting up a spanner over the numerical columns, we use markdown to achieve proper formatting. fmt_number() makes common number formatting options a simple task - we use to control number of decimal places.

tbl_formatted <- tbl_plain |>
    # this is only a helper column used for conditional formatting and it should not be displayed in the final table
    cols_hide("n_plants") |>
    # replace default NA values with a "-"
    # Note: modifying the data with {dplyr} functions would work equally well but {gt} has a devoted function for this purpose
    sub_missing(columns = "sd_d", missing_text = "-") |>
    tab_style(style = list(
        cell_text(style = "italic")),
    # family names in italics
    locations = cells_body(columns = "family")
    ) |> 
    # ^13^ is markdown for superscript, &delta is html for lower case Greek delta
    tab_spanner(columns = contains("_d"), label = md("&delta;^13^C")) |> 
    cols_label(
        family = "Family",
        country = "Country",
        type = "Type",
        mean_d = "Mean", 
        sd_d = "SD"
    ) |> 
    fmt_markdown(columns = c("type")) |> 
    fmt_number(columns = c("mean_d", "sd_d"), decimals = 2)
Providing columns to formatting functions

The {gt} packages comes with a number of very useful functions to control formatting of common data types, such as fmt_number(), fmt_percent(), fmt_datetime() and many more. Another useful function is to allow markdown in specified columns: fmt_markdown(). These are most effectively combined with {tidyverse} search terms such as contains(), matches(), starts_with() or ends_with().

In the code chunk above, instead of providing full column names

fmt_number(columns = c("mean_d", "sd_d"), decimals = 2)

we can achieve the same outcome with:

# previous code
    fmt_markdown(columns = c("type")) |> 
    fmt_number(columns = ends_with("_d"), decimals = 2)
Family Country Type
δ13C
Mean SD
Acanthaceae Kenya C3 −27.00 -
Amaranthaceae Kenya C3 −29.90 -
Asclepiadaceae Kenya C3 −28.10 -
Balinitaceae Kenya C3 −28.60 0.85
Bignoniaceae Kenya C3 −28.90 -
Boraginaceae Kenya C3 −25.50 0.85
Burseraceae Kenya C3 −28.70 1.92
Caesalpiniaceae Democratic Republic of the Congo C3 −32.35 1.91
Capparaceae Kenya C3 −27.68 2.23
Combretaceae Kenya C3 −25.90 -
Connaraceae Democratic Republic of the Congo C3 −34.50 -
Cucurbitaceae Kenya C3 −27.50 -
Cyperaceae Mongolia C3 −27.60 -
Ebenaceae Democratic Republic of the Congo C3 −32.10 -
Euphorbiaceae Democratic Republic of the Congo C3 −33.40 -
Euphorbiaceae Kenya C3 −27.25 0.21
Flacourtiaceae Democratic Republic of the Congo C3 −34.85 0.78
Flacourtiaceae Kenya C3 −26.30 -
Gramineae Argentina C3 −27.62 1.84
Gramineae Democratic Republic of the Congo C3 −32.20 -
Gramineae Kenya C4 −12.11 1.07
Gramineae Mongolia C3 −24.82 1.60
Labiatae Kenya C3 −28.30 -
Leguminosae Kenya C3 −27.03 1.69
Malvaceae Kenya C3 −26.85 1.77
Maranthaceae Democratic Republic of the Congo C3 −36.35 0.21
Palmae Kenya C3 −25.90 1.56
Papilionaceae Kenya C3 −28.60 -
Pedaliaceae Kenya C3 −28.10 -
Rhamnaceae Kenya C3 −27.40 1.98
Rubiaceae Democratic Republic of the Congo C3 −33.00 -
Rubiaceae Kenya C3 −27.90 -
Salvadoraceae Kenya C3 −27.15 1.35
Solanaceae Kenya C3 −27.50 0.57
Sterculiaceae Democratic Republic of the Congo C3 −36.00 -
Tiliaceae Kenya C3 −27.50 -
Urticaceae Democratic Republic of the Congo C3 −34.90 -
Urticaceae Kenya C3 −28.20 -
Violaceae Democratic Republic of the Congo C3 −34.40 -

3.3 Custom theme

A publication may contain multiple figures. Instead of repeating the same code again and potentially making the same adjustments at multiple places if we decide to make changes to the table design, we can define a custom theme once. We use {gt} function and formatting options as with a regular table but wrap all of our code into a function. In our theme, we will define font family and size for individual components of the table. We will also ensure that column headings are displayed in bold font face.

paper_gt_theme <- function(gt_table) {
  gt_table |> 
    # overall aspects such as font and padding
    tab_options(
      table.font.names = "Times New Roman",
      data_row.padding = px(6),
      heading.align = "center",
      heading.title.font.size = px(26),
      heading.subtitle.font.size = px(14),
      table_body.hlines.width = px(0)
    ) |> 
    # column labels and spanners in bold font face
    tab_style(
        style = cell_text(weight = "bold"),
        locations = cells_column_labels(everything())
    ) |> 
    tab_style(
        style = cell_text(weight = "bold"),
        locations = cells_column_spanners(spanners = everything())
    )      
}
Custom theme placement

The custom scheme contains formatting options for column spanners and the theme definition must thus come only once spanner were defined. In other case, they will remain unaffected by the custom theme.

tbl_formatted |>
  # Note: we intorduced column spanners earlier. It is important that the custom theme is used after a (all) spanner(s) were created because these are targeted by the theme
  paper_gt_theme()|>
  tab_options(table.width = px(800)) |> 
  cols_width(matches("country") ~ px(200))
Family Country Type
δ13C
Mean SD
Acanthaceae Kenya C3 −27.00 -
Amaranthaceae Kenya C3 −29.90 -
Asclepiadaceae Kenya C3 −28.10 -
Balinitaceae Kenya C3 −28.60 0.85
Bignoniaceae Kenya C3 −28.90 -
Boraginaceae Kenya C3 −25.50 0.85
Burseraceae Kenya C3 −28.70 1.92
Caesalpiniaceae Democratic Republic of the Congo C3 −32.35 1.91
Capparaceae Kenya C3 −27.68 2.23
Combretaceae Kenya C3 −25.90 -
Connaraceae Democratic Republic of the Congo C3 −34.50 -
Cucurbitaceae Kenya C3 −27.50 -
Cyperaceae Mongolia C3 −27.60 -
Ebenaceae Democratic Republic of the Congo C3 −32.10 -
Euphorbiaceae Democratic Republic of the Congo C3 −33.40 -
Euphorbiaceae Kenya C3 −27.25 0.21
Flacourtiaceae Democratic Republic of the Congo C3 −34.85 0.78
Flacourtiaceae Kenya C3 −26.30 -
Gramineae Argentina C3 −27.62 1.84
Gramineae Democratic Republic of the Congo C3 −32.20 -
Gramineae Kenya C4 −12.11 1.07
Gramineae Mongolia C3 −24.82 1.60
Labiatae Kenya C3 −28.30 -
Leguminosae Kenya C3 −27.03 1.69
Malvaceae Kenya C3 −26.85 1.77
Maranthaceae Democratic Republic of the Congo C3 −36.35 0.21
Palmae Kenya C3 −25.90 1.56
Papilionaceae Kenya C3 −28.60 -
Pedaliaceae Kenya C3 −28.10 -
Rhamnaceae Kenya C3 −27.40 1.98
Rubiaceae Democratic Republic of the Congo C3 −33.00 -
Rubiaceae Kenya C3 −27.90 -
Salvadoraceae Kenya C3 −27.15 1.35
Solanaceae Kenya C3 −27.50 0.57
Sterculiaceae Democratic Republic of the Congo C3 −36.00 -
Tiliaceae Kenya C3 −27.50 -
Urticaceae Democratic Republic of the Congo C3 −34.90 -
Urticaceae Kenya C3 −28.20 -
Violaceae Democratic Republic of the Congo C3 −34.40 -

3.4 Conditional row formatting

We take the existing, formatted table a little further. In some families, the number of measured species was low and we will use this information for conditional formatting of the affected rows. We will also include a table footnote to explain the formatting right in place.

We stored the previous table as a gt table and we will take advantage of it. We can add additional formatting options to existing gt object which is more elegant and less error-prone than copy-pasting of longer pieces of code.

We take advantage of n_plants “helper column” to grey out families with less than three measurements, with tab_footnote() we can easily provide more details about meaning of the formatting options.

tbl_publication_conditional <- tbl_formatted |>
  paper_gt_theme() |>
  # families with less than three measurements in grey
  tab_style(style = list(
    cell_text(color = "grey50")
    ),
    locations = cells_body(columns = everything(),
                           rows = n_plants < 3)
    ) |> 
  # conditional formatting was introduced and it should be explained - a table footnote is a good place to do so
  tab_footnote(footnote = md(paste(folio_footnote, "<br>", 
                                   "Families which have less than three measurements are greyed out."))) |> 
  tab_style(style = cell_text(align = "left"), locations = cells_footnotes())
Table 3.1
Family Country Type
δ13C
Mean SD
Acanthaceae Kenya C3 −27.00 -
Amaranthaceae Kenya C3 −29.90 -
Asclepiadaceae Kenya C3 −28.10 -
Balinitaceae Kenya C3 −28.60 0.85
Bignoniaceae Kenya C3 −28.90 -
Boraginaceae Kenya C3 −25.50 0.85
Burseraceae Kenya C3 −28.70 1.92
Caesalpiniaceae Democratic Republic of the Congo C3 −32.35 1.91
Capparaceae Kenya C3 −27.68 2.23
Combretaceae Kenya C3 −25.90 -
Connaraceae Democratic Republic of the Congo C3 −34.50 -
Cucurbitaceae Kenya C3 −27.50 -
Cyperaceae Mongolia C3 −27.60 -
Ebenaceae Democratic Republic of the Congo C3 −32.10 -
Euphorbiaceae Democratic Republic of the Congo C3 −33.40 -
Euphorbiaceae Kenya C3 −27.25 0.21
Flacourtiaceae Democratic Republic of the Congo C3 −34.85 0.78
Flacourtiaceae Kenya C3 −26.30 -
Gramineae Argentina C3 −27.62 1.84
Gramineae Democratic Republic of the Congo C3 −32.20 -
Gramineae Kenya C4 −12.11 1.07
Gramineae Mongolia C3 −24.82 1.60
Labiatae Kenya C3 −28.30 -
Leguminosae Kenya C3 −27.03 1.69
Malvaceae Kenya C3 −26.85 1.77
Maranthaceae Democratic Republic of the Congo C3 −36.35 0.21
Palmae Kenya C3 −25.90 1.56
Papilionaceae Kenya C3 −28.60 -
Pedaliaceae Kenya C3 −28.10 -
Rhamnaceae Kenya C3 −27.40 1.98
Rubiaceae Democratic Republic of the Congo C3 −33.00 -
Rubiaceae Kenya C3 −27.90 -
Salvadoraceae Kenya C3 −27.15 1.35
Solanaceae Kenya C3 −27.50 0.57
Sterculiaceae Democratic Republic of the Congo C3 −36.00 -
Tiliaceae Kenya C3 −27.50 -
Urticaceae Democratic Republic of the Congo C3 −34.90 -
Urticaceae Kenya C3 −28.20 -
Violaceae Democratic Republic of the Congo C3 −34.40 -
Data source: vegetation data from the {folio} package
Families which have less than three measurements are greyed out.

3.5 Default table processing by Quarto

Table processing in Quarto

Quarto, by default, applies a Bootstrap CSS class (table-striped) to tables generated from code chunks, which introduces row stripping in HTML tables. Row stripping is not common in publications and we thus turn it off in the code chunk below (with html-table-processing: "none") to show how a final publication-ready table might look like.

Table 3.2
Family Country Type
δ13C
Mean SD
Acanthaceae Kenya C3 −27.00 -
Amaranthaceae Kenya C3 −29.90 -
Asclepiadaceae Kenya C3 −28.10 -
Balinitaceae Kenya C3 −28.60 0.85
Bignoniaceae Kenya C3 −28.90 -
Boraginaceae Kenya C3 −25.50 0.85
Burseraceae Kenya C3 −28.70 1.92
Caesalpiniaceae Democratic Republic of the Congo C3 −32.35 1.91
Capparaceae Kenya C3 −27.68 2.23
Combretaceae Kenya C3 −25.90 -
Connaraceae Democratic Republic of the Congo C3 −34.50 -
Cucurbitaceae Kenya C3 −27.50 -
Cyperaceae Mongolia C3 −27.60 -
Ebenaceae Democratic Republic of the Congo C3 −32.10 -
Euphorbiaceae Democratic Republic of the Congo C3 −33.40 -
Euphorbiaceae Kenya C3 −27.25 0.21
Flacourtiaceae Democratic Republic of the Congo C3 −34.85 0.78
Flacourtiaceae Kenya C3 −26.30 -
Gramineae Argentina C3 −27.62 1.84
Gramineae Democratic Republic of the Congo C3 −32.20 -
Gramineae Kenya C4 −12.11 1.07
Gramineae Mongolia C3 −24.82 1.60
Labiatae Kenya C3 −28.30 -
Leguminosae Kenya C3 −27.03 1.69
Malvaceae Kenya C3 −26.85 1.77
Maranthaceae Democratic Republic of the Congo C3 −36.35 0.21
Palmae Kenya C3 −25.90 1.56
Papilionaceae Kenya C3 −28.60 -
Pedaliaceae Kenya C3 −28.10 -
Rhamnaceae Kenya C3 −27.40 1.98
Rubiaceae Democratic Republic of the Congo C3 −33.00 -
Rubiaceae Kenya C3 −27.90 -
Salvadoraceae Kenya C3 −27.15 1.35
Solanaceae Kenya C3 −27.50 0.57
Sterculiaceae Democratic Republic of the Congo C3 −36.00 -
Tiliaceae Kenya C3 −27.50 -
Urticaceae Democratic Republic of the Congo C3 −34.90 -
Urticaceae Kenya C3 −28.20 -
Violaceae Democratic Republic of the Congo C3 −34.40 -
Data source: vegetation data from the {folio} package
Families which have less than three measurements are greyed out.