Quarto

Recherche reproductible en écologie numérique

François Guilhaumon

IRD (ENTROPIE)

November 21, 2023

Notebooks

RMarkdown & Jupyter Notebook

RMarkdown

With time, RMarkdown gathered an entire ecosystem of R packages

Quarto: Next gen R Markdown

Quarto unifies and extends the R Markdown ecosystem

Quarto is a new, open-source, scientific and technical publishing system

Quarto is a new, open-source, scientific and technical publishing system

Quarto is a software (command line interface) that renders plain text formats such as .qmd, .rmd, .md into static PDF/Word/HTML reports, books, websites, presentations and more

Quarto CLI orchestrates each step of rendering

Quarto basics

This is a Quarto file – a plain text file that has the extension .qmd:

---
title: "Diamond sizes"
date: 2022-09-12
format: html
---

```{r}
#| label: setup
#| include: false

library(tidyverse)

smaller <- diamonds |> 
  filter(carat <= 2.5)
```

We have data about `r nrow(diamonds)` diamonds.
Only `r nrow(diamonds) - nrow(smaller)` are larger than 2.5 carats.
The distribution of the remainder is shown below:

```{r}
#| label: plot-smaller-diamonds
#| echo: false

smaller |> 
  ggplot(aes(x = carat)) + 
  geom_freqpoly(binwidth = 0.01)
```

Quarto basics

It contains three important types of content:

1. An (optional) YAML header surrounded by ---s.
2. Chunks of R code surrounded by ```.
3. Text mixed with simple text formatting like # heading and _italics_.

Quarto basics

---
title: "Diamond sizes"
date: 2022-09-12
format: html
---

```{r}
#| label: setup
#| include: false

library(tidyverse)

smaller <- diamonds |> 
  filter(carat <= 2.5)
```

We have data about `r nrow(diamonds)` diamonds.
Only `r nrow(diamonds) - nrow(smaller)` are larger than 2.5 carats.
The distribution of the remainder is shown below:

```{r}
#| label: plot-smaller-diamonds
#| echo: false

smaller |> 
  ggplot(aes(x = carat)) + 
  geom_freqpoly(binwidth = 0.01)
```

For example, Quarto powers Computo

A journal of the French Statistical Society SFdS - ISSN 2824-7795

Quarto VS Rmarkdown

Decoupling from R

• Quarto is multi-core and multi-engine
• Dedicated CLI
• Unlike Rmd / Jupyter notebooks (Python), Quarto is not tied to a language (You can use Python in Rmd within Rstudio and R in Jupyter notebooks but few people do)
• Compatible with your editor (Jupyter Lab, Neovim, VS Code, RStudio, etc …), with many visual edition modes available
• Makes collaboration easier

Quarto highlights

• Consistent implementation of features across outputs: (tabsets, code-folding, syntax highlighting)
• More accessible defaults, better support for accessibility
• Guardrails, particularly helpful for new learners: (YAML completion, informative syntax errors)
• Support for other languages like Python, Julia, Observable, …

Citations / cross-references

• citations: bibliography files (bibtex), bibliography style (csl)

---
title: "My Document"
bibliography: references.bib
csl: nature.csl
---

She said "[...] but you can't stop the future" [@Sp231992].

• cross-references for figures (fig-), tables (tbl-), sections (sec-), equations (eq-), (thm-), etc

## Introduction {#sec-introduction}

See @sec-introduction for additional context.

Extensions

• include-code-files : code from source files
• fontawesome, academicons, … : Use icons
• collapse-social-embeds : include social items.
• Journal Articles Template
• quarto-inrae-extension : INRAE formats for HTML, PDF, Docx, Revealjs, and Beamer, thanks to @david_carayon
• … Quarto Extensions

Moving between formats is straightforward

Document HTML

lesson-1.qmd

title: "Lesson 1"
format: html

Document PDF

lesson-1.qmd

title: "Lesson 1"
format: pdf

Presentation

lesson-1.qmd

title: "Lesson 1"
format: revealjs

Book

_quarto.yml

project:
  type: book
  output-dir: _book

Website

_quarto.yml

project:
  type: website
website: 
  navbar: 
    left:
      - lesson-1.qmd

And more in the Gallery …

RStudio integration

Presentations

Easy presentations

Toggle the slide menu with the menu button to go to other slides and access presentation tools. Some other tools like PDF Export in this settings.

Use the chalkboard button to toggle the chalkboard.

Use the notes canvas button to toggle drawing on top of the current slide.

Callout-blocks

::: {.callout-note}
Five types of callouts: `note`, `warning`, 
`important`, `tip`, and `caution`.
:::

Note

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

Tip

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

Diagrams

```{mermaid}
flowchart LR
  A[Hard edge] --> B(Round edge)
  B --> C{Decision}
  C --> D[Result one]
  C --> E[Result two]
```

flowchart LR
  A[Hard edge] --> B(Round edge)
  B --> C{Decision}
  C --> D[Result one]
  C --> E[Result two]

Videos

{{< video https://www.youtube.com/watch?v=KPXFs2YU3F4>}}

Widgets

Native support for JupyterWidgets (Jupyter) and htmlwidgets (R/knitr)

```{r}
#| output-location: column-fragment
library(leaflet)
leaflet(width = "480px") %>%
  addTiles() %>%
  addMarkers(
    lat=43.61270525357229, 
    lng=3.8733237524215443, 
    popup="We are here!"
  )
```

Transitions

Use . . . to indicate a break at an arbitrary location

Let's have a look at `iris`

. . . 

```{r}
head(iris) |> knitr::kable()
```

Let’s have a look at iris

Sepal.Length	Sepal.Width	Petal.Length	Petal.Width	Species
5.1	3.5	1.4	0.2	setosa
4.9	3.0	1.4	0.2	setosa
4.7	3.2	1.3	0.2	setosa
4.6	3.1	1.5	0.2	setosa
5.0	3.6	1.4	0.2	setosa
5.4	3.9	1.7	0.4	setosa

Fragments

::: {.fragment}
Fade in
:::

::: {.fragment .fade-out}
Fade out
:::

::: {.fragment .strike}
Strike text
:::

::: {.fragment .fade-in-then-out}
Fade in, then out
:::

::: {.fragment .fade-up}
Slide up while fading in
:::

Fade in

Fade out

Strike text

Fade in, then out

Slide up while fading in

Column output

```{r}
#| code-line-numbers: "|3"
#| output-location: column

library(ggplot2)

ggplot(mtcars, aes(hp, mpg)) +
  geom_point() +
  geom_smooth(formula = y ~ x, method = "loess")
```

```{r}
#| code-line-numbers: "|3"
#| output-location: column-fragment
ggplot(mtcars, aes(hp, mpg)) +
  geom_point() +
  geom_smooth(formula = y ~ x, method = "loess")
```

Tabset output

• Code
• Plot
• Under the hood

```{r}
p <- ggplot(mtcars, aes(hp, mpg)) +
  geom_point() +
  geom_smooth(formula = y ~ x, method = "loess")
```

::: {.panel-tabset}

### Plot code

```{r}
#| echo: fenced
p <- ggplot(mtcars, aes(hp, mpg)) +
  geom_point() +
  geom_smooth(formula = y ~ x, method = "loess")
```

### Plot

```{r}
p
```

:::

Easy layouts

• Code
• Plot

• Use negative values for white space

```{r}
#| eval: false
#| fig-subcap:
#|   - "boring 🥱"
#|   - "boooring 🥱🥱"
#|   - "boooriiing 🥱🥱🥱"
#| fig-height: 2
#| layout: [[40,-20,40], [100]]
p
p
p
```

boring 🥱

 

boooring 🥱🥱

boooriiing 🥱🥱🥱

RMarkdown

```{r setup, include=FALSE}
knitr::opts_chunk$set(echo = TRUE)
library(tidyverse)
library(DT)
library(ggimage)
```

Quarto

```{r}
#| label: "setup"
#| include: false
knitr::opts_chunk$set(echo = TRUE)
library(tidyverse)
library(DT)
library(ggimage)
```

Options are moved to within the code chunk using #| (hash-pipe) for each line

How to move to Quarto

1. Install Quarto
2. Start a Quarto Project
3. Convert your Rmarkdown Documents
   • Change your output: to the corresponding format: in your YAML
   • Use knitr::convert_chunk_header() to convert your code blocks (outputs a .qmd file)
4. Render your files
5. For websites: edit your _quarto.yml file if necessary
6. Publish

Take Home Messages

• Quarto is a new, open-source, scientific and technical publishing system
• Quarto supports multiple languages / IDEs
• Quarto standardizes a lot of outputs
• Does a better job of one document, many outputs than Rmd
• Lots of publishing features (references, figures, etc.)
• Very well documented

Ressources

Ressources

• Quarto documentation
• Hadley’s intro to Quarto
• Awesome Quarto
• La présentation originale de Cédric Midoux