1.1 Logiciels de type WYSIWYM

Avec les logiciels de type WYSIWYM, un document se crée en :

• éditant un fichier source, puis en
• compilant le fichier source pour obtenir le document final.

Figure 1.1: Production de documents avec un logiciel de type WYSIWYM

Markdown :

Markdown est un langage simple de composition de documents en format HTML (interprétable par un navigateur web). Il s’agit donc d’un outil permettant de créer des pages web sans avoir à connaître le langage HTML.

Figure 1.2: Production de documents avec Markdown

Markdown offre moins de possibilités de mise en forme que LaTeX, mais il est plus simple à apprendre et à utiliser.

1.2 Recherche reproductible et programmation lettrée

1.3 Sweave et knitr

En R, il est possible d’effectuer de la programmation lettrée avec la fonction Sweave (du package utils) ou avec le package knitr.

Ces packages permettent de créer des publications qui contiennent des bouts de code et/ou des sorties R, sans faire de copier/coller à partir d’un programme R ou de la console R.

Sweave :

Sweave est le premier outil a avoir été développé pour faire de la programmation lettrée en R. Il permet d’intégrer du code R à des documents LaTeX.

Les tags encadrant les bouts de code R dans le fichier source acceptent des options permettant de contrôler :

• ce qui doit être compilé ou non,
• ce qui doit être affiché ou non (code, sorties, figures),
• la mise en forme de l’affichage.

Figure 1.3: Schéma de compilation avec Sweave

knitr :

knitr est une alternative à Sweave, plus récente et maintenant plus utilisée. Les options de mise en forme par défaut des éléments R intégrés au fichier LaTeX ne sont pas les mêmes avec knitr qu’avec Sweave. De plus, knitr permet d’intégrer des éléments R à d’autres types de fichiers que LaTeX, notamment à des fichiers Markdown. C’est ce qui est appelé le R Markdown.

Figure 1.4: Schéma de compilation avec R Markdown

2.1 Création d’un document R Markdown en RSudio

Un bon outil pour rédiger et compiler des documents R Markdown est RStudio, qui est d’ailleurs derrière le développement de cet outil de programmation lettrée. En RStudio, nous pouvons créer un nouveau document R Markdown (extension .Rmd) par le menu :

• « File > New File > R Markdown… »

Une fenêtre s’ouvre alors. Nous devons spécifier quelques informations à propos de notre fichier.

1. Le menu de gauche sert à indiquer quel type de produit final nous voulons créer :
   • un document,
   • une présentation,
   • un document avec composantes interactives (Shiny) ou
   • un document suivant un certain modèle prédéfini (p. ex. document GitHub ou vignette de package).
2. Dans la partie de droite de la fenêtre, nous spécifions :
   • le titre du document,
   • le nom de l’auteur,
   • le format préféré pour le fichier final.

En cliquant sur OK, un fichier est créé. Il devrait avoir l’allure suivante :

Figure 2.1: Exemple de nouveau document R Markdown

Il ne reste plus qu’à :

1. enregistrer le fichier,
2. éditer le fichier en respectant :
   • la syntaxe YAML dans l’entête,
   • la syntaxe Markdown dans le corps du document,
   • la syntaxe de knitr dans les options des bouts de code R.
3. compiler le fichier.

2.2 Entête d’un fichier R Markdown

Un fichier R Markdown débute pratiquement toujours par un entête encadré de deux lignes contenant uniquement trois tirets (---). Cet entête contient des métadonnées concernant le document, écrites en utilisant la syntaxe YAML.

Les métadonnées de base sont :

• title : le titre du document,
• author : le nom de l’auteur,
• date : la date de publication du document.

Ces métadonnées servent à créer l’entête du document final.

L’entête YAML du document R Markdown contient aussi typiquement des informations spécifiant le format du document final et des options de mise en forme de ce document final. Les options varient en fonction du format de sortie. Plusieurs formats de sorties peuvent être spécifiés dans l’entête d’un document R Markdown.

Par exemple, voici un extrait de l’entête YAML du fichier source du document que vous êtes en train de lire :

---
title: "Rédaction de documents en R Markdown"
author: "Sophie Baillargeon, Université Laval"
date: "2021-03-18"
output:
  pdf_document:
    toc: yes
    toc_depth: 3
    number_sections: yes
    highlight: tango
  blogdown::html_page:
    toc: yes
    toc_depth: 3
    number_sections: yes
    highlight: tango
---

Ce fichier source a servi à produire le document en deux formats de sortie différents : PDF et HTML (convenant à l’outil blogdown, qui est utilisé pour créer ce site web). L’option toc a permis de créer une table des matières (de profondeur contrôlée par l’option toc_depth), les sections sont numérotées grâce à l’option number_sections et les blocs de code utilisent la coloration syntaxique tango grâce à l’option highlight. Il ne s’agit là que de quelques-unes des options pouvant être spécifiées (voir https://bookdown.org/yihui/rmarkdown/documents.html pour d’autres options possibles selon le format de sortie).

2.3 Syntaxe Markdown

La syntaxe Markdown utilisée par R Markdown est la version Pandoc de Markdown, documentée sur le site web suivant :

• http://rmarkdown.rstudio.com/authoring_pandoc_markdown.html

Les éléments de base de cette syntaxe sont bien présentés

• sur la page web suivante :
  http://rmarkdown.rstudio.com/authoring_basics.html
  
• ainsi que dans une partie du document suivant :
  https://github.com/rstudio/cheatsheets/blob/master/rmarkdown-2.0.pdf
  (aussi disponible en RStudio via le menu « Help > Cheatsheets > R Markdown Cheat Sheet »).

Par exemple, un titre de section est créé par une ligne débutant par un caractère #, suivi d’au moins un espace, puis du titre de la section et d’un retour à la ligne. Un titre de sous-section est créé de la même façon, mais en débutant la ligne par ##. Il est ainsi possible de créer des titres de différents niveaux (allant jusqu’à un sixième niveau avec ######).

Aussi, pour mettre des bouts de texte en italique, il suffit de les encadrer du caractère * ou _. Ainsi, *bonjour* ou _bonjour_ dans un fichier source R Markdown devient bonjour dans le document final obtenu suite à la compilation. Pour mettre des bouts de texte en gras, il faut les encadrer de deux caractères * ou _ (donc **très important** devient très important).

De plus, la syntaxe suivante :

- premier élément (obligatoirement précédé d'une ligne vide)
    - sous élément (obligatoirement précédé de 4 à 7 espaces)
        - sous-sous élément (obligatoirement précédé de 8 à 11 espaces)
- dernier élément (obligatoirement suivi d'une ligne vide)

crée la liste suivante :

• premier élément (obligatoirement précédé d’une ligne vide)
  • sous élément (obligatoirement précédé de 4 à 7 espaces)
    • sous-sous élément (obligatoirement précédé de 8 à 11 espaces)
• dernier élément (obligatoirement suivi d’une ligne vide)

Je vous laisse découvrir par vous même les autres possibilités de la syntaxe Markdown à partir des sources proposées ci-dessus.

2.4 Compilation de fichier R Markdown en RStudio

La compilation d’un fichier R Markdown est démarrée en cliquant sur le bouton Knit de RStudio. Ce bouton se trouve dans la barre en haut d’un fichier R Markdown. Il est accompagné d’un logo représentant une pelote de laine avec une aiguille à tricoter.

Le petit triangle vers le bas semblable à \(\blacktriangledown\) à côté du bouton Knit permet de sélectionner le format du fichier final. Le symbole de roue d’engrenage permet d’ouvrir un menu pour modifier les paramètres de la compilation.

Peu importe le format final de la sortie, la compilation cache toujours en fait plusieurs étapes intermédiaires dont :

• la compilation du code R dans une nouvelle session R (pas dans celle déjà ouverte en RStudio);
• l’intégration des résultats de cette compilation à un document Markdown (.md);
• la compilation avec Pandoc du document Markdown vers le format de sortie demandée (s’il s’agit du format PDF, il y a création d’un fichier au format LaTeX (.tex) qui est ensuite compilé vers le format PDF).

Notons que la compilation d’un fichier R Markdown peut aussi être demandée en appelant la fonction render du package R nommé rmarkdown.

2.5 Blocs de code R

Dans un fichier R Markdown, le code R doit être encadré par le tag d’ouverture composé de trois apostrophes inversées suivies de {r} et le tag de fermeture composé de trois apostrophes inversées. Entre les accolades et après le r, nous pouvons ajouter un nom et des options de blocs de code R, séparées par des virgules. Nommer les blocs de code est utile pour se retrouver plus facilement dans un document contenant plusieurs blocs de code. Voici un exemple de bloc de code nommé, mais pour lequel aucune option n’a été modifiée.

```{r chunck}
a <- 1 + 1
a
```

Sans modifier les options par défaut du bloc de code, le code et les sorties produites seront intégrés au document comme suit.

a <- 1 + 1
a

## [1] 2

```{r  R.options = list(width = 50), comment = ""}
b <- c(1:10, rep(11, 20))
b
```

b <- c(1:10, rep(11, 20))
b

 [1]  1  2  3  4  5  6  7  8  9 10 11 11 11 11 11
[16] 11 11 11 11 11 11 11 11 11 11 11 11 11 11 11

2.6 Commande R intégrée à un bout de texte (inline)

Il est aussi possible d’inclure une commande R retournant un simple vecteur dans un bout de texte (en anglais on parle de inline R code). Seulement la sortie produite par la commande R sera affichée. Il faut encadrer la commande du tag ouvrant composé d’une seule apostrophe inversée suivie de r et du tag fermant composé uniquement d’une apostrophe inversée.

Par exemple, la phrase suivante dans un document R Markdown :

produit le résultat suivant :

La division de 5 par 3 donne le résultat 1.6666667.

2.7 Intégration de figures

À partir d’un fichier image :

Il est possible d’intégrer une figure provenant d’un fichier image en utilisant la syntaxe Markdown suivante :

• fichier local : ![](chemin/relatif/vers/fichier.png)
• fichier provenant du web : ![](http://example.com/logo.png)

Note : Pour les fichiers image locaux, seuls les chemins d’accès relatifs à l’emplacement du fichier source R Markdown sont acceptés. Alors le plus simple est de positionner les fichiers dans le même répertoire que le fichier .Rmd ou dans un sous-répertoire de ce répertoire.

Si nous ajoutons du texte entre les crochets, celui-ci devient le titre de la figure.

Par exemple, la commande Markdown suivante :

![Exemple de figure](fig/WYSIWYM.png)

produit le résultat suivant :

Exemple de figure

Il est aussi possible d’intégrer une figure provenant d’un fichier image en utilisant la fonction include_graphics du package knitr. Cette façon de faire facilite le contrôle de la mise en forme de la figure produite. Il faut utiliser cette fonction dans un bloc de code R, comme dans l’exemple suivant :

```{r echo = FALSE, out.width = "60%", fig.align = 'center', fig.cap = "Autre exemple de figure"}
knitr::include_graphics("fig/WYSIWYM.png")
```

Figure 2.2: Autre exemple de figure

Les options de bloc de code out.height et out.width permettent de contrôler les dimensions de la figure, fig.align contrôle son alignement et fig.cap permet d’ajouter un titre.

À partir d’un bloc de code R qui génère un graphique :

Nous pouvons aussi intégrer une figure à un fichier R Markdown à l’aide d’un bloc de code R qui génère un graphique. Voici un exemple suivi du résultat produit.

```{r  fig.height = 4.5, out.width = "70%", fig.cap = "Encore un exemple de figure"}
plot(cars, main = "Relation entre la vitesse et la distance de freinage de voitures")
```

Figure 2.3: Encore un exemple de figure

Lorsque la figure est créée par le code R, nous pouvons contrôler les dimensions de la fenêtre graphique avec les options fig.height et fig.width. Malgré tout, les options out.height et out.width continuent de contrôler la dimension de la figure dans le document final.

2.8 Intégration de tableaux

Il existe une syntaxe Markdown pour créer des tableaux. Par exemple, le code Markdown suivant :

| Droite | Gauche | Défaut | Centré |
|-------:|:-------|--------|:------:|
| 12 | 12 | 12 | 12 |
| 123 | 123 | 123 | 123 |
| 1 | 1 | 1 | 1 | 

Table: Premier exemple de tableau

produit le tableau suivant :

C’est l’emplacement des caractères « deux-points » (:) sur la ligne séparant l’entête du tableau à son contenu qui détermine l’alignement de la colonne. Pour donner un titre au tableau, il faut ajouter au-dessus ou en-dessous du code source du tableau une ligne débutant par Table:, suivi du titre.

Aussi, la fonction kable du package knitr permet d’intégrer un data frame R sous forme de tableau dans un document produit avec R Markdown.

Voici un exemple suivi du résultat produit (l’option results = 'asis' est nécessaire ici).

```{r  results = 'asis'}
knitr::kable(head(cars, 3), caption = "Exemple de tableau")
```

Notons que d’autres fonctions permettent de formater une matrice ou un data frame R pour créer un tableau dans un document rédigé en R Markdown. Notamment, le package kableExtra ajoute des possibilités à la fonction kable du package knitr. Quelques autres outils sont mentionnés dans le document https://github.com/rstudio/cheatsheets/blob/master/rmarkdown-2.0.pdf. La mise en forme du tableau obtenu diffère légèrement d’une fonction à l’autre.

Si le document final doit être en HTML uniquement, des outils supplémentaires s’offrent à nous pour mettre en forme des tableaux, notamment :

• le package gt pour formater un data frame ou un tibble à afficher sous forme de tableau :
  https://gt.rstudio.com/
• le package DT pour créer des tableaux interactifs :
  • https://rstudio.github.io/DT/
  • https://stt4230.rbind.io/tutoriels_etudiants/hiver_2019/dt/

2.9 Astuces diverses dans l’édition de documents R Markdown

• Pour faire un changement de ligne sans changer de paragraphe :
  insérer une barre oblique inversée \ (an anglais backslash) ou deux caractères espace à la fin d’une ligne, avant le retour à la ligne.

• Pour insérer un espace insécable (aussi utile pour insérer une ligne vide si placé seul sur une ligne) :
  insérer une barre oblique inversée \ suivie d’un caractère espace ou encore   (qui représente un espace en HTML).

• Pour insérer un commentaire (texte n’apparaissant pas dans le document final) :
  utiliser les tags HTML pour des commentaires, soit

<!-- commentaire ici (possiblement sur plusieurs lignes) -->

• Raccourci clavier pour insérer un bloc de code R dans un fichier R Markdown en RStudio :
  • Sous Windows : « Ctrl + Alt + i »,
  • Sous macOS : « Option + Command + i ».
    
    
• Pour modifier les options par défaut pour les blocs de code R :
  insérer la ligne suivante (avec les options désirées) au tout début du fichier .Rmd (juste en dessous de l’entête)

`r knitr::opts_chunk$set(echo = FALSE, results = 'hide')`

• Pour avoir des noms automatiques d’éléments en français lors de la création d’un document final au format PDF (par exemple le titre de la table des matières) : ajouter dans l’entête les lignes suivantes

header-includes:
- \usepackage[french]{babel}

Le livre R Markdown Cookbook contient une grande quantité d’autres astuces pour l’édition de documents R Markdown.