Quarto

class: title-slide

# Quarto

### Day 1, Session 3

<div class="title-footer">
  <img src="images/academy-logo.png">
  <div> September 17, 2023</div>
</div>

---
class: middle

# Agenda

1. What is Quarto?
1. Why use Quarto?
1. The 3 essential ingredients
  - Text
  - Code
  - Metadata

---
class: middle chapter-slide red

.big-white-number[1.]

# What is Quarto?

---
# What is Quarto?

✍️ An authoring framework for data science

💾 A file format (`.qmd`)

📦 An [R package](https://quarto-dev.github.io/quarto-r/) (quarto)

🛠 A tool for integrating prose, code, and output

✨ Magic

---
# What's in a `.qmd`?

.pull-left[

📃 Text and headers

💻 Code (R, Python, and more)

📊 Output (e.g. plots, tables, model results)

🖼 Images

... and more!
]

.pull-right[
<img src="images/session03-quarto/doc-make.jpg" width="100%" />
]
---
class: middle chapter-slide blue

.big-white-number[2.]

# Why use Quarto?

---
background-image: url(images/session03-quarto/replication-crisis.png
background-position: center;
background-size: 80% 
# Replication crisis

???

* These are just a few headlines from the past or so that highlight an ongoing problem across many fields of science -- that many published studies fail to replicate.

* I won't go into details here, but suffice it to say, to solve the reproducibility crisis, 
we need both cultural changes in how science is conducted AND technological solutions.

* Quarto gives us just that -- a technological solution for reproducibility.

---
background-image: url(images/session03-quarto/reproducibility.gif)
background-position: center;
background-size: 100%

???

* To put this in perspective, I'm going to borrow one of my favorite historical analogies; 
we can think of Quarto like the advent of the printing press in the 15th century.

* The printing press made it possible to reproduce any book AND, more importantly, make that process AUTOMATABLE. This revolutionary technology allowed the dissemination of information to the masses,
which had a wide-ranging impact on society at large

* Quarto does something similar for data science today -- you can share your 
Quarto document with someone else, and that person will have everything they 
need to reproduce your analysis AUTOMATICALLY, with the click of a button.

* Because this process can be entirely automated, this has huge potential in a 
business setting to increase the efficiency of data science workflows, which in turn can lead
to better business outcomes

---
# Beautiful data products

https://quarto.org/docs/gallery/

---
# Multilingual data science

.center[
<img src="images/session03-quarto/quarto-languages.png" width="70%" />
]

Image source: ["Hello Quarto", rstudio::conf(2022)](https://posit.co/keynotes/hello-quarto-share-collaborate-teach-reimagine/)
---
class: middle chapter-slide green

.big-white-number[3.]

# The 3 essential ingredients

---
# The 3 essential ingredients

.pull-left[
## 1. Text

## 2. Code

## 3. Metadata
]

.pull-right[
<img src="images/session03-quarto/qmd-anatomy.png" width="100%" />
]

---
# The 3 essential <span style="color:red">frameworks</span>

.pull-left[
## 1. Text &rarr; <span style="color:red">Markdown</span>

## 2. Code &rarr; <span style="color:red">knitr</span>

## 3. Metadata &rarr; <span style="color:red">YAML</span>
]

.pull-right[
<img src="images/session03-quarto/qmd-anatomy.png" width="100%" />
]

???

How does this all come together? Rendering!

---
# Render

<br>

.center[
<img src="images/session03-quarto/rstudio-qmd-how-it-works.png" width="100%" />
]

???
When you render the document...

1. Quarto sends the .qmd file to knitr, runs all the code and embeds results and text into an .md file.

2. Pandoc then converts the .md file into your chosen output format, which you specify using YAML metadata.

---
# Render

---
# Roadmap

<br>

.center[
<img src="images/session03-quarto/build-report.png" width="100%" />
]

---
class: inverse middle center

# Text
## Markdown

---

# Text

.pull-left[

What you type in `.qmd` 👇

***

````markdown
Regular text

*italics*

**bold**

`verbatim code`

> Blockquote
````
]

.pull-right[

Rendered output 👇

***

Regular text

*italics*

**bold**

`verbatim code`

> Blockquote
]

???
I will go through this information quickly. Don't worry about absorbing all of this detail now. Have your cheatsheet handy for the exercises.

---

# Headers

.pull-left[
````markdown
# Header 1

## Header 2

### Header 3

#### Header 4

##### Header 5

###### Header 6
````
]

.pull-right[
# Header 1

## Header 2

### Header 3

#### Header 4

##### Header 5

###### Header 6
]

---
# Lists

.panelset[
.panel[.panel-name[Unordered]

.pull-left[

````markdown
* item 1
    + sub-item 1
    + sub-item 2
````

]

.pull-right[
* item 1
    + sub-item 1
    + sub-item 2
]
]

.panel[.panel-name[Ordered]

.pull-left[

```markdown
1. item 1
2. item 2
    i) sub-item 1
```

]

.pull-right[
1.  item 1
2.  item 2  
    i)  sub-item 1

]
]
]

---
# Images

```markdown
![](images/quarto.png)
```

---
# Images

```markdown
![Hex logo](images/quarto.png)
```

---
# Images

```markdown
![Hex logo](images/quarto.png){width=50%}
```

---

# Links

```markdown
Read more about Quarto [here](https://quarto.org/).
```

Read more about Quarto [here](https://quarto.org/).

---
# Callouts

```markdown
::: {.callout-note}
A special note about the data.
:::
```

ℹ️ Five types of callouts, including:
`note`, `warning`, `important`, `tip`, and `caution`.

---
class: your-turn

# Your Turn 1 (with a partner!)

.panelset[
.panel[.panel-name[Overview]

1. 📁 Open `your_turn_01.qmd`.

1. 🔍 Inspect the contents of <a href="https://rsacdn.link/milestones/conf/r-intro/conf-sessions/session03-quarto/data/your_turn_01_solution.html" rel="noopener noreferrer" target="_blank">this HTML output</a>.

1. 💻 Add **markdown formatting** to `your_turn_01.qmd` to re-create the HTML output.

1.  Render `your_turn_01.qmd` to check your work.

]

.panel[.panel-name[Steps]

1. Add Level-1 and Level-2 headers

1. Add a bulleted list

1. Add a [hyperlink](https://www.americangemsociety.org/4cs-of-diamonds/)

1. Add an image (saved in the `images/` directory)

1. Add *italicized* and **bolded** text
]
]

---
class: inverse middle center

# Code
## knitr

---
# Add a code chunk

.panelset[
.panel[.panel-name[Option 1]
![](images/session03-quarto/rmarkdown-type-backticks.gif)
]

.panel[.panel-name[Option 2]
<img src="images/session03-quarto/insert-chunk.gif" width="60%" />
]

.panel[.panel-name[Option 3]
<img src="images/session03-quarto/code-chunk-shortcuts.png" width="70%" />
]
]

---
# Chunk options

By default, code and output are both displayed.

.pull-left[

**Input**

````
```{r}
ggplot(mpg, aes(displ, hwy)) + 
  geom_point()
```
````
]

.pull-right[

**Output**

```r
ggplot(mpg, aes(displ, hwy)) + 
  geom_point()
```

<img src="session03-quarto-slides_files/figure-html/unnamed-chunk-14-1.png" width="35%" />
]

---
# Chunk options

Chunk output can be customized with **options**, which are specified using the "hashpipe":

.center[

.big-text[`#|`]

]

---
# `echo`

`echo: FALSE` hides the code. Especially useful for plots!

.pull-left[

**Input**

````
```{r}
#| echo: false
ggplot(mpg, aes(displ, hwy)) + 
  geom_point()
```
````
]

.pull-right[

**Output**

<img src="session03-quarto-slides_files/figure-html/unnamed-chunk-15-1.png" width="50%" />
]

---
# `eval`

`eval: FALSE` prevents the code from being run.

.pull-left[

**Input**

````
```{r}
#| eval: false
ggplot(mpg, aes(displ, hwy)) + 
  geom_point()
```
````
]

.pull-right[

**Output**

```r
ggplot(mpg, aes(displ, hwy)) + 
  geom_point()
```
]

---
# `include`

`include: FALSE` runs the code, but prevents both the code and the output from appearing. Especially useful for setup chunks.

.pull-left[

**Input**

````
```{r}
#| include: false
ggplot(mpg, aes(displ, hwy)) + 
  geom_point()
```
````
]

.pull-right[

**Output**

[no code or output shown]
]

---
# `warning`

Some code will return a warning message along with the output.

.pull-left[

**Input**

````

```{r}
#| echo: false
ggplot(airquality, aes(Temp, Ozone)) + 
    geom_point()
```
````
]

.pull-right[

**Output**

```
## Warning: Removed 37 rows containing missing values (`geom_point()`).
```

<img src="session03-quarto-slides_files/figure-html/unnamed-chunk-17-1.png" width="40%" />
]

---
# `warning`

`warning: false` will suppress warning messages in the output.

.pull-left[

**Input**

````

```{r}
#| echo: false
#| warning: false
ggplot(airquality, aes(Temp, Ozone)) + 
    geom_point()
```
````
]

.pull-right[

**Output**

<img src="session03-quarto-slides_files/figure-html/unnamed-chunk-18-1.png" width="40%" />
]

---
# Chunk labels

Use `label` to give chunks a descriptive summary.

.pull-left[

````
```{r}
#| label: peek
glimpse(mpg)
```
````

]

.pull-right[

````
```{r}
#| label: peek
head(mpg)
```
````

````
Error in parse_block(g[-1], g[1], params.src) : 
  duplicate label 'peek'
Calls: <Anonymous> ... process_file -> split_file -> lapply -> FUN -> parse_block
Execution halted
````

⚠️ Careful! No duplicate chunk labels

]

???

how can we make it easier on ourselves to explore the code in here?

show how to add chunk labels and view in IDE interactively

---
# Chunk labels

💡 Think "kebabs, not snakes"

.pull-left[

.center[

**Good**

`my-plot`

`myplot`

`myplot1`

`MY-PLOT`

]

.pull-right[

.center[

**Bad**

`my_plot`

`my plot`

...everything else!

]
]

---
# Chunk labels

Easier to organize and navigate your document

---
# Inline code

To include executable code within markdown text, enclose your code in `r` surrounded by single backticks.

.pull-left[

**Input**

````markdown
Our data includes measurements 
from `r n_distinct(mpg$model)` 
different car models.
````

]

.pull-right[

**Output**

Our data includes measurements from 38 different car models.

]

---
class: your-turn

# Your Turn 2

.panelset[
.panel[.panel-name[Overview]

1. 📁 Open `your_turn_02.qmd`.

1. 🔍 Inspect the contents of <a href="https://rsacdn.link/milestones/conf/r-intro/conf-sessions/session03-quarto/data/your_turn_02_solution.html" rel="noopener noreferrer" target="_blank">this HTML output</a>.

1. 💻 Add **chunk options** to `your_turn_02.qmd` to re-create the HTML output.

1.  Render `your_turn_02.qmd` to check your work.

]

.panel[.panel-name[Steps]

1. Hide the code and output of the setup chunk

1. Hide the code for all plots

1. Bonus: Add descriptive labels to your code chunks

]
]

---
class: inverse middle center

# Metadata
## YAML

---
# YAML

[_"YAML Ain't Markup Language"_](https://en.wikipedia.org/wiki/YAML#History_and_name)

A section of `key: value` pairs separated by dashes <code>---</code>

```yaml
---
key: value
---
```

---
# YAML

.pull-left[

````
---
title: Diamonds Exploration
author: Brendan Cullen
format: html
---
````
]

.pull-right[
````
---
title: Diamonds Exploration
author: Brendan Cullen
format:
  html:
    toc: true
---
````

.center[
Add a **table of contents**
]
]

---
# YAML

.pull-left[

````
---
title: Diamonds Exploration
author: Brendan Cullen
format: html
---
````
]

.pull-right[

````
---
title: Diamonds Exploration
author: Brendan Cullen
format:
  html:
    toc: true
    toc-depth: 3
---
````

.center[

Add a table of contents

...with **3 levels**

]
]

---
# YAML - indentation matters!

.pull-left[
````
---
title: Diamonds Exploration
author: Brendan Cullen
format:
html:
toc: true
toc-depth: 3
---
````
.center[
❌
]

]

.pull-right[

````
---
title: Diamonds Exploration
author: Brendan Cullen
format:
  html:
    toc: true
    toc-depth: 3
---
````

.center[
✅

Indent **format** 2 characters<br> Indent **options** 4 characters
]
]

---
# Output formats

https://quarto.org/docs/gallery/

---
class: your-turn

# Your Turn 3

.panelset[
.panel[.panel-name[Overview]

1. 📁 Open `your_turn_03.qmd`.

1. 🔍 Inspect the contents of <a href="https://rsacdn.link/milestones/conf/r-intro/conf-sessions/session03-quarto/data/your_turn_03_solution.html" rel="noopener noreferrer" target="_blank">this HTML output</a>.

1. 💻 Add **YAML metadata** to `your_turn_03.qmd` to re-create the HTML output.

1.  Render `your_turn_03.qmd` to check your work.

]

.panel[.panel-name[Steps]

1. Add your name as the author

1. Add today's date

1. Add a table of contents

1. Apply the `lux` theme to your document

1. Print the `diamonds` dataset as a paged table

]
]

---
class: inverse
# Take-aways

✅ **Document your document:** use YAML to set up meaningful metadata

✅ **Style your document:** use YAML to add options to your chosen output format

✅ **Style your text:** use markdown for **bold**, *italics*, `code`, <svg aria-hidden="true" role="img" viewBox="0 0 512 512" style="height:1em;width:1em;vertical-align:-0.125em;margin-left:auto;margin-right:auto;font-size:inherit;fill:currentColor;overflow:visible;position:relative;"><path d="M40 48C26.7 48 16 58.7 16 72v48c0 13.3 10.7 24 24 24H88c13.3 0 24-10.7 24-24V72c0-13.3-10.7-24-24-24H40zM192 64c-17.7 0-32 14.3-32 32s14.3 32 32 32H480c17.7 0 32-14.3 32-32s-14.3-32-32-32H192zm0 160c-17.7 0-32 14.3-32 32s14.3 32 32 32H480c17.7 0 32-14.3 32-32s-14.3-32-32-32H192zm0 160c-17.7 0-32 14.3-32 32s14.3 32 32 32H480c17.7 0 32-14.3 32-32s-14.3-32-32-32H192zM16 232v48c0 13.3 10.7 24 24 24H88c13.3 0 24-10.7 24-24V232c0-13.3-10.7-24-24-24H40c-13.3 0-24 10.7-24 24zM40 368c-13.3 0-24 10.7-24 24v48c0 13.3 10.7 24 24 24H88c13.3 0 24-10.7 24-24V392c0-13.3-10.7-24-24-24H40z"/></svg> bullets and <svg aria-hidden="true" role="img" viewBox="0 0 512 512" style="height:1em;width:1em;vertical-align:-0.125em;margin-left:auto;margin-right:auto;font-size:inherit;fill:currentColor;overflow:visible;position:relative;"><path d="M24 56c0-13.3 10.7-24 24-24H80c13.3 0 24 10.7 24 24V176h16c13.3 0 24 10.7 24 24s-10.7 24-24 24H40c-13.3 0-24-10.7-24-24s10.7-24 24-24H56V80H48C34.7 80 24 69.3 24 56zM86.7 341.2c-6.5-7.4-18.3-6.9-24 1.2L51.5 357.9c-7.7 10.8-22.7 13.3-33.5 5.6s-13.3-22.7-5.6-33.5l11.1-15.6c23.7-33.2 72.3-35.6 99.2-4.9c21.3 24.4 20.8 60.9-1.1 84.7L86.8 432H120c13.3 0 24 10.7 24 24s-10.7 24-24 24H32c-9.5 0-18.2-5.6-22-14.4s-2.1-18.9 4.3-25.9l72-78c5.3-5.8 5.4-14.6 .3-20.5zM224 64H480c17.7 0 32 14.3 32 32s-14.3 32-32 32H224c-17.7 0-32-14.3-32-32s14.3-32 32-32zm0 160H480c17.7 0 32 14.3 32 32s-14.3 32-32 32H224c-17.7 0-32-14.3-32-32s14.3-32 32-32zm0 160H480c17.7 0 32 14.3 32 32s-14.3 32-32 32H224c-17.7 0-32-14.3-32-32s14.3-32 32-32z"/></svg> lists

✅ **Style your output:** use chunk options (`echo`, `eval`, etc.)

✅ **Organize your text:** use markdown headers with `#`

✅ **Organize your code:** use chunk labels

✅ **Preview your work:** render early, render often

---
class: inverse middle center

# Questions?

---
class: inverse, center, middle

# Demo: Posit Connect

https://docs.posit.co/connect/user/publishing/#publishing-documents

---
# Demo: Posit Connect

---
class: inverse, center, middle
# Voilà!

https://conf01-metaproxy.production05.posit.academy/rsc/diamonds-report/my_diamonds_report.html