Documenter ses données

Comment rendre sa recherche plus reproductible ?

Accueil Vos besoins Documenter ses données Comment rendre sa recherche plus reproductible ?
Sommaire

La question de la documentation des données devient un enjeu prégnant dans le cadre des plans de gestion de données et du débat sur la reproductibilité scientifique. Il y a donc un réel intérêt à y réfléchir en amont. Quels outils choisir ? Sans prétendre à l’exhaustivité, nous vous présentons plusieurs options possibles, tout en illustrant le poids croissant de cet enjeu avec l’exemple d’un cours donné à l’Université de Lyon 1.

S’appuyer sur les travaux existants est un pré-requis de toute recherche. Mais comprendre comment les données ont été obtenues afin de vérifier leur fiabilité s’avère difficile si les résultats présentés ne sont accompagnés d’aucun commentaire ou documentation. Cette réalité recouvre plusieurs enjeux :

  • Expliciter les variables utilisées
  • Lorsque les fichiers sont volumineux et complexes, prévoir une méthode pour standardiser et automatiser la création d’une documentation. 

Divers outils couvrant un grand nombre de langages et de logiciels différents existent pour vous aider dans cette tâche. Leur fonctionnement est généralement à peu près le même : il s’agit d’ajouter dans le script avec lequel vous produisez vos données des blocs de commentaires selon une structure prédéfinie par l’outil. Ce dernier va ensuite pouvoir générer automatiquement un document lors de l’exécution du fichier en “lisant” ces différents blocs de commentaires. 

Il faut donc bien distinguer ceux qui seront lus par la machine et qui serviront à l’outil pour générer la documentation, des commentaires ponctuels produits pour expliquer le code (1). Le contenu généré est ainsi accessible selon différents formats (le plus souvent en pdf ou html dans un navigateur web).

Markdown pour la reproductibilité des données

Créé en 2004, Markdown est un langage de balisage permettant de découper et structurer un document selon une syntaxe prédéfinie. Il est léger, car lisible avec un éditeur de texte simple et sa syntaxe est facilement compréhensible. Bien qu’il ait très peu évolué depuis sa création, il est tout de même très utilisé par exemple dans les fichiers “readme” sur GitHub, qui sont tous écrits en Markdown, ainsi que dans différents logiciels comme R avec la librairie R-Markdown. Ainsi, R Markdown permet de créer des documents riches intégrant code, texte, tableaux de données et graphiques. Les formats de ces documents peuvent être standard (PDF, html…) mais R Markdown permet aussi l’export dans d’autres formats très utilisés comme Word, LibreOffice, ou PowerPoint.

Pour une ergonomie et une saisie optimales, il est recommandé d’utiliser l’environnement de développement gratuit et open source RStudio, qui intègre R Markdown. L’intérêt est d’avoir directement depuis le logiciel la fenêtre de script, permettant d’écrire et de structurer le code ainsi que la fenêtre d’aperçu du document final R Markdown. Cela permet de modifier le document de manière dynamique et d’y apporter des corrections très facilement. Voici un exemple tiré du site de R Markdown. Dans cette illustration, on retrouve dans la fenêtre de gauche le script où l’on écrit le contenu du document (champs remplis sur fond blanc) et les commandes R (fond gris). A droite, le document généré après l’exécution du script. De plus, la librairie R Markdown supporte d’autres langages comme Python et SQL.

Des cours sur la reproductibilité pour des étudiants de Master à Lyon 1

Depuis 2019, les étudiants en Master NanoScale Engineering de l’Université de Lyon 1 apprennent à coder afin d’améliorer la reproductibilité de leurs travaux. Un enseignement mis en place à l’initiative de Colin Bousige, chargé de recherche CNRS en physique affilié au laboratoire des multimatériaux et interfaces (LMI). Ce cours vise à enseigner aux étudiants de Master 1 les bases de R pour le traitement de données expérimentales reproductibles et l’emploi de notebooks R Markdown.
Le cours, qui permet de comprendre les bases de R Markdown, donne les premiers éléments de syntaxe, tout en permettant d’aller plus loin grâce aux multiples références qui y sont présentes. Le site est d’ailleurs lui-même  écrit en R Markdown et le code est téléchargeable dans la bannière du haut. Vous pouvez également y retrouver une liste des différents langages supportés par R Markdown.
Autre initiative, un cours en ligne disponible sur FunMooc, à l’initiative de trois chercheurs : Arnaud Legrand, Christophe Pouzat et Konrad Hinsen. Intitulé « Recherche reproductible : principes méthodologiques pour une science transparente » , il aborde notamment les outils Markdown, Jupyter, Rstudio et Org-mode.

Jupyter notebook

Créé en 2015, Jupyter Notebook (2) est une application web permettant de créer des notebooks (carnets) contenant à la fois du code et du texte en Markdown. Il est bien sûr possible d’y joindre graphiques, tableaux, formules mathématiques et widgets permettant d’interagir avec le document. Les langages principaux soutenus par Jupyter sont Python, R et Julia. D’autres langages sont disponibles grâce à la communauté, mais sont en revanche moins bien intégrés. Pour installer Jupyter Notebook, deux solutions s’offrent à vous :

  • L’option la plus facile consiste à installer la suite Anaconda téléchargeable depuis leur site. Cela permet de disposer directement de Jupyter et Python, mais aussi d’autres outils comme RStudio ou Spyder (environnement de développement Python). 
  • Si vous disposez déjà de Python, la méthode consiste à installer Jupyter Notebook via la commande pip. Vous trouverez plus d’informations sur cette page.
  • Si vous avez du mal à vous familiariser avec l’interface de base de Jupyter Notebook, vous pouvez utiliser l’outil nteract.io qui permet de réaliser des notebooks Jupyter plus facilement avec une extension. Il suffit de l’installer sur votre ordinateur.

Comme pour R Markdown, vous pourrez exporter votre notebook sous différents formats (html, PDF, LaTeX, des slides, etc). 

Si vous souhaitez voir à quoi l’interface ressemble avant de vous lancer dans l’installation, une version de démo existe sur le site de Jupyter pour les principaux langages : Python, R, Julia, C++ et Ruby. Vous trouverez la démo ici. L’interface ressemble à un éditeur de texte des plus basiques. Vous pouvez ajouter des blocs (cellules) à la suite et choisir le type de contenu qu’elles afficheront : un titre, du texte, du code, ou du Markdown pour le contenu riche. Il vous suffit ensuite d’exécuter vos blocs pour afficher le résultat final.

Le projet Jupyter est de plus développé de manière ouverte sur GitHub et soutenu par le programme européen Horizon 2020. Le rapport annuel sur les infrastructures numériques de l’enseignement supérieur et de la recherche en fait également mention en alertant sur la nécessité, pour les étudiants, de disposer de “Jupyter notebooks hébergés dans des clouds académiques français”, dans un souci de respect de la “souveraineté” des données.

Org-mode pour une bonne documentation des données

Dans l’objectif de créer une documentation structurée pour vos données, certains outils permettent d’augmenter une page de texte en y intégrant du code et des tableaux. Le département d’ingénierie chimique de Carnegie aux Etats-Unis a justement adopté cette démarche. Celle-ci repose sur l’association entre Emacs, un éditeur de texte et Org-mode, une syntaxe avancée d’édition de document. Cette combinaison permet de réaliser des documents finaux structurés et accessibles sous différents formats (PDF, html ou encore LaTeX) et leur permet notamment de réaliser la documentation de leurs données. Cette dernière a le même rôle qu’un fichier readme (“lisez-moi”), qui accompagne souvent les jeux de données. En revanche, les fichiers readme sont la plupart du temps de simples fichiers texte plus ou moins faciles à lire. Pratiques car rapides à créer, ils font au minimum la description de l’origine des données, l’objectif recherché et le mode d’obtention (3). D’où l’utilisation d’une méthode rendant la lecture plus agréable pour des personnes extérieures à l’équipe.

R, Pydoc et Sphinx pour les librairies

Lorsqu’on manipule des données informatiquement de manière quotidienne, on peut être amené à créer des librairies, ou packages en anglais, dans le but d’automatiser et faciliter l’accès à certains processus. Les librairies sont ainsi un ensemble de fonctions (liées entre-elles ou non) qui permettent d’améliorer le langage de base. Elles sont propres à chaque langage, par exemple R et Python ont leurs propres librairies, qui peuvent tout à fait réaliser la même chose, mais leur syntaxe est différente. Un grand nombre de librairies sont disponibles sur le web pour chaque langage (sur le CRAN pour R par exemple). Lorsqu’on crée une librairie, quel que soit le langage et l’objectif de celle-ci, l’une des étapes indispensables est sa documentation. Tout d’abord car cela permet de réviser sa librairie et de voir si des erreurs ont pu être commises durant sa conception, mais aussi pour permettre à tous de comprendre de quoi elle retourne, si elle est amenée à être distribuée – ce qui arrive dans la majorité des cas, que cela soit distribué publiquement sur le web ou à l’échelle d’une équipe.

Pour comprendre un peu mieux ce fonctionnement, nous allons voir un exemple avec la librairie roxygen2 pour R. Elle peut être importée directement depuis votre script R grâce à la commande install.packages (« roxygen2 »).

Les commentaires en R sont précédés d’un simple dièse, comme ceci :

# Commentaire ponctuel

Les commentaires roxygen2 sont précédés d’un dièse et d’un guillemet simple, comme ceci :

#’ Ceci est un commentaire roxygen2

C’est ce qui permet à la machine de les interpréter.

Prenons l’exemple disponible sur le site de la librairie :

Les lignes en gris correspondent aux commentaires roxygen2. Celles en bleu correspondent aux commandes R basiques, en l’occurrence, à la déclaration d’une fonction. Dans cette exemple, la première ligne sera la description de la fonction, les lignes @param seront les paramètres de la fonction, la ligne @return sera le résultat retourné, et la ligne @examples correspond à des exemples d’utilisation de la fonction. Lorsque le script sera exécuté, roxygen2 va convertir tous les commentaires qu’il reconnaît en format Rd, puis R va s’occuper de convertir celui-ci dans un format lisible par l’homme.

Pour les utilisateurs de Python, vous pouvez regarder les modules de documentation Sphinx et Pydoc.

Ce dernier est simple à installer : il suffit d’importer le module directement depuis votre script Python avec la commande import Pydoc.

Quant à Sphinx, il doit avoir été installé et ajouté à Python avant de pouvoir l’utiliser. Vous pouvez consulter cette page qui vous indiquera la marche à suivre selon votre système d’exploitation. Pour comprendre comment Sphinx fonctionne, vous pouvez feuilleter la documentation disponible sur le web, qui a justement été générée grâce Sphinx. La syntaxe utilisée pour obtenir cette doc est disponible ici.

Un article publié en mai 2018 dans Metabolomics (4) fait mention de l’utilisation de Sphinx pour générer la documentation issue de la librairie Python qu’ils ont conçue. L’objectif de cette librairie est d’améliorer le dépôt dans l’entrepôt de données Metabolomics Workbench accueillant des données de spectrométrie de masse et de résonance magnétique nucléaire au format mwTab afin que les données puissent être interopérables et facilement réutilisables.

  1. DESQUILBET, Loic, GRANGER Sabrina, HEJBLUM Boris, LEGRAND Arnaud, PERNOT Pascal et al. Vers une recherche reproductible : Faire évoluer ses pratiques. Unité régionale de formation à l’information scientifique et technique de Bordeaux, 2019, p. 112.
  2. What Is the Jupyter Notebook? — Jupyter Notebook 6.0.3 Documentation. Consultable sur : https://jupyter-notebook.readthedocs.io/en/stable/examples/Notebook/What%20is%20the%20Jupyter%20Notebook.html.
  3. ZANETTA, Pierre-marie. Data for: Modal Abundance, Density and Chemistry of Micrometer-Sized Assemblages by Advanced Electron Microscopy: Application to Chondrites. Vol. 1, Apr. 2019, doi:10.17632/kdr8wk63h6.1
  4. SMELTER, Andrey. MOSELEY, Hunter N. B.. A Python library for FAIRer access and deposition to the Metabolomics Workbench Data Repository. Vol. 15, May 2018, doi:10.1007/s11306-018-1356-6