A deep dive into Quarto

---

# Quarto

---

---

## Quarto basics

````default
---
title: "Gun deaths"
date: "`r lubridate::today()`"
format: html
---

```{r}
#| label = "setup"
#| include: false
library(tidyverse)
library(rcis)

youth <- gun_deaths %>%
  filter(age <= 65)
```

# Gun deaths by age

We have data about `` `r knitr::inline_expr("nrow(gun_deaths)")` individuals killed by guns. Only `` `r knitr::inline_expr("nrow(gun_deaths) - nrow(youth)")` are older than 65. The distribution of the remainder is shown below:

```{r}
#| label = "youth-dist"
#| echo: false
youth %>% 
  ggplot(aes(age)) + 
  geom_freqpoly(binwidth = 1)
```

# Gun deaths by race

```{r}
#| label = "race-dist"
youth %>%
  ggplot(aes(fct_infreq(race) %>% fct_rev())) +
  geom_bar() +
  coord_flip() +
  labs(x = "Victim race")
```

````

]

---

## Major components

1. A **YAML header** surrounded by `---`s
1. **Chunks** of code surounded by ` ``` `
1. Text mixed with simple text formatting using the [Markdown syntax](https://quarto.org/docs/authoring/markdown-basics.html)

---

# **knitr** code chunks

---

## Rendering process

.footnote[Artwork from "Hello, Quarto" keynote by Julia Lowndes and Mine Çetinkaya-Rundel, presented at RStudio Conference 2022. Illustrated by Allison Horst.]

---

## Rendering process

.footnote[Artwork from "Hello, Quarto" keynote by Julia Lowndes and Mine Çetinkaya-Rundel, presented at RStudio Conference 2022. Illustrated by Allison Horst.]

---

## Stop, collaborate, and listen

* Render `gun-deaths.qmd` as an HTML document
* Add text describing the frequency polygon

---

## Code chunks

````markdown
```{r}
#| label = "youth-dist"
#| echo: false
#| message: false
#| warning: false

# code goes here
```
````

* Naming code chunks
* Code chunk options
* `eval: false`
* `include: false`
* `echo: false`
* `message: false` or `warning: false`
* `error: true`
* `cache: true`

---

## Dependencies

````default
```{r}
#| label = "raw-data"
rawdata <- readr::read_csv("a_very_large_file.csv")
```
    
```{r}
#| label = "processed-data"
#| cache: true
processed_data <- rawdata %>% 
  filter(!is.na(import_var)) %>% 
  mutate(new_variable = complicated_transformation(x, y, z))
```
````

]

````default
```{r}
#| label = "raw-data"
rawdata <- readr::read_csv("a_very_large_file.csv")
```

```{r}
#| label = "processed-data"
#| cache: true
#| dependson: "raw_data"
processed_data <- rawdata %>% 
  filter(!is.na(import_var)) %>% 
  mutate(new_variable = complicated_transformation(x, y, z))
```
````

]
]

---

## Inline code

```markdown
We have data about `r nrow(gun_deaths)` individuals killed by guns. Only `r nrow(gun_deaths) - nrow(youth)` are older than 65. The distribution of the remainder is shown below:
```

We have data about 100798 individuals killed by guns. Only 15687 are older than 65.

---

## Ice is back with my brand new invention

* Set `echo: false` as a global option
* Enable caching for each chunk and render the document. Look at the file structure for the cache. Now render the document again. Does it run faster?

---

# YAML header

---

## YAML header

```verbatim
---
title: Gun deaths
author: Benjamin Soltoff
date: '2022-09-25'
format: gfm
---
```

* **Y**et **A**nother **M**arkup **L**anguage
* Standardized format for storing hierarchical data in a human-readable syntax
* Defines how `quarto` renders your `.qmd` file

---

## HTML document

```verbatim
---
title: Gun deaths
author: Benjamin Soltoff
date: '2022-09-25'
format: html
---
```

---

## Table of contents

```verbatim
---
title: Gun deaths
author: Benjamin Soltoff
date: '2022-09-25'
format:
  html:
    toc: true
    toc-depth: 2
---
```

---

## Appearance and style

```verbatim
---
title: Gun deaths
author: Benjamin Soltoff
date: '2022-09-25'
format:
  html:
    theme: superhero
    highlight: github
---
```

---

## Global options

````verbatim
---
title: "My Document"
format: html
knitr:
  opts_chunk: 
    collapse: true
    echo: true
---
````

- Default document-level chunk options

---

## Something grabs a hold of me tightly

* Add a table of contents
* Use the `"minty"` theme
* Modify the figures so they are 8 inches wide by 6 inches tall
* Set `knitr` code chunk options globally

---

## PDF document

```verbatim
---
title: Gun deaths
author: Benjamin Soltoff
date: '2022-09-25'
format: pdf
---
```

---

## `render()`

```r
quarto::quarto_render("my-document.qmd", output_format = "html")
quarto::quarto_render("my-document.qmd", output_format = "all")
```

---

## Flow like a harpoon daily and nightly

* Render `gun-deaths.qmd` as both an HTML document and a PDF document
    * If you do not have `\(\LaTeX\)` installed, render as an HTML document and a Word document

---

### R scripts

```r
# gun-deaths.R
# 2017-02-01
# Examine the distribution of age of victims in gun_deaths

# load packages
library(tidyverse)
library(rcis)

# filter data for under 65
youth <- gun_deaths %>%
  filter(age <= 65)

# number of individuals under 65 killed
nrow(gun_deaths) - nrow(youth)

# graph the distribution of youth
youth %>% 
  ggplot(aes(age)) + 
  geom_freqpoly(binwidth = 1)

# graph the distribution of youth, by race
youth %>%
  ggplot(aes(fct_infreq(race) %>% fct_rev())) +
  geom_bar() +
  coord_flip() +
  labs(x = "Victim race")
```

---

## When to use a script

* For troubleshooting
* Initial stages of project
* Building a reproducible pipeline
* It depends

## Running scripts

* Interactively
* Programmatically using `source()`