Partager votre travail sur R en suivant les bonnes pratiques depuis un simple notebook

· 1271 mots. · 6 minutes de lecture.
r-scripts · packages
rstatsfr · fusen · développement

Vous écrivez des scripts R et vous souhaitez les partager avec d’autres utilisateurs, de manière durable et maintenable. Vous écrivez déjà votre code dans un notebook (Rmarkdown ou Quarto) et partagez sa sortie en HTML. Vous souhaitez documenter les chunks, et rendre cette documentation visible dans une page HTML séparée. L’écriture d’un package R semble être une tâche trop lourde et vous souhaitez expérimenter les bonnes pratiques pour une alternative. Laissez-moi vous montrer comment {fusen} peut vous aider à présenter et à partager votre travail avec R en suivant des bonnes pratiques de développement comme doc et test, tout en partant d’un endroit unique que vous connaissez déjà : le notebook Rmarkdown (ou Quarto).

Un projet R entièrement documenté et testé, d’un notebook à un site web en cinq étapes

Dans la prochaine section, vous verrez les cinq étapes pour préparer votre projet et écrire votre notebook en suivant le modèle suivant…

…de façon à créer ce site web

Créer vos scripts avec {fusen} et les partager sur un site GitHub

Vous devez installer {fusen} depuis r-universe
Vous pouvez également l’installer depuis le CRAN, mais l’une des fonctionnalités ci-dessous n’est pas encore incluse dans le CRAN.

install.packages("fusen", repos = 'https://thinkr-open.r-universe.dev')

1. Créer un nouveau projet localement

  • Créer un nouveau projet avec {fusen} avec git

    • Utilisez template = "full" si vous voulez des explications sur la façon de remplir les sections, ou explorez la documentation de {fusen} par ici : https://thinkr-open.github.io/fusen. Le template = "minimal" fera l’affaire sinon.
    path_project <- "your/path/where/to/start/your/project/project_name"
fusen::create_fusen(path = path_project, template = "minimal", with_git = TRUE, open = TRUE)

2. Décrivez votre projet

  • Suivez le fichier “dev/0-dev_history.Rmd” pour décrire votre projet.

    • Au minimum, vous devrez remplir la fonction fusen::fill_description() avec votre identité, comme ci-dessous
    # Describe your project
fusen::fill_description(
  pkg = here::here(),
  fields = list(
    Title = "Share Your Project Following Good Development Practices From a Rmarkdown File",
    Description = "Use Rmarkdown First method. Strengthen your work with documentation and tests. Everything can be set from a Rmarkdown file in your project.",
    `Authors@R` = c(
      person("John", "Doe", email = "john@email.me", role = c("aut", "cre"), comment = c(ORCID = "0000-0000-0000-0000"))
    )
  )
)
# Define License with use_*_license()
usethis::use_mit_license("John Doe")

3. Rédigez votre notebook en suivant le squelette

La première fois, vous pouvez laisser le contenu tel quel.

  • Ouvrez le fichier “dev/flat_full.Rmd”.

    • C’est le squelette à suivre si vous voulez un travail correctement documenté et testé.
      • Écrivez ce que le code est censé faire en markdown.
      • Séparez les chunks de function de ceux des example et de test.
      • Créez les nouvelles sections ci-dessous dans votre modèle plat à l’aide de l’Addin > “add {fusen} chunk”

4. Gonfler le notebook avec {fusen}

  • Gonfler le template plat avec inflate() pour construire la structure correcte du projet

    • Les sections seront transférées aux bons endroits afin d’obtenir un projet correct.
    • Un ensemble de contrôles sera effectué pour vérifier que votre travail est correctement documenté et testé.
    fusen::inflate(flat_file = "dev/flat_full.Rmd", vignette_name = "Get started")

5. Partagez votre travail sur un site GitHub

Ceci n’est disponible que sur la version de développement de {fusen} pour le moment.

  • Vous devrez peut-être exécuter usethis::create_github_token(), puis gitcreds::gitcreds_set() avant, si vous n’avez pas encore de token GitHub enregistré.

  • Exécutez fusen::init_share_on_github() pour créer tout ce qui est nécessaire à la mise en place de votre site sur GitHub. Il vous sera demandé plusieurs fois si vous voulez “commit”, vous pouvez dire “oui” à chaque fois.

    fusen::init_share_on_github()

Lisez attentivement les instructions dans la console pour pouvoir configurer correctement votre site Web GitHub.

Voilà, c’est fait.
Vous avez créé un projet R correctement documenté et testé et l’avez partagé sur un site web accessible à tous.
Chaque changement poussé vers la branche “main” mettra à jour le site web.

Vous pouvez voir le site web cible du projet que j’ai créé pour cet article de blog : https://statnmap.github.io/fusen.github.0.4.1.9000/ et le dépôt des sources : https://github.com/statnmap/fusen.github.0.4.1.9000/

Acceuil
Référentiel de fonctions
Articles vignettes
NEWS, changement de version

Comment poursuivre le développement avec le modèle plat ?

Écrivez en texte clair ce que le code est censé faire avant d’écrire le moindre code R.

Ensuite, vous devrez factoriser votre code pour le rendre compatible avec le format de fonctions R.
Cela permet de documenter et de tester votre code, de le rendre utilisable par d’autres, et robuste aux changements futurs.

  • Commencez par capturer l’ensemble du code dans les accolades de myfun <- function() {}.
  • Utilisez ensuite la fonction dans le chunk example pour créer un exemple reproductible.
  • Lorsque l’exemple fonctionne, vous pouvez l’utiliser pour un test unitaire dans le chunk test.

Si vous n’avez jamais factorisé ou créé de fonctions auparavant, je vous suggère de suivre cette présentation : Construire des analyses de données reproductibles et partageables à l’aide de packages R

Utilisez le RStudio Addin “add {fusen} chunks” pour ajouter un nouvel ensemble de chunks dans votre fichier plat et continuer avec de nouvelles fonctions.

N’oubliez pas de suivre le même squelette que celui proposé dans le modèle plat pour écrire les fonctions :

  • Le Chunk nommé function récupère le code et la documentation d’une fonction.
  • Le Chunk nommé example récupère le code des exemples d’utilisation de la fonction. Il sera utilisé pour la partie @examples de votre fonction et sera conservé pour la vignette.
  • Le Chunk nommé tests contient le code pour les tests unitaires.
  • Le Chunk nommé development contient le code pour le développement, généralement utilisé une seule fois comme les fonctions {usethis}.

Lisez les différents articles du site pkgdown de {fusen} pour vous guider dans les étapes d’après : https://thinkr-open.github.io/fusen/dev/index.html

Oui, je dois admettre que vous avez créé un package R. Et son site web de type {pkgdown}.
Maintenant, la partie la plus difficile pour vous est de trouver un logo hexagonal approprié. {fusen} ne peut pas vous aider, mais {hexmake} le peut : https://connect.thinkr.fr/hexmake/

Comment partager mon analyse si le fichier plat présente la documentation de mes fonctions et non pas mon analyse en tant que telle ?

En effet, le fichier plat n’est pas exactement le notebook que vous souhaitez partager. CE que vous souhaitez c’est un rapport présentant vos données. Le fichier plat, ainsi que le site web, c’est plutôt la documentation sur la façon d’utiliser les fonctions que vous avez créées pour analyser vos données et les résultats de l’analyse.
Cela rend l’ensemble du travail reproductible pour d’autres analyses similaires. Et c’est tout l’intérêt ! Le partage de votre travail.

Dans la présentation Construire des analyses de données reproductibles et partageables à l’aide de packages R, il y a un chapitre spécifique sur Qu’en est-il des analyses de données dans un package ?.
Vous verrez que je propose deux manières possibles de construire vos rapports d’analyse :

  • Package classique : Utiliser des projets externes pour utiliser les fonctions de votre paquet dans les rapports Rmd/Quarto. C’est probablement ce que vous faites déjà maintenant. Cependant, avec {fusen}, vous pouvez écrire vos fonctions R à l’intérieur de votre package réalisé avec {fusen}, afin qu’elles soient documentées, testées et partagées en tant que site web pour vos travaux futurs et pour la communauté.
  • Compendium-like : Inclure les rapports Rmd/Quarto dans le projet de développement du paquet, dans un dossier spécifique.

Dans les deux cas, vous pouvez considérer que votre template plat suit les mêmes étapes que votre rapport (par exemple, la préparation des données, l’exploration, la sortie du modèle…). Ainsi, la vignette de votre paquet, résultant du gonflement de votre template “flat”, est votre squelette pour présenter votre analyse. Cela signifie également que pour une nouvelle analyse, vous pouvez copier la vignette source comme point de départ.

Note: J’ai suivi le switch vers Mastodon, vous pouvez me suivre sur @statnmap@mastodon.social


Citation :

Merci de citer ce travail avec :
Rochette Sébastien. (2022, oct.. 28). "Partager votre travail sur R en suivant les bonnes pratiques depuis un simple notebook". Retrieved from https://statnmap.com/fr/2022-10-28-share-your-r-work-following-good-dev-practices-from-a-single-notebook/.


Citation BibTex : 
@misc{Roche2022Parta,
    author = {Rochette Sébastien},
    title = {Partager votre travail sur R en suivant les bonnes pratiques depuis un simple notebook},
    url = {https://statnmap.com/fr/2022-10-28-share-your-r-work-following-good-dev-practices-from-a-single-notebook/},
    year = {2022}
  }

Articles similaires