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.

 

Table des matières :

  1. Rapport dynamique et R markdown
  2. Avant de commencer
  3. Générez votre premier rapport dynamique
  4. Organisation du fichier Rmd
  5. Quelques éléments pour débuter
  6. Mais comment ça marche ?
  7. Remarques
  8. Pour aller plus loin
  9. Conclusion
   

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

 

2. Avant de commencer:

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

2.2. 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 de commandes :

install.packages("knitr")
install.packages("rmarkdown")
install.packages("markdown")

library(knitr)
library(rmarkdown)
library(markdown)

 

3. Générez votre premier rapport dynamique

3.1 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

3.2 Lancer la génération

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

3.3 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

 

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.

4 Organisation du fichier Rmd

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

 

4.2 Les chunks contenant le code R

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.  

4.3 Le chunk de 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.

 

R markdown

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

 

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

 

5.Quelques éléments pour débuter

5.1 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 :

5.2 Gestion du code

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

R markdown  

Le rendu :

R markdown

5.2.2 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 :

5.2.3 Gérer la taille des figures

On utilise les arguments fig.width et fig.height

R markdown  

Le rendu :

R markdown

5.3 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 :

R markdown  

Le rendu :

J’ai l’habitude de placer les images dans un dossier img dans le working, directory. Dans ce cas, j’utilise

 

5.4 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  

5.6 Insérer un lien hypertexe

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

R markdown

Le rendu :

5.7 Insérer un nouveau chunck

Sous windows, un nouveau chunk peut être insérer en utilisant les touches Ctrl+Alt+I.

 

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

7. Remarques

7.1. Exécuter les codes des chuncks.

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

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

 

8 Pour aller plus loin :

Vous pouvez les télécharger directement depuis l’onglet Help –> Cheatsheet

21 réponses

  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.

Laisser un commentaire

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