Transiter de Rmarkdown vers quarto

Introduction

Si vous utilisez Rmarkdown pour générer vos rapports d’analyse, vos notices techniques ou encore vos TPs, vous avez sans doute entendu parler de Quarto.

Quarto, c’est la nouvelle génération de R markdown. Elle est présentée comme avancée et enrichie.

Quarto existe depuis l’été 2021, mais son début ont plutôt été timides ; sans doute parce que l’outil était encore en développement. Il l’est toujours aujourd’hui, mais à présent Quarto est bien abouti.

Avec Quarto, nous pouvons faire globalement les mêmes choses qu’avec R markdown, mais de manière plus flexible et plus intégrée.

De manière basique, vous pourrez générer des documents (qui intègrent ou pas du code R) dans les formats html, word ou pdf, mais avec plus de facilité pour gérer, par exemple, les images, les références croisées, ou encore pour ajouter des boites d’alerte.

Vous pourrez également réaliser des diapositives, des dashboards et des sites webs, des livres, comme R markdown mais nativement, c’est à dire sans faire appel à des packages complémentaires comme bookdown (livres), xaringan (slides), flexdasboard (dashboard).

Quarto bénéficie d’une documentation très riche, que vous pouvez retrouver en cliquant sur ce lien https://quarto.org/docs/guide/

À noter aussi que Quarto est multilangage de programmation : il peut être utilisé avec R, Python Julia et SQL. Il peut aussi être employé avec d’autres interfaces que R Studio, par exemple JupyterLab ou VS code.

Table des matières

Comment installer Quarto ?

Quarto est associé à R Studio, pour disposer de cet outil, il est nécessaire d’installer une version récente de RStudio : https://posit.co/download/rstudio-desktop/

La documentation de Quarto

Vous trouverez un guide d’utilisation de Quarto ici : https://quarto.org/docs/guide/

Dans la section intitulée Authoring, vous découvrirez les informations fondamentales.

La section Documents contient des explications détaillées sur les formats de sortie les plus importants.

Quant aux présentations, aux tableaux de bord, aux sites web et aux livres, ils bénéficient chacun de sections spécifiques.

Il est également important de souligner que d’autres éléments intéressant comme des extensions, des template et des exemples sont accessibles dans le menu supérieur.

Générer son premier document avec Quarto

Comme d’habitude, je vous conseille d’organiser au préalable votre travail selon un projet R (pour davantage d’informations, vous pouvez consulter l’article “7 étapes pour organiser son travail sous R” )

Ensuite, allez dans le menu File –> Newfile –> Quarto document –> entrer un titre et sauvez le (à la racine de votre projet R ou dans un sous dossier). 

Créer son premier document quarto

Puis passez en mode “Source” :

Passez en mode source

Et cliquez sur le bouton Render, pour générer le document rendu en html.

La syntaxe Quarto

Similitudes avec Rmarkdown

Quarto utilise globalement les mêmes balises que R markdown :

  • les titres sont marqués par des dièses
  • les balises étoile pour passer un texte en gras, italique, etc… sont les mêmes
  • les balises pour les liens hypertextes, et l’importation des images sont conservées
  • les listes numérotées, ou à puces, sont créées de la même façon avec les symboles +, – , *
  • les parties de code sont à intégrer dans des chunks délimités par les apostrophes “` (AltGr + 7)
  • les équations en latex toujours contenues dans un simple dollar pour les intégrer dans le texte, et un double dollar pour en faire un bloc
  • etc…

Vous pouvez retrouver ces informations ici.

Différences avec Rmarkdown

Partie en tête

La partie en tête, dans le yaml, est légèrement différente dans la précision des formats de sortie :

Comparaison des entetes Rmarkdown et Quarto

Il faut toujours faire attention a l’indentation (les espaces avant le nom des options).

Partie code

La différence qui saute aux yeux quand on commence à employer Quarto, c’est la syntaxe des options à l’intérieur des chunks. Celles-ci ne sont plus dans les accolades, mais en dehors, et précédées de #|, comme ceci :

```{r}
#| echo: true
#| fig-cap : "Iris data"

library(ggplot2)
ggplot(iris,aes(x=Sepal.Length, y=Petal.Length, colour=Species))+
  geom_point()+
  geom_smooth()
``` 

À noter aussi qu’à présent les options sont en minuscule et utilisent les 2 pointsecho : true contre echo="TRUE" (signe = et utilisation des majuscules) pour R markdown :

```{r, echo="TRUE", fig.cap="Iris data"}

library(ggplot2)
ggplot(iris,aes(x=Sepal.Length, y=Petal.Length, colour=Species))+
  geom_point()+
  geom_smooth()
``` 
```{r}
#| echo: true
#| fig-cap : "Iris data"

library(ggplot2)
ggplot(iris,aes(x=Sepal.Length, y=Petal.Length, colour=Species))+
  geom_point()+
  geom_smooth()
``` 

Cela dit, vous pouvez continuer à utiliser votre syntaxe R markdown (avec les options dans les accolades), dans Quarto !

Remarques: Dans la documentation de Quarto (https://quarto.org/docs/guide/) je n’ai pas trouvé de liste globale répertoriant toutes les options de chunk possibles, elles sont disséminés dans les différents paragraphes

Création du document rendu

On ne retrouve plus de bouton knit mais un bouton Render.

Les 3 formats peuvent s’indiquer comme ceci :


---
title: "My Document"
format:
  docx:
    toc: true
    number-sections: true
    highlight-style: github
  html:
    toc: true
    number-sections: true
  pdf:
    toc: true
    number-sections: true 
editor: visual
editor_options: 
  chunk_output_type: console    
--- 

Par défaut, le document est rendu dans le premier format indiqué. Mais comme avec Rmarkdown, vous pouvez choisir le format de sortie en ouvrant le menu du bouton Render, et en sélectionnant le format de sortie désiré (À condition d’avoir spécifier les 3 formats dans l’entête)

Vous pouvez aussi utiliser la fonction quarto_render() pour générer le document dans le format de sortie désiré. Pour cela, il est nécessaire d’installer la package quarto, et de charger la librairie.

Par exemple, pour générer le document en html, word et pdf, vous pouvez utiliser le code suivant :

# library(quarto)
# quarto_render( "mon_script_quarto.qmd", output_format="html")
# 
# quarto_render( "mon_script_quarto.qmd", output_format="docx")
# 
# quarto_render( "mon_script_quarto.qmd", output_format="pdf") 

À noter que si vous voulez un rendu au pdf, vous devez, au préalable, installer TinyTex en exécutant les commande suivant dans le terminal (onglet voisin de la console):

quarto install tinytex 

NB: si vous n’avez pas d’onglet Terminal, vous pouvez l’ouvrir en allant dans le menu supérieur –> Tools –> Terminal –> New Terminal.

Mes premiers pas avec Quarto

Le chunk setup des options par défaut

Avec R markdown, quand on ouvre un nouveau fichier R Markdown, le script comporte un chunk set up dans lequel on peut mettre toutes les options par défaut des chunks subséquents :

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

Je n’ai rien trouvé de comparable dans Quarto, alors j’ai simplement copier-coller ce chunk, et cela fonctionne très bien. Par exemple, ici, j’utilise l’option message=FALSE pour ne pas afficher les messages d’information générés dans les chunks, ici concernant les packages tidyverse et drc:

EDIT : Il s’avère que vous pouvez mettre ces options dans l’entête (voir les commentaires d’Antoine et Audrey)

Gestion des chemins d’accès

```{r}
#| eval : false  
#| echo : false  

write.csv2(airquality,"data/airquality.csv", row.names = FALSE)
``` 

Comme dans Rmarkdown, le répertoire par défaut d’éxécution des chunks est le répertoire où se trouve le script quarto.

J’utilise en général cette hiérarchie pour mon projet R :

Mon script Quarto est dans le dossier “scripts”. Pour importer des data, j’utilise la fonction here() du package here() , comme ceci : here::here(data/mesdata.csv).

Cela me permet d’importer les données en

  • exécutant la commande directement dans la console,
  • ou en générant le document avec le bouton render (ça marche dans les deux cas)

Voici un exemple :

```{r}
AQ <- read.csv2(here::here("data/airquality.csv"))
head(AQ)

``` 

Equations

Pas de changement par rapport à RMardown, vous pouvez employer un dollar pour intégrer une équation ou des caractères mathématiques dans une phrase, et 2 dollars pour faire un bloc :

Si vous employez beaucoup d’équation, je vous recommande l’outil Mathpix pour les capturer et les écrire automatiquement. Vous trouverez plus d’informations dans cet article : Les équations en LaTeX pour Rmarkdown : même pas peur

Intégrer un encart

Quarto appelle cela des callout Block. C’est une belle nouveauté, car cela est très utile pour attirer l’attention du lecteur, et cela se réalise hyper facilement. Il y en a 5 types :

  • note
  • tip
  • warning
  • caution
  • important

 

Pour les générer, c’est tout simple, il suffit d’employer le code suivant directement dans le script (et non dans un chunk)

Belle astuce indiquée par Antoine (voir son commentaire)  : pour insérer des callout blocks, vous pouvez utiliser l’addin Quartostamp : https://matt-dray.github.io/quartostamp/index.html

# pour installer quartostamp

install.packages("remotes")  # if not yet installed
remotes::install_github("matt-dray/quartostamp") 

Est ce que vous devez passer à Quarto ?

Je dirais que si vous travaillez seul, dans votre coin, et que vous faites seulement des comptes rendus d’analyse simples, des notices techniques ou des TP, que vous parvenez à faire ce dont vous avez besoins et que le résultat est satisfaisant, cela ne me parait pas complètement indispensable de passer à Quarto (en tout cas il n’y a pas urgence).

Si vous travaillez en équipe, que tout le monde est encore en R markdown et que ça fait le job, là encore il n’y a pas de nécessité absolue.

Par contre, si vous collaborez avec des personnes qui ont tendance à suivre l’évolution de R, et/ou si vous faites de multiples taches (rédiger des livres, éditer des slides, construire des tableaux de bord), je pense que ça vaut le coup de franchir le pas. Quarto vous permettra de dépasser les difficultés que l’on peut rencontrer avec R markdown, et vous permettra une plus grande flexibilité dans les rendus.

Conclusion

Quarto se présente comme une évolution significative de R Markdown, offrant une flexibilité et une intégration accrue pour la création de documents, de présentations, de tableaux de bord etc… 

L’installation aisée, la documentation riche et les fonctionnalités avancées telles que la gestion des références croisées et des alertes, ainsi que la prise en charge native de divers formats de sortie, rendent Quarto particulièrement attrayant.

De plus, la transition de R Markdown à Quarto est facilitée par la conservation de nombreuses syntaxes familières.

Personnellement, je suis convaincu par les atouts de Quarto et je choisis de faire la transition vers cet outil pour mes futurs projets.

Et vous ?

Est-ce que vous êtes convaincus ?

Est-ce que vous avez déjà franchi le pas ?

Est-ce que vous allez franchir le pas ?

Dites-le-moi en commentaire. Et surtout, n’hésitez pas à partager vos expériences, qu’elles soient positives ou négatives, avec Quarto. Vos retours sont précieux ! 👇👇👇

7 Responses

  1. Bonjour,
    Bravo pour ces blogs très pédagogiques
    Quelques petits infos complémentaires:
    – L’option de choix de sortie (la petite fléche qui est a coté de render) n’est disponible que si on a renseigné plusieurs formats de sortie dans le Yaml (et que pour celà.
    – Les options generales des chunks se gère dans le Yaml ( la documentation de Quarto n’est pas très claire) mais echo : false, cache : true dans le format marche.
    Mon option préférée pour les formats html est code-fold: true qui permet d’avoir le code visible après dépliment
    – Pour les encarts, onglet et la mise en page, il existe un addins Quartostamp, qui permet d’avoir un apprentissage assisté des commandes spécifiques

    1. Bonsoir Antoine,

      Merci beaucoup pour ces précisions et pour l’astuce de l’addin Quartostamp ! J’ai essayé et c’est pas mal du tout !

  2. Chère Claire, dans ce post, tu proposes la ligne de code `AQ <- read.csv2(here::here("data/airquality.csv"))`, mais un simple `AQ <- read.csv2("data/airquality.csv")` ne fait-il pas la même chose si le wd est correctement déclaré ? Quelle est la valeur ajoutée de `here()` ?

    1. Bonjour Sandrine,
      Si sans doute (en tout cas d’après ma compréhension). Mais personnellement, dans ma pratique courante, je n’utilise pas la fonction setwd(). Je range mes scripts dans un dossier que j’appelle “scripts” et comme le répertoire d’exécution du fichier.qmd est celui où il se trouve (“scripts” pour moi) je ne suis pas au même niveai d’exécution lorsque je copie colle la commande d d’importation dans la console (là je suis au niveau de la racine du projet) et lorsque je le knit (render) (là je suis au niveau du dossier script). La commande here() permet d’écrire le chemin d’accès des données en absolue, et ça fonctionne quel que soit le niveau d’exécution (à la racine du projet, ou dans le dossier script). Ça me permet donc d’avoir une seule ligne de commande qui fonctionne à tous les coups, sans avoir à toucher au working directory.
      J’espère que mes explications sont compréhensibles 😁

  3. Bonjour Claire,
    Je tiens à vous remercier pou votre publication aussi limpide que surprenante sur la migration de RMarkdown vers Quarto. Je ne savais que Quarto existe déjà, sauf que ce nom me rappelle un tableur du même nom que nous avons utilisé autrefois avec plaisir avant qu’il soit remplacé définitivement par MS Excel. Passé le moment surprise, je pense que moi je reste encore chez RMarkdown d’autant que je ne l’utilise que rarement. Mais c’est toujours bon de savoir ce qui ce passe dans ce domaine.

Laisser un commentaire

Votre adresse e-mail ne sera pas publiée. Les champs obligatoires sont indiqués avec *

Vous souhaitez vous former à R, ou aux statistiques ?

Retrouver le planning et les programmes de  mes formations ici  👇👇👇 

Vous avez besoin d'un assitance pour analyser vos données ?

Retrouver mes propositions de services ici  👇👇👇 

Vous souhaitez soutenir mon travail ?​

C’est possible en faisant un don  sur la page Tipeee du blog  👇👇👇

Bonjour !

vous venez souvent ?

Identifiez-vous pour avoir accès à toutes les fontionnalités !

Aide mémoire off'R ;)

Enregistrez vous pour recevoir gratuitement mes fiches “aide mémoire” (ou cheat sheets) qui vous permettront de réaliser facilement les principales analyses biostatistiques avec le logiciel R et pour être informés des mises à jour du site.