Réaliser un article scientifique avec Quarto

Note

Twitch du 18 mars 2025.

Code disponible sur GitHub.

C’est quoi Quarto ?

Après une dizaine d’année de développement sur RMarkdown, Posit (anciennement RStudio) a annoncé en 2022 la naissance de Quarto.
Donc Quarto est l’héritier de RMarkdown qui combien le texte sous format Markdown et les portions de code appelé chunk.
Le code peut-être en R comme en Python.

Comme RMarkdown, sa grande force est de rendre reproductible, répétable et réutilisable les lignes de codes.

Innovation

Il n’y aura pas ou peu d’innovations sur RMarkdown maintenant que Quarto existe.

Création d’un projet Quarto

La grosse nouveauté entre RMarkdown et Quarto est que Quarto est une infrastructure plus large qui remplace le classique projet RStudio.

Pour créer un projet Quarto, c’est très simple, il suffit de cliquer sur l’icône bleue projet ou File > New Project....
Ensuite, il faut cliquer sur Quarto project. S’il n’apparaît pas ce que RStudio n’est pas à jour. Il est nécessaire de commencer par mettre à jour R et RStudio.

Le projet créé contient trois fichiers :

_ Le fichier _quarto.yml qui contient les paramétrages du dossier
_ Le fichier nom_du_projet.qmd qui est un document Quarto généré automatiquement
_ Le fichier nom_du_projet.Rproj, le fichier du projet

Le document Quarto généré automatiquement est très simple. Il est là pour comprendre le fonctionnement de base. Il est très utile pour apprendre à manipuler Quarto.

Lecture d’un fichier Quarto

Les fichiers Quarto ont une composition classique : une en-tête YAML facultative avec un enchaînement de texte et de blocs de codes.

Deux vues sont disponibles :

_ Visual : Qui ressemble à ce qui sera obtenu avec des clics boutons proches d’un logiciel de traitement texte tels que Word, Mot, Writer…
_ Source : Qui contient le script en Markdown

En-tête YAML (facultative)

Elle permet de paramétrer les sorties du document mais elle n’est pas obligatoire

Indentation

Si l’indentation (les espaces avant le texte) n’a que peu d’importance dans le code R, elle est très importante en YAML et doit-être regardé avec attention !

Le document généré automatiquement ne possède qu’un titre dans l’en-tête.

Syntaxe du texte

Le texte en Quarto, utilise la syntaxe Markdown :

_ Les titres sont caractérisés par des # en fonction du niveau : #Titre de niveau 1, ##Titre de niveau 2…
_ La mise en forme du texte se fait avec les étoiles ou les impostrophes (apostrophe à l’envers) :

• Une étoile * avant et après la partie à valoriser permet de mettre en italique (codé *italique*)
  
• Deux ** avant et après mettent en gras (codé **gras**)
  
• Trois *** avant et après mettent en gras et italique (codé ***gras et italique***)
  
• Un double espace permet de passer à la ligne. Il faut donc toujours mettre deux espaces à la fin de chaque ligne. Sans ces espaces, toutes les lignes sont collées les unes à la suite des autres
  
• Pour éditer un format code (sans qu’il se lance) pour présenter les packages, les fonctions ou les objets utilisés (comme fait dans ce document), il faut encadrer d’impostrophes

Des images peuvent aussi être intégrées grâce à ![*légende_de_l_image*](adresse_de_l_image.format_de_l_image)

Portion de code

Le code est enregistré dans des chuncks délimités par trois impostrophes comme ci-dessous.
Les paramètres du chunk sont précédés de #|.
Cela permet de donner un nom au chunck avec #| label: nom_du_chunk ou de choisir les sorties #| echo: true : le code est affiché dans le format de sortie, #| warning: false : les messages de type warning ne sont pas affichés…
Touts les paramétrages peuvent se retrouver dans le guide Quatro.

```{r}
#| label: nom_du_chunk
#| warning: false

1 + 1
```

[1] 2

Si un des impostrophes est supprimé par erreur, le code ne peut pas se lancer !
Il faut toujours vérifier que les chunks soient bien fermés (fond d’une couleur différente).

Ajout d’une équation

Dans la ligne avec le symbole dollar Soit on peut choisir de les intégrer dans le texte : $Y = aX + b$ ou dans un bloc à part grâce au double dollar $$ Z = Y + zb $$

Ajout de référence bibliographiques

Grâce à Zotero

Association via Zotero Web grâce à une clé API : Global Options > R Markdown > Citations

Plus d’info sur le tuto de Claire Della Vedova

Grâce à une recherche

Dans l’onglet Visual, cliquer sur Insert puis Citation.
Il est possible de chercher directement via le DOI ou dans Crossref, DataCite ou PubMed.

Intégrer un graphique

Il y a deux possibilités pour générer un graphique :

• Le coder dans le document Quarto
  
• Le coder dans un autre document Quarto puis l’intégrer dans celui de l’article

Dans les deux cas, il faut faire le graphique dans un chunk en le nommant avec label: fig-nom_du_graph

```{r}
#| label: fig-iris

plot(iris)
```

Figure 1

Si le graphique est généré dans un autre document, il peut être intégré grâce à {{< embed nom_du_doc.qmd#fig-nom_du_graph >}} codé {{< embed 01_graph_explo.qmd#fig-graph_iris >}} dans la vidéo sur Twitch.

Pour ensuite faire un lien hypertexte vers un graphique, il suffit dans le texte de rajouter @fig-nom_du_graph codé @fig-iris dans la vidéo.