Org mode, un compagnon de route pour les adeptes de data science et de recherche reproductible

Quelques mots sur Org mode

En très peu de mots, Org mode pourrait être présenté comme le cousin germain des Jupyter notebooks. Org mode et les notebooks créés via Jupyter lab représentent 2 solutions particulièrement intéressantes et matures dans un contexte de recherche. Les interfaces interactives créées via Org mode et les Jupyter notebooks permettent à leurs utilisateurs de : développer, documenter (Markdown, HTML/CSS), gérer des citations BibTeX ou des équations, exécuter du code, à partir d’un seul et même document. 

Grâce à Babel, Org-mode permet donc d’exécuter des blocs de code à partir d’un même fichier texte. Fortran, Python, R, des scripts de traitement en Bash, des formules LaTeX, des images. 

Quels sont les avantages de ce type de solution pour des chercheurs.euses et des data scientists ?

(merci à Frédéric Santos – statisticien à l’UMR Pacea – et Christophe Halgand – ingénieur de recherche en calcul scientifique à l’Institut de Neurosciences Cognitives et Intégratives d’Aquitaine – pour leurs avis éclairants)

  • générer plusieurs formats d’exports à partir d’un même fichier : pratique pour créer des pages web facilement intégrables dans un site web
  • bénéficier des avantages de LaTeX … la complexité du langage en moins pour gérer des références internes, de la biblio
  • présenter des résultats sous forme de diaporamas qu’on peut modifier en direct : les visualisations comme les calculs sont mis à jour directement
  • créer des démonstrations permettant de répondre à un point spécifique (ex. démonstration mathématique), créer des tutos pour donner la possibilité d’interagir avec le code mais aussi de figer facilement les données en créant une page html
  • concevoir des supports pédagogiques interactifs
  • quand on est en situation de prise de notes : pouvoir créer des modules de code interactifs
  • rédiger des articles plus reproductibles : certes, un outil ne fera jamais tout car la méthode joue un rôle majeur, mais Org mode peut rendre de fiers services

Org-mode, un outil pour les happy few ? Pas vraiment, Org mode peut séduire un large public :

Whether you are a statistician or data scientist or algorithm/software developer, you will benefit from this elegant open-source tool for efficient and robust reproducible research. I will outline my favorite set-up (Virtual Machine, Linux, Emacs, LaTeX, CDLaTeX, R, ESS) and demonstrate its potential in statistical analysis and algorithm development.

(Chen 2018)

Org mode : vers la rédaction d’articles plus reproductibles. Échanges avec Frédéric Santos, R-addict et statisticien (UMR Pacea)

R-addict et statisticien, Frédéric Santos exerce ses missions au sein de l’unité mixte de recherche Pacea (De la préhistoire à l’actuel). Fr. Santos est chargé d’analyser, de définir et de mettre en œuvre les outils statistiques et informatiques pour la gestion et le traitement des données dans le cadre des projets de recherche de l’unité Pacea. Il anime également des formations à la statistique. 

Propos recueillis par Sabrina Granger, Urfist de Bordeaux

Comment se servir d’Org mode tout en appliquant les consignes impartis par les éditeurs aux auteurs ? Ne s’expose-t-on pas à des problèmes de non interopérabilité ? 

Tous les journaux acceptant les manuscrits en format LaTeX et fournissant des templates LaTeX sont compatibles. C’est le cas de toutes les revues PLOS, de Nature, de PNAS, à priori de toutes les revues Elsevier et Springer, etc. Il n’y a que chez Wiley que beaucoup de journaux n’acceptent que des manuscrits au format Word, parfois en plus avec des exigences de mise en forme fantaisistes… dans un tel cas, en effet, c’est pratiquement incompatible avec l’utilisation d’Org mode (ou alors, les difficultés liées au respect de la mise en forme deviennent supérieures aux bénéfices tirés de l’utilisation d’Org mode).

En fait, tout fichier Org mode peut être exporté en LaTeX en utilisant une classe LaTeX externe. Si l’éditeur la fournit (et fournit aussi un .csl ou un .bst pour le style biblio), c’est gagné : il n’y a rien de spécifique à faire.

Il faut aussi noter que de nouveaux systèmes de publication se développent en dehors du giron des éditeurs classiques, comme les “Peer Community In” (NDLR : voir aussi les supports du workshop 2018 Urfist de Bordeaux sur le peer review) . Comme il s’agit d’un système de peer-review sur la base de preprints déposés sur arXiv ou bioRxiv, l’auteur a toutes les libertés imaginables en termes de mise en forme, et peut employer les outils qui lui plaisent sans se soucier de leur compatibilité avec les normes des éditeurs.

Sous quel format le fichier est-il envoyé à la revue, quels formats de sortie peut-on gérer ? 

Par exemple chez Elsevier ou Springer, le manuscrit initial peut être envoyé comme un simple PDF, sans fichier source éditable. Un fichier source éditable doit ensuite être fourni avec la première révision. On peut alors envoyer le fichier PDF généré par Org mode (qui sera consulté par les reviewers), ainsi que le fichier .tex (qui sera utilisé par l’éditeur) exporté à partir du document Org mode. Tout ce que souhaitent les éditeurs, c’est d’avoir un .tex éditable : peu importe si le fichier .tex a été tapé directement en LaTeX, ou converti/exporté en LaTeX depuis un fichier Org mode, Rmarkdown ou Jupyter.

Puis-je facilement revoir le manuscrit collaborativement avec ce type de solution ? 

Oui et non ! Si les co-auteurs connaissent eux aussi Org mode (ou Rmarkdown) et Git, on peut faire un petit dépôt GitLab ou GitHub pour orchestrer et coordonner tout ça. Mais ce n’est pas encore répandu dans toutes les disciplines.

Si aucun autre co-auteur ne connaît ces outils et qu’aucun ne veut/peut les apprendre, alors une solution est de faire le manuscrit en Rmarkdown, d’exporter le Rmarkdown en Word, de transmettre le Word aux co-auteurs, et ensuite d’utiliser le package R “redoc” qui permet de répercuter automatiquement sur le fichier Rmarkdown les modifications faites dans le Word. 

C’est à l’heure actuelle la seule solution qui existe pour travailler “en mode notebook” avec des co-auteurs qui ne veulent pas le faire ; il n’existe encore aucun équivalent en Org mode ou Jupyter à ma connaissance.

Soumettre un papier de cette manière, ça change surtout la vie des reviewers ou celle de l’auteur ?

Clairement les deux ! 

Pour l’auteur, écrire un article en Word est une galère abominable ; écrire un article en Rmarkdown ou Org mode tient presque du plaisir (je suis sérieux !). En plus, on est sûr de ne pas écrire de bêtises, on gagne du temps en s’assurant que toute modification faite en cours de route sur les données sera automatiquement répercutée sur l’ensemble des résultats sans avoir rien à faire, on a absolument tout dans le même fichier (texte, code, figures, tables, résultats, et même lettre à l’éditeur, réponse aux reviewers, et même mails envoyés par des collaborateurs si on veut !), etc

Org mode a également la particularité d’offrir des fonctionnalités de gestion de projet pour planifier très précisément l’avancée du travail. On peut établir un planning, fixer des dates limites par tâche, mettre des “timers”, des priorités, des tags, des statuts, suivre le % d’avancement pour chaque tâche, etc. Bref, tout devient plus simple, et complètement centralisé. Un dernier avantage évident pour l’auteur : on gagne fortement en potentiel de citation, parce que l’article devient à la fois plus “crédible” et transparent, et parce qu’il sert également d’exemple auquel d’autres chercheurs peuvent se référer.

Pour les reviewers, cela les prédispose très favorablement à faire des commentaires plus agréables sur le papier, et cela leur garantit aussi que l’auteur ne “triche” pas sur ses données (cela leur épargne aussi des vérifications manuelles).

Org mode, c’est ok pour un papier, mais quid d’un livre ou une thèse?

Voici un exemple de livre écrit à 100% en Org mode. Il n’y en a pas encore énormément à ma connaissance, mais Org mode est très clairement l’outil le plus adapté à la rédaction de documents très longs mêlant texte, code informatique, et résultats de ce code. Pour des documents très courts ou des petites notes/présentations, Jupyter peut être une solution plus légère.

Une seconde alternative, ciblant spécifiquement les manuscrits de thèses, est le package R Huskydown, , voir le template de l’Université George Washington :

This project provides a template for writing a PhD thesis in R Markdown, and rendering those files into a PDF formatted according to the requirements of the University of Washington. It uses the University of Washington Thesis class to convert R Markdown files into a PDF formatted ready for submission at UW. This project was inspired by the thesisdown and bookdown packages. Currently, the PDF and gitbook versions are fully-functional, and are the focus of this package. The word and epub versions are in development, have no templates behind them, and are essentially calls to the appropriate functions in bookdown. If you are new to working with bookdown and rmarkdown, please read over the documentation available in huskydown PDF template (which you can create by following the simple instructions below) and the bookdown book. Under the hood, the University of Washington Thesis LaTeX template is used to ensure that documents conform precisely to submission standards. At the same time, composition and formatting can be done using lightweight markdown syntax, and R code and its output can be seamlessly included using rmarkdown

Découvrir Org mode

Chen, Feiming. 2018. ‘Organizing Research Projects with an Efficient Open-Source Tool (Emacs Org-Mode)’. presented at the Washington  Statistical Society, October 23. http://washstat.org/presentations/20181024/Chen_F.pdf.

Schulte, Eric, and Dan Davison. 2011. ‘Active Documents with Org-Mode’. Computing in Science & Engineering 13 (3): 66–73. https://doi.org/10.1109/MCSE.2011.41.

Stanisic, Luka, Arnaud Legrand, and Vincent Danjean. 2014. ‘An Effective Git And Org-Mode Based Workflow For Reproducible Research’. Operating Systems Review 49: 61–70. https://doi.org/10.1145/2723872.2723881.

Se former

07/04/2020, Bordeaux (campus de Talence) : Meet up : Org mode versus Jupyter lab (notebooks). Tu crois que tu sais interagir avec du code ?

Tutoriel de Frédéric Santos