Quarto

R for Data Science

Heather Turner | Department of Statistics | University of Warwick

March 21, 2024

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 this 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 |>
  summarize(mean = mean(mpg), .by = "cyl")
```
  cyl     mean
1   6 19.74286
2   4 26.66364
3   8 15.10000

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.
#| fig-alt: A scatterplot of ozone level against temparature, with a local regression fit that has a confidence band. The ozone level is fairly constant at around 15ppb from a temperature of 55°F to 75°F, then increases linearly to around 80ppb at a temperature of 90°F, where the ozone level starts to asymptote. The points are generally close to this curve apart from 7 outliers with higher than expected ozone between 75°F and 95°F.
#| warning: false

library(ggplot2)

ggplot(airquality, aes(Temp, Ozone)) + 
  geom_point() + 
  geom_smooth(method = "loess")
```
A scatterplot of ozone level against temparature, with a local regression fit that has a confidence band. The ozone level is fairly constant at around 15ppb from a temperature of 55°F to 75°F, then increases linearly to around 80ppb at a temperature of 90°F, where the ozone level starts to asymptote. The points are generally close to this curve apart from 7 outliers with higher than expected ozone between 75°F and 95°F.
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")
```

Your Turn!

  1. Install Quarto

  2. Open a new, empty Quarto document in RStudio and copy the example code from the previous slide.

  • Render the document
  • Try setting format in the YAML to docx rather than html
  • What does format: typst create?

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 for Data Science
author: Heather Turner | Department of Statistics | University of Warwick
title-slide-attributes:
  data-background-color: "#552D62"
date: 2024-03-21
date-format: long
format: 
  warwickpres-revealjs:
    execute:
      echo: true
      code-overflow: wrap
---

More on Quarto presentations

Demo

Publishing

Web publishing venues

Destination Description
Quarto Pub Publishing service for Quarto documents, websites, and books.
GitHub Pages Publish content based on source code managed within a GitHub repository.
Posit Connect Publishing platform for secure sharing of data products within an organization.
Netlify Professional web publishing platform.
Confluence Publishing platform for supporting team collaboration.

… and more.

Quarto Pub

Visit https://quartopub.com/ and set up a free account.

quarto publish



At the Terminal, run:


quarto publish <document>

See e.g. https://jjallaire.quarto.pub/

Netlify

Visit https://app.netlify.com/ and set up a free account.

At the Terminal, run:

quarto publish netlify <document>

Resources

SkillsForge password

End matter

Resources

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.

License

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