DellaData

Transformez vos données en connaissances

Les scripts RMarkdown paramétrés : Interface et automatisation

Réaliser des analyses de données reproductibles et flexibles est devenu incontournable. Dans cette démarche, RMarkdown est un outil indispensable pour documenter, présenter et partager nos analyses réalisées avec R.

Mais parfois ce que l’on souhaite, c’est rendre un rapport RMarkdown adaptable à différentes situations, afin répéter la création de rapports sous différents scénarios.

Et dans cette situation, les scripts RMarkdown paramétrés peuvent réellement répondre à cette problématique et vous faire gagner un temps considérable !

Qu’est-ce qu’un script RMarkdown paramétrés ?

Un script RMarkdown paramétré est un fichier RMarkdown qui accepte un ou plusieurs paramètres lors de son exécution. Ces paramètres peuvent être utilisés pour contrôler divers aspects du rapport, tels que la source des données, les variables à analyser, les graphiques à générer, les titres des différents paragraphes etc. Cela rend le rapport adaptable à différents scénarios sans avoir à modifier manuellement le code à chaque fois.

De plus, avec les scripts paramétrés, il est relativement facile de construire une petite interface graphique pour sélectionner manuellement les valeurs des paramètres à employer, ou de créer une fonction d’automatisation de la génération de documents rendus.

L’interface graphique est particulièrement confortable pour permettre à des personnes moins à l’aise avec R, de créer facilement toute une série de rapports.

Création d’un script Rmarkdown paramétré

Nous allons employer le jeu de données iris, et imaginer que l’on souhaite réaliser la même analyse pour les 3 espèces présentes dans les données (setosa, versicolor, virginica).

Pour cela, nous créons un fichier .Rmd, dans lequel nous allons insérer, au niveau de l’entête une section params, comme ceci :

output: 
  html_document:
params: 
  species:
    label: "Choisissez une espèce"
    value : "versicolor"
    input : select
    choices : [setosa, versicolor, virginica]

L’argument label permet d’écrire du texte dans l’interface.
L’argument value permet de fixer l’espèce qui sera affichée par défaut.
L’argument input correspond au type d’outil de sélection intégré à l’interface.
L’argument choices permet d’indiquer les possibilités à intégrer à l’interface.

Il est possible d’utiliser d’autres types d’input :

D’après https://bookdown.org/yihui/rmarkdown/params-knit.html

Nous continuons le script avec un code pour réaliser un graphique tout simple

# permet de récupérer l'espèce qui sera choisie
select_species <- params$species


library(tidyverse)
# permet de garder les lignes correspondantes à l'espèce choisie
mydata <- iris %>% 
  filter(Species==select_species) 

# résumé des données
summary(mydata )

# réalisation d'un graphique
mydata %>% 
  ggplot(aes(x=Petal.Length, y=Sepal.Length))+
  geom_point()+
  geom_smooth(method="lm")

Dans le titre du script Rmarkdown, nous pouvons insérer `r params$species`, afin que le titre du document rendu s’adapte automatiquement à l’espèce qui sera choisie.

Au final, voici l’ensemble de mon script .Rmd.

---
title: "Analyse des données de l'espèce `r params$species`"
author: "Claire Della-Vedova <"
date: "`r Sys.Date()`"
output:
  html_document:
params:
  species:
    label: "Choisissez une espèce"
    value : "versicolor"
    input : select
    choices : [setosa, versicolor, virginica]
---

```{r }

# permet de récupérer l'espèce qui sera choisie
select_species <- params$species


library(tidyverse)
# permet de garder les lignes correspondantes à l'espèce choisie
mydata <- iris %>%
  filter(Species==select_species)

# résumé des données
summary(mydata )

# réalisation d'un graphique
mydata %>%
  ggplot(aes(x=Petal.Length, y=Sepal.Length))+
  geom_point()+
  geom_smooth(method="lm")
```

Si vous voulez essayer, il vous suffit d’ouvrir un nouveau document Rmarkdown, et de replacer le code par celui-ci

Accéder à l'interface

Rien de plus simple ! Dépliez le menu Knit et choisissez Knit With Parameters

Vous allez alors obtenir l’interface suivante :

Sélectionnez une espèce et cliquez sur le bouton Knit en bas de la page pour générer le document rendu (uniquement html) ci-dessous :

Il ne vous reste plus qu’à renommer le fichier rendu obtenu, et recommencer avec une autre espèce !

Automatiser la réalisation des rapports

Si vous le souhaitez, vous pouvez automatiser la génération des rapports pour les différentes espèces, en vous appuyant sur la fonction render() du package rmarkdown. Cette fonction render() est celle qui est employée lorsqu’on utilise le bouton Knit, pour générer le document rendu.

Dans l’exemple ci-dessous, j’ai créé ma propre fonction render(). Celle-ci prend en argument le nom d’une espèce, puis va chercher le script rmd (ici, il se nomme exemple_rmd-parametres.rmd), fixe la valeur du paramètre species avec celle passée en argument, exécute le script et cré le document rendu en lui donnant un nom qui combine l’espèce entrée en argument, et la date du jour !

# fonction de render en fonction de l'espece spécfiée
render_species <- function(species){
  rmarkdown::render(
  input="exemple_rmd-parametres.rmd",
  output_file = paste0("report_",
    species,
    "_",
    Sys.Date(),
    ".html"),
  params=list(species=species)
  )
}

# exemple d'utilisation 
render_species("Adelie")

NB : la fonction et son appel doivent être exécutés dans la console.

À l’aide d’une boucle ou d’une fonction lapply(), vous pouvez alors appliquer automatiquement la fonction sur toutes les espèces et ainsi générer automatiquement tous les rapports !

library(forcats)
species_list <- fct_unique(iris$Species)

# application de la fonction à toutes les espèces
lapply(species_list, render_species)

Enjoy 🤩🚀

Pour aller plus loin sur les scripts paramétrés

Il est bien évidemment possible d’intégrer plusieurs paramètres dans vos script.Rmd et donc dans vos interfaces, et dans vos fonctions pour automatiser la génération des documents rendus. Vous trouverez plus d’informations ici.

• https://bookdown.org/yihui/rmarkdown/parameterized-reports.html

• https://docs.posit.co/connect/user/param-rmarkdown/

• https://bookdown.org/yihui/rmarkdown-cookbook/parameterized-reports.html

Alors, que pensez-vous de ces scripts paramétrés ?

🙏 Dites-moi le en commentaire 👇👇👇

3 Responses

LAURENT PIERRE APICELLA dit :
3 novembre 2023 à 11 h 15 min
Merci pour vos cours !
Répondre
Sandrine CHARLES dit :
6 novembre 2023 à 16 h 25 min
Je connaissais pas, merci c’est chouette cette fonctionnalité.
Répondre
Céline dit :
18 novembre 2023 à 10 h 01 min
Je ne connaissais pas non plus mais c’est super utile !
Un grand merci !
Répondre