S'outiller et s'organiser pour mieux travailler

TL;DR La repro­duc­ti­bi­li­té, c’est la vie (dans le monde scien­ti­fique) ! Tout résul­tat doit pou­voir être repro­duit. La tech­no­lo­gie per­met de faci­li­ter la recherche de repro­duc­ti­bi­li­té. Les cahiers de labo­ra­toire papiers ne sont plus du tout adap­tés à la recherche actuelle et au besoin de repro­duc­ti­bi­li­té. Je pré­co­nise donc d’utiliser git et GitHub, de bien orga­ni­ser ses pro­jets et d’utiliser des cahiers de labo­ra­toire élec­tro­niques.

Un des prin­cipes essen­tiels de la méthode scien­ti­fique est la repro­duc­ti­bi­li­té, i.e. la capa­ci­té pour tous de repro­duire toute expé­rience ou étude tout en obte­nant des résul­tats simi­laires. C’est la pierre angu­laire de la Recherche (Sandve, 2013) et ce qui dis­tingue le carac­tère scien­ti­fique d’une étude. La repro­duc­ti­bi­li­té n’est pas seule­ment une res­pon­sa­bi­li­té morale vis-à-vis de la recherche. Le manque de repro­duc­ti­bi­li­té peut aus­si être un far­deau pour les scien­ti­fiques eux-même en limi­tant, par exemple, leur capa­ci­té à réuti­li­ser leur code ou à réana­ly­ser un jeu de don­nées. De plus, la mise en place de bonnes pra­tiques de repro­duc­ti­bi­li­té amé­liore la qua­li­té des col­la­bo­ra­tions, en garan­tis­sant la capa­ci­té de repro­duc­tion et de trans­pa­rence des ana­lyses. Ces pra­tiques per­mettent un gain de temps à long terme et sont un gage d’une recherche de qua­li­té.

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

http://​blog​.f1000​re​search​.com/​2​0​1​4​/​0​4​/​0​4​/​r​e​p​r​o​d​u​c​i​b​i​l​i​t​y​-​t​w​e​e​t​c​h​a​t​-​r​e​c​ap/

 

La repro­duc­ti­bli­té se base prin­ci­pa­le­ment sur la trans­pa­rence et une orga­ni­sa­tion claire des pro­jets. N’importe qui (un relec­teur, un col­la­bo­ra­teur ou soi-même après quelques mois) ayant un pro­jet en main doit pou­voir com­prendre ce qui sa été fait (et pour­quoi) et pou­voir repro­duire les résul­tats obte­nus. Pour cela, toute étude scien­ti­fique doit être bien orga­ni­sée et docu­men­tée et suivre 10 règles (Sandve, 2013) essen­tielles :

  1. Le pro­ces­sus de pro­duc­tion de chaque résul­tat est tota­le­ment retra­cable
  2. Toute étape de mani­pu­la­tion manuelle des don­nées est évi­tée
  3. Les ver­sions exactes des pro­grammes externes uti­li­sés sont archi­vées
  4. Tous les scripts déve­lop­pés et uti­li­sés sont ver­sion­nés
  5. Tous les résul­tats inter­mé­diaires sont conser­vés, si pos­sible dans un for­mat stan­dar­di­sé
  6. Les graines de l’aléatoire (ran­dom seeds) pour des études incluant une part d’aléatoire sont notées
  7. Les don­nées brutes uti­li­sés pour les gra­phiques sont conser­vées
  8. Les sor­ties des ana­lyses sont orga­ni­sées hié­rar­chi­que­ment
  9. Les résul­tats sont com­men­tés par écrit
  10. Les scripts et résul­tats sont publi­que­ment acces­sibles

 

Mettre en place ces règles n’est pas tou­jours évident et on ne nous a géné­ra­le­ment pas appris à le faire. Pen­dant nos études, la plu­part de nos cours de bio­in­for­ma­tique se foca­li­saient sur la pro­gram­ma­tion et l’utilisation d’outils exis­tants. Rien ne nous a donc pré­pa­ré à gérer plu­sieurs pro­jets scien­ti­fiques col­la­bo­ra­tifs qui soient repro­duc­tibles. Nous appre­nons sur le tas ces pra­tiques, au grès des ren­contres et des inter­ac­tions avec nos col­lègues. De plus, nous avons sou­vent pas conscience de l’importance de la repro­duc­ti­bi­li­té et de la trans­pa­rence dans la méthode scien­ti­fique.

Depuis un peu plus de 5 ans, je tra­vaille sur dif­fé­rents pro­jets bio­in­for­ma­tiques au quo­ti­dien. J’ai eu la chance de pou­voir tra­vailler dans plu­sieurs labo­ra­toires avec des scien­ti­fiques très dif­fé­rents. J’ai pu ain­si apprendre et essayer dif­fé­rentes tech­niques et pra­tiques. Mais ce n’est que récem­ment que j’ai com­men­cé à me poser des ques­tions sur notre façon de faire de la recherche. J’ai alors essayé de com­prendre quelles pou­vaient être les bonnes pra­tiques, leurs avan­tages et leur mise en oeuvre. 3 grandes pra­tiques, que je vais détailler dans cet article, me paraissent essen­tielles pour gérer un pro­jet bio­in­for­ma­tique et prendre soin du prin­cipe de repro­duc­ti­bi­li­té.

Bien organiser ses projets

Tout le conte­nu d’un pro­jet (à l’exception pour du code source ou des scripts par­ta­gés entre plu­sieurs pro­jets) doit être conser­vé dans un dos­sier (un dos­sier par pro­jet). Je parle ici du conte­nu sous forme infor­ma­tique, la forme pri­vi­lé­giée (la plus facile à tra­cer et par­ta­ger de nos jours). Ce dos­sier doit être bien struc­tu­ré. En effet, la bonne struc­ture d’un dos­sier peut faire la dif­fé­rence dans la réus­site d’un pro­jet (accès facile et rapide aux bonnes don­nées, à la bonne ver­sion du work­flow, …). William Staf­ford Noble (2009) pro­pose une réflexion sur la struc­ture idéale des dos­siers que Samuel Lam­pa a étof­fée (2015). Quelques idées inté­res­santes res­sortent de ces réflexions :

  • Une struc­ture uni­fiée avec d’abord un niveau logique, puis un sous-niveau chro­no­lo­gique, puis encore un sous-niveau logique
  • Un dos­sier pour chaque nou­velle expé­rience ou ana­lyse incluant
    • Un script per­met­tant de repro­duire exac­te­ment l’analyse
    • Tous les chan­ge­ments (code, work­flow, confi­gu­ra­tion, …) par rap­port aux autres expé­riences ou ana­lyses

 

Pour illus­trer ces idées, Samuel Lam­pa (2015) pro­pose d’organiser les dos­siers des pro­jets sui­vant la hié­rar­chie :

├── bin  --------------------# Binary files and executables
├── conf --------------------# Project-wide configuraiotn
├── doc --------------------# Any documents, such as manuscripts being written
├── exp --------------------# The main experiments folder
│ ├── 2000-01-01-example --# An example Experiment
│ │ ├── audit -----------# Audit logs from workflow runs
│ │ ├── bin -----------# Experiment-specific executables and scripts
│ │ ├── conf -----------# Experiment-specific config
│ │ ├── data -----------# Any data generated by workflows
│ │ ├── doc -----------# Experiment-specific documents
│ │ ├── log -----------# Log files from workflow runs
│ │ ├── raw -----------# Raw-data to be used in the experiment
│ │ ├── results --------# Results from workflow runs
│ │ ├── run -----------# All files rel. to running experiment
│ │ └── tmp -----------# Any temporary files not supposed to be saved
├── raw --------------------# Project-wide raw data
├── results ----------------# Project-wide results
└── src --------------------# Project-wide source code (that needs to be compiled)

Cette struc­ture est bien adap­tée à un pro­jet en pro­duc­tion, où des expé­riences sont lan­cées avec pour seules dif­fé­rences des chan­ge­ments mineurs (confi­gu­ra­tion, para­mètres, …). Pour des ana­lyses explo­ra­trices, j’utilise plu­tôt la hié­rar­chie :

├── bin
├── doc
├── raw
├── results
└── src

J’utilise le ges­tion­naire de paquets conda pour gérer toutes les dépen­dances et les ver­sions des outils néces­saires pour le pro­jet. conda est un ges­tion­naire de paquet indé­pen­dant de tout lan­gage de pro­gram­ma­tion et de tout sys­tème, per­met­tant une ins­tal­la­tion facile et robuste. Ain­si, grâce aux efforts de la com­mu­nau­té Bio­con­da, plus de 1 500 outils bio­in­for­ma­tiques (dans n'importe quel lan­gage) peuvent être faci­le­ment ins­tal­lés via un package conda. conda pro­pose aus­si des envi­ron­ne­ments, dont je me sers pour archi­ver les ver­sions exactes des pro­grammes uti­li­sés (3e règle de la repro­duc­ti­bi­li­té). Ces envi­ron­ne­ments peuvent être expor­tés (fichier yaml) et partagés/​versionnés pour per­mettre l’import des mêmes outils avec les mêmes ver­sions et repro­duire les ana­lyses.

Tous les exé­cu­tables (hors dépen­dances, c’est-à-dire prin­ci­pa­le­ment des scripts bash) sont conser­vés dans le dos­sier bin. Mes scripts Python, pour mani­pu­ler les don­nées par exemple, (cor­rec­te­ment docu­men­tés et véri­fiés par flake8) se trouvent dans le dos­sier src. Avec ces scripts, je garde une trace de toute mani­pu­la­tion des don­nées et des pro­ces­sus de pro­duc­tion des résul­tats (1e et 2nde règles de la repro­duc­ti­bi­li­té)

Un fichier README est aus­si ajou­té à la racine. Ce fichier contient une courte des­crip­tion du pro­jet, des ins­truc­tions pour repro­duire le pro­jet, … D’autre part, j’ajoute aus­si sys­té­ma­ti­que­ment un fichier CITATION qui explique com­ment citer le pro­jet et un fichier LICENSE, impor­tant pour décrire les droits d’utilisation et de modi­fi­ca­tion du code (sans licence expli­cite, tous les droits sont réser­vés et le pro­jet ne peut pas être uti­li­sé libre­ment).

Avec cette hié­rar­chie claire et simi­laire pour tous les pro­jets, il est facile pour n’importe qui de navi­guer dans le pro­jet, de com­prendre ce qui est fait et de repro­duire les ana­lyses et résul­tats, sans y consa­crer plus de temps que néces­saire.

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

La 4e règle de la repro­duc­ti­bi­li­té concerne le ver­sion­nage des scripts déve­lop­pés et uti­li­sés pour le pro­jet. Je pense que plus que les scripts, tout fichier impor­tant pour le pro­jet doit être ver­sion­né.

Un logi­ciel de ges­tion de ver­sions est un sys­tème qui per­met de gar­der une trace des chan­ge­ments de fichiers dans le temps. Ce type de logi­ciel faci­lite le tra­vail quo­ti­dien et les col­la­bo­ra­tions :

  • Rien de ce qui est sou­mis au logi­ciel n’est per­du (ou il faut vrai­ment le vou­loir), et comme toutes les ver­sions sont sau­vées, il est tou­jours pos­sible de reve­nir en arrière
  • Avec la trace des auteurs et des dates des chan­ge­ments, il est facile de savoir à qui deman­der si un chan­ge­ment n’est pas clair
  • Le logi­ciel per­met aus­si de gérer les conflits lorsque plu­sieurs per­sonnes ont modi­fié des par­ties iden­tiques d’un fichier

 

Les logi­ciels de ges­tion de ver­sions sont comme les cahiers de labo­ra­toire du monde numé­rique. Tout tra­vail scien­ti­fique, qui par nature évo­lue dans le temps et a besoin d’être par­ta­gé, doit être sto­cké avec un logi­ciel de ges­tion de ver­sions. Et c’est par­ti­cu­liè­re­ment vrai pour tous les pro­jets bio­in­for­ma­tiques !!!

Plu­sieurs logi­ciels de ges­tion de ver­sions existent (Sub­ver­sion, Mer­cu­rial, …). Depuis quelques années,git est le plus popu­laire, aus­si dans le monde scien­ti­fique et la recherche. git est un outil indis­pen­sable, qu’il est impor­tant de savoir uti­li­ser. De nom­breux tuto­riels sont dis­po­nibles, comme ceux de ce blog (pre­miers pas), ou les cours de Soft­ware Car­pen­try.

Bien que l’idée de base der­rière un logi­ciel de ges­tion de ver­sions soit simple, son uti­li­sa­tion requiert un peu de dis­ci­pline. Il existe évi­dem­ment une ver­sion en ligne de com­mande, mais aus­si des inter­faces gra­phiques, et git s’intègre aus­si très bien à divers IDE (Eclipse, Net­beans, Intel­liJ IDEA) et trai­te­ment de texte (Sublime Text, Atom et même Gedit ! Ama­zing, isn’t it ? )

Quelques conseils pour bien débuter

Plus un logi­ciel de ges­tion de ver­sions est uti­li­sé régu­liè­re­ment, plus ses avan­tages se font sen­tir. L’historique des chan­ge­ments enre­gis­tré est alors le plus com­plet pos­sible et per­met de reve­nir faci­le­ment en arrière en limi­tant au maxi­mum les effets de bord. Ain­si, une bonne règle est d’ajouter les chan­ge­ments au moins une fois par jour et de faire des chan­ge­ments assez petits. Un petit conseil : l’option -p de la com­mande git add per­met de choi­sir les por­tions de code à ajou­ter pour un commit, plu­tôt que de sou­mettre tous les chan­ge­ments d’un même fichiers d’un seul coup. Et pour les phases de chan­ge­ments majeurs, l’idéal est d’utiliser des branches (his­to­rique paral­lèle).

Un logi­ciel de ges­tion de ver­sions ne devrait être uti­li­sé que pour les fichiers édi­tés à la main. Les fichiers géné­rés auto­ma­ti­que­ment (pro­grammes com­pi­lés, résul­tats, …) ne doivent pas être ver­sion­nés car sou­vent ces fichiers sont lourds et/​ou binaires et ne sont donc pas cor­rec­te­ment pris en charge par le logi­ciel de ges­tion de ver­sions. De plus, ces fichiers sont faci­le­ment repro­duc­tibles grâce au ver­sion­nage des scripts uti­li­sés pour les géné­rer. Cepen­dant, pour des rai­sons de repro­duc­ti­bi­li­té et trans­pa­rence, les résul­tats (inter­mé­diaires et finaux) doivent être sau­ve­gar­dés pour être ensuite ren­dus publics (5e et 10e règles de la repro­duc­ti­bi­li­té). Et, récem­ment, Nature a publié un article encou­ra­geant les auteurs à rendre public leurs jeux de don­nées et à les asso­cier à des digi­tal object iden­ti­fiers (DOIs). Des solu­tions comme Zeno­do ou fig­share per­mettent de sto­cker les résul­tats en leur asso­ciant un DOI, fixant ain­si une date et une ver­sion pour les résul­tats et per­met­tant aus­si la cita­tion.

Un der­nier petit conseil concer­nant git. Comme tous les fichiers du pro­jet ne sont pas ver­sion­nés (les résul­tats, par exemple), le logi­ciel de ges­tion de ver­sions va se “plaindre”, cachant poten­tiel­le­ment de vraies erreurs. Il est pos­sible d’ajouter un fichier .gitignore à la racine du dos­sier pour que git ignore cer­tains fichiers ou dos­siers, comme les fichiers de confi­gu­ra­tion qui contiennent les mots de passe root de votre base de don­nées 😉

Héberger son projet

Une fois le logi­ciel de ges­tion de ver­sions choi­si (donc git), la ques­tion du sto­ckage des réper­toires se pose alors. Géné­ra­le­ment nos uni­ver­si­tés et ins­ti­tuts pro­posent des solu­tions d’hébergement internes. Cepen­dant, les ser­vices en ligne comme GitLab ou GitHub pro­posent des solu­tions plus fiables et d’autres fonc­tion­na­li­tés qui en font bien plus qu’un simple héber­ge­ment :

  • De nom­breuses fonc­tion­na­li­tés pour faci­li­ter la col­la­bo­ra­tion en per­met­tant l’organisation et le par­tage des tâches entre les dif­fé­rents contri­bu­teurs (par­cou­rir la docu­men­ta­tion riche de GitHub per­met rapi­de­ment d’être convain­cu)
  • Des inter­faces intui­tives pour aider toute per­sonne peu à l’aise avec git.

 

De plus, les fonc­tion­na­li­tés pro­po­sées par Git­Lab et GitHub évo­luent très vite, faci­li­tant tou­jours plus la ges­tion et les col­la­bo­ra­tions. Open-source (contrai­re­ment à GitHub), Git­Lab peut être ins­tal­lé sur notre machine/​serveur, mais il existe aus­si des pro­jets faciles à déployer comme Gogs.

Mais, GitHub est la solu­tion la plus uti­li­sée actuel­le­ment (plus de 35 mil­lion de réper­toires en avril 2016), et est la pla­te­forme qui a enclen­ché l’essor du mou­ve­ment open-source. Et de nom­breux pro­jets bio­in­for­ma­tiques sont héber­gés par GitHub (par exemple Bio­Py­thon, Galaxy ou Bio­con­da).

GitHub est un bon outil pour les pro­jets scien­ti­fiques, comme le montrent Yas­set Per­ez-Rive­rol et ses col­lègues (2016).

Philosophie de GitHub

Un réper­toire dans GitHub est par défaut public. Chaque réper­toire est asso­cié à un uti­li­sa­teur, le créa­teur et prin­ci­pal admi­nis­tra­teur. Les réper­toires publics sont visibles par tous (avec ou sans compte GitHub), mais tout le monde n’a pas la per­mis­sion en écri­ture. Les admi­nis­tra­teurs du réper­toire doivent don­ner expli­ci­te­ment ces droits aux uti­li­sa­teurs inté­res­sés.

Cepen­dant, par­fois, des réper­toires pri­vés peuvent être utiles (au moins tem­po­rai­re­ment), mais ils sont nor­ma­le­ment payants. Cepen­dant, pour la recherche et l’éducation, GitHub pro­pose des réper­toires pri­vés gra­tuits, sou­vent en col­la­bo­ra­tion avec les uni­ver­si­tés et les ins­ti­tuts. Il faut pour­tant savoir que GitHub est héber­gé sur le sol amé­ri­cain, pou­vant poser des pro­blèmes éthiques ou de confi­den­tia­li­té pour cer­tains (Patriot Act).

L’utilisateur, une per­sonne avec un pro­fil et des pro­jets aux­quel il contri­bue, est l’élément cen­tral du sys­tème de ges­tion dans GitHub. Mais un autre niveau est aus­si pro­po­sé, les orga­ni­sa­tions : un ensemble d’utilisateurs gérant des réper­toires liés à un pro­jet, un labo­ra­toire, un ins­ti­tut ou des gros pro­jets open-source (le pro­jet Galaxy, par exemple). Les réper­toires dans ces orga­ni­sa­tions peuvent avoir plu­sieurs pro­prié­taires et admi­nis­tra­teurs.

Collaboration

Le prin­cipe même de GitHub repose sur la faci­li­té de tout uti­li­sa­teur à contri­buer à tous les pro­jets aux­quels l’utilisateur a accès. GitHub four­nit ain­si de nom­breuses fonc­tion­na­li­tés pour faci­li­ter la col­la­bo­ra­tion au sein de pro­jets.

N’importe quel uti­li­sa­teur peut for­ker n’importe quel réper­toire auquel il a accès. Une copie com­plète du conte­nu du réper­toire est créée sur le compte de l’utilisateur, tout en main­te­nant un lien avec le réper­toire ori­gi­nal. L’utilisateur peut alors modi­fier libre­ment le pro­jet sans affec­ter direc­te­ment le pro­jet ori­gi­nal. Une fois les chan­ge­ments prêts (cor­rec­tions d’erreurs, déve­lop­pe­ment de nou­velles fonc­tion­na­li­tés, ajout de docu­men­ta­tion, etc), ils peuvent être sou­mis au réper­toire ori­gi­nal via des pull request. Les pull request sont ensuite revues, com­men­tées et ajou­tées au pro­jet ori­gi­nal par les contri­bu­teurs et admi­nis­tra­teurs. Avec ce sys­tème, les admi­nis­tra­teurs gardent le contrôle sur les contri­bu­tions et leur qua­li­té. L’interface de GitHub pro­pose quelques faci­li­tés pour créer des pull request lorsqu’il n’y a que très peu de chan­ge­ments à faire. De cette façon, nul besoin d’avoir une copie inté­grale du pro­jet. L’ouverture de pull request par n’importe quel uti­li­sa­teur de GitHub est une méthode simple pour la col­la­bo­ra­tion. C’est la base du social coding. Il a été mon­tré que ce sys­tème d’échanges et contri­bu­tions (le GitHub Flow) aug­mente la qua­li­té du code (Dab­bish et al., 2012), mais aus­si de tout pro­jet col­la­bo­ra­tif.

screen-shot-2016-10-03-at-11-19-09
GitHub Flow — https://​guides​.github​.com/​i​n​t​r​o​d​u​c​t​i​o​n​/​f​l​ow/

 

GitHub pro­pose aus­si un sys­tème de tickets (ou issues). Les issues per­mettent de gar­der une trace des erreurs, des tâches à faire, des demandes de fonc­tion­na­li­tés, … avec un puis­sant sys­tème de tag. Ouvrir une issue est facile et rapide (titre, courte des­crip­tion). Les issues ont une struc­ture claire avec de la place pour des com­men­taires et des dis­cus­sions. De plus, les admi­nis­tra­teurs pro­jet peut éga­le­ment don­ner des recom­men­da­tions sur la manière de rédi­ger des issues. L’ajout de labels, de jalons et d’assignations aident le fil­trage et la prio­ri­ti­sa­tion des tâches. Ce sys­tème d’issues peut ain­si se trans­for­mer en un puis­sant outil de pla­ni­fi­ca­tion de pro­jets.

Automatisation de tâches et intégration continue

GitHub offre aus­si un ensemble d’outils qui peuvent être exé­cu­tés auto­ma­ti­que­ment après chaque push sur un réper­toire. Par exemple, l’intégration conti­nue per­met de tes­ter l’intégrité et les per­for­mances du code avec Tra­vis CI, une pla­te­forme gra­tuite pour tous les pro­jets publiques. À chaque chan­ge­ment du code, Tra­vis CI com­pile et teste le pro­jet pour dif­fé­rentes pla­te­formes, avec de nom­breuses options et noti­fie de toute erreur. GitHub per­met ain­si de faci­li­ter une phase essen­tielle (mais sou­vent oubliée) du déve­lop­pe­ment : les tests.

Les scripts auto­ma­ti­sés peuvent aus­si être uti­li­sés pour auto­ma­ti­ser d’autres tâches comme le déploie­ment ou la géné­ra­tion de docu­men­ta­tion. Ain­si, pour du code Python ou C/C++, la docu­men­ta­tion peut être géné­rée auto­ma­ti­que­ment avec sphinx et publiée via Read the Docs. GitHub pro­pose aus­si une autre solu­tion pour la docu­men­ta­tion : les wikis (qui sont ver­sion­nés) où les uti­li­sa­teurs peuvent créer et édi­ter des pages pour de la docu­men­ta­tion, des exemples, …

Promotion de projets

Tra­di­tion­nel­le­ment, un pro­jet scien­ti­fique est pro­mu par la publi­ca­tion d’un (ou plu­sieurs) papier(s) dans un jour­nal avec comi­té de lec­ture. Mais sou­vent, un pro­jet et son code évo­luent à une vitesse tota­le­ment dif­fé­rente du pro­ces­sus de publi­ca­tion. Ain­si, des nou­velles fonc­tion­na­li­tés ou carac­té­ris­tiques peuvent ne pas être décrites dans la publi­ca­tion ori­gi­nelle, ou le délai de publi­ca­tion trop long pour un pro­jet est déjà prêt à être uti­li­sé. GitHub pro­pose des fonc­tion­na­li­tés pour pro­mou­voir son pro­jet, paral­lè­le­ment au cir­cuit clas­sique de la publi­ca­tion.

Il est pos­sible d’interfacer n'importe quel réper­toire public avec des ser­vices d’archivage comme Zeno­do ou fig­share pour assi­gner des DOIs. La pro­cé­dure est simple à mettre en place. À chaque fois qu’une nou­velle release est créée sur GitHub, Zeno­do crée une archive du réper­toire, l’associe à un DOI et per­met ain­si une cita­tion tou­jours à jour et une dis­tri­bu­tion du pro­jet (10e règle de la repro­duc­ti­bi­li­té).

Pour aug­men­ter la visi­bi­li­té du pro­jet, d’autres outils peuvent être uti­li­sés. Ain­si, GitHub pro­pose des GitHub Pages, des sites web simples héber­gés par GitHub. Tout uti­li­sa­teur peut ain­si créer et héber­ger des sites de blog, des pages d’aide, des manuels, des tuto­riels, … Ces pages peuvent être géné­rées auto­ma­ti­que­ment avec Jekyll, un puis­sant géné­ra­teur de site sta­tique, ou grâce au géné­ra­teur auto­ma­tique de GitHub. Ces fonc­tion­na­li­tés, très faciles à prendre en main, sont un excellent moyen pour décrire un pro­jet, pro­mou­voir un pos­ter (ajout de conte­nu), publier des pré­sen­ta­tions ou même avoir faci­le­ment son propre site Web. Toutes ces fonc­tion­na­li­tés aug­mentent la visi­bi­li­té des pro­jets (plus d’utilisateurs, plus de cita­tions) et aus­si sa propre visi­bi­li­té (pour le futur).

Se lancer ?

Uti­li­ser un logi­ciel de ges­tion de ver­sions est ain­si indis­pen­sable pour une bonne gesion d’un pro­jet. GitHub et git sont de puis­sants outils qui doivent être explo­rés et tes­tés pour leurs poten­tia­li­tés. Même si comme sou­vent, l’apprentissage n’est pas évident. De nom­breuses res­sources (docu­men­ta­tion, tuto­riels, …) sont dis­po­nibles pour se fami­lia­ri­ser avec git et GitHub :

 

Mais plu­sieurs fonc­tion­na­li­tés puis­santes et basiques sont faci­le­ment acces­sibles même aux débu­tants (sur­tout grâce à l’interface intui­tive de GitHub). La récom­pense à terme sera plus forte que l’effort inves­ti.

Tenir un cahier de laboratoire

CC BY-NC-ND 2.0 - https://flic.kr/p/4Kumbh
Black­book — haw­kex­press — CC BY-NC-ND 2.0 — https://​flic​.kr/​p​/​4​K​u​mbh

 

La bonne ges­tion d'un pro­jet passe aus­si par une trans­pa­rence totale, en par­ti­cu­lier vis-à-vis de nos col­la­bo­ra­teurs. Tout doit donc être noté pour ain­si gar­der une trace des pro­ces­sus de créa­tion des résul­tats et com­men­ter les résul­tats (1e et 9e règles de la repro­duc­ti­bi­li­té). Pour cela, la meilleure solu­tion est de tenir un cahier de labo­ra­toire pour chaque pro­jet. Ce cahier doit être sau­ve­gar­dé avec le reste des docu­ments liés au pro­jet, être ver­sion­né et conte­nir l’avancée détaillée du pro­jet, avec des entrées datées, signées et assez détaillées (images et tables pour décrire les résul­tats si néces­saire). En bon car­net de bord, il doit décrire ce qui est fait, les obser­va­tions, les conclu­sions, les idées pour le futur, mais aus­si des expli­ca­tions des résul­tats et tous les échecs (bien sûr). Il doit aus­si conte­nir des notes de toutes les conver­sa­tions liées au pro­jet. Ain­si, le cahier de labo­ra­toire doit don­ner une vision com­plète du pro­jet et son avan­cée dans le temps. Toute per­sonne le lisant peut ain­si com­prendre ce qui est fait et s’en ser­vir de base pour suivre le pro­jet et col­la­bo­rer.

Plu­sieurs solu­tions existent pour ce cahier, comme l’historique cahier de labo papier. Cepen­dant, sous cette forme, le cahier n’est pas faci­le­ment par­ta­geable, ver­sion­nable et peut être per­du. Je penche donc plu­tôt pour une ver­sion élec­tro­nique avec un fichier markdown (syn­taxe facile à lire et à écrire), faci­le­ment com­pi­lable en PDF avec pandoc, enre­gis­tré dans le dos­sier doc et ver­sion­né. Le wiki du réper­toire GitHub du pro­jet ou des solu­tions comme Jupy­ter peuvent aus­si ser­vir de cahier de labo­ra­toire.

Paral­lè­le­ment aux cahiers liés aux pro­jets, je tiens aus­si un cahier de labo­ra­toire géné­ral, plus per­son­nel. Je note tout ce que je fait (tous les pro­jets avec des liens sur les cahiers de labo­ra­toires des pro­jets, toutes les réunions, …). Il me sert aus­si beau­coup de brouillon pour tes­ter des choses et prendre des notes infor­melles ou conser­ver des liens ou com­mandes utiles. Pour ce cahier, j’utilise Monod, un édi­teur markdown en ligne. Ce cahier est pour moi assez infor­mel mais je me suis quand même ins­pi­rée des conseils de San­tia­go Schnell (Schnell, 2015). Il me per­met de gar­der une trace de tout mon tra­vail scien­ti­fique, de mes idées, des solu­tions à cer­tains pro­blème, etc.

Conclusions

Lorsqu’on évo­lue dans le monde scien­ti­fique et celui de la recherche, le prin­cipe de repro­duc­ti­bi­li­té doit tou­jours être gar­dé en tête. N’importe qui doit pou­voir repro­duire ce qui a été fait. Pour cela, nos pro­jets doivent être bien orga­ni­sés, sui­vis avec un logi­ciel de ges­tion de ver­sions et sur­tout expli­qués. De nom­breux outils sont dis­po­nibles pour faci­li­ter tout ça. J’ai essayé d’en pré­sen­ter quelques-uns ain­si que quelques bonnes pra­tiques, mais c’est loin d’être exhaus­tif ! Et les tech­no­lo­gies évo­luent vite.

Pour écrire cet article, j’ai (re)lu pleins d’articles inté­res­sants 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 ges­tion des pro­jets en science. Cette vision n’est peut être pas la vôtre donc j’aimerais aus­si avoir vos visions : Com­ment fonc­tion­nez-vous ? Que pen­sez-vous des cahiers de labo­ra­toire ? Quelle forme fonc­tionne le mieux ? Avez-vous déjà réflé­chi à l’organisation glo­bale de vos pro­jets ? Que faut-il tou­jours gar­der en tête ? Quels ver­rous avez-vous ren­con­tré ?

Remerciements

Mer­ci à Maga­li Michaut : sa pré­sen­ta­tion au work­shop JeBif m’a don­né envie d’écrire enfin cet article. Mer­ci aus­si Will, Kévin, Yoann MClemZaZo0o, NiGo­Pol pour leur relec­tures et leurs com­men­taires construc­tifs.

Sources

Une par­tie du conte­nu de cet article est ins­pi­ré d’articles de PLoS Com­pu­ta­tio­nal Bio­lo­gy et par­ti­cu­liè­re­ment de la col­lec­tion Ten Simple Rules.

Dab­bish, L., Stuart, C., Tsay, J. & Herbs­leb, J. (2012). Social Coding in GitHub : Trans­pa­ren­cy and Col­la­bo­ra­tion in an Open Soft­ware Repo­si­to­ry. In Pro­cee­dings of the ACM 2012 Confe­rence on Com­pu­ter Sup­por­ted Coope­ra­tive Work (pp. 1277—1286).http://​doi​.acm​.org/​1​0​.​1​1​4​5​/​2​1​4​5​2​0​4​.​2​1​4​5​396

Lam­pa, S. (2015). A few thoughts on orga­ni­zing com­pu­ta­tio­nal (bio­lo­gy) pro­jects. Acces­sed : 2016-09-01

Noble, W. S. (2009). A Quick Guide to Orga­ni­zing Com­pu­ta­tio­nal Bio­lo­gy Pro­jects. PLoS Com­put Biol, 5(7), 1–5.http://​dx​.doi​.org/​1​0​.​1​3​7​1​/​j​o​u​r​n​a​l​.​p​c​b​i​.​1​0​0​0​424

Per­ez-Rive­rol, Y. A. G. (2016). Ten Simple Rules for Taking Advan­tage of Git and GitHub. PLoS Com­put Biol, 12(7), 1–11.http://​dx​.doi​.org/​1​0​.​1​3​7​1​/​j​o​u​r​n​a​l​.​p​c​b​i​.​1​0​0​4​947

Sandve, G. K. A. N. (2013). Ten Simple Rules for Repro­du­cible Com­pu­ta­tio­nal Research. PLoS Com­put Biol, 9(10), 1–4.http://​dx​.doi​.org/​1​0​.​1​3​7​1​/​j​o​u​r​n​a​l​.​p​c​b​i​.​1​0​0​3​285

Schnell, S. (2015). Ten Simple Rules for a Com­pu­ta­tio­nal Biologist’s Labo­ra­to­ry Note­book. PLoS Com­put Biol, 11(9), 1–5.http://​dx​.doi​.org/​1​0​.​1​3​7​1​/​j​o​u​r​n​a​l​.​p​c​b​i​.​1​0​0​4​385



Pour continuer la lecture :


Commentaires

3 réponses à “S'outiller et s'organiser pour mieux travailler”

  1. Super article !

  2. pas tout lu mais
    Sour­ce­forge c'est la fin des années 90 …
    github n'existait pas ..

  3. Excellent ! Mer­ci pour cet article Béré­nice. Très inté­res­sant, et ravie que ma pré­sen­ta­tion t'ait ins­pi­rée. 🙂

Laisser un commentaire