Formation Quarto

Parcours de formation R perfectionnement SSP

Michaël Delorme
michael.delorme@agriculture.gouv.fr

SSP/DéMéSIS

2025-02-07

Pré-requis techniques

  • Quarto (≥ 1.5)
  • RStudio (≥ 2022.07) et R (≥ 4)
library(dplyr)   # manip. données
library(ggplot2) # graphiques
library(sf)      # carto.
library(leaflet) # carto.
library(gt)      # formatage tableaux

# un theme ggplot utilisant la typographie Marianne
theme_masa <- function(...) {
  theme_grey(...) %+replace%
    theme(
      text = element_text(family = "Marianne"))
}

Introduction

Mise en garde

DIAPORAMA EN COURS DE CONSTRUCTION

Un module des formations à R dispensées au MASA

Objectifs

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

Quarto

Un système de publication

Figure 1 –  Principe de fonctionnement (source RStudio)

Formats/moteurs

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

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

Inconvénients

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

Sur CERISE

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

Structure et syntaxe

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

And when it has gone past I will turn the `{r} somme` inner eye to see its 
path. Where the fear has gone there will be nothing. 

> Only I will remain.

markdown

Un langage balisé simplifié

doc

chunks

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

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

1+1
```

Ctrl Alt i

doc

En-tête de configuration

  • YAML
  • bloc entre ---
  • Facultatif mais a minima : title:, author:, date:, format:
  • options nombreuses et variables selon les formats

Rendu

(knit)

quarto render mon_document.qmd

Ctrl ⇧ k ou (ou )

À 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

Liens

[Texte du lien](https://fr.wikipedia.org/wiki/Arrakis)

Texte du lien

Images

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

A sand worm on Arrakis

Figure 2 –  Fremen 

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

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: " &ndash; "
---

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 facile1 à faire si on se rappelle de la syntaxe.

É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

Citations/bibliographie

Avec Zotero et l’extension Better BibTeX pour auto-exporter en BibTeX la collection quand elle est modifiée.

Préciser le fichier utilisé en en-tête, puis utilisation des identifiants du fichier BibTex.

---
title: "Mon document"
bibliography: formation_quarto.bib
---

Comme le dit @rdevelopmentcoreteamLanguageEnvironmentStatistical2010 :

> Lorem ipsum dolor sit amet[@rstudioGuide2024], consectetur adipiscing elit

Comme le dit R Development Core Team (2010) :

Lorem ipsum dolor sit amet (RStudio, 2024a), consectetur adipiscing elit

La bibliographie est directement générée :

  • en fin de document ou

  • après un <div> identifié avec #refs ex. :

    ## Références
::: {#refs}
:::

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é des colonnettes à crémaillère (…)

::: callout-warning
#### Attention

Le caisson de calibrage de la bride du commutateur à fuseaux (...)
:::

Attention

Le caisson de calibrage de la bride du commutateur à fuseaux rotatifs est HORS-SERVICE

doc

À vous de jouer

Exercice 2. produire un document simple

Code

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

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

  • exécution :
  • #| eval: exécuter le code
  • #| echo: afficher le code
  • nommage :
  • #| label: identifiant du chunk
  • #| fig-cap: légende du bloc

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

Sorties de code

  • texte, avec :
    • #| results: markup ou
    • cat() et #| results: asis
  • tableaux
  • images
  • éléments interactifs

À 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

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

ou avec {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)

À vous de jouer

Exercice 4. Tableaux

Graphiques

ggplot(iris, aes(Petal.Length, 
                 Petal.Width, 
                 color = Species)) +
  geom_point() +
  theme_masa()
Graphique en nuage de points des longueurs et largeurs de pétales par espèce d'Iris
Figure 3 –  Iris

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

À vous de jouer

Exercice 5. Graphiques

Cartes

"~/CERISE/03-Espace-de-Diffusion/000_Referentiels/0040_Geo/IGN/adminexpress/adminexpress_cog_simpl_000_2024.gpkg" |> 
  read_sf(layer = "region") |> 
  leaflet() |>
  addTiles() |> 
  addPolygons()
Figure 4 –  Exemple Leaflet

À vous de jouer

Exercice 6. Cartes

Diagrammes

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
param:
  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

À vous de jouer

Exercice 8. rapports paramétrés

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

Crosstalk

// TODO

doc

Dashboards

// TODO

doc

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

Couleurs

Modification du thème ou des CSS

// TODO

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 >