Formation Quarto

Parcours de formation R perfectionnement SSP

Michaël Delorme et PAOS

michael.delorme@agriculture.gouv.fr

SSP/DéMéSIS/PAOS

2025-10-14

Table des matières

• Introduction
• Structure et syntaxe
• Marque de l’État
• Références

Pré-requis techniques

• Quarto (≥ 1.5)

• RStudio (≥ 2022.07) et R (≥ 4)

• => Installé par défaut sur Cerise !

Introduction

Un module des formations à R dispensées au SSM Agriculture

Objectifs

• Intérêt des publications reproductibles
• Découvrir la versatilité de Quarto
• Réaliser un document, de simple à complexe

versatile : pour le langage en entrée et les formats en sortie (diapo suivante)

Quarto

Un système de publication

Figure 1 –  Principe de fonctionnement (source RStudio)

• qmd : fichier quarto
• knitr : package R pour générer des fichiers markdown
  
• md : fichier markdown
  
• pandoc : convertisseur universel de documents
  
• sorties multi-formats (html, word, pdf…)

• Mélange code et texte : une partie du document est générée par des données (tableaux, graphiques ou texte)
• Successeur de Rmarkdown
• Commandes complémentaires LaTeX ou Typst pour le PDF
• Pandoc est un convertisseur “universel” de formats de texte

Formats/moteurs

• multi-format
  • HTML (rapports, livres, présentations)
  • PDF
  • Appli web (statique/interactif) : blog, site, tableau de bord
  • Powerpoint
  • MS Word

• multi-langage
  • R
  • Python
  • Observable
  • Julia

Le format PDF nécessite {tinytex}

Avantages

• intégration avec R
• reproductibilité
  • session vierge à chaque génération
  • limiter les copier/coller entre outils
  • prise en compte des changements de données ou de méthodes
• interactivité possible dans le document (HTML)
• versionnement avec Git et compatible avec le CI/CD (intégration continue)

• afficher du code dans le doc
• éviter les copier/coller : synchronisation analyse/résultats
• faciliter la reproductibilité avec {renv}

Inconvénients

• syntaxe (markdown)
• génération active du rendu pour visualiser
• débogage parfois plus complexe

• Mais disponibilité d’un éditeur visuel What You See Is What You Mean dans RStudio.
• Asynchrone

Derniers détails sur l’installation

Un paquet {quarto} et un binaire quarto (ils sont pré-installés sur CERISE).

Vérification dans le terminal :

quarto check install
quarto check knitr

Si nécesaire

install.packages("quarto")

Le format PDF nécessite LaTeX.

quarto install tinytex

• Le programme est livré avec RStudio (mais peut être installé à part aussi)
• La paquet n’est pas indispensable mais peut être utile
• Typst n’est pas encore disponible sur CERISE (sauf en pré-prod) pour générer du PDF sans LaTeX

Structure et syntaxe

Premiers pas avec quarto

• Comment créer votre premier document quarto ?
• Un mode “source” et un mode “visuel”
• Générer un document “self contained”

Premier exemple

On passe en revue rapidement les éléments d’un document Quarto, puis on revient sur chaque élément en détail par la suite

---
title: "Litany against fear"
author: "Bene Gesserit"
---

I must not fear. *Fear is the mind-killer*. Fear is the little-death that
brings total obliteration. 

```{python}
import numpy as np
np.exp(np.pi * complex(0, 1)) + 1
```

**I will face my fear.** I will permit it to pass over me and through me.

```{r}
somme <- sum(1:10)
```

Un exemple pour montrer rapidement les différents éléments qu’on décrira ci-après

markdown

Un langage balisé simplifié

doc

Inventé en 2004 pour offrir une syntaxe facile à lire et à écrire, en l’état, sans formatage.

chunks

Le code exécutable est intégré dans un chunk (bloc) :

```{r}
#| label: mon-chunk
#| warning: false

1+1
```

Ctrl Alt i

doc

• détails dans la partie Code
• Triple quote + le langage dans des accolades
• Les commentaires/pipe permettent de préciser des options (la plus grosse différence visible entre Rmarkdown et Quarto)
• label: est un identifiant (facultatif mais conseillé)

En-tête de configuration

• En language YAML
• bloc entre ---
• Facultatif mais a minima : title:, author:, date:, format:
• Options nombreuses et variables selon les formats => voir ici

Rendu

Avec la console R :

quarto_render("mon_document.qmd")

Avec le terminal :

quarto render mon_document.qmd

Ctrl ⇧ k ou (ou )

Le tricotage/rendu se fait dans une nouvelle session à chaque fois et n’impacte pas votre environnement courant ; de même les objets de votre environnement courant ne sont pas disponibles, par défaut, lors du rendu

À vous de jouer

Exercice 1. : découvrir l’interface

Éléments

Texte

• 2 retours à la ligne pour faire un paragraphe
• 2 espaces et 1 retour à la ligne pour un saut de ligne
• * ou _ pour mettre en *italique* ou en **gras**
• [un lien](https://www.example.org/) → un lien
• une portion de texte peut être stylée en vert avec [vert]{style="color:darkgreen"}
• mais du HTML est aussi possible <span style="color:red">rouge</span> pour mettre en rouge

doc

Titres

Préfixer le titre avec #, ## ou ### pour avoir les titres de niveau 1, 2 ou 3, etc..

#### Titre de niveau 4

Titre de niveau 4

Listes

- Atréides
  - Leto
  - Jessica
  - Paul
- Harkonnen
  - Vladimir
  - Rabban
  - Feyd-Rautha

ou

- Atréides
  * Leto
  * Jessica
  * Paul
- Harkonnen
  + Vladimir
  + Rabban
  + Feyd-Rautha

• Atréides
  • Leto
  • Jessica
  • Paul
• Harkonnen
  • Vladimir
  • Rabban
  • Feyd-Rautha

1. Atréides
   - Leto
   - Jessica\
     **2 espaces (ou `\`) + nouvelle ligne + aligner
     pour ajouter du texte dans les items**
   - Paul
2. Harkonnen
   - Vladimir
   - Rabban
   - Feyd-Rautha

1. Atréides
   • Leto
   • Jessica
     2 espaces (ou \) + nouvelle ligne + aligner pour ajouter du texte dans les items
   • Paul
2. Harkonnen
   • Vladimir
   • Rabban
   • Feyd-Rautha

Renumérotation automatique incrémentée à partir du premier numéro trouvé.

Images

![Fremen](images/images/dune_book.jpg)

Figure 2 –  Fremen

![Fremen](images/images/dune_book.jpg){#fig-dune fig-alt="A sand worm on Arrakis"}

Utiliser le préfixe fig- pour l’identifiant afin de pouvoir bénéficier des renvois automatiques et de la numérotation automatique

Renvois

(cross-references)

Un lien automatique est créé si on indique @fig-dune : Quarto nous écrit le lien (type et numéro) qui renvoie à figure 2.

Les noms des types affichés peuvent être modifiés dans l’en-tête :

---
crossref:
  fig-prefix: figure # par défaut : Figure
  fig-title:  Figure
  tbl-prefix: tableau # par défaut : Tableau
  tbl-title:  Tableau
  title-delim: " – "
---

Notes de pied de page

Les notes se construisent en ajoutant un [^1] dans le texte, avec le 1 pouvant être une numérotation (pas obligatoirement dans l’ordre) ou tout autre mot clé. La note est ensuite introduite avec le même symbole dans un nouveau paragraphe :

[^1]: texte de la note

C’est normalement facile¹ à faire si on se rappelle de la syntaxe.

1. page d’aide sur les notes de bas de page.

Équations

Syntaxe LaTeX entre des $ (inline) ou $$ (bloc).

$\sigma = \sqrt{\frac{1}{N} \sum_{i=1}^N (x_i - \mu)^2},\text{ où } \mu = \frac{1}{N} \sum_{i=1}^N x_i$

\[\sigma = \sqrt{\frac{1}{N} \sum_{i=1}^N (x_i - \mu)^2},\text{ où } \mu = \frac{1}{N} \sum_{i=1}^N x_i\] doc

Libellés

(Callout)

Les “libellés” permettent de mettre en exergue des informations complémentaires.

:::{.callout-note}
Il existe cinq types de libellés : 
`note`, `tip`, `warning`, `caution` et `important`.
:::

Note

Il existe cinq types de libellés : note, tip, warning, caution et important.

::: callout-warning
Suite aux nombreux manquements à l’obligation de contrôle hebdomadaire (...)
:::

Avertissement

Suite aux nombreux manquements à l’obligation de contrôle hebdomadaire de l’étanchéité (…)

::: {.callout-tip title="Mon titre"}
This is a callout with a title.
:::

Mon titre

This is a callout with a title.

doc

À vous de jouer

Exercice 2. produire un document simple

Thèmes

Quarto est fourni avec plusieurs thèmes => voir ici.

Code

Un bloc de code (ou chunk en anglais) exécuté sans options.

glm(Sepal.Length ~ Sepal.Width, data = iris)

Call:  glm(formula = Sepal.Length ~ Sepal.Width, data = iris)

Coefficients:
(Intercept)  Sepal.Width  
     6.5262      -0.2234  

Degrees of Freedom: 149 Total (i.e. Null);  148 Residual
Null Deviance:      102.2 
Residual Deviance: 100.8    AIC: 372

Options de bloc de code

De nombreuses options sont disponibles pour personnaliser les blocs de code.

• Exécution :
• #| eval: exécuter le code
• #| echo: afficher le code
• Nommage :
• #| label: identifiant du chunk (pas obligatoire mais si vous décidez d’en mettre, pas de doublons)
• #| fig-cap: sert uniquement à légender une figure (image ou graphique par exemple)

Outils

Si on a #| echo: true l’utilisateur voit le code

On peut aussi ajouter des outils pour l’utilisateur pour qu’il affiche ou cache les chunks avec, dans l’en-tête YAML :

format: 
  html:
    code-fold: true
    code-tools: true

• code-fold: true permet à l’utilisateur de plier / déplier le code sous les résultats.

• code-tools: true permet d’ajouter une barre d’outils en haut du quarto pour les blocs de code.

Le bloc de code setup

Pour charger les packages et gérer la configuration de votre quarto, il est recommandé d’inclure un premier bloc de code juste après l’en-tête de votre document.
Voici un exemple :

Figure 3 –  Bloc de setup

À vous de jouer

Exercice 3. Code

Tableaux

Les tableaux sont balisés ainsi en Markdown :

| année | titre                   |
|------:|:------------------------|
|  1965 | Dune                    |
|  1969 | Le Messie de Dune       |
|  1976 | Les Enfants de Dune     |
|  1981 | L'Empereur-Dieu de Dune |
|  1984 | Les Hérétiques de Dune  |
|  1985 | La Maison des mères     |

: Cycle de Dune {#tbl-cycle}

année	titre
1965	Dune
1969	Le Messie de Dune
1976	Les Enfants de Dune
1981	L’Empereur-Dieu de Dune
1984	Les Hérétiques de Dune
1985	La Maison des mères

Tableau 1 –  Cycle de Dune

doc

Voir cet outil en ligne.

Mais la plupart du temps on affichera des tableaux programmatiquement.

iris |> 
  summarise(.by = Species,
            moy_sepales = sum(Sepal.Length))

     Species moy_sepales
1     setosa       250.3
2 versicolor       296.8
3  virginica       329.4

Tableau 2 –  Iris (tibble)

Avec {knitr} ou le paramètre en en-tête :

format:
  html:
    df-print: kable

iris |> 
  summarise(.by = Species,
            moy_sepales = sum(Sepal.Length)) |> 
  knitr::kable()

Species	moy_sepales
setosa	250.3
versicolor	296.8
virginica	329.4

Tableau 3 –  Iris (kable)

doc

Contrôler l’impression de data.frame avec df-print: kable ou df-print: paged, df-print: tibble Interactivité javascript df-print: paged à voir en exercice

ou avec {gt}

library(gt)

iris |> 
  summarise(.by = Species,
            moy_sepales = sum(Sepal.Length)) |> 
  gt()

Species	moy_sepales
setosa	250.3
versicolor	296.8
virginica	329.4

Tableau 4 –  Iris (gt)

Utiliser le préfixe tbl- pour l’identifiant afin de pouvoir bénéficier des renvois automatiques et la numérotation automatique

À vous de jouer

Exercice 4. Tableaux

Graphiques

ggplot(iris, aes(Petal.Length, 
                 Petal.Width, 
                 color = Species)) +
  geom_point()

Figure 4 –  Iris

Taille d’image dans Quarto (Arel-Bundock, 2024)

Interactivité possible avec {plotly} ou {ggiraph}. cf. exercices

À vous de jouer

Exercice 5. Graphiques

Cartes

library(leaflet)
library(sf)

"donnees/adminexpress_cog_simpl_000_2024.gpkg" |> 
  read_sf(layer = "region") |> 
  leaflet() |> 
  addTiles() |> 
  addPolygons()

Figure 5 –  Exemple Leaflet

À vous de jouer

Exercice 6. Cartes

Présentations

On peut faire des présentations.

• Chaque nouvelle slide est définie avec un titre de niveau 2 (##).
  
• Pour rédiger une slide sur plusieurs colonnes c’est ici.
  
• L’emplacement des outputs des blocs de code peut être configuré.

Diagrammes

• Mermaid
• À construire avec mermaid.live

flowchart TD
    A[(données)] --> B(importer) 
    B --> C[/données valides/]
    C --> D{"sum(sau > 200)"}
    D -- oui --> E(OK)
    D -- non --> F(Stop)

flowchart TD
    A[(données)] --> B(importer) 
    B --> C[/données valides/]
    C --> D{"sum(sau > 200)"}
    D -- oui --> E(OK)
    D -- non --> F(Stop)

Fonctionnalités avancées

Rapports paramétrés

mon_document.qmd

---
title: Rapport
format:
  html: default
params:
  region: 84
  sortie: knitr
---

## Région `{r} params$region`

```{r}
sau <- ra |> 
  filter(siege_reg == params$region) |> 
  summarise(.by = siege_dep,
            sau_tot = sum(sau_tot, na.rm = TRUE))

if (params$sortie == "knitr") kable::knitr(sau) else sau
```

On n’est pas obligé de changer manuellement les paramètres et re-tricoter ; on peut itérer sur une liste :

for (r in c(11, 94, 84, 04)) {
  quarto::quarto_render("mon_document.qmd",
                        execute_params = list(region = r),
                        output_file = paste0("rapport_", r, ".html"))
}

résultera en 4 rapports personnalisés : rapport_11.html, rapport_94.html,…

doc

Autres exemples de rapports paramétrés

Exemple 1 qui génère un contenu différent en Html/Pdf ou en fonction du paramètre srise.

Exemple 2 issu de la documentation officielle.

Inclusions

En tout point du qmd :

{{< include entete.qmd >}}

doc

ou dans le YAML pour ajouter de simples en-tête et pieds de page :

---
format:
  html:
    include-before-body: en_tete.html
    include-after-body: pied.html
---

doc

Cache

Pour les calculs longs et rarement variables on peut gagner du temps avec cache: true (au niveau document ou chunk).

```{r}
#| label: long-traitement
#| cache: true
#| cache-extra : !expr file.mtime("donnees/departements.gpkg")

region <- read_sf("donnees/departements.gpkg") |> 
  st_union()
```

Ne sera exécuté qu’une fois sauf si le code du chunk change ou si la date du fichier change ou si on passe à cache: false, ou via :

quarto render mon_document.qmd --cache-refresh

doc

cache peut être défini au niveau projet, document ou chunk.

Marque de l’État

Typographie Marianne

Pour textes et graphiques (Service d’information du gouvernement, 2020)

• Installer {ragg}, {systemfonts} et {textshaping}

• Dans l’en-tête yaml du document Quarto :

  ---
  mainfont: Marianne
  knitr:
    opts_chunk: 
      dev: "ragg_png"
  ---

Permet d’avoir la police Marianne pour le texte et de la prendre en compte dans les graphiques ggplot.

Autre possibilité (à mettre dans un chunk de configuration en début de document) : knitr::opts_chunk$set(dev = "ragg_png")

Références

Arel-Bundock V. Consistent Figures in Quarto. Vincent Arel-Bundock. juillet 2024. Disponible sur : < https://arelbundock.com/posts/quarto_figures/index.html >

Canouil M. Awesome-Quarto. janvier 2025. Disponible sur : < https://github.com/mcanouil/awesome-quarto >

Choe J. Setting up and Debugging Custom Fonts. June Choe. juin 2021. Disponible sur : < https://yjunechoe.github.io/posts/2021-06-24-setting-up-and-debugging-custom-fonts/ >

Heiss A. Working with R, Cairo Graphics, Custom Fonts, and Ggplot. Andrew Heiss. avril 2023. Disponible sur : < https://www.andrewheiss.com/blog/2017/09/27/working-with-r-cairo-graphics-custom-fonts-and-ggplot/ > (consulté le 21 janvier 2025)

R Development Core Team. R: A Language and Environment for Statistical Computing. 2010. Disponible sur : < http://www.R-project.org/ >

RStudio. Guide. Quarto. 2024a. Disponible sur : < https://quarto.org/docs/guide/ >

RStudio. Publish and Share with Quarto :: Cheatsheet. 2024b. Disponible sur : < https://rstudio.github.io/cheatsheets/html/quarto.html >

Service d’information du gouvernement. Charte graphique de l’État. [s.l.] : République française, 2020. Disponible sur : < https://www.gouvernement.fr/marque-Etat >