Cours
Créer des rapports avec R Markdown
4 h
46K
Cet article passe en revue un package incontournable et très utile en data science que tout utilisateur de R devrait connaître : R Markdown. Nous verrons ce qu’est R Markdown, ses avantages, ses cas d’usage, comment l’installer, comment il permet d’articuler code, narration et visualisations, la syntaxe qu’il utilise, les formats de sortie disponibles, ainsi que la façon de générer ces documents et de les partager avec vos collaborateurs.
Comme R Markdown est particulièrement bien intégré à l’environnement de développement RStudio (IDE), nous utiliserons cet IDE tout au long de l’article. Le tutoriel RStudio vous guide pas à pas pour installer RStudio et démarrer.
Allons-y !
Qu’est-ce que R Markdown ?
R Markdown est un package R libre et open source qui offre un espace de travail pour créer des projets de data science. Son atout majeur : il vous permet de combiner code, texte et visualisations dans un document unique, soigné, partageable et entièrement reproductible, exportable dans une grande variété de formats, statiques comme interactifs.
Parmi ses formats de sortie les plus courants : HTML, PDF, Microsoft Word, présentations, applications, sites web, tableaux de bord, rapports, modèles, articles, livres, etc.
R Markdown facilite en outre le suivi de version et prend en charge de nombreux langages au-delà de R, notamment Python et SQL.
Pour aller plus loin dans la production de rapports dynamiques avec R Markdown, démarrez avec le cours Reporting with R Markdown.
Installer R Markdown
Si vous utilisez R Markdown en dehors de RStudio, installez-le comme n’importe quel package R depuis le dépôt CRAN (Comprehensive R Archive Network) :
install.packages("rmarkdown")Après l’installation, chargez le package dans votre environnement R :
library(rmarkdown)En revanche, si vous travaillez avec R Markdown dans RStudio — ce que nous ferons dans ce tutoriel — vous n’avez pas besoin d’installer et charger explicitement le package rmarkdown. En cliquant sur File — New File — R Markdown dans la barre de menus de RStudio, un nouveau document R Markdown s’ouvre. À ce stade, vous pouvez recevoir une notification Install Required Packages, comme ci-dessous :
Après avoir confirmé l’installation des packages requis, une nouvelle fenêtre s’ouvre pour saisir le titre du document et le nom de l’auteur (tous deux facultatifs mais recommandés). Laissez les autres paramètres par défaut et cliquez sur OK :
Document R Markdown par défaut
À l’étape précédente, nous avons ouvert un nouveau document R Markdown dans RStudio. Il se présente ainsi :
On y retrouve le titre, le nom de l’auteur, la date du jour et le format de sortie par défaut, tels que fournis dans la fenêtre initiale. On y voit aussi des exemples de la syntaxe de base de R Markdown : ajout et mise en forme de blocs de code, titres, insertion de liens, emphase typographique, et génération de graphiques.
Nous allons examiner plus finement les différentes fonctionnalités et leur syntaxe. Pour l’instant, enregistrons ce fichier par défaut puis générons-le dans le format choisi (ici : HTML) pour voir le rendu.
Pour enregistrer le fichier, cliquez sur File — Save As... dans la barre de menus de RStudio.
NOTE : le nom de document R Markdown renseigné plus tôt n’est pas le nom du fichier. Il faut enregistrer le fichier dans le répertoire du projet, puis penser à l’enregistrer régulièrement (File — Save) pendant l’édition.
Pour générer le fichier enregistré dans le format sélectionné (HTML), cliquez sur Knit dans la barre d’outils du fichier :
Voici le rendu HTML de notre document R Markdown par défaut :
Mise en forme du texte dans R Markdown
Le texte représente souvent la majeure partie d’un projet de data science. Il est donc essentiel de savoir le mettre en forme dans R Markdown pour qu’il soit lisible, efficace et convaincant.
Si vous souhaitez apprendre à utiliser R pour l’analyse de données et la data science tout en développant vos compétences en programmation R, explorez ces parcours complets et accessibles aux débutants :
Titres
Vous pouvez créer différents niveaux de titres dans un document R Markdown à l’aide du symbole dièse (#). Syntaxe :
# Titre 1 (titre principal)
## Titre 2 (section)
### Titre 3 (sous-section)
etc.
Une fois générés, les titres apparaissent ainsi :
Emphase typographique
R Markdown permet d’appliquer différents types d’emphase : italique, gras, barré, exposant et indice, comme suit :
- *italique* ou _italique_
- **gras** ou __gras__
- ~~barré~~
- texte^exposant^
- texte~indice~
Voici le rendu correspondant :
Listes
Pour créer une liste non ordonnée, utilisez l’une des trois syntaxes suivantes :
* Élément 1* Élément 2* Élément 3
ou :
- Élément 1- Élément 2- Élément 3
ou :
+ Élément 1+ Élément 2+ Élément 3
Dans tous les cas, le rendu sera identique :
Pour créer une liste ordonnée, utilisez la syntaxe suivante :
1. Élément 12. Élément 23. Élément 3
Le rendu sera similaire, avec un retrait avant chaque numéro.
Notez que si vous supprimez un élément, en ajoutez un ou vous trompez dans un numéro (par exemple 20. au lieu de 2.), la numérotation sera automatiquement corrigée à l’affichage :
Citations
Pour les blocs de citation, utilisez le symbole > avant le premier caractère du texte cité :
> Lorem ipsum dolor sit amet, consectetur adipiscing elit. Nam hendrerit nisi sed sollicitudin pellentesque. Nunc posuere purus rhoncus pulvinar aliquam. Ut aliquet tristique nisl vitae volutpat. Nulla aliquet porttitor venenatis. Donec a dui et dui fringilla consectetur id nec massa. Aliquam erat volutpat. Sed ut dui ut lacus dictum fermentum vel tincidunt neque.
Le rendu sera :
Ajoutez une ligne vide après le bloc cité pour revenir au texte courant.
Liens
Pour inclure un lien en clair, placez l’URL entre les symboles < et >. Par exemple :
sera affiché ainsi :
Pour ancrer un lien sur un mot ou un court texte, utilisez la syntaxe suivante (toujours avec Google en exemple) :
[Google](https://www.google.com/)
Ce qui sera rendu :
Images
Pour insérer une image dans votre narration, vous pouvez procéder de plusieurs manières :
- Ajouter une image depuis Internet :
- Si l’image est enregistrée dans le dossier du projet (même emplacement que le document R Markdown) :
- Si l’image est sur votre ordinateur mais en dehors du dossier du projet :
Le texte alternatif décrit brièvement l’image et s’affiche lorsqu’elle ne peut pas être chargée pour une raison quelconque.
Voyons la première approche avec une image Pixabay, dont l’URL est https://cdn.pixabay.com/photo/2018/12/02/10/07/web-3850917_1280.jpg :
Une fois le document généré, l’image s’affiche :
Sauts
R Markdown propose plusieurs types de sauts :
- Saut de ligne — pour passer à la ligne suivante. S’obtient en terminant la ligne précédente par un antislash (\).
- Saut de paragraphe — pour commencer un nouveau paragraphe. S’obtient en terminant le paragraphe précédent par deux espaces.
- Saut de diapositive — pour démarrer une nouvelle diapositive dans les formats de présentation, ou une nouvelle section dans les autres formats. S’obtient en insérant une règle horizontale (***) dans le document.
- Saut de page — pour commencer une nouvelle page dans les formats qui le permettent (par ex. Microsoft Word). S’obtient en insérant la commande \newpage.
Mettons en pratique les trois premiers. Voici un extrait de Lorem ipsum avec les symboles de mise en forme correspondants :
Lorem ipsum dolor sit amet, consectetur adipiscing elit.\Nam hendrerit nisi sed sollicitudin pellentesque.
Nunc posuere purus rhoncus pulvinar aliquam.
***
Ut aliquet tristique nisl vitae volutpat.
Et voici le rendu dans un document HTML :
Lorem ipsum dolor sit amet, consectetur adipiscing elit.Nam hendrerit nisi sed sollicitudin pellentesque.
Nunc posuere purus rhoncus pulvinar aliquam.
Ut aliquet tristique nisl vitae volutpat.
Mise en forme et exécution du code dans R Markdown
Le code est un autre élément essentiel de tout projet de data science. Avec R Markdown, vous pouvez exécuter du code (pas uniquement en R), afficher le code et sa sortie, n’afficher que le code en masquant la sortie, ou à l’inverse n’afficher que la sortie, etc.
Le parcours "carrière" R Programmer et le parcours "compétence" R Programming sont d’excellentes ressources pour apprendre, pratiquer et perfectionner votre code R.
Blocs de code
Pour mettre en forme et exécuter un bloc de code R dans R Markdown, encadrez-le par trois accents graves, le premier étant suivi de r entre accolades. Exemple :
```{r}
print("Hello, World!")
```Si vous générez le document sans exécuter le code, le bloc apparaîtra comme ci-dessous :
Langage de code
Avec R Markdown, vous n’êtes pas limité à R : de nombreux autres langages sont pris en charge. Pour exécuter du code dans un autre langage, indiquez son nom à la place de R entre accolades. Il peut être nécessaire d’installer et charger des packages supplémentaires dans R.
Par exemple, pour utiliser Python dans R Markdown, installez et chargez le package reticulate, qui permet une communication bidirectionnelle (création et accès aux variables) entre Python et R dans un même document.
Réécrivons l’exemple précédent en Python (après installation et chargement de reticulate) :
```{python}
print("Hello, World!")
```
Exécution des blocs de code
Pour exécuter un bloc de code (ou des lignes sélectionnées) dans RStudio, cliquez sur le bouton Run dans la barre d’outils du document et choisissez l’option souhaitée dans la liste déroulante :
Chaque option de lancement dispose d’un raccourci clavier, pratique pour éviter d’ouvrir la liste à chaque fois.
Nommer les blocs de code
Sans être obligatoire, nommer les blocs de code est une bonne pratique : pour les référencer dans le document, faciliter le débogage, naviguer rapidement entre les blocs, etc. C’est particulièrement utile dans les documents longs contenant de nombreux blocs.
Ajoutez le nom du bloc entre accolades, juste après le nom du langage, séparé par un espace. Le nom ne doit pas contenir d’espace.
Dans l’exemple ci-dessous, nous avons nommé le bloc hello_world :
```{r hello_world}
print("Hello, World!")
```Options des blocs de code
Les options de bloc permettent de contrôler l’évaluation du code, la sortie, la décoration, le cache, l’animation (le cas échéant) et les graphiques (si applicables) — bloc par bloc. Vous pouvez combiner plusieurs options. Côté syntaxe, placez les options entre accolades, après le nom du bloc (s’il existe, sinon après le langage), en les séparant par des virgules.
R Markdown propose de nombreuses options. Chacune a une valeur par défaut, mais vous souhaiterez souvent la modifier. Voici les plus utilisées :
echo=FALSE— le code n’apparaît pas dans le document final, seules ses sorties sont affichées.eval=FALSE— le code du bloc n’est pas exécuté.include=FALSE— le bloc est exécuté mais n’est pas inclus dans le document final.results— valeur par défaut : "markup" ; autres valeurs :- "hide" — la sortie du code est masquée dans le document final
- "hold" — la sortie du code n’est affichée qu’après l’exécution complète du bloc
- "asis" — la sortie est transmise telle quelle, sans reformatage.
message=FALSE— masque les messages produits par le code.error=FALSE— masque les erreurs produites par le code.warning=FALSE— masque les avertissements produits par le code.highlight=FALSE— désactive la coloration du code dans le document final.prompt=TRUE— ajoute le symbole > au début de chaque ligne de code affichée dans le document final.
Voici quelques exemples de blocs de code exécutés dans RStudio puis rendus dans le document final :
Code dans R Markdown :
Sortie dans le document final :
Code en ligne
Le code en ligne permet d’insérer directement de courts fragments de code dans le texte d’un document R Markdown : ils seront exécutés et leur sortie s’affichera au sein du texte. La syntaxe est r <code>.
Exemple simple avec code en ligne :
There are `r 1+6` colors of the rainbow.
et son rendu dans le document final :
There are 7 colors of the rainbow.
En pratique, le code en ligne sert à agréger des informations sur les données et évite les erreurs liées à une saisie manuelle ou à l’évolution des données.
Tracer des graphiques dans R Markdown
Générer des graphiques dans R Markdown revient à exécuter du code qui produit des visuels. Tout ce que nous avons vu sur la mise en forme et l’exécution du code (sauf le code en ligne) s’applique donc. La différence principale : la sortie est graphique plutôt que textuelle.
Le parcours "compétence" Data Visualization with R vous aidera à développer les compétences nécessaires pour analyser et visualiser des données avec R et ainsi mieux raconter vos analyses basées sur les données.
Pour personnaliser les graphiques dans R Markdown, utilisez les outils des packages de visualisation R, ainsi que la fonction plot() de base R.
Pour contrôler le comportement d’affichage des graphiques dans un document R Markdown, exploitez les options de bloc spécifiques au traçage. La plupart sont assez pointues et sortent du cadre de cette prise en main. Voici toutefois quelques options utiles :
fig.show— valeur par défaut : "asis" ; autres valeurs :- "hide" — les graphiques sont générés mais non inclus dans le document final
- "hold" — les graphiques ne s’affichent qu’après l’exécution complète du bloc
- "animate" — tous les graphiques du bloc sont combinés en une animation.
fig.width— largeur du graphique en pouces, 7 par défaut.fig.height— hauteur du graphique en pouces, 7 par défaut.fig.align— alignement dans le document final : "left", "center" ou "right".fig.cap— légende du visuel, sous forme de chaîne de caractères.fig.path— chemin du répertoire où stocker les fichiers graphiques produits par le bloc.fig.ext— extension des fichiers graphiques générés par le bloc.
Voici quelques exemples d’options spécifiques aux graphiques, avec le code source et le rendu :
Code dans R Markdown :
Sortie dans le document final :
Formats de sortie
Jusqu’ici, nous avons travaillé en HTML (html_document) comme format de sortie. R Markdown prend toutefois en charge de nombreux autres formats, dont Microsoft Word, Microsoft PowerPoint, PDF, carnets interactifs R, tableaux de bord, etc.
Par exemple, pour créer des documents, on peut utiliser html_document, pdf_document, word_document, github_document, html_notebook, html_vignette, etc. Pour les présentations : powerpoint_presentation, ioslides_presentation, slidy_presentation et beamer_presentation.
Pour définir le format de sortie, attribuez la valeur correspondante au paramètre output dans l’en-tête du document (appelé en-tête YAML, pour "yet another markup language"). Dans notre document de travail, le format de sortie est html_document, valeur par défaut de R Markdown :
Pour le changer, remplacez html_document par le format souhaité (pdf_document, word_document, powerpoint_presentation, etc.). En cliquant sur Knit, le document sera généré dans le format choisi.
Publier des documents R Markdown
Pour publier un document R Markdown, cliquez sur File — Publish dans la barre de menus de RStudio et choisissez la destination :
Suivez ensuite les instructions selon l’option sélectionnée, puis cliquez sur Publish. Votre document est prêt à être partagé avec vos collaborateurs.
Conclusion
Pour résumer, nous avons vu comment bien démarrer avec R Markdown : définition et usages, installation, mise en forme du texte et de ses composants, mise en forme et exécution du code, génération de graphiques, formats de sortie disponibles, génération du document dans l’un de ces formats, et publication pour le partage avec des collègues.
Pour vous exercer concrètement à R Markdown, suivez notre cours Reporting with R Markdown : vous apprendrez à mettre en évidence des insights et à présenter vos résultats en PDF, en fichier HTML ou sous forme d’application Shiny.
Sujets