Astuce :
S'outiller et s'organiser pour mieux travailler

TL;DR La reproductibilité, c’est la vie (dans le monde scientifique) ! Tout résultat doit pouvoir être reproduit. La technologie permet de faciliter la recherche de reproductibilité. Les cahiers de laboratoire papiers ne sont plus du tout adaptés à la recherche actuelle et au besoin de reproductibilité. Je préconise donc d’utiliser git et GitHub, de bien organiser ses projets et d’utiliser des cahiers de laboratoire électroniques.

Un des principes essentiels de la méthode scientifique est la reproductibilité, i.e. la capacité pour tous de reproduire toute expérience ou étude tout en obtenant des résultats similaires. C’est la pierre angulaire de la Recherche (Sandve, 2013) et ce qui distingue le caractère scientifique d’une étude. La reproductibilité n’est pas seulement une responsabilité morale vis-à-vis de la recherche. Le manque de reproductibilité peut aussi être un fardeau pour les scientifiques eux-même en limitant, par exemple, leur capacité à réutiliser leur code ou à réanalyser un jeu de données. De plus, la mise en place de bonnes pratiques de reproductibilité améliore la qualité des collaborations, en garantissant la capacité de reproduction et de transparence des analyses. Ces pratiques permettent un gain de temps à long terme et sont un gage d’une recherche de qualité.

La reproductibilité, c’est la vie (dans le monde scientifique)

http://blog.f1000research.com/2014/04/04/reproducibility-tweetchat-recap/

 

La reproductiblité se base principalement sur la transparence et une organisation claire des projets. N’importe qui (un relecteur, un collaborateur ou soi-même après quelques mois) ayant un projet en main doit pouvoir comprendre ce qui sa été fait (et pourquoi) et pouvoir reproduire les résultats obtenus. Pour cela, toute étude scientifique doit être bien organisée et documentée et suivre 10 règles (Sandve, 2013) essentielles :

  1. Le processus de production de chaque résultat est totalement retracable
  2. Toute étape de manipulation manuelle des données est évitée
  3. Les versions exactes des programmes externes utilisés sont archivées
  4. Tous les scripts développés et utilisés sont versionnés
  5. Tous les résultats intermédiaires sont conservés, si possible dans un format standardisé
  6. Les graines de l’aléatoire (random seeds) pour des études incluant une part d’aléatoire sont notées
  7. Les données brutes utilisés pour les graphiques sont conservées
  8. Les sorties des analyses sont organisées hiérarchiquement
  9. Les résultats sont commentés par écrit
  10. Les scripts et résultats sont publiquement accessibles

 

Mettre en place ces règles n’est pas toujours évident et on ne nous a généralement pas appris à le faire. Pendant nos études, la plupart de nos cours de bioinformatique se focalisaient sur la programmation et l’utilisation d’outils existants. Rien ne nous a donc préparé à gérer plusieurs projets scientifiques collaboratifs qui soient reproductibles. Nous apprenons sur le tas ces pratiques, au grès des rencontres et des interactions avec nos collègues. De plus, nous avons souvent pas conscience de l’importance de la reproductibilité et de la transparence dans la méthode scientifique.

Depuis un peu plus de 5 ans, je travaille sur différents projets bioinformatiques au quotidien. J’ai eu la chance de pouvoir travailler dans plusieurs laboratoires avec des scientifiques très différents. J’ai pu ainsi apprendre et essayer différentes techniques et pratiques. Mais ce n’est que récemment que j’ai commencé à me poser des questions sur notre façon de faire de la recherche. J’ai alors essayé de comprendre quelles pouvaient être les bonnes pratiques, leurs avantages et leur mise en oeuvre. 3 grandes pratiques, que je vais détailler dans cet article, me paraissent essentielles pour gérer un projet bioinformatique et prendre soin du principe de reproductibilité.

Bien organiser ses projets

Tout le contenu d’un projet (à l’exception pour du code source ou des scripts partagés entre plusieurs projets) doit être conservé dans un dossier (un dossier par projet). Je parle ici du contenu sous forme informatique, la forme privilégiée (la plus facile à tracer et partager de nos jours). Ce dossier doit être bien structuré. En effet, la bonne structure d’un dossier peut faire la différence dans la réussite d’un projet (accès facile et rapide aux bonnes données, à la bonne version du workflow, …). William Stafford Noble (2009) propose une réflexion sur la structure idéale des dossiers que Samuel Lampa a étoffée (2015). Quelques idées intéressantes ressortent de ces réflexions :

  • Une structure unifiée avec d’abord un niveau logique, puis un sous-niveau chronologique, puis encore un sous-niveau logique
  • Un dossier pour chaque nouvelle expérience ou analyse incluant
    • Un script permettant de reproduire exactement l’analyse
    • Tous les changements (code, workflow, configuration, …) par rapport aux autres expériences ou analyses

 

Pour illustrer ces idées, Samuel Lampa (2015) propose d’organiser les dossiers des projets suivant la hiérarchie :

Cette structure est bien adaptée à un projet en production, où des expériences sont lancées avec pour seules différences des changements mineurs (configuration, paramètres, …). Pour des analyses exploratrices, j’utilise plutôt la hiérarchie :

J’utilise le gestionnaire de paquets conda pour gérer toutes les dépendances et les versions des outils nécessaires pour le projet. conda est un gestionnaire de paquet indépendant de tout langage de programmation et de tout système, permettant une installation facile et robuste. Ainsi, grâce aux efforts de la communauté Bioconda, plus de 1 500 outils bioinformatiques (dans n'importe quel langage) peuvent être facilement installés via un package conda. conda propose aussi des environnements, dont je me sers pour archiver les versions exactes des programmes utilisés (3e règle de la reproductibilité). Ces environnements peuvent être exportés (fichier yaml) et partagés/versionnés pour permettre l’import des mêmes outils avec les mêmes versions et reproduire les analyses.

Tous les exécutables (hors dépendances, c’est-à-dire principalement des scripts bash) sont conservés dans le dossier bin. Mes scripts Python, pour manipuler les données par exemple, (correctement documentés et vérifiés par flake8) se trouvent dans le dossier src. Avec ces scripts, je garde une trace de toute manipulation des données et des processus de production des résultats (1e et 2nde règles de la reproductibilité)

Un fichier README est aussi ajouté à la racine. Ce fichier contient une courte description du projet, des instructions pour reproduire le projet, … D’autre part, j’ajoute aussi systématiquement un fichier CITATION qui explique comment citer le projet et un fichier LICENSE, important pour décrire les droits d’utilisation et de modification du code (sans licence explicite, tous les droits sont réservés et le projet ne peut pas être utilisé librement).

Avec cette hiérarchie claire et similaire pour tous les projets, il est facile pour n’importe qui de naviguer dans le projet, de comprendre ce qui est fait et de reproduire les analyses et résultats, sans y consacrer plus de temps que nécessaire.

Utiliser un logiciel de gestion de versions (ils sont là pour nous aider)

La 4e règle de la reproductibilité concerne le versionnage des scripts développés et utilisés pour le projet. Je pense que plus que les scripts, tout fichier important pour le projet doit être versionné.

Un logiciel de gestion de versions est un système qui permet de garder une trace des changements de fichiers dans le temps. Ce type de logiciel facilite le travail quotidien et les collaborations :

  • Rien de ce qui est soumis au logiciel n’est perdu (ou il faut vraiment le vouloir), et comme toutes les versions sont sauvées, il est toujours possible de revenir en arrière
  • Avec la trace des auteurs et des dates des changements, il est facile de savoir à qui demander si un changement n’est pas clair
  • Le logiciel permet aussi de gérer les conflits lorsque plusieurs personnes ont modifié des parties identiques d’un fichier

 

Les logiciels de gestion de versions sont comme les cahiers de laboratoire du monde numérique. Tout travail scientifique, qui par nature évolue dans le temps et a besoin d’être partagé, doit être stocké avec un logiciel de gestion de versions. Et c’est particulièrement vrai pour tous les projets bioinformatiques !!!

Plusieurs logiciels de gestion de versions existent (Subversion, Mercurial, …). Depuis quelques années,git est le plus populaire, aussi dans le monde scientifique et la recherche. git est un outil indispensable, qu’il est important de savoir utiliser. De nombreux tutoriels sont disponibles, comme ceux de ce blog (premiers pas), ou les cours de Software Carpentry.

Bien que l’idée de base derrière un logiciel de gestion de versions soit simple, son utilisation requiert un peu de discipline. Il existe évidemment une version en ligne de commande, mais aussi des interfaces graphiques, et git s’intègre aussi très bien à divers IDE (Eclipse, Netbeans, IntelliJ IDEA) et traitement de texte (Sublime Text, Atom et même Gedit ! Amazing, isn’t it? )

Quelques conseils pour bien débuter

Plus un logiciel de gestion de versions est utilisé régulièrement, plus ses avantages se font sentir. L’historique des changements enregistré est alors le plus complet possible et permet de revenir facilement en arrière en limitant au maximum les effets de bord. Ainsi, une bonne règle est d’ajouter les changements au moins une fois par jour et de faire des changements assez petits. Un petit conseil : l’option -p de la commande git add permet de choisir les portions de code à ajouter pour un commit, plutôt que de soumettre tous les changements d’un même fichiers d’un seul coup. Et pour les phases de changements majeurs, l’idéal est d’utiliser des branches (historique parallèle).

Un logiciel de gestion de versions ne devrait être utilisé que pour les fichiers édités à la main. Les fichiers générés automatiquement (programmes compilés, résultats, …) ne doivent pas être versionnés car souvent ces fichiers sont lourds et/ou binaires et ne sont donc pas correctement pris en charge par le logiciel de gestion de versions. De plus, ces fichiers sont facilement reproductibles grâce au versionnage des scripts utilisés pour les générer. Cependant, pour des raisons de reproductibilité et transparence, les résultats (intermédiaires et finaux) doivent être sauvegardés pour être ensuite rendus publics (5e et 10e règles de la reproductibilité). Et, récemment, Nature a publié un article encourageant les auteurs à rendre public leurs jeux de données et à les associer à des digital object identifiers (DOIs). Des solutions comme Zenodo ou figshare permettent de stocker les résultats en leur associant un DOI, fixant ainsi une date et une version pour les résultats et permettant aussi la citation.

Un dernier petit conseil concernant git. Comme tous les fichiers du projet ne sont pas versionnés (les résultats, par exemple), le logiciel de gestion de versions va se “plaindre”, cachant potentiellement de vraies erreurs. Il est possible d’ajouter un fichier .gitignore à la racine du dossier pour que git ignore certains fichiers ou dossiers, comme les fichiers de configuration qui contiennent les mots de passe root de votre base de données 😉

Héberger son projet

Une fois le logiciel de gestion de versions choisi (donc git), la question du stockage des répertoires se pose alors. Généralement nos universités et instituts proposent des solutions d’hébergement internes. Cependant, les services en ligne comme GitLab ou GitHub proposent des solutions plus fiables et d’autres fonctionnalités qui en font bien plus qu’un simple hébergement :

  • De nombreuses fonctionnalités pour faciliter la collaboration en permettant l’organisation et le partage des tâches entre les différents contributeurs (parcourir la documentation riche de GitHub permet rapidement d’être convaincu)
  • Des interfaces intuitives pour aider toute personne peu à l’aise avec git.

 

De plus, les fonctionnalités proposées par GitLab et GitHub évoluent très vite, facilitant toujours plus la gestion et les collaborations. Open-source (contrairement à GitHub), GitLab peut être installé sur notre machine/serveur, mais il existe aussi des projets faciles à déployer comme Gogs.

Mais, GitHub est la solution la plus utilisée actuellement (plus de 35 million de répertoires en avril 2016), et est la plateforme qui a enclenché l’essor du mouvement open-source. Et de nombreux projets bioinformatiques sont hébergés par GitHub (par exemple BioPython, Galaxy ou Bioconda).

GitHub est un bon outil pour les projets scientifiques, comme le montrent Yasset Perez-Riverol et ses collègues (2016).

Philosophie de GitHub

Un répertoire dans GitHub est par défaut public. Chaque répertoire est associé à un utilisateur, le créateur et principal administrateur. Les répertoires publics sont visibles par tous (avec ou sans compte GitHub), mais tout le monde n’a pas la permission en écriture. Les administrateurs du répertoire doivent donner explicitement ces droits aux utilisateurs intéressés.

Cependant, parfois, des répertoires privés peuvent être utiles (au moins temporairement), mais ils sont normalement payants. Cependant, pour la recherche et l’éducation, GitHub propose des répertoires privés gratuits, souvent en collaboration avec les universités et les instituts. Il faut pourtant savoir que GitHub est hébergé sur le sol américain, pouvant poser des problèmes éthiques ou de confidentialité pour certains (Patriot Act).

L’utilisateur, une personne avec un profil et des projets auxquel il contribue, est l’élément central du système de gestion dans GitHub. Mais un autre niveau est aussi proposé, les organisations : un ensemble d’utilisateurs gérant des répertoires liés à un projet, un laboratoire, un institut ou des gros projets open-source (le projet Galaxy, par exemple). Les répertoires dans ces organisations peuvent avoir plusieurs propriétaires et administrateurs.

Collaboration

Le principe même de GitHub repose sur la facilité de tout utilisateur à contribuer à tous les projets auxquels l’utilisateur a accès. GitHub fournit ainsi de nombreuses fonctionnalités pour faciliter la collaboration au sein de projets.

N’importe quel utilisateur peut forker n’importe quel répertoire auquel il a accès. Une copie complète du contenu du répertoire est créée sur le compte de l’utilisateur, tout en maintenant un lien avec le répertoire original. L’utilisateur peut alors modifier librement le projet sans affecter directement le projet original. Une fois les changements prêts (corrections d’erreurs, développement de nouvelles fonctionnalités, ajout de documentation, etc), ils peuvent être soumis au répertoire original via des pull request. Les pull request sont ensuite revues, commentées et ajoutées au projet original par les contributeurs et administrateurs. Avec ce système, les administrateurs gardent le contrôle sur les contributions et leur qualité. L’interface de GitHub propose quelques facilités pour créer des pull request lorsqu’il n’y a que très peu de changements à faire. De cette façon, nul besoin d’avoir une copie intégrale du projet. L’ouverture de pull request par n’importe quel utilisateur de GitHub est une méthode simple pour la collaboration. C’est la base du social coding. Il a été montré que ce système d’échanges et contributions (le GitHub Flow) augmente la qualité du code (Dabbish et al., 2012), mais aussi de tout projet collaboratif.

screen-shot-2016-10-03-at-11-19-09

GitHub Flow - https://guides.github.com/introduction/flow/

 

GitHub propose aussi un système de tickets (ou issues). Les issues permettent de garder une trace des erreurs, des tâches à faire, des demandes de fonctionnalités, … avec un puissant système de tag. Ouvrir une issue est facile et rapide (titre, courte description). Les issues ont une structure claire avec de la place pour des commentaires et des discussions. De plus, les administrateurs projet peut également donner des recommendations sur la manière de rédiger des issues. L’ajout de labels, de jalons et d’assignations aident le filtrage et la prioritisation des tâches. Ce système d’issues peut ainsi se transformer en un puissant outil de planification de projets.

Automatisation de tâches et intégration continue

GitHub offre aussi un ensemble d’outils qui peuvent être exécutés automatiquement après chaque push sur un répertoire. Par exemple, l’intégration continue permet de tester l’intégrité et les performances du code avec Travis CI, une plateforme gratuite pour tous les projets publiques. À chaque changement du code, Travis CI compile et teste le projet pour différentes plateformes, avec de nombreuses options et notifie de toute erreur. GitHub permet ainsi de faciliter une phase essentielle (mais souvent oubliée) du développement : les tests.

Les scripts automatisés peuvent aussi être utilisés pour automatiser d’autres tâches comme le déploiement ou la génération de documentation. Ainsi, pour du code Python ou C/C++, la documentation peut être générée automatiquement avec sphinx et publiée via Read the Docs. GitHub propose aussi une autre solution pour la documentation : les wikis (qui sont versionnés) où les utilisateurs peuvent créer et éditer des pages pour de la documentation, des exemples, …

Promotion de projets

Traditionnellement, un projet scientifique est promu par la publication d’un (ou plusieurs) papier(s) dans un journal avec comité de lecture. Mais souvent, un projet et son code évoluent à une vitesse totalement différente du processus de publication. Ainsi, des nouvelles fonctionnalités ou caractéristiques peuvent ne pas être décrites dans la publication originelle, ou le délai de publication trop long pour un projet est déjà prêt à être utilisé. GitHub propose des fonctionnalités pour promouvoir son projet, parallèlement au circuit classique de la publication.

Il est possible d’interfacer n'importe quel répertoire public avec des services d’archivage comme Zenodo ou figshare pour assigner des DOIs. La procédure est simple à mettre en place. À chaque fois qu’une nouvelle release est créée sur GitHub, Zenodo crée une archive du répertoire, l’associe à un DOI et permet ainsi une citation toujours à jour et une distribution du projet (10e règle de la reproductibilité).

Pour augmenter la visibilité du projet, d’autres outils peuvent être utilisés. Ainsi, GitHub propose des GitHub Pages, des sites web simples hébergés par GitHub. Tout utilisateur peut ainsi créer et héberger des sites de blog, des pages d’aide, des manuels, des tutoriels, … Ces pages peuvent être générées automatiquement avec Jekyll, un puissant générateur de site statique, ou grâce au générateur automatique de GitHub. Ces fonctionnalités, très faciles à prendre en main, sont un excellent moyen pour décrire un projet, promouvoir un poster (ajout de contenu), publier des présentations ou même avoir facilement son propre site Web. Toutes ces fonctionnalités augmentent la visibilité des projets (plus d’utilisateurs, plus de citations) et aussi sa propre visibilité (pour le futur).

Se lancer ?

Utiliser un logiciel de gestion de versions est ainsi indispensable pour une bonne gesion d’un projet. GitHub et git sont de puissants outils qui doivent être explorés et testés pour leurs potentialités. Même si comme souvent, l’apprentissage n’est pas évident. De nombreuses ressources (documentation, tutoriels, …) sont disponibles pour se familiariser avec git et GitHub :

 

Mais plusieurs fonctionnalités puissantes et basiques sont facilement accessibles même aux débutants (surtout grâce à l’interface intuitive de GitHub). La récompense à terme sera plus forte que l’effort investi.

Tenir un cahier de laboratoire

CC BY-NC-ND 2.0 - https://flic.kr/p/4Kumbh

Blackbook - hawkexpress - CC BY-NC-ND 2.0 - https://flic.kr/p/4Kumbh

 

La bonne gestion d'un projet passe aussi par une transparence totale, en particulier vis-à-vis de nos collaborateurs. Tout doit donc être noté pour ainsi garder une trace des processus de création des résultats et commenter les résultats (1e et 9e règles de la reproductibilité). Pour cela, la meilleure solution est de tenir un cahier de laboratoire pour chaque projet. Ce cahier doit être sauvegardé avec le reste des documents liés au projet, être versionné et contenir l’avancée détaillée du projet, avec des entrées datées, signées et assez détaillées (images et tables pour décrire les résultats si nécessaire). En bon carnet de bord, il doit décrire ce qui est fait, les observations, les conclusions, les idées pour le futur, mais aussi des explications des résultats et tous les échecs (bien sûr). Il doit aussi contenir des notes de toutes les conversations liées au projet. Ainsi, le cahier de laboratoire doit donner une vision complète du projet et son avancée dans le temps. Toute personne le lisant peut ainsi comprendre ce qui est fait et s’en servir de base pour suivre le projet et collaborer.

Plusieurs solutions existent pour ce cahier, comme l’historique cahier de labo papier. Cependant, sous cette forme, le cahier n’est pas facilement partageable, versionnable et peut être perdu. Je penche donc plutôt pour une version électronique avec un fichier markdown (syntaxe facile à lire et à écrire), facilement compilable en PDF avec pandoc, enregistré dans le dossier doc et versionné. Le wiki du répertoire GitHub du projet ou des solutions comme Jupyter peuvent aussi servir de cahier de laboratoire.

Parallèlement aux cahiers liés aux projets, je tiens aussi un cahier de laboratoire général, plus personnel. Je note tout ce que je fait (tous les projets avec des liens sur les cahiers de laboratoires des projets, toutes les réunions, …). Il me sert aussi beaucoup de brouillon pour tester des choses et prendre des notes informelles ou conserver des liens ou commandes utiles. Pour ce cahier, j’utilise Monod, un éditeur markdown en ligne. Ce cahier est pour moi assez informel mais je me suis quand même inspirée des conseils de Santiago Schnell (Schnell, 2015). Il me permet de garder une trace de tout mon travail scientifique, de mes idées, des solutions à certains problème, etc.

Conclusions

Lorsqu’on évolue dans le monde scientifique et celui de la recherche, le principe de reproductibilité doit toujours être gardé en tête. N’importe qui doit pouvoir reproduire ce qui a été fait. Pour cela, nos projets doivent être bien organisés, suivis avec un logiciel de gestion de versions et surtout expliqués. De nombreux outils sont disponibles pour faciliter tout ça. J’ai essayé d’en présenter quelques-uns ainsi que quelques bonnes pratiques, mais c’est loin d’être exhaustif! Et les technologies évoluent vite.

Pour écrire cet article, j’ai (re)lu pleins d’articles intéressants sur le sujet. J’ai pu prendre du recul sur ma façon de faire de la science et de la recherche, pour extraire ma vision actuelle de la gestion des projets en science. Cette vision n’est peut être pas la vôtre donc j’aimerais aussi avoir vos visions : Comment fonctionnez-vous? Que pensez-vous des cahiers de laboratoire ? Quelle forme fonctionne le mieux ? Avez-vous déjà réfléchi à l’organisation globale de vos projets ? Que faut-il toujours garder en tête ? Quels verrous avez-vous rencontré ?

Remerciements

Merci à Magali Michaut : sa présentation au workshop JeBif m’a donné envie d’écrire enfin cet article. Merci aussi Will, Kévin, Yoann MClemZaZo0o, NiGoPol pour leur relectures et leurs commentaires constructifs.

Sources

Une partie du contenu de cet article est inspiré d’articles de PLoS Computational Biology et particulièrement de la collection Ten Simple Rules.

Dabbish, L., Stuart, C., Tsay, J. & Herbsleb, J. (2012). Social Coding in GitHub: Transparency and Collaboration in an Open Software Repository. In Proceedings of the ACM 2012 Conference on Computer Supported Cooperative Work (pp. 1277—1286).http://doi.acm.org/10.1145/2145204.2145396

Lampa, S. (2015). A few thoughts on organizing computational (biology) projects. Accessed: 2016-09-01

Noble, W. S. (2009). A Quick Guide to Organizing Computational Biology Projects. PLoS Comput Biol, 5(7), 1-5.http://dx.doi.org/10.1371/journal.pcbi.1000424

Perez-Riverol, Y. A. G. (2016). Ten Simple Rules for Taking Advantage of Git and GitHub. PLoS Comput Biol, 12(7), 1-11.http://dx.doi.org/10.1371/journal.pcbi.1004947

Sandve, G. K. A. N. (2013). Ten Simple Rules for Reproducible Computational Research. PLoS Comput Biol, 9(10), 1-4.http://dx.doi.org/10.1371/journal.pcbi.1003285

Schnell, S. (2015). Ten Simple Rules for a Computational Biologist’s Laboratory Notebook. PLoS Comput Biol, 11(9), 1-5.http://dx.doi.org/10.1371/journal.pcbi.1004385

  • À propos de
  • Je suis en post-doc à Freiburg, après un premier post-doc sur le traitement des données liées aux microbiotes à Clermont-Ferrand. Ma thèse en évolution bactérienne était à l'interface entre biologie computationnelle (évolution artificielle) et bioinformatique (génomique comparative). Mais, avant tout ça, j'ai suivi la formation d'ingénieur en Bioinformatique et Modélisation (BIM à l'INSA de Lyon) et un master d'Informatique Fondamentale (option Modélisation des systèmes complexes à l'ENS de Lyon). Je m'intéresse à ce qui tourne autour de l'open science, l'open source, la communication scientifique, la science des données et de nombreux autres sujets. Compte Twitter : @bebatut

3 commentaires sur “S'outiller et s'organiser pour mieux travailler

  1. Super article !

  2. pas tout lu mais
    Sourceforge c\'est la fin des années 90 ...
    github n\'existait pas ..

  3. Excellent ! Merci pour cet article Bérénice. Très intéressant, et ravie que ma présentation t\'ait inspirée. 🙂

Laisser un commentaire