+ - 0:00:00
Notes for current slide
Notes for next slide

Quarto

Day 1, Session 3

September 17, 2023
1 / 52

Agenda

  1. What is Quarto?
  2. Why use Quarto?
  3. The 3 essential ingredients
    • Text
    • Code
    • Metadata
2 / 52

1.

What is Quarto?

3 / 52

What is Quarto?

✍️ An authoring framework for data science

4 / 52

What is Quarto?

✍️ An authoring framework for data science

💾 A file format (.qmd)

4 / 52

What is Quarto?

✍️ An authoring framework for data science

💾 A file format (.qmd)

A command line interface

4 / 52

What is Quarto?

✍️ An authoring framework for data science

💾 A file format (.qmd)

A command line interface

📦 An R package (quarto)

4 / 52

What is Quarto?

✍️ An authoring framework for data science

💾 A file format (.qmd)

A command line interface

📦 An R package (quarto)

🛠 A tool for integrating prose, code, and output

4 / 52

What is Quarto?

✍️ An authoring framework for data science

💾 A file format (.qmd)

A command line interface

📦 An R package (quarto)

🛠 A tool for integrating prose, code, and output

✨ Magic

4 / 52

What's in a .qmd?

📃 Text and headers

💻 Code (R, Python, and more)

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

🖼 Images

... and more!

5 / 52

2.

Why use Quarto?

6 / 52

Replication crisis

7 / 52

  • 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.

8 / 52

  • 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/

9 / 52

Multilingual data science

Image source: "Hello Quarto", rstudio::conf(2022)

10 / 52

3.

The 3 essential ingredients

11 / 52

The 3 essential ingredients

1. Text

2. Code

3. Metadata

12 / 52

The 3 essential frameworks

1. Text → Markdown

2. Code → knitr

3. Metadata → YAML

13 / 52

How does this all come together? Rendering!

Render


14 / 52

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

15 / 52

Roadmap


16 / 52

Text

Markdown

17 / 52

Text

What you type in .qmd 👇 

Regular text
*italics*
**bold**  
`verbatim code` 
> Blockquote

Rendered output 👇

Regular text

italics

bold

verbatim code

Blockquote

18 / 52

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

# Header 1
## Header 2
### Header 3
#### Header 4
##### Header 5
###### Header 6

Header 1

Header 2

Header 3

Header 4

Header 5
Header 6
19 / 52

Lists

* item 1
    + sub-item 1
    + sub-item 2
  • item 1
    • sub-item 1
    • sub-item 2
1. item 1
2. item 2
    i) sub-item 1
  1. item 1
  2. item 2
    i) sub-item 1
20 / 52

Images

![](images/quarto.png)
21 / 52

Images

![Hex logo](images/quarto.png)
Hex logo
22 / 52

Images

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

Links

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

Read more about Quarto here.

24 / 52

Callouts

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

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

25 / 52

Your Turn 1 (with a partner!)

  1. 📁 Open your_turn_01.qmd.

  2. 🔍 Inspect the contents of this HTML output.

  3. 💻 Add markdown formatting to your_turn_01.qmd to re-create the HTML output.

  4. Render your_turn_01.qmd to check your work.

  1. Add Level-1 and Level-2 headers

  2. Add a bulleted list

  3. Add a hyperlink

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

  5. Add italicized and bolded text

05:00
26 / 52

Code

knitr

27 / 52

Add a code chunk

28 / 52

Chunk options

By default, code and output are both displayed.

Input

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

Output

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

29 / 52

Chunk options

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

#|

30 / 52

echo

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

Input

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

Output

31 / 52

eval

eval: FALSE prevents the code from being run.

Input

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

Output

ggplot(mpg, aes(displ, hwy)) + 
  geom_point()
32 / 52

include

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

Input

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

Output

[no code or output shown]

33 / 52

warning

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

Input

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

Output

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

34 / 52

warning

warning: false will suppress warning messages in the output.

Input

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

Output

35 / 52

Chunk labels

Use label to give chunks a descriptive summary.

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

Chunk labels

Use label to give chunks a descriptive summary.

```{r}
#| label: peek
glimpse(mpg)
```
```{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

36 / 52

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"

Good

my-plot

myplot

myplot1

MY-PLOT

Bad

my_plot

my plot

...everything else!

37 / 52

Chunk labels

Easier to organize and navigate your document

38 / 52

Inline code

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

Input

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

Output

Our data includes measurements from 38 different car models.

39 / 52

Your Turn 2

  1. 📁 Open your_turn_02.qmd.

  2. 🔍 Inspect the contents of this HTML output.

  3. 💻 Add chunk options to your_turn_02.qmd to re-create the HTML output.

  4. Render your_turn_02.qmd to check your work.

  1. Hide the code and output of the setup chunk

  2. Hide the code for all plots

  3. Bonus: Add descriptive labels to your code chunks

05:00
40 / 52

Metadata

YAML

41 / 52

YAML

"YAML Ain't Markup Language"

A section of key: value pairs separated by dashes ---

---
key: value
---
42 / 52

YAML

---
title: Diamonds Exploration
author: Brendan Cullen
format: html
---
43 / 52

YAML

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

Add a table of contents

43 / 52

YAML

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

Add a table of contents

...with 3 levels

44 / 52

YAML - indentation matters!

45 / 52

YAML - indentation matters!

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

❌

45 / 52

YAML - indentation matters!

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

❌

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

✅

Indent format 2 characters
Indent options 4 characters

45 / 52

Output formats

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

46 / 52

Your Turn 3

  1. 📁 Open your_turn_03.qmd.

  2. 🔍 Inspect the contents of this HTML output.

  3. 💻 Add YAML metadata to your_turn_03.qmd to re-create the HTML output.

  4. Render your_turn_03.qmd to check your work.

  1. Add your name as the author

  2. Add today's date

  3. Add a table of contents

  4. Apply the lux theme to your document

  5. Print the diamonds dataset as a paged table

05:00
47 / 52

Take-aways

48 / 52

Take-aways

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

48 / 52

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

48 / 52

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, bullets and lists

48 / 52

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, bullets and lists

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

48 / 52

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, bullets and lists

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

✅ Organize your text: use markdown headers with #

48 / 52

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, bullets and lists

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

✅ Organize your text: use markdown headers with #

✅ Organize your code: use chunk labels

48 / 52

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, bullets and 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

48 / 52

Questions?

49 / 52

Demo: Posit Connect

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

50 / 52

Demo: Posit Connect

51 / 52

Voilà!

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

52 / 52

Agenda

  1. What is Quarto?
  2. Why use Quarto?
  3. The 3 essential ingredients
    • Text
    • Code
    • Metadata
2 / 52
Paused

Help

Keyboard shortcuts

↑, ←, Pg Up, k Go to previous slide
↓, →, Pg Dn, Space, j Go to next slide
Home Go to first slide
End Go to last slide
Number + Return Go to specific slide
b / m / f Toggle blackout / mirrored / fullscreen mode
c Clone slideshow
p Toggle presenter mode
t Restart the presentation timer
?, h Toggle this help
oTile View: Overview of Slides
Esc Back to slideshow