Didacticiel :
Pourquoi et comment déposer un package R sur Bioconductor ?

Ça y est, votre code R un poil brut commence à avoir de la substance et vous envisagez d'en faire un outil à part entière. Comme tout bioinformaticien qui se respecte, vous envisagez donc de packager (ou paqueter en français) proprement cet ensemble de scripts R.

Non on ne largue pas une nuée de scripts non commentés, non documentés, avec juste un mail disant "Non mais tu changes tel et tel paramètres et ça fonctionne"...

Quand j'essaie d'expliquer le concept de reproductibilité à un mauvais bioinformaticien

Votre package R étant évidemment d'une grande utilité à la communauté bioinformatique, vous envisagez de le partager. La question du répertoire de packages où vous le déposerez une fois fini va donc se poser, et avec, les conditions de développement du package qui s'appliqueront.

Pourquoi déposer son package sur Bioconductor alors qu'il y a le CRAN ?

Le CRAN (pour Comprehensive R Archive Network) est évidemment LE répertoire de packages R. Il centralise bon nombre d'entre eux, touchant à des domaines variés : statistiques, physique, mathématiques, psychologie, écologie, visualisations, machine learning, cartographie, ..., et bioinformatique. Cependant à avoir autant de variété, on s'y perd. C'est pourquoi Bioconductor a en partie été créé.

Bioconductor c'est un répertoire alternatif de packages R spécifiquement dédié à la bioinformatique créé en 2002. Akira vous le présentait en 2012 sur le blog, et huit ans plus tard, force est de constater que le projet tient toujours, et même prend de l'ampleur (cf. Figure 1). La vocation est restée la même : regrouper sous une même bannière des packages spécifiques à la bioinformatique, et notamment à l'analyse et la compréhension de données de séquençage haut débit.

Figure 1 : évolution du nombre de packages déposés sur Bioconductor

L'avantage, c'est que la visibilité de votre package est augmentée au sein de la communauté bioinfo. Et au-delà du simple répertoire, c'est également une communauté particulièrement active qui s'y rattache, avec un système à la StackOverflow.

Mais est-ce intéressant pour autant dans votre cas ? Car tout le monde n'a pas intérêt et ne peut pas déposer dans Bioconductor.

Comment savoir si on doit déposer son package dans le CRAN ou Biocondutor ?

Alors pourquoi avoir fait ce répertoire plutôt que d'avoir tout mis dans le CRAN ? Et comment choisir où votre package doit être déposé ? Quelques éléments pour vous aider :

  • Comme dit plus haut, Bioconductor est spécialisé en package pour la bioinformatique. Donc si vous développez un package avec des méthodes généralistes comme dplyr ou spécialisées dans d'autres domaines comme ecodist en écologie, visez plutôt le CRAN.
  • À l'inverse, si vous importez dans votre package d'autres package qui proviennent de Bioconductor, visez plutôt un dépôt sur celui-ci.
  • Si vous êtes prêts à assurer un support à long terme, notamment en répondant aux questions sur votre package, dirigez-vous vers Bioconductor. Sinon visez le CRAN.
  • Si vous souhaitez une publication "en production" rapide de votre package, visez le CRAN. En effet Bioconductor fonctionne avec un système de release (publication) bisannuelle (une en avril, et une en octobre). Vous avez cependant accès à une branche dites de développement en attendant la release, la bioc-devel. Sachez tout de même qu'on a déjà vu des articles sortir avec un lien vers cette branche. La branche de production ne semble donc pas être une obligation pour publier son article même si c'est recommandé (question de stabilité).
  • Le CRAN est en droit de déprécier un package car il ne convient pas avec la nouvelle release de R (en vous mettant au courant quelques semaines au plus avant de le faire). Bioconductor possède une plus grande souplesse sur ce point : si vous vous assurez qu'il fonctionne pour chaque release, il est peu probable qu'il soit déprécié.
  • Si vous avez envie de ne pas passer les tests qui cassent les gonades de Bioconductor, allez sur le CRAN

Évidemment, vous trouverez des packages de bioinformatique sur le CRAN également (ex: WGCNA), mais c'est là une occasion de manquer de visibilité au sein de notre communauté. À savoir également que rien n'est gravé dans le marbre. La preuve avec le package mixOmics qui était initialement sur le CRAN mais a été déplacé sur Bioconductor il y a un peu plus d'un an !

J'ai choisi, ce sera Bioconductor ! Mais comment ça se passe ?

Félicitations ! Mais attendez-vous à un chemin pavé d’embûches et assez éprouvant, je ne vais pas vous mentir. Une fois fini, vous verrez que le jeu en vaut la chandelle.

Note:

  • Si vous avez déjà soumis un package sur le CRAN, sautez directement à la section Les prérequis spécifiques à Bioconductor 😉
  • Si vous n'avez jamais développé de package R, laissez-moi un commentaire comme quoi ça vous intéresse. J'y consacrerai alors un autre billet de blog. En attendant, je vous laisse suivre ce très bon tutoriel pour apprendre (ou bien lire le manuel du CRAN si vous avez un côté maso... puriste).

Imaginons à présent que vous avez (ou pensez avoir) terminé votre package appelé, de façon très originale, mypkg. Il va falloir passer par plusieurs phases de pré-soumission.

Le tronc commun avec le CRAN

Pour vous assurer que votre package soit partageable à la communauté, il est nécessaire de respecter certaines bonnes pratiques, ainsi que de s'assurer qu'il soit exécutable par d'autres. Et en concret, comment on teste ça ?

Commençons par la compilation de votre package, ou build. Si vos fonctions tournent sans problème lorsque vous les exécutez à la main hors de votre package, il n'est pas assuré que celui-ci fonctionne en tant que tel pour autant !

Deux choix s'offrent alors à vous quant à la façon de procéder :

  • Vous êtes un accro du shell et de R sans IDE ? Il vous faudra faire rouler dans votre shell la commande R CMD install. Exemple : R CMD install /home/bioinfofr/dev/R/mypkg
  • Vous aimez bien Rstudio et avoir un coup de pouce ? Le package devtools est fait pour vous. C'est lui qui est utilisé derrière les boutons de build de Rstudio. Rendez-vous dans cet onglet comme en Figure 2 et cliquez sur Build Source Package.

Figure 2 : Interface de Rstudio avec la localisation de la fenêtre de build et le bouton de compilation du package source.

Si tout se passe bien, vous devriez avoir ce genre de rapport :

Et sinon... Eh bien les messages d'erreurs sont plutôt explicites sur la source du problème. Le plus souvent vous aurez simplement mal respecté l'architecture d'un package R (un dossier mal nommé, des fichiers qui traînent, etc.) ou des informations manquantes dans le fichier DESCRIPTION.

Une fois que votre package est compilé, passons aux checks (vérifications) automatiques. À nouveau, deux choix s'offrent à vous :

  • En shell : Il vous faudra faire rouler la commande R CMD check. Exemple : R CMD check /home/bioinfofr/dev/R/mypkg
  • Avec Rstudio/devtools : rendez-vous dans l'onglet build comme en Figure 3 et cliquez sur Check. Cela lance la fonction devtools::check().

Figure 3 : Interface de Rstudio avec la localisation de la fenêtre de build et le bouton de check

Une fois terminé, voici le genre de rapport que vous devriez obtenir :

Comme vous le voyez, le risque d'erreurs/avertissements est assez grand (trop grand pour que je couvre ici tous les cas !). Mais rassurez-vous, personne ne pense à tout dès la première fois qu'il développe son package. Vous finirez donc irrémédiablement avec des corrections à faire, car pour pouvoir soumettre votre package, vous ne devez avoir aucune ERROR ou WARNING. La meilleure pratique pour éviter d'avoir des dizaines de corrections à faire, c'est de tester le build et exécuter les checks régulièrement dans votre processus de développement (ça vous évitera de devoir recoder des pans entiers de votre outil car l'erreur vient d'un bout de code sur lequel s'appuient d'autres). Pensez également à mettre à jour les packages sur votre poste local car ce sont les dernières version de ceux-ci qui seront utilisées par le CRAN pour rouler les checks de leur côté (et pareil pour Bioconductor).

Les NOTEs sont quant à elles tolérées dans une certaine mesure, et cette mesure est à la discrétion de la personne qui fera la relecture critique de votre package (mais comme nous allons viser Bioconductor dans cet article, ce sont d'autres reviewers encore que ceux du CRAN).

Les prérequis spécifiques à Bioconductor

Vous avez tous vos checks qui passent ? Bien joué. Mais il va encore vous falloir passer ceux de Bioconductor ! Et c'est pas gagné.

Bioconductor est encore plus restrictif que le CRAN sur ses tests appelés BiocCheck. En effet, ils ont défini tout un ensemble de bonnes pratiques supplémentaires liées à la fois aux spécificités bioinformatiques, à la lisibilité du code, à des recommandations sur l'utilisation de telle ou telle façon de coder. Si certains de leurs partis pris sont discutables, il n'en reste pas moins que vous allez devoir vous y soumettre.

À défaut de vous les lister tous, je vais vous indiquer le minimum à respecter pour vous éviter masse de changement. L'idéal reste tout de même de les lire avant de commencer à développer votre package, car certains vont fortement impacter votre package.

  • Il va falloir définir à quelle catégorie votre package appartient : Software, Experiment Data, ou Annotation. La première est celle regroupant les outils d'analyse à proprement dit. Les deux dernières sont des packages de données aux noms assez explicites quant à leur contenu.
  • Si votre package utilise des données classiques en bioinfo (matrices gènes X échantillons, FASTA, VCF, spectro de masse, etc.) sachez que vous devrez au moins rendre compatible votre package avec les common classes de Bioconductor. Ces formats sont une tentative de standardisation de l'input dans les packages de ce dépôt.
  • Si c'est un Software, votre package final devra faire moins de 5Mo. Attention donc aux jeux de données d'exemple que vous insérez dedans. Si jamais vous souhaitez inclure des données plus grosses, on vous conseille de soumettre un autre package de type Experiment Data, ou Annotation et de l'appeler dans votre package.
  • Il devra être compatible Linux ET Windows ! Mauvaise idée donc de se baser sur des spécificités de votre OS. Ou alors préparez-vous à devoir développer un équivalent dans l'autre OS.
  • Toutes vos fonctions/données doivent être documentées ! Et pas seulement avec une rapide description. On parle d'une explication des paramètres, d'une valeur retour, et surtout d'un exemple exécutable fonctionnel.
  • Il faudra écrire une vignette, ce document faisant office d'introduction à votre package et de tutoriel. Il est nécessaire qu'on passe à travers un maximum des fonctionnalités de votre package, l'idéal étant d'y réaliser une analyse type, sur de véritables données ou des données simulées.
  • Les tests unitaires ne sont pas obligatoires d'après leur guidelines, mais soyez assurés qu'ils vous les demanderont tout de même pour la majorité de vos fonctions au moment de la revue. Mais en tant que bioinformaticien consciencieux vous les auriez déjà faits n'est-ce pas 😉 ?
  • Vous devez être inscrits au site de support de Bioconductor et abonné à la liste bioc-devel

Vous pensez avoir respecté ces recommandations ainsi que la liste complète sur leur site ? Passons à la vérification ! Tout d'abord, installez le package BiocCheck car les checks de Bioconductor ne se trouvent pas nativement dans l'install de R. Ensuite, lancez-le depuis votre session R en vous assurant d'avoir votre working

Des erreurs/warnings vont à nouveau s'afficher, et recommence le jeu de la correction en fonction des messages donnés.

À savoir que même si les NOTEs sont en théorie acceptées, il suffit que vous tombiez sur un reviewer un peu zélé pour que vous deviez également les corriger entièrement. Voici un exemple de rapport BiocCheck :

Comme vous le voyez il reste des NOTEs, libre à vous de choisir de les corriger à présent ou attendre de voir si le reviewer vous l'impose (personnellement j'ai perdu à ce jeu comme vous pourrez le voir dans la section Retour d'expérience personnelle).

Le processus de soumission à Bioconductor

Tout semble bon ? Ça compile ? Vous passez tous les checks ? Bien, passons à la soumission de votre package.

  • Si ce n'est pas déjà fait, poussez votre package sur GitHub (et si vous n'y connaissez rien à git, lisez cet article 😉 ). C'est en effet l'hebergeur qu'a choisi Bioconductor pour gérer la soumission et le suivi du développement des packages (mais rien ne vous empêche d'avoir votre repo sur un GitLab, Bitbucket, etc. à côté bien évidemment).
  • Créez une issue sur le repo Contributions de Bioconductor en suivant le guide fournit. Rajoutez un petit bonjour et une phrase rapide de description, ça ne mange pas de pain non plus.
  • Créez un webhook pour votre repo. Cela va permettre au bot qui gère l'automatisation des soumissions d'être informé qu'il y a un nouveau package à aller chercher, et par la suite ça permettra qu'il soit informé quand vous effectuez des modifications sur votre repo (correction de code, ajout de nouvelle fonctionnalité...).
  • Ajoutez une clef SSH publique. Elle sera utilisée pour copier votre repo une fois votre package accepté.
  • Attendez... Votre package va être tagué comme "1. awaiting moderation'" en attendant, comme c'est dit dans le tag, qu'un reviewer soit assigné et vienne estimer si votre package vaut le coup d'être ajouté à Bioconductor.
  • Si sa pertinance est jugée bonne, le tag changera pour "2. review in progress" et le bot commencera alors à re-exécuter tous les checks que vous avez en théorie déjà passés haut la main.
  • Et là… Peu importe si vous avez mis tout votre cœur, sueur et temps dans vos checks, peu importe que ça roule sur votre PC et votre VM pour l'autre OS, vous allez avoir des erreurs ! Murphy, si tu nous entends…
  • Le bot va taguer votre issue avec ERROR ou WARNINGS ainsi que vous donner un lien vers un rapport détaillé des tests et erreurs obtenues pour chacun des OS (voir Figure 4, attention, ça pique les yeux). Et si Murphy vous a épargné, sautez directement trois points plus loin (ne passez pas par la case départ, ne touchez pas 20K).
  • Commence alors un nouveau cycle d'essai/erreur pour la correction des derniers soucis qui sont apparus. Cependant, pour que le bot prenne en compte les modifications, il vous faudra incrémenter la version de votre package. Vous commencez normalement à 0.99.0 (format imposé par Bioconductor) et à chaque modification que vous poussez et où vous souhaiterez une évaluation, il faudra passer à 0.99.1, 0.99.2, etc.
  • Notez que si le bot détecte des modifications poussées mais pas d'incrément, il taguera votre issue avec "VERSION BUMP REQUIRED". Il est donc de bonne pratique d'effectuer vos modifications sur une autre branche que le master, puis de merger avec le master quand vous avez fini votre modification et fait repasser tous les tests. Je ne saurais que trop vous recommander un modèle de branches git de ce type. Attention, n'incrémentez la version qu'après le merge, sinon le bot ne déclenche pas un nouveau build.

Figure 4 : Exemple d'un rapport de build que vous donne le bot Bioconductor en lien dans votre issue sur GitHub

  • Une fois toutes les modifications faites pour n'avoir aucunes erreurs et le précieux tag "OK", votre reviewer va évaluer votre package. C'est notamment à ce moment-là que vous verrez s'il vous demande d'adresser les NOTEs laissées, si vous ne suivez pas des guidelines non testées automatiquement comme l'utilisation des common classes. Il vous demandera probablement des modifications, et vous repartirez pour un nouveau cycle d'essai/erreur.
  • Enfin, une fois tout cela fini, l'encore plus précieux tag "3a. accepted" vous sera normalement attribué et votre package sera ajouté au repo de Bioconductor. Il sera alors publié avec la prochaine release à venir.
  • Si pour une raison ou une autre votre package était tagué "3b. declined", n'hésitez pas à communiquer avec les reviewers pour en connaitre la raison.

Vous pouvez souffler, c'est fait ! À présent, il ne vous reste plus qu'à savourer votre victoire, et vous assurer à chaque release de Bioconductor (2 fois par an donc) que votre package compile toujours et passe les checks.

Retour d'expérience personnelle et astuces

Avant de vous laisser avec quelques conclusions, je voudrais vous apporter rapidement quelques points basés sur un ressenti personnel de cette "expérience" :

  • Le processus est LONG, et c'est un euphémisme. Entre les checks de base qui ne passent pas, puis ceux de BiocChecks, il y a déja pas mal de temps passé à corriger le code, et je les passais pourtant régulièrement au cours de mon développement ainsi que mes tests unitaires + la même chose sur ma VM Windows. Quand une fois fini j'ai vu de nouvelles erreurs s'afficher dans le rapport du bot de Bioconductor, j'ai ragé assez fort... Je maintiens que la fonction BiocCheck devrait intégrer ces tests supplémentaires effectués sur leurs serveurs...
  • Si vous visez une release en particulier, prenez-vous-y à l'avance de facilement 1 à 2 mois. Les reviewers sont surchargés sur la fin et mettent du temps à faire les reviews. Le mien n'a d'ailleurs donné de signe de vie que deux semaines après la date buttoir de dépôt, me laissant moins de 5 jours pour corriger les nombreuses remarques qu'il m'a faites. J'ai finalement loupé la release…
  • J'ai aussi eu la malchance de tomber en plein changement de version majeure de R (3.6 -> 4.0) sur laquelle vous devez tester votre package, alors que la release officielle n'est pas encore disponible. À vous les joies de la compilation de la R-alpha ! Ou sinon vous faites les bourrins et vous vous servez du rapport d'erreur du bot Bioconductor mais c'est pas mal plus lent de faire les allers-retours, et je préfère avec un master (un peu) propre.
  • Mettez vos packages à jour avant de pousser sur Bioconductor, vraiment. Ça évite de ronchonner sur votre reviewer en disant que vous n'arrivez pas à reproduire ce bug magique qui n'existe que sur leurs serveurs et sur aucune de vos VM (et donc éviter de passer pour une andouille).
  • Pour ceux qui développent sous Linux et ne veulent pas se prendre la tête avec une VM, il existe win-builder. Vous pouvez d'ailleurs l'utiliser directement dans devtools avec la fonction check_win_release(). Je ne l'ai découvert qu'après avoir monté ma VM et compilé la R-alpha dessus...
  • À la relecture, Guillaume m'a parlé de R-hub. C'est une version plus poussée de win-builder qui vous permet de faire les checks sur sur une grande variété d'OS et de versions de chacun. Très utile aussi donc 😉
  • Certains reviewers sont mieux que d'autres : le mien était particulièrement désagréable dans sa façon de parler et assez zélé. Il m'a obligé à corriger l'intégralité des NOTEs. Mais d'autres sont charmants et comprennent que certaines NOTEs ne justifient pas un refus du package.

Conclusion

La soumission d'un package de Bioconductor est une épreuve en soi. Il y a de quoi se décourager à de maintes reprises, mais le résultat est là : un package visible par toute la communauté bioinfo. Il sera donc plus facilement partageable et pourra potentiellement devenir incontournable dans votre domaine.

Bon courage à vous si vous vous lancez dedans !

Merci à mes relecteurs Guillaume, lhtd, et neolem pour la relecture de cet article assez dense !

Références

  • À propos de
  • Doctorante rousse à vocation bioinformatique / biostatistiques, je suis admin de bioinfo-fr depuis 2017, et ex-trésorière de JeBiF. Après un parcours assez inhabituel (BTS Bio, Licence Stats/Info, Master BIBS de l'U. Paris Sud/Polytechnique), je suis actuellement en doctorat au CHU de Québec/U. Laval au Canada où je travaille dans le cadre de ma thèse sur les réseaux de co-expression appliqués au vieillissement de la peau.

2 commentaires sur “Pourquoi et comment déposer un package R sur Bioconductor ?

  1. Super article Gwen ! Ça sent le vécu et le retour d'expérience qui sera surement très utile à d'autres. J'ai hâte de découvrir ton package quand tu pourras enfin communiquer dessus. Bon courage !

Laisser un commentaire