---
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
-
-
-
# 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
Power"),
msrp = html("List
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")
```