Guide de démarrage en R markdown
Vous avez entendu parler de génération de rapports dynamiques incorporant du code R, les sorties de ce code et des commentaires, mais vous ne savez pas par où commencer ? Cet article est fait pour vous ! Je vais vous expliquer comment ça marche et vous donner les quelques éléments nécessaires pour débuter facilement dans la production de ces rapports dynamiques.
Rapport dynamique et R markdown
Un rapport dynamique, c’est un rapport qui se génère automatiquement à partir d’un fichier écrit dans un certain format. Ici il s’agit du R markdown (.Rmd). C’est un format qui contient des balises, un peu comme du html, mais en plus simple, et qui permet de concevoir un rapport dynamique comportant :
- du code R : ce qui permet de montrer comment les analyses ont été
faites, par exemple en termes de jeu de données, ou de fonctions
utilisées. - les résultats du code R : il s’agit par exemple des sorties d’un
modèle de régression, ou encore d’un plot. - des commentaires : qui permettent, par exemple, d’ajouter une
interprétation aux résultats.
Les rapports dynamiques générés à partir d’un fichier R markdown s’intègrent dans le concept de “Recherche reproductible“, puisque l’analyse statistique réalisée peut être reproduite, strictement àl’identique, par quiconque dispose du fichier.Rmd. Les rapports peuvent, en outre, être générés sous divers formats, html, pdf ou docx, par exemple. Au final le langage R markdown, est un outil parfaitement adapté à la collaboration (y compris avec vous-même) et à la diffusion des résultats
Avant de commencer
Organisez votre travail sous la forme d'un projet R
Créer un dossier sous windows à l’emplacement souhaité, puis dans R Studio :
File –> New Project –> Existing Directory –> Indiquez l’emplacement –> Create Project.
Pour plus de détails, vous pouvez consulter cet article.
Installez et chargez les packages rmarkdown, markdown et knitr
Avec l’outil d’installation (fenêtre en bas à gauche dans R studio), ou avec les lignes decommandes :
install.packages("knitr")
install.packages("rmarkdown")
install.packages("markdown")
library(knitr)
library(rmarkdown)
library(markdown) Générer votre premier rapport dynamique
Ouvrez un nouveau fichier R markdown et enregistrez le
File –> New File –> Rmarkdown
Laissez toutes les options par défaut (document et html), et remplissez le champs “Title” , ce titre correspondra au titre du document, il peut être long.
Après avoir appuyé sur “OK”, un fichier Rmd apparaît dans la fenêtre d’édition (en haut à gauche). Ce fichier est un exemple, il comporte du code et du texte, ainsi que le titre que vous lui avez donné.
Enregistrez le, en lui donnant un nom (un nom de fichie cette fois, “RappDyn1” par exemple) :
File –> Save ou CTRL + S
Lancer la génération du document
Pour cela, c’est très simple, cliquez sur le bouton avec la pelote de laine et les aiguilles :
Un fichier html portant le même nom que le fichier.Rmd est alors créé dans le working directory (là où vous avez créé votre projet R), et en même temps le rapport généré s’ouvre dans le viewer de R Studio :
Choisissez votre format de sortie : html, word, pdf
En cliquant sur la flèche vers le bas, du bouton knit vous pourrez changer le format de sortie du rapport dynamique.
En cliquant sur la flèche vers le bas, du bouton knit vous pourrez changer le format de sortie du rapport dynamique.
Le format par défaut est celui choisi à l’étape précédente, c’est à dire html, ici. Vous pourrez choisir Word ou pdf. Pour obtenir votre rapport au format pdf, vous devez d’abord télécharger MikTeX et lors de l’installation, choisir “install missing packages”. Vous pouvez aussi choisir cette option après l’installation en allant dans “settings”.
Maintenant que vous avez vu le rendu, nous allons regarder de plus prés le fichier Rmd.
Organisation du fichier Rmd
L'en tête
L’en-tête est contenu entre deux séries de pointillés. Par défaut, il contient deux types d’éléments : le titre du document, et son format de sortie. Il est possible d’ajouter d’autres éléments, comme l’auteur, et la date de création, par exemple.
Il est encore possible d’ajouter une table des matières, ou encore un lien vers un fichier de références bibliographiques (voir cet article).
Les chunks contenant le code R
Il est encore possible d’ajouter une table des matières, ou encore un lien vers un fichier de références bibliographiques (voir cet article).
Les parties de code R sont contenues dans des blocs, appelés chunks”. Ces chunks commencent et finissent par les balises “`
Entre les deux, se trouve une accolade contenant la lettre r. C’est dans cette accolade, après la lettre r (il ne faut pas l’enlever) que les options vont pouvoir être passées, pour choisir de faire apparaître, ou non, le code dans le rapport dynamique, ainsi que les résultats, ou encore pour définir la taille des plots.
Ces chunks peuvent être nommés. Dans l’exemple précédent, le nom du chunk est cars.
Le chunk set up
Ce chunk se trouve en dessous de l’en-tête, il permet de régler les options par défaut de tous les chunks. Par exemple, on va pouvoir indiquer que l’on ne veut pas faire les messages et les warnings qui pourraient être générés lors de l’exécution des chunck. Au lieu de le faire pour tous les chunks, on peut le faire une seule fois ici.
Et si, pour un chunck donné, on veut faire apparaître les warnings et les messages, on utilisera message=TRUE et warnings=TRUE dans l’accolade du chunck concerné.
Les parties texte
Elles peuvent être insérées partout en dehors des chunks.
Il est possible de mettre en gras, ou en italique, certaines parties du texte.
Quelques éléments pour débuter
Il est possible de mettre en gras, ou en italique, certaines parties du texte.
Titre, liste, gras, italique
Voici comment faire des titres, des listes, des puces, mettre en gras et en italique :
Le rendu
La table des matières du document peut être visualisée en cliquant sur le bouton suivant :
Gestion du code
Affichage du code
Par défaut, le code R est affiché lors de la génération du rapport, cela correspond à l’option echo=TRUE. Pour supprimer l’affichage du code, il faut utiliser l’argument echo=FALSE.Lorem ipsum dolor sit amet, consectetur adipiscing elit. Ut elit tellus, luctus nec ullamcorper mattis, pulvinar dapibus leo.
Le rendu :
Affichage du résultat du code
Par défaut, le résultat du code est affiché lors de la génération du rapport, cela correspond à l’option results=”markup”. Pour le supprimer, il faut utiliser l’argument results=”hide”
Le rendu :
Gérer la taille des figures
On utilise les arguments fig.width et fig.height
Le rendu :
Insérer une image
Pour insérer une image, il suffit de placer l’image dans le working directory (par exemple une image nommée “Graffiti\_Manosque.jpg” ) et d’utiliser, en dehors d’un chunck, la commande suivante :
Le rendu :
J’ai l’habitude de placer les images dans un dossier img dans le working, directory. Dans ce cas, j’utilise :
Créer une table de données
Pour cela, on utilise, dans un chunk, la fonction kable du package knitr.
Ici, une sortie sans le formatage :
head(iris)
## Sepal.Length Sepal.Width Petal.Length Petal.Width Species
## 1 5.1 3.5 1.4 0.2 setosa
## 2 4.9 3.0 1.4 0.2 setosa
## 3 4.7 3.2 1.3 0.2 setosa
## 4 4.6 3.1 1.5 0.2 setosa
## 5 5.0 3.6 1.4 0.2 setosa
## 6 5.4 3.9 1.7 0.4 setosa Ici avec une table :
library(knitr)
kable(head(iris)) 
Insérer un lien hypertexte
Pour insérer un lien hypertexte, il suffit de placer l’adresse entre les symboles < et >, par exemple :
Le rendu :
Insérer un nouveau chunk
Sous windows, un nouveau chunk peut être insérer en utilisant les touches Ctrl+Alt+I.
Mais comment ça marche ?
La production des rapports se réalise en deux étapes :
- Le fichier .Rmd qui contient des blocs de code R (que l’on appelle chunk) et du texte est fournit au package knitr qui va exécuter les codes R afin d’obtenir les sorties, et créer un document au format markdown (.md). Ce document contient alors les codes R, les résultats (ou les sorties), et les textes de commentaires.
- Ce fichier .md est ensuite converti vers le format souhaité, comme “html”, “docx” ou encore “pdf”, par le package markdown basé sur pandoc (c’est un outil de conversion de document).
Remarques
Exécuter les codes des chunks
Les codes contenus dans les chunks d’un document.Rmd peuvent être exécutés comme les codes contenus dans un script R en.R. Vous pouvez exécuter l’ensemble en faisant CTRL + A pour tout sélectionner et CRTL + ENTER pour exécuter. Vous pouvez aussi exécuter le code chunk par chunk en placer votre souris au début d’un chunk puis en utilisant CTRL + ENTER. D’autres options sont disponibles dans le menu déroulant du bouton run ( tout près de celui permettant d’afficher la table des matières)
Lorsque le code est excécuté, par défaut les résultats (sorties), et les plots sont affichés dans le document .Rmd. Pour afficher les sorties dans la console et les plots dans la fenêtre graphique, il faut choisir l’option “Chunk Output in Console“.
Utiliser le R markdown pour autre chose
Les fichiers R markdown peuvent également être utilisés pour réaliser des diapositives de présentation (avec le package slidify), des tableaux de bord (avec shiny), du contenu pour un site web (package blogdown), ou encore pour écrire un article une publication ou un livre (package bookdown).
Pour aller plus loin
Vous pouvez les télécharger directement depuis l’onglet Help –> Cheatsheet
- l’add on remedy, développé par ThinkR, qui s’intègre à R Studio pour simplifier l’écriture des fichiers Rmd
- le livre “R Markdown: The Definitive Guide” , ou en version papier:
- le livre “ blogdown : Creating Websites with R markdown “, ou en version papier:
- le livre “bookdown: Authoring Books and Technical Documents with R Markdown , ou en version papier:
Conclusion
Pour ceux qui ne travaillent pas encore en R markdown , j’espère que cet article vous convaincra qu’il est facile de franchir le pas. Cela demande un investissement minime pour un gain maximal. En passant en R markdown vous gagnerez en temps, en productivité, et en qualité. N’hésitez plus, lancez vous ! Vous ne le regretterez pas ! Dans un prochain article, je vous montrerai quelques astuces pour améliorer vos rapports dynamiques.
Si cet article vous a plu, ou vous a été utile, et si vous le souhaitez, vous pouvez soutenir ce blog en faisant un don sur sa page Tipeee 
Credits photos : dejdj, Tumisu.
Note : Je touche une petite commission (entre 3 et 6%) si vous passez par les liens Amazon de cet article pour acheter les livres mentionnés. cela m’aide à entretenir ce blog, merci si vous le faites ! 
Bonjour Claire, bon résumé du potentiel de RMarkdown.
Aurais-tu une idée pourquoi je suis incapable d’imprimer correctement les accents et autres caractères spéciaux dans l’exemple suivant:
—
title: “Test”
output:
html_document
—
## Special characters
Test sur les caractères spéciaux. 1999–2015.
Voici ce que j’obtiens en sortie:
Test
Special characters
Test sur les caractères spéciaux. 1999–2015.
Bonjour Benoit,
je ne sais pas trop pourquoi il y a parfois des problèmes d’accents, mais j’ai quand même deux conseils : ne pas ouvrir Rstudio en double cliqant sur le .Rmd, mais toujours en passant par l’icône du Projet R, ou par celui de Rstudio, et vérifier la langue utilisée dans la sortie de sessionInfo(). Pour passer en français on peut utiliser les commandes Sys.setlocale(“LC_TIME”, “French”). Bonne continuation.
Bjr, c est surtout un pb d encodage, si tu as enregistré ton rmd, et que tu fermes, puis ouvres ton projet via Carl O, tu peux faire reopen with encoding puis tu choisis UTF8.
Tes caractères spéciaux redeviendront des accents.
[…] Guide démarrage en français par Claire Della Vedova. […]
Bonjour et tout d’abord merci beaucoup pour vos précieux articles !
Je me demandais s’il était possible d’insérer plusieurs images et de les ordonner dans rmarkdown. Mon problème vient du fait que j’utilise des pirateplot qui ne sont pas pris en compte par grid.arrange… J’ai donc pensé enregistrer chaque figure en png ou pdf, et les insérer après, mais je ne sais pas comment faire…
Merci d’avance ! 🙂
Bien cordialement
Bonjour,
c’est sans doute possible, je vous conseille d’aller voir ce post : https://www.zevross.com/blog/2017/06/19/tips-and-tricks-for-working-with-images-and-figures-in-r-markdown-documents/
Bonne continuation.
Bonjour Claire,
Juste te dire merci pour tes articles.
Merci pour cet article très utile en analyse.
Bravo à toi.
Bonjour Claire,
Je voudrai tout simplement vous remercier pour tout ce que vous nous apportez à travers votre blog.
C’est une aide inestimable pour moi.
Tout simplement merci.
Bonjour Claire,
Egalement un grand merci de ma part. Super aide, claire, bien expliqué…
Ces guides m’aident beaucoup 🙂
Booké en tant que favoris 😉
Merci beaucoup 🙏🙏
🙋♀️ Antoine
👍🤩
😏
Bonjour Claire, merci pour vos articles précieux,
mais auriez vous une idée pourquoi je parviens pas à retourner à la ligne?
Si je rédige, tout le texte est concanténé.
Merci d’avance !!
Cordialement.
Bonjour,
Il faut insérer deux espaces en fin de ligne.
Bonne continuation.
Bonjour à tous et merci Claire pour tes tutos et articles toujours aussi précis.
Je vais parler d’un truc qui “fâche”, l’encodage.. Ce n’est pas tout à fait le problème de Benoit car moi mon fichier .Rmd imprime bien les accents mais c’est plus au niveau de la compilation (html ici) avec le warning ci-dessous et un fichier html qui s’arrête juste avant l’accent. C’est très embêtant car j’ai beaucoup d’accent dans mes labels de variable et donc je ne peux pas utiliser les packages auto de summary tels que arsenal (write2html(tableby(…))) ou tout simplement créer un markdown. Ça fait longtemps que je cherche et rien.
Merci d’avance pour votre aide
Julien
Mes infos :
Je suis sous windows (c’est aussi la le pb) et j’ai bien mis options(encoding = “UTF-8”) dans .Rprofile. Je n’arrive pas à changer la variable locale ci-dessous avec Sys.setlocale(“LC_ALL”, “fr_FR.UTF-8”).
R version 3.6.3 (2020-02-29)
Platform: x86_64-w64-mingw32/x64 (64-bit)
Running under: Windows 8.1 x64 (build 9600)
Matrix products: default
locale:
[1] LC_COLLATE=French_France.1252 LC_CTYPE=French_France.1252 LC_MONETARY=French_France.1252 LC_NUMERIC=C
[5] LC_TIME=French_France.1252
Voici le message :
“Warning message: In knitr::knit(knit_input, knit_output, envir = envir, quiet = quiet) :
The file “test.Rmd” must be encoded in UTF-8. Please see https://yihui.org/en/2018/11/biggest-regret-knitr/ for more info.”
Bonjour Julien,
non, désolée, je ne sais pas du tout…
Essayez de poser la question sur twitter avec les #rstatfr
Bonne continuation.
Bonjour Claire
Merci pour ce Tutos
Bonjour,
merci pour toutes ces infos !
J’ai une petite question, lorsque que je génère mon document HTML sur R, celui apparait toujours vierge… Ai-je loupé une manipulation ?
Merci à Vous
Bonsoir Audrey,
J’ai récemment remarqué ce problème, lorsque le fichier est nommé avec un espace.
Renommez-le et relancer.
Il est également possible que le rendu html s’ouvre dans une autre fenêtre. POur le voir dans R Studio, allez dans le menu Tools –> Global Options –> Rmarkdown (sur la gauche) et choisissez “Show output preview in Viewer Pane”.
En espérant que cela vous aide …
Bonne continuation