basic-features.Rmd

---
title: "GT Demo - basic features"
author: "John D. Smith"
date: "10/16/2020"
output: html_document
---

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

# Resources

-   <https://blog.rstudio.com/2020/04/08/great-looking-tables-gt-0-2/>
-   <https://gt.rstudio.com/>
-   <https://gt.rstudio.com/reference/index.html>

# Is it really a *grammar*?

Tables are very complex and seem under-theorized (Wilkinson's Grammar of Graphics [book](https://isbn.nu/0387987746) really describes a **theory**). Whether we have a theory of tables might be debatable. There may be formal definitions of a grammar, but from a practical point of view, a grammar is internalized through use and hopefully becomes invisible when we *think in the grammar's language.*

Nice features of `gt` include:

-   Ability to build tables by chaining functions with the `%>%` pipe

-   An intuitive naming of functions starting with the following roots:

    -   `tab_`
    -   `fmt_`
    -   `cols_`
    -   `cels_`
    -   `opt_`
    -   `info_`

-   Heavy reliance on `tidyverse` functions

A grammar is something you can learn (even if it's difficult) but becomes so intuitive that we become unaware of using it. That level of familiarity seems far off to me.

# Demo Set up

## Load libraries

```{r, message=FALSE}
suppressPackageStartupMessages(library(tidyverse))
library(gt)
```

This demo meanders from the outside and top of a table and works its way in.

![](img/gt_parts_of_a_table.svg)

## `gtcars` is a handy demo table that comes with the `gt` package

```{r}
glimpse(gtcars)

```

Right off the bat: a table with 15 columns and 47 rows would be too wide and too long to be useful. Start with a US subset.

```{r}
us_cars <- gtcars %>% filter(ctry_origin == "United States")
```

# The tour

In lieu of something really cool like [Gina Reynold's flipbook setup](https://evamaerey.github.io/ggplot_flipbook/ggplot_flipbook_xaringan.html#1), we can write and re-write a `gt` object called `t.`

## A default table

15 columns is still too wide, although `gt` tries to produce something:

```{r}
t <- us_cars %>% 
  gt()
t
```

## Tidy the data before passing it to `gt`

The tidyverse norm is to shape the data, select columns and order them before passing to a special-purpose sub-language like `gt`:

```{r}
t <- us_cars %>% 
  select(mfr, model, year, bdy_style, hp, msrp) %>% 
  gt()
t
```

That replaces the `t` object. The `gt` object `t` caries a list of columns with it. It's a list of lists that gets added to step-by-step, starting with:

```{r}
str(t, max.level = 1)
```

## Add a minimal title & subtitle

The *grammar* aspect of `gt` is reminiscent of `gglot2` and takes some effort to learn.

```{r}
t <- t %>% 
  tab_header(title = "Luxury US cars", subtitle = "basic characteristics")
t
```

## Add a source note at the bottom

Once you get the hang of it, you can remember the grammar or reason by analogy.

```{r}
t <- t %>% 
  tab_source_note("source: data included in the 'gt' package")
t
```

## Replace variable names with column labels

As we'll see, some `gt` functions take a raw column name while others require the `vars()` function.

```{r}
t <- t %>% 
  cols_label(
    mfr = "Manufacturer",
    year = "Year",
    model = "Model",
    bdy_style = "Style",
    hp = "Horse Power",
    msrp = "List Price"
  )
t
```

`md()` and `html()` functions are the mechanisms for formatting text using either markdown or HTML notation, either at a column or table header level.

```{r}
t <- t %>% 
  cols_label(
    mfr = md("**Manufacturer**"),
    year = "Year",
    model = "Model",
    bdy_style = "Style",
    hp = html("Horse<br>Power"),
    msrp = html("List<br>Price")
  )
t
```

## Reordering columns

The `cols_move_to_start` and related functions require that you specify the list of columns you are referring to using the tidyverse `dplyr` functions like `vars()`, `starts_with()`, `ends_with()`, `contains()`, `matches()`, `one_of()`, or `everything()`.

```{r}
t <- t %>% 
  cols_move_to_start(columns = vars(mfr, bdy_style))
t
```

## Formatting the data in a column

All the "`fmt_*` functions require the use of the `dplyr` helper functions:

-   `fmt_currency()` - Format currency values
-   `fmt_number()` - Format numeric values
-   `fmt_scientific()` - Format values to scientific notation
-   `fmt_percent()` - Format values as a percentage
-   `fmt_date()` - Format values as dates
-   `fmt_time()` - Format values as times
-   `fmt_datetime()` - Format values as dates-times

```{r}
t <- t %>% 
  fmt_currency(columns = vars(msrp), currency =  "USD", decimals = 0)
t
```

## Save the table as html, png, latex, or rtf

```{r}
gtsave(t, "basic-demo.html")
```