Introduction à Quarto

Charles Martin

Avril 2024

• Introduction
• Fonctionnement
• Mise en forme du texte
• Tableaux
• Code R
• Code Python
• Figures
• Équations
• Liens internes
• Notes de bas de page et encadrés
• Note à propos de l’envoi des fichiers HTML Quarto
• Conclusion

Introduction

L’atelier d’aujourd’hui portera sur Quarto¹, le nouveau système de publication en libre accès publié par la compagnie Posit (anciennement RStudio).

Ce nouvel environnement est essentiellement une évolution de ce qui s’appelait autrefois RMarkdown. Mais puisque Posit a élargi ses horizons, Quarto peut maintenant s’utiliser autant pour créer des projets R que Python.

De façon succincte, Quarto permet de mélanger une panoplie de contenus dans un document (du texte, des équations, des images, du code, des graphiques, etc.) et ensuite de compiler tout cela en un seul document, soit HTML, PDF, etc. Le terme utilisé dans l’environnement Quarto pour cette compilation se nomme, très poétiquement, le tricotage (knitting).

Fonctionnement

Bien qu’utilisable à l’extérieur de RStudio, Quarto est beaucoup plus simple d’utilisation à l’intérieur de celui-ci. Pour créer une fichier Quarto, il faut simplement cliquer le menu Fichier > Nouveau Fichier > Document Quarto. Cette séquence devrait vous ouvrir un fichier .qmd avec lequel vous êtes prêtes à travailler. À n’importe quel moment, vous pouvez tricoter votre fichier en cliquant le bouton Render, ou en utilisant le raccourci Cmd+Shift+K. Selon la configuration utilisée, votre document s’ouvrira dans une fenêtre externe ou dans l’onglet Aperçu de RStudio.

Mise en forme du texte

La chose la plus commune que vous risquez de faire dans votre document Quarto est de mettre en forme du texte. Le langage utilisé pour se faire se nomme Markdown. Ce dernier est une langage assez rudimentaire, mais qui permet de faire de façon intuitive la majorité des mises en formes de base.

Tout d’abord, toutes les lignes précédées d’un # (hashtag/dièse) sont considérées comme des titres. On peut créer une hiérarchie de titres en mettant plusieurs dièses au début de chaque ligne. Par exemple :

# Titre
## Sous-titre
### Sous-sous-titre

deviendra :

Titre

Sous-titre

Sous-sous-titre

On peut aussi utiliser du gras et de l’italique avec les astérisques :

Ce texte deviendras *gras*, celui-là en **italique**

Ce texte deviendras gras, celui-là en italique

On peut aussi mettre le texte en indice ou en exposant :

I^2^ = x~2~

I² = x₂

Il est aussi possible d’ajouter des liens, soit directement comme ceci :

<https://quarto.org/>

https://quarto.org/

Ou sur un bout de texte, comme cela :

Le [site web de Quarto](https://quarto.org/) est très intéressant.

Le site web de Quarto est très intéressant.

On peut, évidemment, aussi faire des listes à puces, comme ceci :

* A
  * B
    * C
* D

• A
  • B
    • C
• D

Et des listes numérotées, comme cela :

1. A
2. B
3. C

1. A
2. B
3. C

Tableaux

On peut aussi créer des tableaux :

| fruit  | price  |
|--------|--------|
| apple  | 2.05   |
| pear   | 1.37   |
| orange | 3.09   |

devient

Et avec les “:”, contrôler l’alignement dans les cellules :

| gauche  | centré  | droite |
|:--------|:-------:|-------:|
| 1.99    | 1.99    | 1.99   |
| 10.99   | 10.99   | 10.99  |

Code R

On peut ajouter du code R n’importe où à travers notre document, en utilisant ces balises :

```{r}
library(ggplot2)
library(dplyr)
```

Attaching package: 'dplyr'

The following objects are masked from 'package:stats':

    filter, lag

The following objects are masked from 'package:base':

    intersect, setdiff, setequal, union

```{r}
ggplot(msleep, aes(sleep_total)) + 
  geom_histogram()
```

`stat_bin()` using `bins = 30`. Pick better value with `binwidth`.

Si vous ne voulez pas encombrer votre code avec les messages, vous pouvez les cacher en changeant les options du bloc de code :

```{r}
#| warning : FALSE
#| message : FALSE
library(ggplot2)
library(dplyr)
ggplot(msleep, aes(sleep_total)) + 
  geom_histogram()
```

Votre code R, plutôt que d’être dans un bloc, peut aussi s’intégrer à votre paragraphe de texte. Par exemple, si vous écrivez ceci :

Notre tableau de données compte `r length(unique(msleep$vore))` types d'alimentation différents.

Vous obtiendrez cela :

Notre tableau de données compte 5 types d’alimentation différents.

Remarquez que le code est exécuté en séquence. Les librairies chargées et les objets créés sont disponibles dans le reste du document.

Le code R générant des tableaux sera mis en forme comme les tableaux manuels vu ci-haut, pour autant que l’on passe le tableau de données à la fonction kable de la librairie kableExtra

```{r}
#| message: false
#| warning: false
library(kableExtra)
msleep %>% 
  select(name, vore, bodywt) %>% 
  slice(1:5) %>% 
  kable
```

Code Python

Tout ce que nous venons de voir est également vrai pour le code Python, pour autant que Python et RStudio soient configurés correctement.

Par exemple :

```{python}
especes = ['A','B','C']
especes[2] = 'D'
print(especes)
```

['A', 'B', 'D']

Les graphiques sortiront aussi proprement avec Python :

```{python}
import matplotlib.pyplot as plt
import pandas as pd
iris = pd.read_csv('https://raw.githubusercontent.com/mwaskom/seaborn-data/master/iris.csv')
plt.hist('sepal_length', data = iris)
```

Figures

Il peut parfois vous arriver que les images que vous voulez afficher ne soient pas créées par un bout de code, mais trainent plutôt sur votre ordinateur, par exemple, une photo de chat :

![](chat.jpg)

Pour insérer une image avec sa légende, il suffit d’utiliser le code en deux parties suivant :

![Une photo de mon chat](chat.jpg)

Entre les parenthèses carrées, on retrouve la légende, et entre les vraies parenthèses, le nom de l’image.

Si vous voulez que vos légendes soient constantes entre vos figures mêmes si certaines sont produites par programmation, vous pouvez aussi ajouter une légende aux graphiques créés par programmation, comme cela :

```{r}
#| message : FALSE 
#| echo : FALSE 
#| fig-cap : "Temps de sommeil des autres animaux qui ne sont pas mon chat"
ggplot(msleep, aes(sleep_total)) + 
  geom_histogram()
```

Ici, l’option echo : FALSE permet de cacher le code et de n’afficher que le graphique directement.

Équations

Comme les documents Quarto sont souvent très techniques, les auteurs ont prévu une façon simple d’insérer des équations mathématiques, en utilisant le langage Latex.

Pour insérer une formule à l’intérieur d’un bloc de texte (on parle alors de formule inline), on entoure notre équation de signes de dollars. Ceci $E=mc^2$ devient par exemple cela $E=mc^2$.

Si on veut que notre équation soit par elle-même sur une ligne, il faut alors l’entourer de doubles signes de dollars. $$y=ax+b$$ devient \(y=ax+b\)

Outre les éléments intuitifs comme =, +, -, etc., le langage contient toute une série de caractères spéciaux, incluant entre autres les lettres grecques, majuscules ou minuscules. On peut appeler des caractères spéciaux Latex grâce au \. Par exemple, ce code Latex $\alpha,\beta,\Gamma,\pi$ devient $\alpha,\beta,\Gamma,\pi$.

Il existe toute une série de codes concernant des structures mathématiques particulières, entre autre les exposants et les indices :

Par exemple, $$y_i=\beta_0+\beta_1 x_1+\beta_2 x_1^2+\epsilon_i$$ devient

Si jamais vous avez plus d’un élément à mettre en indices, il faut entourer votre série d’éléments avec des accolades. Par exemple, la séquence $2^{1+x_{i,j}}$ devient $2^{1+x_{i,j}}$.

Remarquez que malheureusement, la syntaxe pour les indices et les exposants est différente, selon que vous écrivez du texte (en Markdown) ou des équations (en Latex).

Vous avez aussi accès aux sommes, aux intégrales, aux produits, etc

$$\sum_{i=1}^{10} t_i$$ \(\sum_{i=1}^{10} t_i\)

$$\int_0^\infty e^{-x}$$ \(\int_0^\infty e^{-x}\)

$$\prod_{i=1}^\infty a_i$$ \(\prod_{i=1}^\infty a_i\)

Enfin, vous pouvez aussi définir des racines carrées et des fractions, comme ceci :

$$x=(\frac{\sqrt{y+2}}{z})$$

Remarquez que par défaut, Latex présente les parenthèses de la même taille que le texte. Vous pouvez cependant demander de les faire ajustables, pour que peu importe la taille du contenu, les parenthèses soient visuellement appropriées.

Pour se faire, vous devez précéder la parenthèse de gauche du code spécial \left et celle de droite… de \right. L’équation précédente sera beaucoup agréable à lire si elle est donc créée comme ceci :

$$x=\left(\frac{\sqrt{y+2}}{z}\right)$$

Évidemment, cet atelier n’est pas dédié entièrement au Latex. C’est pourquoi je vous conseille de consulter une resource externe si jamais vous avez besoin de notation plus avancée².

Liens internes

Si on veut que notre équation soit numérotée et référençable, il faut lui assigner une étiquette immédiatement après sa création. Par exemple $$c=\sqrt{a^2+b^2}$${#eq-hypothenuse} devient : \(c=\sqrt{a^2+b^2} \qquad(1)\)

Remarquez que pour que Quarto considère votre étiquette comme une équation, son nom doit commencer par eq-.

Par la suite, on peut avec une mention @eq-hypothenuse y faire référence n’importe où dans le texte (Équation 1), même au-dessus de sa définition.

Ce mécanisme fonctionne aussi pour les figures. On peut par exemple citer une figure avec @fig-exemple (qui devient : Figure 1), et la créer plus loin dans notre document :

```{r}
#| message: FALSE
#| label: fig-exemple
#| fig-cap: "Titre de la figure référencée"
ggplot(msleep, aes(sleep_total)) + 
  geom_histogram()
```

À ce moment-là, l’étiquette (label) de la figure doit être mentionné dans les options du bloc de code.

Comme vous l’avez peut-être remarqué plus haut, les références sont faites avec des termes anglais, qui commencent par des majuscules, par exemple “Equation 1”. Cette terminologie peut être changée dans les options globales du fichier, par exemple comme ceci pour changer l’étiquette donnée aux équations et aux figures :

---
title: "Titre du document"
crossref:
  eq-prefix: Éq.
  fig-prefix: Fig.
---

Vous pouvez aussi profiter du travail de traduction fait en amont par l’équipe de Quarto, en changeant simplement la langue du document en entier :

---
title: "Titre du document"
lang: fr
---

On peut aussi modifier la référence directement au moment de l’insérer, en l’encadrant par des parenthèses carrées. Par exemple, [Formule @eq-hypothenuse] devient Formule 1

Ces références peuvent aussi être utilisées avec des tableaux, peu importe qu’ils soient créés manuellement ou par programmation :

```{r}
#| tbl-cap: Liste des mammifères
#| label: tbl-mams
#| message: false
#| warning: false
library(kableExtra)
msleep %>% 
  select(name, vore, bodywt) %>% 
  slice(1:5) %>% 
  kable
```

Table 1: Liste des mammifères

Je peux maintenant faire référence au Tableau 1 dans mon texte avec la mention [Tableau @tbl-mams].

Remarquez qu’il faudrait changer l’option globale tbl-prefix pour “Tableau” si on veut que la mention au haut du tableau soit aussi correcte.

Notes de bas de page et encadrés

On peut aussi ajouter des notes de base de page à notre document Quarto. Pour ce faire, il suffit d’insérer une mention [^lanote], et ensuite de définir son contenu quelque part. Par exemple, ce bout de texte :

J'insère ma note ici[^lanote], et je la définis plus bas

[^lanote]: Ici je définis ma note

Sera transformé comme cela :

J’insère ma note ici³, et je la définis plus bas

La note peut même contenu plusieurs paragraphes, pour autant que chacun d’entre eux soit indenté avec au moins 2 tab ou 4 espaces.

Par exemple

Lien vers la longue[^longuenote] note.

[^longuenote]: Deviendra cela.

    Même si j'ai besoin de plusieurs paragraphes pour y arriver.

Lien vers la longue⁴ note.

On peut aussi créer de encadrés, en créant manuellement une cellule Quarto à l’aide des ::: et en choisissant le type d’encadré, par exemple un avertissement :

::: {.callout-warning}
Le contenu important de l'avertissement
:::

devient

Warning

Le contenu important de l’avertissement

Il existe plusieurs autre types :

• note
• important
• tip
• caution

Ces boîtes peuvent être aussi déplacées dans la marge en ajoutant l’option .column-margin à la cellule.

Par exemple, cette note ira se placer à droite :

::: {.column-margin .callout-note}
Le contenu important de la note
:::

Note

Le contenu important de la note

Et en fait, n’importe quel contenu peut être placé dans la marge de droite, même du code R :

```{r}
#| column: margin
ggplot(msleep, aes(bodywt, brainwt)) + 
geom_point()
```

Warning: Removed 27 rows containing missing values or values outside the scale range
(`geom_point()`).

Note à propos de l’envoi des fichiers HTML Quarto

Vous avez peut-être remarqué qu’au moment de tricoter votre fichier HMTL, Quarto crée aussi des dossiers contenant les figures R, des librairies de javascript etc. Ces dossiers doivent toujours accompagner le document HTML si vous voulez que ce dernier s’affiche correctement.

Si cette façon de faire ne vous plaît pas, vous pouvez modifier activer l’option embed-resources. Celle-ci indiquera à Quarto d’intégrer toute l’information, même le contenu des images, à l’intérieur d’un seul fichier HTML. Ce dernier deviendra plus lourd, mais pourra être transféré directement.

---
format:
  html:
    embed-resources: true
---

Conclusion

Ceci termine notre petit survol des capacité du système Quarto développé par Posit. Comme vous le constatez, il s’agit d’un système à la fois simple et extrêmement puissant pour communiquer les résultats de vos analyses.

Si jamais vous voulez pousser l’aventure plus loin, Quarto peut-être aussi utilisé, entre autres, pour publier facilement des livres et des blogues.