gt A grammar of Tables

gt

- Table data is modified with dplyr, tidyr, etc.

- The gt_object is modified using functions from the gt package

- Default output is HTML

- Output can be changed to LaTeX, RTF, and Word format

Step 1 - create a tibble that you want to transform to a table

T1 <- diamonds |> 
  group_by(cut, color) |>  
  summarise(price_median = median(price),
            price_iqr   = IQR(price),
            mm3_mean = mean(x*y*z),
            mm3_sd   = sd(x*y*z),
            n = n()) |> 
  mutate(n_freq = n / sum(n)) |> 
  ungroup() |> 
  mutate(n_freq_tot = n / sum(n)) |> 
  arrange(cut, color) 

Step 1 - create a tibble that you want to transform to a table

For better overview on the slides:

cut %in% c("Fair", "Ideal") & color %in% c("D", "G")

T1 <- diamonds |> 
  group_by(cut, color) |>  
  summarise(price_median = median(price),
            price_iqr   = IQR(price),
            mm3_mean = mean(x*y*z),
            mm3_sd   = sd(x*y*z),
            n = n()) |> 
  mutate(n_freq = n / sum(n)) |> 
  ungroup() |> 
  mutate(n_freq_tot = n / sum(n)) |> 
  arrange(cut, color) |> 
  filter(cut %in% c("Fair", "Ideal") &
         color %in% c("D", "G"))

T1

# A tibble: 4 × 9
  cut   color price_median price_iqr mm3_mean mm3_sd     n n_freq n_freq_tot
  <ord> <ord>        <dbl>     <dbl>    <dbl>  <dbl> <int>  <dbl>      <dbl>
1 Fair  D            3730      2592.    146.    64.3   163  0.101    0.00302
2 Fair  G            3057      3086     161.    77.1   314  0.195    0.00582
3 Ideal D            1576      2248.     93.1   48.9  2834  0.132    0.0525 
4 Ideal G            1858.     4694.    115.    67.0  4884  0.227    0.0905 

Step 2 - pipe the tibble to gt()

Notice the effect of group_by()

T1 |> 
  gt() 

T1 |> 
  group_by(cut) |> 
  gt()

Step 2 - pipe the tibble to gt()

T1 |> 
  group_by(cut) |> 
  gt() 

T1 |> 
  group_by(cut) |> 
  gt(rowname_col = "color")

Step 3,4,5,…. Transform the gt object

The main group of functions

1. tab_ Creates or modifies parts of the overall table structure

2. fmt_ Formats the data in the table

3. col_ Modifies the Columns

4. cells_ Location helpers for targeting specific cells

5. gtsave and as_ Export functions

tab_ functions

tab_header() Add a table header

tab_spanner() Add a spanner column label

tab_spanner_delim() Create column labels and spanners via delimited names

tab_row_group() Add a row group to a gt table

tab_stubhead() Add label text to the stubhead

tab_footnote() Add a table footnote

tab_source_note() Add a source note citation

tab_style() Add custom styles to one or more cells

tab_options() Modify the table output option

tab_header and tab_source_note()

T2 <- T1 |> 
  group_by(cut) |> 
  gt(rowname_col = "color") |> 
  
  tab_header(
    title = "Price and mm3 of diamonds",
    subtitle = "Only displaying ´Fair´ and ´Ideal` cuts") |> 
  
  tab_source_note(
    source_note = "Data is from the Diamonds dataset included in the ggplot2 package") |> 
  
  tab_stubhead(
    label = "Cut Color"
  )

T2

tab_spanner()

T2 <- T2 |> 
  
  tab_spanner(
    label = "Counts and frequencies",
    columns = 7:9)

T2

tab_spanner_delim()

T2 <- T2 |> 
  
  tab_spanner_delim(
    delim = "_",
    columns = 3:6)

T2

fmt_ functions

fmt_number() Format numeric values

fmt_integer() Format values as integers

fmt_scientific() Format values to scientific notation

fmt_engineering() Format values to engineering notation

fmt_percent() Format values as a percentage

fmt_currency() Format values as currencies

fmt_bytes() Format values as bytes

fmt_date() Format values as dates

fmt_time() Format values as times

fmt_datetime() Format values as date-times

fmt_markdown() Format Markdown text

fmt_passthrough() Format by simply passing data through

fmt_missing() Format missing values

col_ functions

The cols_*() functions allow for modifications that act on entire columns.

cols_align() Set the alignment of columns

cols_width() Set the widths of columns

cols_label() Relabel one or more columns

cols_move_to_start() Move one or more columns to the start

cols_move_to_end() Move one or more columns to the end

cols_move() Move one or more columns

cols_hide() Hide one or more columns

cols_unhide() Unhide one or more columns

cols_merge_range() Merge two columns to a value range column

cols_merge_uncert() Merge two columns to a value & uncertainty column

cols_merge_n_pct() Merge two columns to combine counts and percentages

cols_merge() Merge data from two or more columns to a single column

col_merge_n_pct() and cols_label()

T4 <- T3 |> 
  
  cols_merge_n_pct(
    col_n = n,
    col_pct = n_freq) |> 
  
  cols_label(
    n = "n (% of group)") |> 
  
  cols_label(
    n_freq_tot = "% of total")

T4

cells_ and other helper functions

md() Interpret input text as Markdown-formatted text

The various cells_*() functions are used for targeting cells with the locations = argument in the tab_footnote(), tab_style(), and text_transform() functions.

cells_title() Location helper for targeting the table title and subtitle

cells_stubhead() Location helper for targeting the table stubhead cell

cells_column_spanners() Location helper for targeting the column spanners

cells_column_labels() Location helper for targeting the column labels

cells_row_groups() Location helper for targeting row groups

cells_stub() Location helper for targeting cells in the table stub

cells_body() Location helper for targeting data cells in the table body

cells_summary() Location helper for targeting group summary cells

cells_grand_summary() Location helper for targeting cells in a grand summary

cells_stub_summary() Location helper for targeting the stub cells in a summary

cells_stub_grand_summary() Location helper for targeting the stub cells in a grand summary

cells_footnotes() Location helper for targeting the footnotes

cells_source_notes() Location helper for targeting the source notes

md()

T5 <- T4 |> 
  
  tab_header(
    title = md("**Price and mm<sup>3</sup> of diamonds**"),
    subtitle = md("Only displaying *Fair* and *Ideal* cuts"))

T5

tab_footnote() and cells_body()

T6 <- T5 |> 
  
  tab_footnote(
    footnote = md("**OMG** this is a ***CHEAP*** *median price*!!!!"),
    locations = cells_body(
      columns = price_median,
      rows = cut == "Ideal" & price_median < 3000))

T6

tab_footnote() and cells_column_labels()

T7 <- T6 |> 
  
  tab_footnote(
    footnote = md("*Interquartile range*"),
    locations = cells_column_labels(
      columns = price_iqr))

T7

gtExtras themes

The package gtExtras comes with 8 different themes (HTML only)

T7 |> 
  gt_theme_538()

gtsave

HTML

gtsave(T6, 
       filename = here("tables", "table.HTML")) # HTML

Word

gtsave(T6, 
       filename = here("tables", "table.docx"))  # Word

PDF

# PDF via webshot() - read documentation [zoom = , expand = 
gtsave(T6, 
       filename = here("tables", "table.pdf"))  

As image

# Save the table as an image via webshot()
gtsave(T6, 
       filename = here("tables", "table.png"))  

Thanks!