06-table-option-functions.Rmd

---
title: "Using Table Option Functions"
output: html_document
---

```{r setup, include=FALSE}
knitr::opts_chunk$set(echo = TRUE)
library(gt)
library(tidyverse)
```

## Intro

With the `opt_*()` functions, we have an easy way to set commonly-used table options without having to use `tab_options()` directly. For instance, we can modify the set of marks to use with footnotes, turn on row striping, change the alignment of the table header, and much more.

------

Important functions in this module:

- `opt_footnote_marks()`
- `opt_row_striping()`
- `opt_align_table_header()`
- `opt_all_caps()`
- `opt_table_lines()`
- `opt_table_outline()`
- `opt_table_font()`
- `opt_css()`

Helpers for specifying fonts:

- `google_font()`
- `default_fonts()`

Information function:

- `info_google_fonts()`

------

### `opt_footnote_marks()`: Modify the set of footnote marks

``` r
opt_footnote_marks(
  data,
  marks
)
```

Alter the footnote marks for any footnotes that may be present in the table. Either a vector of marks can be provided (including Unicode characters), or, a specific keyword could be used to signify a preset sequence.

##### EXAMPLES

Use `sza` to create a **gt** table, adding three footnotes. Call `opt_footnote_marks()` to specify which footnote marks to use.

```{r}
sza %>%
  dplyr::select(latitude, tst, sza) %>%
  dplyr::filter(!is.na(sza)) %>%
  dplyr::group_by(latitude, tst) %>%
  dplyr::summarize(
    SZA.Max = max(sza, na.rm = TRUE),
    SZA.Min = min(sza, na.rm = TRUE), .groups = "drop"
  ) %>%
  dplyr::filter(latitude == 30, !is.infinite(SZA.Min)) %>%
  dplyr::select(-latitude) %>%
  gt(rowname_col = "tst") %>%
  tab_spanner_delim(delim = ".") %>%
  tab_stubhead("TST") %>%
  tab_footnote(
    footnote = "True solar time.",
    locations = cells_stubhead()
  ) %>%
  tab_footnote(
    footnote = "Solar zenith angle.",
    locations = cells_column_spanners(spanners = "SZA")
  ) %>%
  tab_footnote(
    footnote = "The Lowest SZA.",
    locations = cells_body(columns = everything(), rows = "1200")
  ) %>%
  opt_footnote_marks(marks = "standard")
```

------

### `opt_row_striping()`: Option to add or remove row striping

``` r
opt_row_striping(
  data,
  row_striping = TRUE
)
```

By default, a **gt** table does not have row striping enabled. However, this function allows us to easily enable or disable striped rows in the table body.

##### EXAMPLE

Use `exibble` to create a **gt** table with a number of table parts added. Next, we add row striping to every second row with the `opt_add_row_striping()` function.

```{r}
exibble %>%
  gt(rowname_col = "row", groupname_col = "group") %>%
  summary_rows(
    groups = "grp_a",
    columns = c(num, currency),
    fns = list(
      min = ~min(., na.rm = TRUE),
      max = ~max(., na.rm = TRUE)
    )) %>%
  grand_summary_rows(
    columns = currency,
    fns = list(
      total = ~sum(., na.rm = TRUE)
    )) %>%
  tab_source_note(source_note = "This is a source note.") %>%
  tab_footnote(
    footnote = "This is a footnote.",
    locations = cells_body(columns = 1, rows = 1)
  ) %>%
  tab_header(
    title = "The title of the table",
    subtitle = "The table's subtitle"
  ) %>%
  opt_row_striping()
```

------

### `opt_align_table_header()`: Option to align the table header

``` r
opt_align_table_header(
  data,
  align = c("left", "center", "right")
)
```

By default, a table header added to a **gt** table has center alignment for both the title and the subtitle elements. This function allows us to easily set the horizontal alignment of the title and subtitle to the left or right by using the `"align"` argument.

##### EXAMPLE

Use `exibble` to create a **gt** table with a number of table parts added. The header (consisting of the title and the subtitle) are to be aligned to the left with the `opt_align_table_header()` function.

```{r}
exibble %>%
  gt(rowname_col = "row", groupname_col = "group") %>%
  summary_rows(
    groups = "grp_a",
    columns = c(num, currency),
    fns = list(
      min = ~min(., na.rm = TRUE),
      max = ~max(., na.rm = TRUE)
    )) %>%
  grand_summary_rows(
    columns = currency,
    fns = list(
      total = ~sum(., na.rm = TRUE)
    )) %>%
  tab_source_note(source_note = "This is a source note.") %>%
  tab_footnote(
    footnote = "This is a footnote.",
    locations = cells_body(columns = 1, rows = 1)
  ) %>%
  tab_header(
    title = "The title of the table",
    subtitle = "The table's subtitle"
  ) %>%
  opt_align_table_header(align = "left")
```

------

### `opt_all_caps()`: Option to use all caps in select table locations

```r
opt_all_caps(
  data,
  all_caps = TRUE,
  locations = c("column_labels", "stub", "row_group")
)
```

Sometimes an all-capitalized look is suitable for a table. With the `opt_all_caps()` function, we can transform characters in the column labels, the stub, and in all row groups in this way (and there's control over which of these locations are transformed).

##### EXAMPLE

Use `exibble` to create a **gt** table with a number of table parts added. All text in the column labels, the stub, and in all row groups is to be transformed to all caps using `opt_all_caps()`.

```{r}
exibble %>%
  gt(rowname_col = "row", groupname_col = "group") %>%
  summary_rows(
    groups = "grp_a",
    columns = c(num, currency),
    fns = list(
      min = ~min(., na.rm = TRUE),
      max = ~max(., na.rm = TRUE)
    )) %>%
  grand_summary_rows(
    columns = currency,
    fns = list(
      total = ~sum(., na.rm = TRUE)
    )) %>%
  tab_source_note(source_note = "This is a source note.") %>%
  tab_footnote(
    footnote = "This is a footnote.",
    locations = cells_body(columns = 1, rows = 1)
  ) %>%
  tab_header(
    title = "The title of the table",
    subtitle = "The table's subtitle"
  ) %>%
  opt_all_caps()
```

------

### `opt_table_lines()`: Option to set table lines to different extents

``` r
opt_table_lines(
  data,
  extent = c("all", "none", "default")
)
```

The `opt_table_lines()` function sets table lines in one of three possible ways: (1) all possible table lines drawn (`"all"`), (2) no table lines at all (`"none"`), and (3) resetting to the default line styles (`"default"`). This is great if you want to start off with lots of lines and subtract just a few of them with `tab_options()` or `tab_style()`. Or, use it to start with a completely lineless table, adding individual lines as needed.

##### EXAMPLE

Use `exibble` to create a gt table with a number of table parts added. Then, use the `opt_table_lines()` function to haves lines everywhere there can possibly be lines.

```{r}
exibble %>%
  gt(rowname_col = "row", groupname_col = "group") %>%
  summary_rows(
    groups = "grp_a",
    columns = c(num, currency),
    fns = list(
      min = ~min(., na.rm = TRUE),
      max = ~max(., na.rm = TRUE)
    )) %>%
  grand_summary_rows(
    columns = currency,
    fns = list(
      total = ~sum(., na.rm = TRUE)
    )) %>%
  tab_source_note(source_note = "This is a source note.") %>%
  tab_footnote(
    footnote = "This is a footnote.",
    locations = cells_body(columns = 1, rows = 1)
  ) %>%
  tab_header(
    title = "The title of the table",
    subtitle = "The table's subtitle"
  ) %>%
  opt_table_lines()
```

------

### `opt_table_outline()`: Option to wrap an outline around the entire table

``` r
opt_table_outline(
  data,
  style = "solid",
  width = px(3),
  color = "#D3D3D3"
)
```

This function puts an outline of consistent `style`, `width`, and `color` around the entire table. It'll write over any existing outside lines so long as the `width` is larger that of the existing lines. The default value of `style` (`"solid"`) will draw a solid outline, whereas a value of `"none"` will remove any present outline.

##### EXAMPLE

Use `exibble` to create a **gt** table with a number of table parts added. Have an outline wrap around the entire table by using `opt_table_outline()`.

```{r}
exibble %>%
  gt(rowname_col = "row", groupname_col = "group") %>%
  summary_rows(
    groups = "grp_a",
    columns = c(num, currency),
    fns = list(
      min = ~min(., na.rm = TRUE),
      max = ~max(., na.rm = TRUE)
    )) %>%
  grand_summary_rows(
    columns = currency,
    fns = list(
      total = ~sum(., na.rm = TRUE)
    )) %>%
  tab_source_note(source_note = "This is a source note.") %>%
  tab_footnote(
    footnote = "This is a footnote.",
    locations = cells_body(columns = 1, rows = 1)
  ) %>%
  tab_header(
    title = "The title of the table",
    subtitle = "The table's subtitle"
  ) %>%
  opt_table_outline()
```

------

### `opt_table_font()`: Option to define a custom font for the table

``` r
opt_table_font(
  data,
  font,
  weight = NULL,
  style = NULL,
  add = TRUE
)
```

The `opt_table_font()` function makes it possible to define a custom font for the entire **gt** table. The standard fallback fonts are still set by default but the font defined here will take precedence. You could still have different fonts in select locations in the table, and for that you would need
to use `tab_style()` in conjunction with the `cell_text()` helper function.

##### EXAMPLES

Use `sp500` to create a small gt table, using `fmt_currency()` to provide a dollar sign for the first row of monetary values; then, set a larger font size for the table and use the `Merriweather` font (from Google Fonts, via `google_font()`) with two font fallbacks (`Cochin` and the catchall `Serif` group).

```{r}
sp500 %>%
  dplyr::slice(1:10) %>%
  dplyr::select(-volume, -adj_close) %>%
  gt() %>%
  fmt_currency(
    columns = 2:5,
    rows = 1,
    currency = "USD",
    use_seps = FALSE
  ) %>%
  tab_options(table.font.size = px(18)) %>%
  opt_table_font(
    font = list(google_font(name = "Merriweather"), "Cochin", "Serif")
  )
```

Use `sza` to create an eleven-row table; within `opt_table_font()`, set up a preferred list of sans-serif fonts that are commonly available in macOS and Windows (using part of the `default_fonts()` vector as a fallback).

```{r}
sza %>%
  dplyr::filter(
    latitude == 20 &
      month == "jan" &
      !is.na(sza)
  ) %>%
  dplyr::select(-latitude, -month) %>%
  gt() %>%
  opt_table_font(
    font = c(
      "Helvetica Neue", "Segoe UI",
      default_fonts()[-c(1:3)]
    )
  ) %>%
  opt_all_caps()
```

------

### `opt_css()`: Option to add custom CSS for the table

``` r
opt_css(
  data,
  css,
  add = TRUE,
  allow_duplicates = FALSE
)
```

The `opt_css()` function makes it possible to add CSS to a **gt** table. This CSS will be added after the compiled CSS that **gt** generates automatically when the object is transformed to an HTML output table. You can supply `css` as a vector of lines or as a single string.

##### EXAMPLES

Let's use `exibble` to create a two-column table with some formatting applied.

```{r}
exibble %>%
  dplyr::select(num, currency) %>%
  gt() %>%
  fmt_currency(
    columns = currency,
    currency = "HKD"
  ) %>%
  fmt_scientific(
    columns = num
  )
```

Let's add some CSS rules with `opt_css()`. First, we need to provide an explicit `id` for the table, and we specify that in the `gt()` function (here as `"one"`). Then, we add three CSS rules that act on the `#one .gt_table`, `#one .gt_row`, and `#one .gt_col_heading` selectors.

How do we discover which rules to use and which selectors to target? Use the browser's developer tools. You can right-click and `Inspect Element` on a rendered table. Each browser's interface for this will be a bit different but the idea will be the same. Experiment with changing values, adding rules, deactivating rules, and using `!important` in some case (to make your rule override). Below is an example with rules set in `opt_css()`.

```{r}
exibble %>%
  dplyr::select(num, currency) %>%
  gt(id = "one") %>%
  fmt_currency(
    columns = currency,
    currency = "HKD"
  ) %>%
  fmt_scientific(columns = num) %>%
  opt_css(
    css = "
  #one .gt_table {
    background-color: skyblue;
  }
  #one .gt_row {
    padding: 20px 30px;
  }
  #one .gt_col_heading {
    text-align: center !important;
  }
  "
  )
```

------

### SUMMARY

1. Specify the type or sequence of footnote marks with `opt_footnote_marks()` (e.g., letters, LETTERS, `"standard"`, `"extended"`).
2. Optionally add row striping to the data rows with the easy-to-use `opt_row_striping()` function.
3. The title and subtitle in the header can be aligned with `opt_align_table_header()`.
4. Get your surrounding labels (column labels, row group labels, and stub) capitalized with `opt_all_caps()`.
5. Get minimal or maximal with table lines by using `opt_table_lines()`.
6. Add a table outline (or remove it) with `opt_table_outline()`.
7. Choose a table font with `opt_table_font()`: goes well with `google_font()` (info available in `info_google_fonts()`).
8. Hack the table CSS (from HTML tables) with `opt_css()`; advanced stuff but you may one day need it.