Quarto

R Foundations Course

Ella Kaye | Department of Statistics | University of Warwick

November 16, 2023

Disclaimer

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

• Workshop website
• Workshop repo

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 Foundations 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

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

Links

• There are several types of “links” or hyperlinks.

• Markdown
• Output

You can embed [named hyperlinks](https://quarto.org/),
direct urls like <https://quarto.org/>, and links to 
[other places](#quarto-anatomy) in 
the document. The syntax is similar for embedding an
inline image: ![Penguins](images/lter_penguins.png).

You can embed named hyperlinks, direct urls like https://quarto.org/, and links to other places in the document. The syntax is similar for embedding an inline image:

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: 2023-11-16
date-format: long
format: 
  revealjs:
    theme: [default, ../../slides.scss]
    slide-number: true
    execute:
      echo: true
---

More on Quarto presentations

• Official guide

• Slidecraft 101 by Emil Hvitfeldt

  • Colours and Fonts
  • Code and Output
  • Theme variants
  • Advanced slide themes
  • 7 tips and tricks

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>

Resources

• https://quarto.org: The official documentation

• Awesome Quarto: A curated list of Quarto talks, tools, examples & articles

• Beautiful Reports and Persentations with Quarto

• Getting Started with Quarto workshop website

• Quarto for R and RStudio workshop

End matter

Resources

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

• Workshop website
• Workshop repo

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