R Markdown : les rapports automatisés

L’extension rmarkdown permet de générer des documents de manière dynamique en mélangeant texte mis en forme et résultats produits par du code R. Les documents générés peuvent être au format HTML, PDF, Word, et bien d’autres¹. C’est donc un outil très pratique pour l’exportation, la communication et la diffusion de résultats d’analyse.

Le présent document a lui-même été généré à partir de fichiers R Markdown.

rmarkdown ne fait pas partie du tidyverse, mais elle est installée et chargée par défaut par RStudio².

Voici un exemple de document R Markdown minimal :

---
title: "Test R Markdown"
---


*R Markdown* permet de mélanger :

- du texte libre mis en forme
- des blocs de code R

Les blocs de code sont exécutés et leur résultat affiché, par exemple :

```{r}
mean(mtcars$mpg)
```

## Graphiques

On peut également inclure des graphiques :

```{r}
plot(mtcars$hp, mtcars$mpg)
```

Ce document peut être compilé sous différents formats. Lors de cette étape, le texte est mis en forme, les blocs de code sont exécutés, leur résultat ajouté au document, et le tout est transformé dans un des différents formats possibles.

Voici le rendu du document précédent au format HTML :

Le rendu du même document au format PDF :

Et le rendu au format Word :

Les avantages de ce système sont nombreux :

le code et ses résultats ne sont pas séparés des commentaires qui leur sont associés
le document final est reproductible
le document peut être très facilement régénéré et mis à jour, par exemple si les données source ont été modifiées.

Créer un nouveau document

Un document R Markdown est un simple fichier texte enregistré avec l’extension .Rmd.

Sous RStudio, on peut créer un nouveau document en allant dans le menu File puis en choisissant New file puis R Markdown…. La boîte de dialogue suivante s’affiche :

On peut indiquer le titre, l’auteur du document ainsi que le format de sortie par défaut (il est possible de modifier facilement ses éléments par la suite). Plutôt qu’un document classique, on verra plus loin qu’on peut aussi choisir de créer une présentation sous forme de slides (entrée Presentation) ou de créer un document à partir d’un modèle (Entrée From Template).

Un fichier comportant un contenu d’exemple s’affiche alors. Vous pouvez l’enregistrer où vous le souhaitez avec une extension .Rmd.

Élements d’un document R Markdown

Un document R Markdown est donc un fichier texte qui ressemble à quelque chose comme ça :

---
title: "Titre"
author: "Prénom Nom"
date: "10 avril 2017"
output: html_document
---

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

## Introduction

Ceci est un document RMarkdown, qui mélange :

- du texte balisé selon la syntaxe Markdown
- des bouts de code R qui seront exécutés

Le code R se présente de la manière suivante :

```{r}
summary(cars)
```

## Graphiques

On peut aussi inclure des graphiques, par exemple :

```{r}
plot(pressure)
```

En-tête (préambule)

La première partie du document est son en-tête. Il se situe en tout début de document, et est délimité par trois tirets (---) avant et après :

---
title: "Titre"
author: "Prénom Nom"
date: "10 avril 2017"
output: html_document
---

Cet en-tête contient les métadonnées du document, comme son titre, son auteur, sa date, plus tout un tas d’options possibles qui vont permettre de configurer ou personnaliser l’ensemble du document et son rendu. Ici, par exemple, la ligne output: html_document indique que le document généré doit être au format HTML.

Texte du document

Le corps du document est constitué de texte qui suit la syntaxe Markdown. Un fichier Markdown est un fichier texte contenant un balisage léger qui permet de définir des niveaux de titres ou de mettre en forme le texte. Par exemple, le texte suivant :

Ceci est du texte avec *de l'italique* et **du gras**.

On peut définir des listes à puces :

- premier élément
- deuxième élément

Génèrera le texte mis en forme suivant :

Ceci est du texte avec de l’italique et du gras.

On peut définir des listes à puces :

premier élément

deuxième élément

On voit que des mots placés entre des astérisques sont mis en italique, des lignes qui commencent par un tiret sont transformés en liste à puce, etc.

On peut définir des titres de différents niveaux en faisant débuter une ligne par un ou plusieurs caractères # :

# Titre de niveau 1

## Titre de niveau 2

### Titre de niveau 3

Quand des titres ont été définis, si vous cliquez sur l’icône Show document outline totalement à droite de la barre d’outils associée au fichier R Markdown, une table des matières dynamique générée automatiquement à partir des titres présents dans le document s’affiche et vous permet de naviguer facilement dans celui-ci :

La syntaxe Markdown permet d’autres mises en forme, comme la possibilité d’insérer des liens ou des images. Par exemple, le code suivant :

[Exemple de lien](https://example.com)

Donnera le lien suivant :

Exemple de lien

Dans RStudio, le menu Help puis Markdown quick reference donne un aperçu plus complet de la syntaxe.

Blocs de code R

En plus du texte libre au format Markdown, un document R Markdown contient, comme son nom l’indique, du code R. Celui-ci est inclus dans des blocs (chunks) délimités par la syntaxe suivante :

```{r}
x <- 1:5
```

Comme cette suite de caractères n’est pas très simple à saisir, vous pouvez utiliser le menu Insert de RStudio et choisir R³, ou utiliser le raccourci clavier Ctrl+Alt+i.

Dans RStudio les blocs de code R sont en général affichés avec une couleur de fond légèrement différente pour les distinguer du reste du document.

Quand votre curseur se trouve dans un bloc, vous pouvez saisir le code R que vous souhaitez, l’exécuter, utiliser l’autocomplétion, exactement comme si vous vous trouviez dans un script R. Vous pouvez également exécuter l’ensemble du code contenu dans un bloc à l’aide du raccourci clavier Ctrl+Shift+Entrée.

Dans RStudio, par défaut, les résultats d’un bloc de code (texte, tableau ou graphique) s’affichent directement dans la fenêtre d’édition du document, permettant de les visualiser facilement et de les conserver le temps de la session ⁴.

Lorsque le document est compilé au format HTML, PDF ou docx, chaque bloc est exécuté tour à tour, et le résultat inclus dans le document final, qu’il s’agisse de texte, d’un tableau ou d’un graphique. Les blocs sont liés entre eux, dans le sens où les données importées ou calculées dans un bloc sont accessibles aux blocs suivants. On peut donc aussi voir un document R Markdown comme un script R dans lequel on aurait intercalé du texte libre au format Markdown.

À noter qu’avant chaque compilation, une nouvelle session R est lancée, ne contenant aucun objet. Les premiers blocs de code d’un document sont donc souvent utilisés pour importer des données, exécuter des recodages, etc.

Compiler un document (Knit)

On peut à tout moment compiler, ou plutôt tricoter (Knit), un document R Markdown pour obtenir et visualiser le document généré. Pour cela, il suffit de cliquer sur le bouton Knit et de choisir le format de sortie voulu :

Vous pouvez aussi utiliser le raccourci Ctrl+Shift+K pour compiler le document dans le dernier format utilisé.

Pour la génération du format PDF, vous devez avoir une installation fonctionnelle de LaTeX sur votre système. C’est en général le cas pour des ordinateurs Mac ou Linux, mais pas sous Windows : dans ce cas vous devrez installer une distribution comme MiKTeX.

Un onglet R Markdown s’ouvre dans la même zone que l’onglet Console et indique la progression de la compilation, ainsi que les messages d’erreur éventuels. Si tout se passe bien, Le document devrait s’afficher soit dans une fenêtre Viewer de RStudio (pour la sortie HTML), soit dans le logiciel par défaut de votre ordinateur.

Personnaliser le document généré

La personnalisation du document généré se fait en modifiant des options dans le préambule du document. RStudio propose néanmoins une petite interface graphique permettant de changer ces options plus facilement. Pour cela, cliquez sur l’icône en forme d’engrenage à droite du bouton Knit et choisissez Output Options…

Une boîte de dialogue s’affiche vous permettant de sélectionner le format de sortie souhaité et, selon le format, différentes options :

Pour le format HTML par exemple, l’onglet General vous permet de spécifier si vous voulez une table des matières, sa profondeur, les thèmes à appliquer pour le document et la coloration syntaxique des blocs R, etc. L’onglet Figures vous permet de changer les dimensions par défaut des graphiques générés.

Une option très intéressante pour les fichiers HTML, accessible via l’onglet Advanced, est l’entrée Create standalone HTML document. Si elle est cochée (ce qui est le cas par défaut), le document HTML généré contiendra en un seul fichier le code HTML mais aussi les images et toutes les autres ressources nécessaires à son affichage. Ceci permet de générer des fichiers (parfois assez volumineux) que vous pouvez transférer très facilement à quelqu’un par mail ou en le mettant en ligne quelque part. Si la case n’est pas cochée, les images et autres ressources sont placées dans un dossier à part.

Lorsque vous changez des options, RStudio va en fait modifier le préambule de votre document. Ainsi, si vous choisissez d’afficher une table des matières et de modifier le thème de coloration syntaxique, votre en-tête va devenir quelque chose comme :

---
title: "Test R Markdown"
output:
   html_document: 
     highlight: kate
     toc: yes
---

Vous pouvez modifier les options directement en éditant le préambule.

À noter qu’il est possible de spécifier des options différentes selon les formats, par exemple :

---
title: "Test R Markdown"
output:
  html_document: 
    highlight: kate
    toc: yes
  pdf_document: 
    fig_caption: yes
    highlight: kate
---

La liste complète des options possibles est présente sur le site de la documentation officielle (très complet et bien fait) et sur l’antisèche et le guide de référence, accessibles depuis RStudio via le menu Help puis Cheatsheets.

Options des blocs de code R

Il est également possible de passer des options à chaque bloc de code R pour modifier son comportement.

On rappelle qu’on bloc de code se présente de la manière suivante :

```{r}
x <- 1:5
```

Les options d’un bloc de code sont à placer à l’intérieur des accolades {r}.

Nom du bloc

La première possibilité est de donner un nom au bloc. Celui-ci est indiqué directement après le r :

{r nom_du_bloc}

Il n’est pas obligatoire de nommer un bloc, mais cela peut être utile en cas d’erreur à la compilation, pour identifier le bloc ayant causé le problème. Attention, on ne peut pas avoir deux blocs avec le même nom.

Options

En plus d’un nom, on peut passer à un bloc une série d’options sous la forme option = valeur. Voici un exemple de bloc avec un nom et des options :

```{r mon_bloc, echo = FALSE, warning = TRUE}
x <- 1:5
```

Et un exemple de bloc non nommé avec des options :

```{r echo = FALSE, warning = FALSE}
x <- 1:5
```

Une des options la plus utile est l’option echo. Par défaut echo vaut TRUE, et le bloc de code R est inséré dans le document généré, de cette manière :

x <- 1:5
print(x)

[1] 1 2 3 4 5

Mais si on positionne l’option echo=FALSE, alors le code R n’est plus inséré dans le document, et seul le résultat est visible :

[1] 1 2 3 4 5

Voici une liste de quelques unes des options disponibles :

Option	Valeurs	Description
echo	TRUE/FALSE	Afficher ou non le code R dans le document
eval	TRUE/FALSE	Exécuter ou non le code R à la compilation
include	TRUE/FALSE	Inclure ou non le code R et ses résultats dans le document
results	“hide”/“asis”/“markup”/“hold”	Type de résultats renvoyés par le bloc de code
warning	TRUE/FALSE	Afficher ou non les avertissements générés par le bloc
message	TRUE/FALSE	Afficher ou non les messages générés par le bloc

Il existe de nombreuses autres options décrites notamment dans guide de référence R Markdown (PDF en anglais).

Modifier les options

Il est possible de modifier les options manuellement en éditant l’en-tête du bloc de code, mais on peut aussi utiliser une petite interface graphique proposée par RStudio. Pour cela, il suffit de cliquer sur l’icône d’engrenage située à droite sur la ligne de l’en-tête de chaque bloc :

Vous pouvez ensuite modifier les options les plus courantes, et cliquer sur Apply pour les appliquer.

Options globales

On peut vouloir appliquer une option à l’ensemble des blocs d’un document. Par exemple, on peut souhaiter par défaut ne pas afficher le code R de chaque bloc dans le document final.

On peut positionner une option globalement en utilisant la fonction knitr::opts_chunk$set(). Par exemple, insérer knitr::opts_chunk$set(echo = FALSE) dans un bloc de code positionnera l’option echo = FALSE par défaut pour tous les blocs suivants.

En général, on place toutes ces modifications globales dans un bloc spécial nommé setup et qui est le premier bloc du document :

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

Par défaut RStudio exécute systématiquement le contenu du bloc setup avant d’exécuter celui d’un autre bloc.

Mise en cache des résultats

Compiler un document R Markdown peut être long, car il faut à chaque fois exécuter l’ensemble des blocs de code R qui le constituent.

Pour accélérer cette opération, R Markdown utilise un système de mise en cache : les résultats de chaque bloc sont enregistrés dans un fichier et à la prochaine compilation, si le code et les options du bloc n’ont pas été modifiés, c’est le contenu du fichier de cache qui est utilisé, ce qui évite d’exécuter le code R.

On peut activer ou désactiver la mise en cache des résultats pour chaque bloc de code avec l’option cache = TRUE ou cache = FALSE, et on peut aussi désactiver totalement la mise en cache pour le document en ajoutant knitr::opts_chunk$set(echo = FALSE) dans le premier bloc setup.

Ce système de cache peut poser problème par exemple si les données source changent : dans ce cas les résultats de certains blocs peuvent ne pas être mis à jour s’ils sont présents en cache. Dans ce cas, on peut vider le cache du document, ce qui forcera un recalcul de tous les blocs de code à la prochaine compilation. Pour cela, vous pouvez ouvrir le menu Knit et choisir Clear Knitr Cache… :

Rendu des tableaux

Tableaux croisés

Par défaut, les tableaux issus de la fonction table sont affichés comme ils apparaissent dans la console de R, en texte brut :

library(questionr)
data(hdv2003)
tab <- lprop(table(hdv2003$qualif, hdv2003$sexe))
tab

                          
                           Homme Femme Total
  Ouvrier specialise        47.3  52.7 100.0
  Ouvrier qualifie          78.4  21.6 100.0
  Technicien                76.7  23.3 100.0
  Profession intermediaire  55.0  45.0 100.0
  Cadre                     55.8  44.2 100.0
  Employe                   16.2  83.8 100.0
  Autre                     36.2  63.8 100.0
  All                       44.8  55.2 100.0

On peut améliorer leur présentation en utilisant la fonction kable de l’extension knitr. Celle-ci fournit un formatage adapté en fonction du format de sortie. On aura donc des tableaux propres que ce soit en HTML, PDF ou aux formats traitements de texte :

library(knitr)
kable(tab)

	Homme	Femme	Total
Ouvrier specialise	47.29064	52.70936	100
Ouvrier qualifie	78.42466	21.57534	100
Technicien	76.74419	23.25581	100
Profession intermediaire	55.00000	45.00000	100
Cadre	55.76923	44.23077	100
Employe	16.16162	83.83838	100
Autre	36.20690	63.79310	100
All	44.82759	55.17241	100

Différents arguments permettent de modifier la sortie de kable. digits, par exemple, permet de spécifier le nombre de chiffres significatifs à afficher dans les colonnes de nombres :

kable(tab, digits = 1)

	Homme	Femme	Total
Ouvrier specialise	47.3	52.7	100
Ouvrier qualifie	78.4	21.6	100
Technicien	76.7	23.3	100
Profession intermediaire	55.0	45.0	100
Cadre	55.8	44.2	100
Employe	16.2	83.8	100
Autre	36.2	63.8	100
All	44.8	55.2	100

Tableaux de données et tris à plat

En ce qui concerne les tableaux de données (tibble ou data frame), l’affichage HTML par défaut se contente d’un affichage texte comme dans la console, très peu lisible dès que le tableau dépasse une certaine dimension.

Une alternative est d’utiliser la fonction paged_table, qui affiche une représentation HTML paginée du tableau :

rmarkdown::paged_table(hdv2003)

Une autre alternative est d’utiliser kable, ou encore la fonction datatable de l’extension DT, qui propose encore davantage d’interactivité :

DT::datatable(hdv2003)

Dans tous les cas il est déconseillé d’afficher de cette manière un tableau de données de très grandes dimensions, car le fichier HTML résultant contiendrait l’ensemble des données et serait donc très volumineux.

On peut définir un mode d’affichage par défaut pour tous les tableaux de données en modifiant les Output options du format HTML (onglet General, Print dataframes as), ou en modifiant manuellement l’option df_print de l’entrée html_document dans le préambule.

À noter que les tableaux issus de la fonction freq de questionr s’affichent comme des tableaux de données (et non comme des tableaux croisés).

Autres extensions pour présenter des tableaux

Il existe de nombreuses extensions offrant des fonctionnalités de présentation enrichie des tableaux et autres objets R.

printr

L’extension printr développée par le même auteur que knitr étent le fonctionnement par défaut de knitr. Une fois chargée, le rendu automatique de certains objets (tel qu’un tableau croisé à trois variables) sera amélioré.

library(printr)

Registered S3 method overwritten by 'printr':
  method                from     
  knit_print.data.frame rmarkdown

x1 = sample(letters[1:2], 1000, TRUE)
x2 = sample(letters[1:2], 1000, TRUE)
x3 = sample(letters[1:2], 1000, TRUE)
table(x1, x2, x3)

x1	x2	x3	Freq
a	a	a	118
		b	129
	b	a	111
		b	123
b	a	a	130
		b	147
	b	a	120
		b	122

Pour d’autres exemples, voir la documentation de l’extension sur https://yihui.name/printr/.

kableExtra

L’extension kableExtra a pour objectif d’étendre la fonction kable de knitr avec des options comme la possibilité de regrouper des colonnes, ajouter des notes de tableau, coloriser certaines cellules…

library(kableExtra)
dt <- mtcars[1:5, 1:4]

kable(dt, format = "html", caption = "Demo Table") %>%
  kable_styling(bootstrap_options = "striped",
                full_width = F) %>%
  add_header_above(c(" ", "Group 1" = 2, "Group 2[note]" = 2)) %>%
  add_footnote(c("table footnote"))

Demo Table
	Group 1		Group 2^a
	mpg	cyl	disp	hp
Mazda RX4	21.0	6	160	110
Mazda RX4 Wag	21.0	6	160	110
Datsun 710	22.8	4	108	93
Hornet 4 Drive	21.4	6	258	110
Hornet Sportabout	18.7	8	360	175
^a table footnote

Pour une présentation détaillée, vous pouvez vous référer aux vignettes disponibles avec l’extension.

Notamment, il est possible d’utiliser kableExtra en conjonction avec l’extension formattable pour des rendus colorés et encore plus personnalisé de vos tableaux (voir la vignette dédiée).

library(knitr)
library(kableExtra)
library(formattable)
library(dplyr, quietly = TRUE)


Attaching package: 'dplyr'

The following object is masked from 'package:kableExtra':

    group_rows

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

    filter, lag

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

    intersect, setdiff, setequal, union

mtcars[1:5, 1:4] %>%
  mutate(
    car = row.names(.),
    mpg = color_tile("white", "orange")(mpg),
    cyl = cell_spec(cyl, "html", angle = (1:5)*60, 
                    background = "red", color = "white", align = "center"),
    disp = ifelse(disp > 200,
                  cell_spec(disp, "html", color = "red", bold = T),
                  cell_spec(disp, "html", color = "green", italic = T)),
    hp = color_bar("lightgreen")(hp)
  ) %>%
  select(car, everything()) %>%
  kable("html", escape = F) %>%
  kable_styling("hover", full_width = F) %>%
  column_spec(5, width = "3cm") %>%
  add_header_above(c(" ", "Hello" = 2, "World" = 2))

	Hello		World
car	mpg	cyl	disp	hp
Mazda RX4	21.0	6	160	110
Mazda RX4 Wag	21.0	6	160	110
Datsun 710	22.8	4	108	93
Hornet 4 Drive	21.4	6	258	110
Hornet Sportabout	18.7	8	360	175

Autres extensions

On peut également citer les extensions suivantes :

pander
xtable
tables
sjPlot et ses fonctions sjt*

Pour chacune, vous trouverez une documentation sur leur page CRAN, notamment sous forme de vignettes.

Modèles de documents

On a vu ici la production de documents classiques, mais R Markdown permet de créer bien d’autres choses.

Le site de documentation de l’extension propose une galerie des différentes sorties possibles. On peut ainsi créer des slides, des sites Web ou même des livres entiers, comme le présent document.

Slides

Un usage intéressant est la création de diaporamas pour des présentations sous forme de slides. Le principe reste toujours le même : on mélange texte au format Markdown et code R, et R Markdown transforme le tout en présentations au format HTML ou PDF. En général les différents slides sont séparés au niveau de certains niveaux de titre.

Certains modèles de slides sont inclus avec R Markdown, notamment :

ioslides et Slidy pour des présentations HTML
beamer pour des présentations en PDF via LaTeX

Quand vous créez un nouveau document dans RStudio, ces modèles sont accessibles via l’entrée Presentation :

D’autres extensions, qui doivent être installées séparément, permettent aussi des diaporamas dans des formats variés. On citera notamment :

revealjs (https://github.com/rstudio/revealjs) pour des présentations HTLM basées sur le framework reveal.js
rmdshower (https://github.com/mangothecat/rmdshower) pour des diaporamas HTML basés sur shower

Une fois l’extension installée, elle propose en général un template de départ lorsqu’on crée un nouveau document dans RStudio. Ceux-ci sont accessibles depuis l’entrée From Template.

Créer une présentation à partir d’un template

Templates

Il existe également différents templates permettant de changer le format et la présentation des documents générés. Une liste de ces formats et leur documentation associée est accessible depuis la page formats de la documentation.

On notera notamment :

le template distill comportant de nombreuses options pour des documents scientifiques et techniques au format HTML (plus d’infos sur https://rstudio.github.io/distill/) ;
des formats d’article correspondant à des publications dans différentes revues : jss_article, elsevier_article, etc. ;
le format Tufte Handouts qui permet de produire des documents PDF ou HTML dans un format proche de celui utilisé par Edward Tufte pour certaines de ses publications.

Enfin, l’extension rmdformats (https://github.com/juba/rmdformats) de Julien Barnier propose plusieurs modèles HTML adaptés notamment pour des documents longs :

Là encore, la plupart du temps, ces modèles de documents proposent un template de départ lorsqu’on crée un nouveau document dans RStudio (entrée From Template) :

Créer un document à partir d’un template

Ressources

Les ressources suivantes sont toutes en anglais…

Yihui Xie, J. J. Allaire et Garrett Grolemund ont écrit un livre dédié intitulé R Markdown: The Definitive Guide. Ce livre est intégralement accessible à https://bookdown.org/yihui/rmarkdown/.

L’ouvrage R for data science, accessible en ligne, contient un chapitre dédié à R Markdown.

Le site officiel de l’extension contient une documentation très complète, tant pour les débutants que pour un usage avancé.

Enfin, l’aide de RStudio (menu Help puis Cheatsheets) permet d’accéder à deux documents de synthèse : une “antisèche” synthétique (R Markdown Cheat Sheet) et un “guide de référence” plus complet (R Markdown Reference Guide).

On peut citer les formats odt, rtf, Markdown, etc.↩
Si vous n’utilisez pas ce dernier, l’extension peut être installée à part avec install.packages("rmarkdown") et chargée explicitement avec library(rmarkdown).↩
Il est possible d’inclure dans un document R Markdown des blocs de code d’autres langages↩
Ce comportement peut être modifié en cliquant sur l’icône d’engrenage de la barre d’outils et en choisissant Chunk Output in Console↩