Guide de démarrage en R markdown

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 :

 

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 :

 

 

Ici avec une table:

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

 

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.

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

Retrouvez ici 4 de mes articles les plus consultés :

Partager l'article
  •  
  •  
  •  
  •  
  •  
    2
    Partages
  • 2
  •  
  •  
  •  
  •  

Laisser un commentaire

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