Skip to contents

Premiers pas avec Quarto

Quelques conseils d’écriture et de format

avant même de commencer

Si votre intention est de faire une prévision, un document de travail, un policy brief, un post de blog ou un document qui s’inscrit dans la chrate graphique, il y a probablement une procédure faite pour votre cas. Par exemple, la mise en place des gabarits pour les documents de travail est faite par (documenté sur le site de référence du package {ofceweb}) :

```{r}
# installer si nécessaire le package ofceweb
# pak::pak("ofceweb/ofceweb")
ofceweb::setup_wp()
```

au commencement

Tout commence par un .qmd. Il doit être placé dans un sous dossier du projet général, pour être rangé de façon compréhensible par tout le monde. Demandez à votre administratrice de projet les règles qu’elle souhaite voir appliquées.

Un exemple de projet est ci-dessous. Il ne respecte pas toutes les règles recommandées, mais c’est souvent comme ça. Notez les fichiers importants :

  • _quarto.yml : dans lequel sont spécifiés les options principales et communes ainsi que les menus et la structure du site

  • index.qmd qui est la page de démarrage du site et qui doit toujours être à la racine du projet et s’appeler index.qmd

  • rinit.r qui contient des options par défaut pour les chunks R (c’est important pour le rendu des graphiques)

  • README.md qui apparaît sur la première page du projet sur github.com

  • _extensions qui contient tous les templates quarto, il faut absolument que ce dossier soit présent (et il ne faut pas y toucher).

legislatives2024
    _quarto.yml
    index.qmd
    about.qmd
    rinit.r
    README.md
    .gitignore
        _extensions/
            ofce/
            ...
    programmes/
        rn.qmd
        nfp.qmd
        Comparatif programmes législatives 2024.xlsx
        ...
    analyses/
        transition.qmd
        tissu_productif.qmd
        ...
        Tables/
            Tableau_retraite.xlsx
            Spreads.xlsx
            spread.rds
            ...

Donnez un nom simple (court, explicite, pas de majuscules, pas de caractères spéciaux), pour que le contenu soit clair, mais aussi qu’il soit facile à retaper quelque part si nécessaire. Les noms à rallonge sont donc à proscrire. Tâchez aussi d’éviter la multiplication des versions dans le dossier (dont une seule est ok), si vous avez des déchets, mettez dans un sous dossier spécifique (moi je l’appelle rkiv) de façon à garder les vieux morceaux d’essais.

Le .qmd est très simple, l’entête yaml n’a besoin que d’un champ : le titre. L’auteur est aussi utile, mais pas obligatoire. Pas besoin d’ajouter un format (ils sont communs au site et défini dans _quarto.yml), ni d’options spécifiques (définies aussi ailleurs). Eventuellement, on peut ajouter des éléments spécifiques au texte comme le champ date ou keyword ou bibliography.

Notez qu’il n’y pas de section de niveau header 1. Ce n’est pas possible parce qu’il y a un titre et que le titre est considéré comme la section header 1 : une alternative au titre dans le yml est une section de niveau header 1 ou simple #. S’il n’y a pas d’auteur ou d’autre champ, l’ensemble yml peut être omis avec simplement le header 1.

Dernier petit détail, il faut sourcer le fichier rinit.r. Ce fichier définit les options par défaut des chunks et permet d’avoir les bonnes polices de caractère dans la bonne taille pour tous les graphiques. La fonction ofce::init_qmd() simplifie le process et trouve le fichier rinit.r même s’il est bien caché. Il faut le mettre au début et à part pour que ces options s’appliquent aux chunks suivants. Il est toujours possible de modifier le rinit.r de votre projet pour des variables globales, comme la taille de la police de tous les graphiques, et des fonctions disponibles dans chaque .qmd.

Si vos graphiques sont moches, si les polices de caractère sont toutes petites ou trop grandes, avant d’appeler à l’aide, vérifiez 1. que ofce::init_qmd() est bien appelé ; 2. que vous n’avez pas un fig-width ou un fig-heigth quelque part dans le chunk ou dans le yml de votre .qmd.

---
title: Mon texte en qmd
author: Georgette
---
```{r, include=FALSE}
ofce::init_qmd()
```
## section 1
blabla
## section 2
blabla

Gardez vos yml les plus simples possibles, c’est le moyen d’assurer l’homogénéité des documents sur le site.

Quarto.org est une excellente source d’informations et d’aide sur l’écriture en markdown et la variante particulière que nous utilisons ici. La section “Authoring” est à avoir lu au moins une fois.

les règles typographiques

Grace à quarto et un filtre développé par Romain Lesur de l’INSEE, les règles typographiques standards au français sont appliquées automatiquement. Par exemple les guillemets sont mis conformément à la pratique en France «…» à partir du caractère tapé directement (“). Les espaces avant les signes de ponctuation ( : ;) sont remplacés par des demi cadratins et les espaces séparateurs des milliers sont remplacés par des espaces insécables. Pas besoin donc de s’embêter avec ça. Juste, pensez à mettre les espaces avant”:“.

Pour un document en anglais, il suffit de rajouter dans le yml la langue anglaise pour que la typographie correspondante soit appliquée. Les principaux champs (date, auteur, tableau, figure, graphique) sont aussi traduits.

---
title: English Version of the Document
author: William 
lang: en
---

les références croisées

Les références croisées demandent un peu de soin, mais permettent de produire des documents plus riches dans lesquels :

  • La numérotation des tableaux et figures, mais aussi tout autre type de documents (un encadré par ex.) est faite automatiquement. La mise en page est automatisée (avec quelques gains en html), les mots récurrents sont traduits automatiquement.

  • On peut appeler la référence croisée dans le texte. En html, cela créé un lien qui permet de naviguer directement vers la référence croisée.

  • On peut générer des tables des tableaux et des figures.

Le secret d’une référence croisée c’est l’instruction (le tag) #| label: xxx que l’on met en tête d’un chunk. “xxx” est l’id du document. Il définit le type (fig pour un graphique ; tbl pour un tableau ; tip pour un encadré ; eq pour une équation) et après le tiret le nom (sans espace ni tiret) qui sera appelé dans le texte par la séquence @fig-id ou @tbl-id (voir quarto cross references pour plus de détails).

On définit également le titre du graphique qui est donc identifié pour être mis en page, utilisé par ailleurs (par exemple la table des figures) et agrémenté des mots récurrents (par exemple tableau pour un tableau, donc on ne met pas dans le titre tableau ou son numéro). Le titre est déini par le tag #| fig-caption: xxx

le cas des graphiques

Pour un graphique (on ne met pas le numéro du graphique dans le titre, c’est fait automatiquement) :

``` {{r}}
#| label: fig-id
#| fig-cap: Le titre du graphique
#| fig-asp: 0.8
```

Merci de privilégier l’utilisation de ggplot2 et de ggiraph pour les graphiques. De nombreuses fonctions d’assistance sont disponibles ainsi que la mise en oeuvre d’une interactivité très simplement dans les graphiques, notamment les tooltips. ofce::girafy() est une fonction utile à bien des égards, qui traite en particulier la production des formats html et pdf proprement. L’utilisation de ofce::margin_download() permet d’ajouter un bouton de téléchargement des données. La structure du chunk est donc la suivante :

``` {{r}}
#| label: fig-id
#| fig-cap: Le titre du graphique
#| fig-asp: 0.8

gg <- ggplot(data) +
  aes(x=axe_x, y=axe_y)+
  geom_point_interactive(
  aes(tooltip=tooltip, data_id=axe_x, fill = couleur),
  shape=21, color="white", size=0.5, stroke=0.25)+
  ...

girafy(gg)

```


```{.r .cell-code}
ofce::margin_donwload(data |> select(-tooltip))
```

Si c’est un graphique produit autrement que par R, la syntaxe standard de markdown fonctionne aussi de cette façon (en changeant image en fonction du contexte, ainsi que le titre ou la légende !):

![Le titre de l'image](limage.png){#fig-image}

This is illustrated well by @fig-image.

le cas des tableaux

Pour un tableau (on ne met pas le numéro du tableau dans le titre, c’est fait automatiquement) :

``` {{r}}
#| label: tbl-id
#| tbl-cap: Le titre du tableau
```

Merci de privilégier les tableaux fait par le package gt. Quelques fonctions d’assistance à la mise en page sont disponibles dans le package ofce.

les encadrés

Pour un encadré, c’est un peu plus compliqué (pour le moment). tip est le hack pour la catégorie, .callout-tip pour le style. L’encadré sera numéroté et on peut le cross référencer par @tip-id.

::: {#tip-id .callout-tip}
## titre  l'encadré
texte de l'encadré
:::

un cas plus général

On peut être dans le cas où le contenu n’est pas une image ou un tableau (par exemple une composition d’images, un tableau sous forme d’un png). Dans ce cas quarto protestera. C’est dans la documentation de Quarto et cela prend la forme suivante (l’utilisation du tag fig implique une figure, la première ligne est le contenu, la dernière est le titre, les autres lignes sont affichées comme CONTENT) :

::: {#fig-example}

CONTENT

Caption

:::

Par ailleurs, on peut définir d’autres catégories de références croisées si nécessaire, par exemple en distinguant les cartes des figures.

Les tabsets

Les tabsets sont un moyen commode de proposer des options pour un tableau, un graphique sans entrer dans des complications trop grandes d’interactivité. Une fonction dans le package ofce facilite le travail (results="asis" est important, si le résultat n’est pas conforme, vérifier ce point en premier).

```{r, results="asis"}
g1 <- un graphique ggplot
g2 <- un autre
mes_graphiques <- list("label de g1" = g1, "label de g2" = g2)
ofce::tabsetize(mes_graphiques)

### une bibliographie

Il est facile d'insérer une bibliographie. La première chose est d'indiquer un (ou plusieurs) fichier `.bib` à `quarto` :

``` markdown
---
title: Mon titre
bibliography: references.bib
---

Le fichier references.bib doit être à la racine du projet et contient dans la syntaxe bibtex les références. Pour entrer une référence, avec RStudio, il y a plusieurs façon de faire.

  1. Dans RStudio, en mode visuel, on fait insérer une citation. Plusieurs sources sont possibles : Zotero, un DOI, une recherche sur Crossref, etc…

  2. Directement en copiant dans le .bib les références (on peut ainsi utiliser la biblio d’un autre document).

Les appels de références sont alors simplement fait en utilisant @angel2021 où angel2021 est l’id de la référence. L’appel de référence, la biblio sera insérée et formattée automatiquement. Les appels de référence peuvent se mettre également en note de bas de page ou dans un tableau en syntaxe markdown.

source_data

Dès qu’un .qmd devient complexe, on se heurte rapidement à une difficulté. D’un côté la mise en page, la rédaction demande des rendus fréquents pour ajuster le travail. De l’autre, l ’accumulation de code de chunk rend l’exécution plus lente et parfois induit des erreurs qui parasitent le travail. Par exemple, le téléchargement de données peut se bloquer (erreur dans l’API, délais de téléchargement) parfois de façon endogène (l’API a un nombre limité de téléchargement). Un autre problème peut être la difficulté à exécuter le code sur une autre machine : partager son repo git ne permet pas à quelqu’un de régler le problème technique de formatage du .qmd parce que le code ne s’exécute pas par exemple à cause d’un chemin absolu dans le code (load("c:/users/10298/mes donnees.rda")).

La fonction ofce::source_data() résoud ces problèmes : l’exécution génère des données qui sont cachées. Pour les exécutions suivantes, suivant les paramètres, le cache sera provilégié et en cas d’erreur d’exécution, il sera toujours utilisé. Cela permet de découpler exécution du code/résolution des bugs. Cela permet également d’accélérer grandement le rendu.

Le principe est simple : on isole le code de téléchargement dans un .r, on termine le .r par un return(data), puis on appelle ce code par data <-source_data("data_code.r") dans le chunk. Par défaut, le code ne sera exécuté qu’une fois et il faudra passer par source_data_refresh().

La fonction ofce::source_data() provient du package sourcoise. En utilisant ce package, documenté sur son site de référence, vous aurez de nombreux outils et en particulier la possibilité de découpler complètement l’exécution du code “données” de leur mise en forme (graphiques ou tableaux). Le répo ofce/wp-xt-travail est un bon exemple d’utilisation extensive de cette technologie. Un autre exemple sont les répo de prévision (ofce/prevxxxx). Utiliser source_data() ou sourcoise() est strictement équivalent.