Sensibilisation aux bonnes pratiques de self

Romain Avouac, Lino Galiana

Introduction

La notion de bonnes pratiques

Origine : communauté des développeurs logiciels

Constats :
- le “code est plus souvent lu qu’écrit” (Guido Van Rossum)
- la maintenance d’un code est très coûteuse

Conséquence : un ensemble de règles informelles, conventionnellement acceptées comme produisant des logiciels fiables, évolutifs et maintenables

Pourquoi s’intéresser aux bonnes pratiques ?

L’activité du statisticien / datascientist tend à se rapprocher de celle du développeur :

projets intenses en code

projets collaboratifs et de grande envergure

complexification des données et donc des infrastructures

déploiement d’applications pour valoriser les analyses

Bonnes pratiques et reproductibilité

Source : Peng R., Reproducible Research in Computational Science, Science (2011)

Une reproductibilité parfaite est coûteuse

Un arbitrage coûts/bénéfices à définir selon les projets

Note

Quel parcours de formation aux bonnes pratiques en R ?

Parcours “socle” (1 jour)

Partie 1 : contrôle de version avec Git
- 1️⃣ Le contrôle de version : pourquoi faire ?
- 2️⃣ Git en pratique
Partie 2 : bonnes pratiques avec R
- 1️⃣ Qualité du code
- 2️⃣ Structure des projets
- 3️⃣ Formats de données

Parcours “avancé” (2 jours)

Parcours socle
Partie 1 : contrôle de version avec Git
- 3️⃣ Travail collaboratif avec Git
Partie 2 : bonnes pratiques avec R
- 4️⃣ Environnements reproductibles
- 5️⃣ Pipelines de données
- 6️⃣ Introduction à la publication reproductible

Des checkpoints pour l’exemple fil rouge

Améliorations graduelles guidées sur un projet
Système de checkpoint (exemple application 1):

script.R

Effort de formation

Modalités : slides + exercices, tout en open-source
- Supports sur Github
- Slides
Stratégie : effet boule de neige
- Formation de formateurs
- Multiples réinstanciations locales (DG, SSM, DR..)

Partie 1 : contrôle de version avec `Git`

Le contrôle de version : pourquoi faire ?

1️⃣ Archiver son code proprement

pour en finir avec ça :

1️⃣ Archiver son code proprement

ou ça :

1️⃣ Archiver son code proprement

ou encore ça :

prior <- read_csv(prior_path)
prior <- prior %>%
    select(id, proba_inter, proba_build, proba_rfl) %>%
    separate(id, into = c('nidt', 'grid_id'), sep = ":") %>%
    group_by(nidt) %>%
    mutate(
        proba_build = proba_build/sum(proba_build),
        proba_rfl = proba_rfl/sum(proba_rfl),
        ) %>%
    unite(col = "id", nidt, grid_id, sep = ":")

# Test
# prior_test <- prior %>%
#    mutate(
#        proba_inter = round(proba_inter, 4)
#        proba_build = round(proba_build, 4)
#        proba_rfl = round(proba_rfl, 4)
#    )

write_csv(prior_round, "~/prior.csv")

1️⃣ Archiver son code proprement

Pour arriver à ça :

Source : ThinkR

Git : concepts et pratique

⚠️ Git est complexe

L’utilisation de Git nécessite certaines notions préalables:

Fonctionnement d’un filesystem
Connaissance basique du terminal Linux
Potentiellement, un grand nombre de commandes

⚠️ Git est complexe

Mais

L’usage quotidien n’implique que quelques commandes
Enormément de ressources disponibles sur internet
Des interfaces visuelles (ex: RStudio, Sublime Merge, VS Code) qui facilitent l’apprentissage
Un petit investissement individuel pour de gros gains collectifs

Des applications (très) guidées

Premiers commits

Créer un dossier 📁 scripts
Y créer les fichiers script1.R et script2.R, chacun contenant quelques commandes R de votre choix
Ajouter ces fichiers à la zone de staging de Git en les cochant dans l’interface RStudio
Effectuer un commit, auquel on donnera un message descriptif pertinent
Supprimer le fichier script1.R et modifier le contenu du fichier script2.R
Analyser ce qui se passe lorsque l’on coche ces fichiers dans l’interface RStudio
Effectuer un nouveau commit pour ajouter ces modifications à l’historique
Visualiser l’historique du projet à partir de l’interface graphique de RStudio

Bonnes pratiques

Format des commits

Fréquence
- Aussi souvent que possible
- Le lot de modifications doit “faire sens”
Messages
- Courts et informatifs (comme un titre de mail)
- Décrire le pourquoi plutôt que le comment dans le texte

Partie 2 : bonnes pratiques en `R`

Qualité du code et structure des projets

Enjeux

D’une vision utilitariste du code à une vision du code comme outil de communication

Favoriser la lisibilité et la maintenabilité

Faciliter la réutilisation

Principes généraux

Adopter les standards communautaires

Utiliser des fonctions

Documentation du code

1️⃣ Adopter les standards communautaires

Guide de référence pour bien coder en R : le Tidyverse style guide

Des outils facilitent l’adoption de ces standards
- lintr : programme qui vérifie que le code est formellement conforme à un certain style guide et émet des recommandations

2️⃣ Favoriser la modularité des projets

Favoriser l’utilisation de fonctions
- Limite les risques d’erreur liés aux copier/coller
- Rend le code plus lisible et plus compact
- Unicité de la source de vérité
Les packages
- Idéal pour favoriser la réutilisation du code
- Coût de maintenance élevé

3️⃣ Documentation du code

Grands principes :
- Documenter le pourquoi plutôt que le comment
- Privilégier l’auto-documentation via des nommages pertinents
Documenter le projet (contexte, objectifs, fonctionnement) dans un fichier README
- Quelques modèles : utilitR, DoReMIFaSol

Application

Application 1

Partie 2 : premiers standards de qualité

Installer les packages R lintr et styler.
Définir le linter à utiliser comme étant de type tidyverse : lintr::use_lintr(type = "tidyverse")
Diagnostiquer le script script.R : lintr::lint("script.R").
- Comprenez-vous la nature des problèmes détectés par le linter?
Appliquer le formatter au script.R : styler::style_file("script.R").
Refaire tourner le linter. Il reste encore un certain nombre d’erreurs de formattage, car styler est un formatter peu intrusif.
Regarder les différents problèmes repérés par le linter, et en corriger quelques uns (un pour chaque type de problème).

Checkpoint

script.R

Partie 3: formats de données

Enjeux

Le choix d’un format de données répond à un arbitrage entre plusieurs critères :
- Finalité (traitement, analyse, diffusion)
- Public cible
- Volumétrie

Recommandations

Eviter impérativement les formats de données adhérents à un langage (RDS, RData, fst, sas7bdat, etc.).

Deux formats à privilégier :
- CSV : pour la plupart des usages courants
  - Avantage : non-compressé donc facilement lisible
  - Inconvénients : pas de gestion des méta-données, peu adapté aux données volumineuses
- Parquet : pour le traitement de données volumineuses
  - Compressé et très performant en lecture/écriture
  - Gestion native des méta-données

Partie 4: environnements reproductibles

Expérience de pensée

Imaginons la situation suivante :
- J’installe une version de R sur mon poste
- Je développe un projet en installant les packages nécessaires
- Une fois terminé, je passe au projet suivant, et ainsi de suite.
Quels problèmes puis-je rencontrer au fil des projets ?
Est-il facile de partager un de mes projets ?

Enjeux

Version de R fixe, celle de l’installation système

Conflits de version : différents projets peuvent requérir différentes versions d’un même package.

Reproductibilité limitée : difficile de dire quel projet nécessite quel package.

Portabilité limitée : difficile de préciser dans un fichier les dépendances spécifiques à un projet.

Des environnements reproductibles avec `renv`

renv permet de créer des environnements reproductibles

Isolation : chaque projet dispose de sa propre librairie de packages

Reproductibilité : renv enregistre les versions exactes des packages nécessaires au projet

Portabilité: un tiers peut exécuter le projet avec les mêmes spécifications

Partie 5: Pipelines de données

Motivations

Une analyse de données ou une chaîne de production font intervenir des étapes standardisées
Ces étapes peuvent être formalisées sous forme d’un pipeline (direct acyclic graph)

Source

Motivations

Modéliser ces étapes sous forme de pipeline (direct acyclic graph) a plusieurs avantages :

Découplage des différentes étapes
Facilite la planification du traitement
Facilite la prise en main du projet par un tiers

Le package `targets`

targets est un framework de modélisation de pipelines spécifiquement dédié aux projets R.
Deux objectifs majeurs :
1. Réduire le coût d’expérimentation
2. Garantir la reproductibilité de la chaîne

Partie 6: Introduction à la publication reproductible

Enjeux

Produire des études reproductibles en intégrant le code et le texte dans un même document

La génération complète de l’étude est contenue dans un unique projet

Limiter les risques d’erreurs dues aux gestes manuels

Gestion native de différents formats pour le document final (pdf, html, odt, etc.)

`R Markdown`

R Markdown est un package R qui permet de lier
- Du texte au format Markdown
- Du code R qui peut être exécuté et dont les sorties peuvent être intégrées au texte

Dissociation du fond et de la forme du document

Un document est compilé en deux étapes
- knit : le package knitr transforme le texte et les sorties R en un document Markdown standard
- convert : le logiciel pandoc transforme le document .md en un format de sortie standard (html, pdf, etc.)

`Quarto`

Quarto est le successeur de R Markdown

Quarto supporte différents moteurs de calcul (knitr, Jupyter, Observable..) ce qui le rend nativement multi-langage (R, Python, JavaScript..)

Le fonctionnement des deux systèmes reste très proche

Anatomie d’un document reproductible

Conclusion

Les bonnes pratiques favorisent la reproductibilité et la réutilisation des projets statistiques

Des outils permettent d’appliquer les bonnes pratiques

Le coût est d’autant plus faible que l’on se place en amont du projet

Sensibilisation aux bonnes pratiques de self

Introduction

La notion de bonnes pratiques

Pourquoi s’intéresser aux bonnes pratiques ?

Bonnes pratiques et reproductibilité

Parcours “socle” (1 jour)

Parcours “avancé” (2 jours)

Des checkpoints pour l’exemple fil rouge

Effort de formation

Partie 1 : contrôle de version avec Git

Le contrôle de version : pourquoi faire ?

1️⃣ Archiver son code proprement

1️⃣ Archiver son code proprement

1️⃣ Archiver son code proprement

1️⃣ Archiver son code proprement

Git : concepts et pratique

⚠️ Git est complexe

⚠️ Git est complexe

Des applications (très) guidées

Bonnes pratiques

Partie 2 : bonnes pratiques en R

Qualité du code et structure des projets

Enjeux

Principes généraux

1️⃣ Adopter les standards communautaires

2️⃣ Favoriser la modularité des projets

3️⃣ Documentation du code

Application

Application 1

Checkpoint

Partie 3: formats de données

Enjeux

Recommandations

Partie 4: environnements reproductibles

Expérience de pensée

Enjeux

Des environnements reproductibles avec renv

Partie 5: Pipelines de données

Motivations

Motivations

Le package targets

Partie 6: Introduction à la publication reproductible

Enjeux

R Markdown

Quarto

Anatomie d’un document reproductible

Conclusion

Conclusion

Partie 1 : contrôle de version avec `Git`

Partie 2 : bonnes pratiques en `R`

Des environnements reproductibles avec `renv`

Le package `targets`

`R Markdown`

`Quarto`