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.

R markdown

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é.

R markdown

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 :

R markdown

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 :

R markdown

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.

R markdown

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

R markdown

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.

R markdown

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

R markdown

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

R markdown

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.

R markdown

Le rendu :

R markdown

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

R markdown

Le rendu :

R markdown

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)) 
R markdown

Insérer un lien hypertexte

Pour insérer un lien hypertexte, il suffit de placer l’adresse entre les symboles < et >, par exemple :

R markdown

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 :

  1. 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.
  2. 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« .

R markdown

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

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 ! 😉

 

Poursuivez votre lecture :

18 Responses

  1. 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.

    1. 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.

    2. 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.

  2. 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

  3. 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.

  4. 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 🙏🙏

  5. 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.

  6. 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. »

    1. Bonjour Julien,

      non, désolée, je ne sais pas du tout…
      Essayez de poser la question sur twitter avec les #rstatfr
      Bonne continuation.

  7. 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

    1. 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

Laisser un commentaire

Votre adresse e-mail ne sera pas publiée. Les champs obligatoires sont indiqués avec *

Aide mémoire off'R ;)

Enregistrez vous pour recevoir gratuitement mes fiches « aide mémoire » (ou cheat sheets) qui vous permettront de réaliser facilement les principales analyses biostatistiques avec le logiciel R et pour être informés des mises à jour du site.