Quarto

R Foundations Course

Ella Kaye | Department of Statistics | University of Warwick

November 28, 2022

Disclaimer

These slides are almost entirely copied from Tom Mock’s ‘Getting Started with Quarto’ workshop at rstudio::conf(2022).

Shared under Creative Commons 4.0 License.

Intro to Quarto

Hello Quarto

Quarto® is an open-source scientific and technical publishing system built on Pandoc

You can weave together narrative text and code to produce elegantly formatted output as documents, web pages, blog posts, books and more.

What about RMarkdown?

So what is Quarto?

Quarto is the next generation of R Markdown. For everyone.

Quarto is a command line interface (CLI) that renders plain text formats (.qmd, .rmd, .md) OR mixed formats (.ipynb/Jupyter notebook) into static PDF/Word/HTML reports, books, websites, presentations and more

Quarto, more than just knitr

We learned from 10 years of literate programming with knitr + rmarkdown

For everyone

  • Works with R, Python, Julia, Observable JS

  • knitr and jupyter engines

  • Works in RStudio, Jupyter Notebooks, VS Code

For the R Training course, we’ll focus on R and RStudio

So what is Quarto?

A Quarto document i.e. a .qmd is a plain text file, like a .rmd, that can be rendered to many different formats

A screenshot of a Visual and Source Quarto document

One install, “Batteries included”

  • RMarkdown grew into a large ecosystem, with varying syntax.

Quarto comes “batteries included” straight out of the box

  • HTML reports and websites
  • PDF reports
  • MS Office (Word, Powerpoint)
  • Presentations (Powerpoint, Beamer, revealjs)
  • Books
  • Any language, exact same approach and syntax

Quarto for RMarkdown users

See FAQs, including a conversion from RMarkdown formats to Quarto equivalents.

Anatomy of a Quarto document

  • Metadata (YAML)
---
format: html
---

Anatomy of a Quarto document

  • Code
```{r}
#| eval: true
library(dplyr)
mtcars %>% 
  group_by(cyl) %>%
  summarize(mean = mean(mpg), .groups = "drop")
```
# A tibble: 3 × 2
    cyl  mean
  <dbl> <dbl>
1     4  26.7
2     6  19.7
3     8  15.1

Anatomy of a Quarto document

  • Text
# Heading 1
This is a sentence with some **bold text** and some *italic text* 
This is an [image](image.png).

Metadata: YAML

The YAML metadata or header is:

processed in many stages of the rendering process and can influence the final document in many different ways. It is placed at the very beginning of the document and is read by each of Pandoc, Quarto and knitr. Along the way, the information that it contains can affect the code, content, and the rendering process.

YAML

---
title: "My Document"
format: 
  html:
    toc: true
    code-fold: true
---

Markdown

Quarto is based on Pandoc and uses its variation of markdown as its underlying document syntax. Pandoc markdown is an extended and slightly revised version of John Gruber’s Markdown syntax.

Markdown is a plain text format that is designed to be easy to write, and, even more importantly, easy to read

Text Formatting

Markdown Syntax Output 
*italics* and **bold**
 italics and bold 
superscript^2^ / subscript~2~
 superscript2 / subscript2 
~~strikethrough~~
 strikethrough 
`verbatim code`
 verbatim code

Headings

Markdown Syntax Output 
# Header 1

Header 1

 
## Header 2

Header 2

 
### Header 3

Header 3

 
#### Header 4

Header 4

 
##### Header 5
Header 5
 
###### Header 6
Header 6

Code

```{r}
#| output-location: column
#| label: fig-airquality
#| fig-cap: Temperature and ozone level.
#| warning: false

library(ggplot2)

ggplot(airquality, aes(Temp, Ozone)) + 
  geom_point() + 
  geom_smooth(method = "loess")
```

Figure 1: Temperature and ozone level.

Literate programming

Literate programming is writing out the program logic in a human language with included (separated by a primitive markup) code snippets and macros. - Wikipedia

---
title: "ggplot2 demo"
date: "5/22/2021"
format: html
---

## Air Quality

There is a relationship between temperature and the ozone level.

```{r}
#| label: fig-airquality
library(ggplot2)
ggplot(airquality, aes(Temp, Ozone)) + 
  geom_point() + 
  geom_smooth(method = "loess"
)
```

Metadata: YAML

“Yet Another Markup Language” or “YAML Ain’t Markup Language”

---
key: value
---

Output Options

---
format: something
---
---
format: html
---
---
format: pdf
---
---
format: revealjs
---

Options on options

Then add option arguments!

---
format: 
  html:
    toc: true
    code-fold: true
---

Sub-options should be below the main format output and spacing matters!

---
format: 
  html:
    option1: text
    option2: logical
---

YAML for format: html

YAML is sensitive

---
format:html # invalid, no space between
---

---
format: # invalid, read as missing
html
---

---
format: 
  html: # valid but needs next object
---

Anatomy of a code chunk

```{r}
#| label: car-stuff
#| echo: false
mtcars %>% 
  distinct(cyl)
```
  • Has 3x backticks on each end ```
  • Indicate engine (r) between curly braces {r}
  • Place options underneath, behind the #| (hashpipe):
    • #| option1: value

Quarto presentations

---
format: revealjs
---
---
format: 
  revealjs:
    slide-number: true
---

This Quarto presentation

---
title: Quarto
subtitle: R Foundations course
author: Ella Kaye | Department of Statistics | University of Warwick
title-slide-attributes:
  data-background-color: "#552D62"
date: 2022-11-28
date-format: long
format: 
  revealjs:
    theme: [default, ../../slides.scss]
    slide-number: true
    execute:
      echo: true
---

More on Quarto presentations

Demo

Resources

End Matter

License

Licensed under a Creative Commons Attribution-NonCommercial-ShareAlike 4.0 International License (CC BY-NC-SA 4.0).