Formation R - Module 3 : Rmarkdown

Author

Noé Barthelemy

I) Introduction

1) Qu’est ce que “R markdown” ?

“R Markdown est un outil puissant pour la création de documents dynamiques qui combinent du texte formaté avec des analyses de données en utilisant le langage de programmation R. Il possède une syntaxe de formatage simple pour la rédaction de documents HTML, PDF et Microsoft Word. Pour plus de détails sur l’utilisation de R Markdown, consultez http://rmarkdown.rstudio.com.”

En fait, vous verrez que Markdown vous permettra de réaliser des scripts plus beaux, mieux ordonnés, et dans lesquels vos idées, vos commentaires et votre code ne feront qu’un. Ce genre de script faciliteront ENORMEMENT le travail de vos relecteurs, mais également le vôtre !

Dans ce tutoriel, nous allons explorer les fonctionnalités de base de R Markdown en créant un document pas à pas.

PS: Ce document provient d’un R markdown !

II) Création d’un document R markdown

  1. Lancez RStudio.
  2. Sélectionnez File (Fichier) > New File (Nouveau fichier) > R Markdown… dans la barre de menu.
  3. Choisissez un titre pour votre document et un auteur.
  4. Sélectionnez le format de sortie, par exemple, HTML, PDF ou Microsoft Word (Je préconise HTML par défaut).
  5. Cliquez sur le bouton OK.

III) Essayons de créer du contenu

1) Les chunks

Dans R markdownk, les commentaires n’ont pas besoin d’être précédés d’un #. En fait, c’est plutôt l’inverse, car c’est le code qui devra être encapsulé dans ce qu’on appelle des “chunks”.

Insérons un chunk avec le raccourci ctrl + alt + i , ou alors avec le bouton vert ci-dessus à droite.

# Le chunk est un espace est réservé au code. Ici, je dois donc à nouveau précéder 
# mes commentaires d'un #.

# Charger le jeu de données 'iris' intégré à R
data(iris)

Notez que le chunk démarre par un {r}. Nous codons en R ! Remplacez ce {r} par {SQL}, et vous pourrez lancer une requête SQL depuis le même script ! Pas mal non ?

2) Intégrer des graphiques

Maintenant, explorons ce jeu de données :

Notez que le paramètre ‘echo = FALSE’ a été ajouté au chunk pour empêcher l’affichage du code R qui a généré le graphique. Ainsi, dans le script, on aura seulement le graphique. Faites la même chose pour les autres chunks que vous ne voulez pas afficher !

Voilà ce que ça donne si on affiche le code :

library(ggplot2)
theme_set(theme_classic())

# Plot
g <- ggplot(iris, aes(Petal.Length))
g + geom_density(aes(fill=factor(Species)), alpha=0.8) + 
    labs(title="Graphique de densité", 
         subtitle="Longueur des pétales groupée par espèce de fleur",
         caption="Source : iris",
         x="Longueur des pétales",
         fill="Espèce de fleur")

Ou encore :

# Créer la donnée
x <- seq(0, 2*pi, length.out=100)
data <- data.frame(
  x=x, 
  y=sin(x) + rnorm(100, sd=0.2)
)
 
# Ajouter une colonne avec un condition pour choisir la couleur
data <- data %>% 
  mutate(mycolor = ifelse(y>0, "type1", "type2"))
 
# plot
ggplot(data, aes(x=x, y=y)) +
  geom_segment( aes(x=x, xend=x, y=0, yend=y, color=mycolor), size=1.3, alpha=0.9) +
  theme_light() +
  theme(
    legend.position = "none",
    panel.border = element_blank(),
  ) +
  xlab("") +
  ylab("Value of Y")
Warning: Using `size` aesthetic for lines was deprecated in ggplot2 3.4.0.
ℹ Please use `linewidth` instead.

Ce chunk est long ! Vous pouvez exécuter l’ensemble du code contenu dans un chunk à l’aide du raccourci clavier Ctrl+Entrée

3) Quelques astuces de formatage.

ITALIQUE : Je peux mettre mon texte en italique en l’entourant de une seule étoile * Texte à afficher en italique * (sans les espaces).

GRAS : Je peux mettre mon texte en gras en l’entourant de deux étoiles ** Texte à afficher en gras ** (sans les espaces).

Saut de ligne : Je peux insérer un saut à la ligne avec la balise <br>.

III) Exporter son script

1) L’export, pour quoi faire ?

La magie de R markdown, c’est l’export ! En exportant votre script (comme je l’ai fait ici), vous obtenez un PDF qu’il sera facile de partager avec les collègues. Vous pourrez leur afficher des figures, des tableaux, etc.

Si des modifications doivent être faites, pas besoin d’exporter une figure, la copier dans word, etc. Vous avez juste à venir changer votre ligne de code dans le script et retricoter !

2) Problèmes techniques fréquents lors de l’export

Pour exporter au format PDF vous aurez besoin de :

  • LaTeX (un langage et un système de composition de documents qui permet d’avoir des rendus super propres) Normalement, TexWorks (MikTeX) est installé sur votre poste. Sinon, ouvrez un ticket.

  • Le package “tinytex” (Normalement installé, sinon ticket)

Avec une nouvelle installation de MiKTeX, de nombreux fichiers de style nécessaires pour “KNIT” (tricoter) un fichier RMarkdown en PDF ne sont pas installés. Pour permettre à MiKTeX de les installer automatiquement, ouvrez la console MiKTeX et allez dans l’onglet Paramètres (settings).

Il y a une option qui dit “You can choose whether missing packages are to be installed automatically (on-the-fly)”. Assurez-vous !que cette option est réglée sur “Always” pour permettre l’installation des fichiers de style nécessaires.

3) Personnaliser son export

La personnalisation du document généré peut être réalisée en ajustant les options dans le préambule du document. Cependant, RStudio propose également une interface graphique simplifiée pour modifier ces options.

Pour y accéder, cliquez sur l’icône en forme d’engrenage située à droite du bouton “Knit” et sélectionnez “Output Options…” dans le menu déroulant.

Personnellement, j’aime ajouter une table des matières.

4) Exportons

Dans R studio, cliquez simplement sur la flèche noire à droite du bouton “Knit” ci-dessus (la pelotte de laine!). Choisissez le format (essayons un PDF).

Voilà, vous n’avez plus qu’à admirer votre document :)

IV) Autres fonctionnalités

IV.I) Script .R –> Rmarkdown

Grace à la fonction rmarkdown::render(), on peut automatiquement générer un rapport de type Rmarkdown en utilisant un script .R comme source. Cela peut être utile si vous souhaitez ce genre de rapport mais que vous ne voulez pas transformer vos scripts .R en format .Rmd.

# Définir le contenu du script R à générer
contenu_script <- c(
  "# Ce script est généré automatiquement",
  "print('Bonjour, ceci est un script généré automatiquement.')",
  "x <- rnorm(100)",
  "hist(x, main='Histogramme de 100 valeurs générées normalement')"
)

# Chemin du fichier où écrire le script
chemin_fichier <- "script_example.R"

# Écrire le contenu dans un nouveau script R
writeLines(contenu_script, chemin_fichier)

# Message pour confirmer la création du fichier
cat("Le script a été généré et sauvegardé en tant que", chemin_fichier)
Le script a été généré et sauvegardé en tant que script_example.R
rmarkdown::render("script_example.R")


processing file: script_example.spin.Rmd

  |                                                         
  |                                                   |   0%
  |                                                         
  |.................                                  |  33%                   
  |                                                         
  |..................................                 |  67% [unnamed-chunk-17]

  |                                                         
  |...................................................| 100%                   
                                                                                                             
output file: script_example.knit.md
"D:/APP/RStudio/resources/app/bin/quarto/bin/tools/pandoc" +RTS -K512m -RTS script_example.knit.md --to html4 --from markdown+autolink_bare_uris+tex_math_single_backslash --output script_example.html --lua-filter "D:\APP\R\R-4.4.1\Library\rmarkdown\rmarkdown\lua\pagebreak.lua" --lua-filter "D:\APP\R\R-4.4.1\Library\rmarkdown\rmarkdown\lua\latex-div.lua" --embed-resources --standalone --variable bs3=TRUE --section-divs --template "D:\APP\R\R-4.4.1\Library\rmarkdown\rmd\h\default.html" --no-highlight --variable highlightjs=1 --variable theme=bootstrap --mathjax --variable "mathjax-url=https://mathjax.rstudio.com/latest/MathJax.js?config=TeX-AMS-MML_HTMLorMML" --include-in-header "C:\Users\NOE~1.BAR\AppData\Local\Temp\RtmpgJV4gf\rmarkdown-strdfc757127f8.html" 

Output created: script_example.html

IV.II) Rmarkdown –> Script .R

Utilisez purl() pour extraire le code R d’un script Rmarkdown et en faire un script .R !

Voici un bloc simple :

1 + 1
[1] 2

Les expressions R que vous insérerez directement dans le texte comme 6.2831853 sont ignorées par défaut. Si vous souhaitez les inclure dans le script R, vous devez définir l’option globale options(knitr.purl.inline = TRUE) avant d’appeler knitr::purl().

Si vous ne souhaitez pas extraire certains chunks de code, vous pouvez définir l’option de chunk purl = FALSE, comme dans le chunk suivant :

x = rnorm(1000)

Si nous appelons knitr::purl("nomdemonscript.Rmd"), cela génère le script R suivant (avec le nom de fichier purl.R par défaut) :

## --—-simple, echo=TRUE--------------------------- 
  1 + 1
[1] 2

Le script R ci-dessus contient les options de bloc dans un commentaire. Si vous souhaitez du code R pur, vous pouvez appeler knitr::purl() avec l’argument documentation = 0, ce qui générera le script R suivant à la place :

1+1
[1] 2

Enfin, si vous souhaitez conserver tout le texte, vous pouvez utiliser l’argument documentation = 2, ce qui génère le script R suivant :

#' Utilisez purl() pour extraire le code R d'un script Rmarkdown et en faire un script .R !

#' Voici un bloc simple :

#' {r, simple, echo=TRUE}
1 + 1
[1] 2
#' Les expressions R que vous insérerez directement dans le texte comme r 2 * pi sont ignorées par défaut.

#' Si vous ne souhaitez pas extraire certains chunks de code, vous pouvez définir l'option de chunk purl = FALSE, comme dans le chunk suivant :

IV.III) Utiliser un objet alors qu’il n’a pas encore été crée.

Il peut être utile d’afficher un objet dans un rapport Rmarkdown avant même que cet objet n’ai été créé. Par exemple, si je souhaite afficher un résumé au début de mon rapport, qui indique combien de tonnes de nickel sont exportées tous les mois, mais que ce calcul n’intervient qu’à la fin du script, c’est possible !

J’essaierai de l’expliquer ici mais, en attendant, vous pouvez le lire (en anglais) ici :

14.2 Use an object before it is created (*) | R Markdown Cookbook (bookdown.org)

J’espère que ce tutoriel vous auras été utile.

Bon code !

Sources

R Markdown Cookbook (bookdown.org)