Hypotheses.org

— Billet écrit avec Florent Bédécarrats

Ce texte vise à présenter l’écriture en RMarkdown, une alternative à Word qui possède de nombreux avantages, dans un contexte actuel complexe pour l’édition scientifique. RMarkdown est une syntaxe, avec laquelle on peut écrire des textes structurés et les transformer ensuite en différents formats (PDF, .docx, HTML) à l’aide d’un logiciel, ici RStudio. Cette philosophie, qui dissocie le contenu du texte et sa mise en forme, est proche de celle de LaTeX, dont RMarkdown reprend les avantages et en évacue la plupart des défauts. De plus, écrire en RMarkdown permet d’intégrer des traitements effectués avec R, tout en favorisant la reproductibilité des calculs. En fin de compte, c’est une solution qui s’approche de la facilité d’utilisation de Word, tout en offrant des avantages nombreux.

Une première partie discute pourquoi l’utiliser, une seconde s’attache au comment. Alors qu’il existe de nombreux articles sur internet présentant la syntaxe RMarkdown, on entre ici dans le détail des coûts de transition en provenance de Word, et de la manière concrète de réaliser l’ensemble des opérations courantes d’écriture.

Pourquoi écrire en RMarkdown ?

L’édition scientifique fait aujourd’hui face à plusieurs transformations : réduction des budgets et des «personnels de renfort» éditoriaux, transition des supports vers le numérique, et crise de la reproductibilité des résultats. Chacune conduit à des évolutions des besoins des éditeurs, donc aussi par contrecoup des auteurs. Alors que Word est l’outil et le format standard pour les textes de sciences sociales depuis les années 1990, RMarkdown apparait mieux adapté à la situation contemporaine.

Quelques problèmes (techniques) de l’édition scientifique aujourd’hui

Depuis les années 1990, les outils de composition des textes se divisent en deux camps, dont les grandes figures sont Word et LaTeX. Le premier se caractérise par la composition directement visuelle du texte : on écrit et on voit, en le faisant, le résultat qui sera imprimé. Le second s’appuie au contraire sur l’idée d’une dissociation du fond et de la forme : en LaTeX, l’écriture s’effectue dans un fichier où on indique le texte et les instructions de mise en forme, et que l’on transforme ensuite en d’autres formats, souvent PDF, par un programme qui se charge de la mise en page. Le modèle Word s’est imposé dans les sciences sociales, le modèle LaTeX dans d’autres disciplines. Aujourd’hui un ensemble de problèmes amènent à remettre en cause cette partition et, nous concernant, l’hégémonie du modèle Word.

Réduction de la division du travail dans l’édition scientifique

Halbwachs noircissait des feuilles volantes, Pasteur des feuillets colorés, Proust collait ses paperolles, Wittgenstein écrivait à voix haute, Pasolini chérissait son Olivetti. Et des secrétaires, correcteurs, typographes, iconographes, éditeurs et imprimeurs en faisaient des livres.

L’édition d’avant les années 1990 apparaît aujourd’hui comme revelant d’un autre monde. Dans le domaine scientifique, une majorité de chercheurs écrivaient à la main, traçaient leurs graphiques sur papier millimétré, avant de transmettre leurs manuscrits à des secrétaires qui le dactylographiaient, transféraient les graphiques sur papier calque et devaient changer les touches de leur machine à écrire pour intégrer les formules mathématiques. Le tout étant copié en plusieurs exemplaires grâce à du papier carbone.

L’informatisation dans les sciences sociales, combinée au resserrement des budgets, a conduit à la fin de cette division du travail. Comme chaque auteur possède un ordinateur capable de réaliser toutes ces opérations, on attend de plus en plus qu’il réalise les tâches auparavant déléguées à ces personnels.

À ces problèmes d’organisation du travail, s’ajoutent ceux relatifs aux supports de publication. On se trouve au milieu d’une transition vers le web, sans que le papier soit nécessairement amené à disparaître. On doit donc gérer la coexistence de ces deux supports, qui sont structurés par des technologies de rendu différentes. Les revues de sciences sociales fonctionnent encore largement avec Word, et le formatage des articles, en particulier pour le web, leur demande, ainsi qu’aux auteurs, un travail de mise en forme effectué «manuellement» ou avec un convertisseur ad hoc. À l’inverse, le modèle LaTeX, qui sépare fond et forme, minimise le travail technique d’édition : comme le texte est séparé de sa mise en forme, et contient les indications de sa structure, il est aisé de le transformer en différents formats grâce à des programmes existants. Les revues fonctionnent avec des budgets toujours plus restreints pourraient donc être amenées à s’orienter vers des modèles plus économes en travail d’édition et de mise en page.

Crise de la reproductibilité et évolution des demandes des revues

Des débats plus épistémologiques, qui se sont cristallisés autour de la question de la reproductibilité, poussent également à des modifications des formats d’écriture demandés aux auteurs.

Ces dernières années, s’est développé un ensemble de critiques du processus de production des résultats scientifiques. La révision par les pairs, qui en est une institution centrale, a vu depuis le début des années 2010 sa fiabilité sérieusement remise en cause, d’abord en médecine, puis en psychologie, en économie et en sociologie. Si auparavant des résultats publiés ont pu être décriés comme frauduleux, et leurs auteurs pointés du doigt, la critique se porte désormais plus sur le processus de véridiction lui-même. Des enquêtes ont montré que la majorité des résultats publiés dans les revues de référence de ces disciplines ne pouvaient pas être reproduits. Ce problème est constitué en problème public, et fait l’objet de débats dans les grandes revues scientifiques ainsi que de rapports publics.

On distingue la reproductibilité empirique, l’obtention de mêmes données si on répète une expérience, de la reproductibilité analytique, obtenir des mêmes résultats si on fait les mêmes calculs. Une partie des réponses apportées jusqu’à maintenant consistent à modifier les pratiques éditoriales afin d’améliorer la reproductibilité analytique. Les revues d’économie, ou l’American Journal of Political Science, demandent désormais, lors de la soumission d’articles, à ce que l’auteur communique en même temps les données et les calculs effectués, pour que la revue puisse tenter de reproduire elle-même les résultats revendiqués.

S’il n’est pas certain qu’une couche supplémentaire de positivisme soit la solution ultime aux problèmes de ce monde, et si ces évolutions posent par ailleurs de nombreuses questions), ces demandes appellent néanmoins à ce que les fichiers transmis aux revues contiennent les calculs produisant les résultats revendiqués. Ceci est assez facile avec une écriture qui dissocie le fond et la forme, mais pas en Word.

Dissocier le fond et la forme – sans avoir à «programmer son texte»

Dans ce contexte, le modèle Word apparait de moins en moins bien adapté. La dissociation de la forme et du fond gagne au contraire en pertinence. Le modèle LaTeX est lourd, mais RMarkdown en possède les avantages sans la plupart des inconvénients.

Est-on si bien avec Word / LibreOffice ?

Le modèle Word a pour avantage l’apparence de la simplicité et de la facilité d’accès : on écrit, le résultat est immédiat. Cependant, pour les documents complexes comme les travaux scientifiques, cet attrait initial masque des difficultés que l’on doit bien souvent résoudre à la fin de l’écriture, rarement le moment idéal. Parmi les coûts cachés du modèle Word, on peut citer :

La mise aux normes typographiques : les doubles espaces, espaces insécables demi-espaces insécables avant les signes de ponctuation, etc., sont à vérifier soi-même

La table des matières : à re-valider à chaque modification du plan, et bien sûr besoin de structurer le texte

Les références à des figures, tableaux ou chapitres/sections, sont souvent écrites «à la main», et lourdes à modifier

Certains écrivent leur bibliographie à la main, parfois à la demande des revues

Sur certains systèmes, le logiciel est lent, et a du mal à traiter de gros fichiers

Le modèle LaTeX possède des avantages et inconvénients très différents.

Pourquoi ne pas écrire en LaTeX alors ?

Utiliser LaTeX permet de résoudre l’ensemble de ces problèmes. Les détails typographiques, comme la table des matières, les références croisées ou la bibliographie, sont pris en charge et générés automatiquement. La fin de l’écriture est beaucoup plus tranquille, et la mise en page est calculée pour se conformer à un ensemble de normes d’esthétique, ce qui rend les textes agréables à lire. Enfin, les fichiers de travail présentent l’avantage d’être en texte, donc très légers, universellement portables et robustes.

Les coûts d’utilisation de ce modèle se paient plutôt au début, à l’apprentissage. De plus, LaTeX présente les difficultés suivantes :

Ce n’est pas un logiciel mais un langage ; on doit utiliser deux logiciels, l’un pour écrire le texte, l’autre pour le mettre en page

On ne voit pas le résultat directement pendant l’écriture

Il faut écrire son texte comme un programme informatique, avec des balises un peu lourdes pour signaler les instructions de mise en forme

Les relectures et travail collaboratif passent par des PDF ou des versions papier, difficilement par le «suivi des modifications» type Word

Pour utiliser une nouvelle fonctionnalité, il faut chercher de l’aide dans les manuels ou sur internet

On comprend ainsi que ce modèle ne se soit pas imposé dans les sciences sociales françaises, en particulier dans la période d’informatisation des années 1990, où la tendance dominante était le retour de l’ethnographie, au terrain et aux «vrais gens», plutôt qu’un rapprochement avec les méthodes statistiques, la programmation et autres «truc de geek», devenus à la mode ces dernières années.

Notons au passage que dans les années 2000 a émergé un outil, LyX, qui se situe à mi-chemin entre LaTeX et RMarkdown. Il simplifie l’écriture d’un fichier LaTeX tout en proposant une interface avec des menus et une présentation du texte qui s’approche de la version finale. Il possède un ensemble d’extensions permettant de répondre à des besoins disciplinaires spécifiques (en linguistique par exemple). S’il est parfaitement utilisable en sciences sociales, il reste orienté vers l’impression papier, et garde certaines limitations comme l’écriture collaborative, la faible lisibilité brute des fichiers contenant le texte et les instructions de mise en page, et la publication sur le web.

RMarkdown : le meilleur des (deux) mondes ?

Écrire en RMarkdown offre, en revanche, un ensemble d’avantages de ces deux familles, tout en minimisant leurs inconvénients.

Tout d’abord cela demande moins de soin qu’en Word. Il faut seulement indiquer la structure du document, à savoir les titres, sous-titres, etc. Mais la typographie est prise en charge automatiquement : impossible de trouver dans le document final de double espace, de signe de ponctuation en début de ligne ; pas besoin non plus de se soucier de la table des matières, des renvois entre sections ou des références à des figures et tableaux. La prise en charge de ces aspects de mise en page permet de se concentrer sur l’écriture elle-même.

Ensuite, les fichiers de travail sont de simples fichiers texte. Ils ont l’avantage d’être aussi légers que possible, et robustes. Ils sont nettement mieux adaptés à ce qui s’appelle le suivi des versions (voir plus bas). Enfin, travailler avec de tels fichiers amène à utiliser des logiciels que l’on appelle des éditeurs de texte (et pas des traitements de texte comme Word). Utilisés par les informaticiens, ils peuvent être simples d’accès tout en permettant d’effectuer des opérations complexes sur le texte (comme du rechercher-remplacer avec des expressions régulières, plus puissantes que les fonctions équivalentes de Word) : tout est texte, donc il est facile de chercher des éléments de texte formaté, comme des mots en gras, les notes de bas de page, etc. Également, ils gèrent sans problème des fichiers lourds, tout en consommant peu de ressources matérielles (processeur, batterie, etc.).

En revanche Word est plus performant pour la correction automatique de l’orthographe et de la syntaxe, et plus intuitif pour le suivi des modifications en écriture collaborative. Cependant rien n’empêche de l’utiliser en combinaison avec un éditeur de texte, seulement pour ces fonctions où il est le plus efficace.

Comment réaliser les opérations habituelles en pratique

Bon, comment faire en pratique ? On présente ici comment écrire en RMarkdown, et produire des fichiers (PDF, Word ou HTML) avec RStudio, en pensant particulièrement à ceux qui ont l’habitude de Word + Zotero.

Bases de l’utilisation de RMarkdown avec RStudio

RMarkdown est une syntaxe, qui appartient à la famille des Markdown. La syntaxe de base, celle du Markdown original, a été conçue dans un double objectif : écrire des fichiers texte avec un formattage lisible, et qui soit facilement convertibles pour la publication web. Elle contient des éléments simples : des niveaux de titres, du gras et de l’italique, des liens hypertexte, des listes. Un ensemble de variantes de cette syntaxe ont été créées pour ajouter des fonctionnalités, tout en gardant le même esprit de lisibilité. Parmi elles, le Pandoc Markdown est très riche, et constitue la base de RMarkdown (Pandoc est un utilitaire qui convertit des fichiers textuels entre différents formats).

La production d’un texte mis en page requiert deux étapes : la saisie, et la mise en page (compilation). On peut utiliser deux logiciels différents pour ces deux opérations. Cependant on peut aussi, pour commencer, travailler uniquement avec RStudio, qui permet de faire les deux. On vous conseille donc d’en installer la dernière version. Le grand avantage de RStudio est que l’étape de compilation peut demander plusieurs logiciels, qu’il est un peu difficile d’installer et d’utiliser (Pandoc, LaTeX), mais RStudio s’occupe de tout cela et masque la complexité à l’utilisateur, qui n’a pas à s’en soucier.

Produire le document : appuyer sur un bouton dans RStudio

Pour donner une idée de ce processus, commençons par un premier test, avec du texte sans formatage.

Dans RStudio, créez un nouveau fichier RMarkdown (à choisir dans le menu Fichier). Des éléments de démonstration sont présents. Dans les premières lignes, entre deux lignes de tirets, on trouve les métadonnées du document (titre, auteur, date) et des options de mise en page. Ces éléments seront automatiquement intégrés dans le document final. Pour ce billet, ces lignes sont :

Ensuite, vous pouvez écrire le texte que vous voulez, puis cliquez sur «Knit to PDF/Word/HTML» («tricoter» dans le format que vous voulez) et vous obtenez le résultat. En cas de problème à cette étape, n’hésitez pas à réinstaller la dernière version de RStudio.

Une syntaxe minimaliste

Pour produire un document plus riche, il faut indiquer là où vous voulez des titres et de la mise en forme du texte. La syntaxe de base du RMarkdown est celle de Markdown.

On écrit :

Cela s’affichera comme des titres, et sera intégré comme tel dans la table des matières.

Pour le texte, un astérisque (*) encadre des caractères *en italique*, deux donnent des caractères **en gras**.

On peut également créer des listes, à un ou plusieurs niveaux, qui peuvent être numérotées ou non :

On peut enfin intégrer du texte cité, qui sera mis en page différemment du corps du texte, en le faisant commencer par un signe > :

Des lignes consécutives sont considérées comme un même paragraphe. La séparation entre deux paragraphe est créée par une ligne vide. On peut également forcer un retour à la ligne en finissant une ligne par deux espaces (ou plus).

Voilà pour les bases. L’écriture scientifique requiert également des fonctions plus complexes : notes de bas de page, tableaux, figures, citations bibliographiques, références croisées… Il est bien sûr possible de les gérer en RMarkdown.

Des objets plus complexes : notes de bas de page, images, tableaux, encadrés

Il existe deux manières d’écrire une note de bas de page. La première est d’exprimer directement son contenu, entre crochets et avec un signe ^, comme ceci : [^Texte de la note.]. La seconde, plus adaptée pour les notes longues, définit un appel de notes avec [^…], et plus loin un paragraphe qui en spécifie le contenu avec le même crochet suivi de deux points, [^…]:, où ici … doit être remplacé par un identifiant de votre choix. Par exemple, ces deux morceaux de code sont équivalents :

On peut également insérer des images et des liens HTML :

Les tableaux seront produits par R, dans l’idéal, soit comme produits d’un calcul, soit comme résultats de l’importation en R d’un fichier de tableur (.xls ou .csv). Pour la mise en forme, en l’absence d’option spécifique, le résultat sera une sortie brute avec une police «informatique» (à largeur fixe). Pour obtenir des tableaux plus doux à l’œil, le plus simple est d’utiliser la fonction kable() du package knitr, par exemple :

Si on veut écrire des tableaux directement en RMarkdown, il existe la syntaxe suivante. Noter que la ligne entre les en-têtes et le contenu indique l’alignement dans la colonne.

Auteur

Package

Année

Yixui Xie

knitr

2012

Hadley Wickham

ggplot2

2005

On peut s’aider d’un utilitaire comme TableFlip sous macOS, ou d’un plug-in pour éditeur de texte, comme TableEditor pour SublimeText.

Quant aux encadrés, ils peuvent être générés de plusieurs manières. La solution de facilité est d’utiliser le mode citation (lignes qui commencent par >) et de tracer des barres horizontales en haut et en bas de la zone d’encadré. Cette technique ne dessine pas de barres latérales, mais ça peut faire l’affaire. Une barre horizontale s’écrit avec trois tirets (ou plus) sur une ligne isolée :

Le statut des bouilleurs de cru

Distinct de la profession de distillateur, le statut de bouilleur de cru, soit le droit de produire soi-même de l’eau-de-vie, est accordé aux propriétaires récoltants, et de manière résiduelle aux bouilleurs ambulants (porteurs d’un quota de droit à distiller, non-transmissible depuis 1959).

Pour de véritables encadrés, en l’état actuel il est plus simple d’utiliser des fonctions spécifiques au format de sortie désiré. Pour des PDF, il est possible d’insérer du code LaTeX brut. Si on veut utiliser le package mdframed, appeler le package dans les en-êtes du fichier .Rmd en insérant les lignes suivantes (en respectant les espaces) :

puis commencer les encadrés par \begin{mdframed} et les terminer avec \end{mdframed} (au lieu des > ---).

Pour une sortie HTML, on peut insérer du HTML brut. Par exemple :

Donne :

Texte à encadrer.

L’ensemble des fonctions disponibles sont résumées dans ce document, dont les versions plus complètes se trouvent aux liens suivants pour RMarkdown et pour le Pandoc Markdown, dont les fonctions sont utilisables en RMarkdown.

Feuilles de style

Pour configurer les options de mise en page (polices, marges, en-têtes, etc.), il suffit d’indiquer un fichier spécifiant ces options, ce qui s’appelle une feuille de style. Il faut la placer dans le même dossier que le fichier de travail, et préciser son nom dans les en-têtes du document.

Pour une sortie en format Word (.docx), la feuille de style est elle-même un fichier .docx, idéalement produit par RMarkdown, dans lequel on a édité les styles des titres de différents niveaux, les marges, etc. Pour indiquer son nom, on écrit dans les en-têtes :

Pour une sortie en format HTML on peut appeler un style pré-défini, ou bien indiquer un fichier CSS que vous aurez placé dans le même dossier que le fichier .Rmd, comme suit :

Pour une sortie en PDF, étant donné que la confection du document utilise LaTeX, on peut utiliser toutes les feuilles de style (ou plus précisément de classes de document) faites pour ce langage, qui possèdent l’extension .cls. En LaTeX, l’appel d’une feuille de style s’accompagne souvent d’options, par exemple pour le format du papier, le choix d’une sortie recto-verso ou non, etc. On peut y inclure la définition de macros, utilisables telles quelles en RMarkdown. On indique le fichier .cls et ses options dans les en-têtes du fichier .Rmd, par exemple de manière suivante :

Voir la documentation pour plus d’options concernant les sorties Word, HTML et PDF.

La bibliographie : compatibilité avec Zotero (et autres gestionnaires)

Concernant la bibliographie, RMarkdown la génère automatiquement à partir d’un fichier contenant le détail des œuvres référencées, d’appels de références dans le document, et d’une feuille de style de bibliographie.

Pour le fichier des œuvres, un ensemble de formats sont acceptés, de BibTeX (.bib) à EndNote (.enl) en passant par JSON citeproc (.json). Il faut également placer ce fichier dans le même dossier que le fichier RMarkdown sur lequel on travaille, et le spécifier dans les en-têtes, par une ligne du type suivant, en indiquant le vrai nom du fichier (ici dans le cas d’un fichier .bib) :

Pour la feuille de style bibliographique, RMarkdown utilise le format CSL (comme Zotero). Une liste de feuilles de style disponibles se trouve ici et aussi là. Celle produite par l’EHESS correspond à l’usage dans les sciences sociales françaises. Elle existe en deux versions, soit «Auteur-date», soit avec les références longues en note de bas de page. Pour l’indiquer c’est la même chose :

En l’absence d’autres indications, la bibliographie est générée automatiquement en fin de document.

Il faut maintenant appeler les références. Dans le fichier bibliographique, à chaque œuvre est associé un identifiant de citation (citekey en anglais), que l’on insère dans le document lorsqu’on veut y faire référence. En RMarkdown cela se fait en écrivant [@citekey], et éventuellement d’autres précisions avec [@citekey, précisions].

Les citekeys elles-mêmes sont arbitraires, elles ne servent qu’à faire le lien entre les appels de références et le fichier des œuvres. Cependant, si vous demandez à votre logiciel de bibliographie de créer les citekeys sous la forme «AuteurDate», alors votre fichier RMarkdown ressemblera à : «Comme le décrit Hoggart [@Hoggart1970, 73] pour les années 1950-60…». C’est presque lisible tel quel, ce qui facilite les relectures et la communication avec les collègues.

Avec les logiciels dont les formats de fichier sont supportés par RMarkdown, il suffit en général de régler le format de création automatique des citekeys. Avec Zotero c’est légèrement plus compliqué. Une solution est d’installer l’extension «Zotero Better BibTeX», ce qui permet de générer des citekeys fixes dans Zotero et de les insérer par glisser-déposer des entrées dans le fichier RMarkdown. Pour cela : une fois l’extension installée, aller dans les préférences de Zotero. À l’onglet «Exportation», choisir le format de sortie par défaut comme «Better BibTeX QuickCopy» ; puis aller à l’onglet «Better BibTeX», à côté de «Citation key format» écrire «[auth][year]», et plus bas dans le menu à côté de «QuickCopy format» choisir «Pandoc». Enfin, sélectionner les références que vous voulez utiliser (ou toutes), faire un clic droit et demander «Generate BibTeX key». Vous verrez apparaître dans le champ «Extra» de chaque entrée un contenu du type «bibtex: Hoggart1970». Il est alors possible de glisser-déposer les références directement dans le texte que vous écrivez. Ne pas oublier d’exporter votre bibliographie au format .bib avant la compilation (confection) du document. Voir la documentation de cette extension pour en savoir plus, notamment si vous préférez un autre format de citekey.

Voilà pour les éléments de texte. Mais l’intérêt de RMarkdown, en particulier par rapport aux autres variantes de Markdown, est de pouvoir aussi prendre en charge des calculs ou des visualisations réalisées avec R.

Intégrer directement les traitements en R : renforcer la reproductibilité analytique

Une des grandes forces du format RMarkdown est sa capacité d’intégrer directement du code R. Les calculs sont effectués au moment de la production du document final. Ainsi on évite d’effectuer des manœuvres hasardeuses avec les données, comme des copier-coller, sources potentielles d’erreurs et de non-reproductibilité éditoriale.

Les balises pour indiquer le code à exécuter

Le code se signale par les signes ```{r} pour commencer, et ``` pour finir :

On peut aussi intégrer du code dans des phrases, en l’entourant par `r et `, par exemple `r 2+2` se transformera en 4.

Le programme qui se charge d’effectuer les calculs s’appelle knitr. C’est un package R. RStudio l’appelle automatiquement quand on demande de fabriquer le document final («Knit to PDF» ou autres). Il possède des options, en particulier celle de faire apparaître ou non les instructions des calculs dans le document. Par défaut elles sont affichées, pour que ce ne soit pas le cas il existe l’option echo = FALSE. L’exemple qui est donné quand vous créez un nouveau document RMarkdown sous RStudio montre comment structurer son document : un premier bloc contient les options générales de knitr pour ce fichier, auquel on peut ajouter le chargement des packages que l’on utilise par la suite ; ensuite on écrit des blocs avec des options spécifiques à chaque bloc. Par exemple, au début du fichier :

Et ensuite, quand on veut intégrer des traitements R :

À noter que dans ces deux exemples, le mot de la première ligne qui suit immédiatement ```{r et précède la première virgule (ici setup et plot_pressure), est simplement le nom, optionnel et arbitraire, que vous donnez à ce bloc d’instructions.

Pour en savoir plus sur knitr, on vous renvoie à son manuel d’utilisation. S’y repérer demande de connaître son vocabulaire : les morceaux de code sont appelés des «chunks» (morceaux), tandis que les options associées sont des «hooks» (des «aiguilles à tricoter»). Les exemples sont parfois écrits sous une forme qui commence par << …… >>= et finit avec @, mais pour les options c’est la même chose.

Les visualisations, leurs légendes et références

Pour produire des graphes, cartes, ou autres visualisations, il suffit d’écrire le morceau de code correspondant.

Le graphique se voit attribuer une numérotation automatiquement, dès lors qu’il possède une légende (caption), ce qui est souvent indispensable. Si vous voulez y faire référence par la suite, il faut y ajouter un identifiant. Cela peut se faire de la manière suivante :

Légende est le texte qui sera affiché sous le graphique. L’identifiant, qu’on a noté ici fig:identifiant et que vous pouvez modifier comme vous le souhaitez, est le petit nom que vous invoquerez pour y faire référence. Par exemple, pour obtenir quelque chose comme «voir figure 2.1», on écrit dans le fichier Rmd :

Cette syntaxe est certes un peu lourde et ne marche que pour produire des PDF. Il existe une meilleure solution, qui marche pour PDF et HTML : appelée Bookdown, elle utilise la syntaxe RMarkdown, et y ajoute quelques fonctionnalités utiles pour la publication. Elle est déjà utilisable avec RStudio mais de façon encore un peu compliquée, mais devrait se simplifier rapidement.

Écrire en pensant la reproductibilité

Enfin, la reproductibilité analytique n’est pas garantie par l’outil RMarkdown seul, mais par la combinaison du fichier .Rmd et des données qui y sont imbriquées. Dans le cas de calculs complexes, on peut vouloir éviter d’effectuer des traitements longs et lourds à chaque fois qu’on modifie le texte, et privilégier la compilation du document final à partir de résultats intermédiaires de calcul.

Or, comme l’en avertit Andrew Gelman, «ce n’est pas reproductible si ça ne marche que sur votre ordinateur». Si on veut optimiser la reproductibilité analytique, il convient donc de la penser au cours de l’élaboration du document, en travaillant ses fichiers d’analyses statistiques jusqu’à ce qu’ils soient lisibles et convocables sur demande, bref en maintenant les liens entre les différents fichiers de travail.

Dissocier les logiciels selon leurs points forts

On a parlé de syntaxe, mais avec quels outils travailler ? Il est possible d’utiliser uniquement RStudio. Cependant, s’il est efficace pour effectuer les calculs R et transformer le fichier vers les formats de sortie, il n’est pas très confortable pour écrire. En pratique, on peut combiner plusieurs logiciels et tirer parti de leurs avantages respectifs. Le grand intérêt des fichiers texte est leur ubiquité : ils sont gérés par tous les logiciels, aussi bien les traitements de texte que les éditeurs de texte. On peut donc passer de l’un à l’autre insensiblement. On propose ici un exemple d’usage réel : une écriture avec un éditeur de texte, une correction orthographique avec Word, et la création du rendu avec RStudio.

Les éditeurs de texte et le (R)Markdown

Tous les éditeurs de texte modernes offrent des outils d’aide à l’écriture en Markdown et en RMarkdown. Les plus simples sont l’insertion de balises de mots en gras ou en italique grâce aux combinaisons de touches (par exemple commande-B et commande-I respectivement). Ils peuvent s’accompagner de coloration de la syntaxe, facilitant la lecture (cf. exemple ci-contre). Ils détectent le contexte, et insèrent les symboles adéquats (parenthèses fermantes, chevrons dans un contexte de citation, etc.), ce qui facilite l’écriture.



Une capture d’écran de ce fichier sous TextMate, avec le thème MultiMarkdown (les couleurs sont facilement modifiables).

TextMate sous macOS est remarquable, et utilisable gratuitement. Simple d’utilisation au premier abord, il est en même temps très puissant, sa complexité se découvrant peu à peu. À la création d’un fichier, sélectionner le langage, ici Pandoc, après avoir installé le module associé : le télécharger là en cliquant sur «Clone or download» et «Download ZIP», puis extraire le .zip en double-cliquant dessus, le renommer en faisant de sorte que son nom se termine par «.tmbundle», et le glisser-déposer sur l’icône de TextMate pour l’installer. Il est possible de naviguer dans le plan avec commande-maj-T.

Disponible pour tous les systèmes d’exploitation, Sublime Text est aussi excellent et utilisable gratuitement, quoique légèrement plus complexe d’utilisation. BBEdit et sa version plus simple et gratuite TextWrangler sont aussi recommandés. Pour vous faire la main, quantité de logiciels plus modestes mais tout à fait utilisables existent.

Sur mobile, de très bons logiciels d’écriture Markdown existent, avec des fonctions plus ou moins riches, dont Ulysses, Editorial, Bear, Byword, iA Writer, JotterPad, etc. Ils utilisent le Markdown simple le plus souvent, parfois le MultiMarkdown, mais cela ne pose pas de problème d’y écrire du RMarkdown, qui en est très proche.

Exporter en Word pour les corrections et l’écriture collaborative…

Pour utiliser le correcteur de Word ou Antidote, ou bien travailler collaborativement avec des utilisateurs de Word, on peut convertir le .Rmd en format Word .docx.

La difficulté se situe au niveau de la validation des commentaires et de leur réintégration en RMarkdown. Le plus simple actuellement est de les intégrer «à la main» dans le fichier .Rmd, c’est un des inconvénients de ce système et la limite de la collaboration avec Word.

Le plus simple est donc de se faire relire directement en .Rmd, ce qui permet d’utiliser le mode révision de Word. Le plus difficile est probablement de trouver un relecteur qui ne soit pas indisposé par le RMarkdown.

… ou utiliser les outils des informaticiens avec RStudio

Si vous trouvez des collaborateurs volontaires, il existe aussi d’autres méthodes permettant l’écriture collaborative directement en RMarkdown. Les informaticiens écrivent à plusieurs des programmes depuis plus d’un demi-siècle, sur des fichiers texte comme le .Rmd, et ont développé des outils pour cela : la comparaison des différences et le suivi des versions. RStudio fait là aussi un travail remarquable pour simplifier et rendre assez indolore leur usage, et donner une ergonomie de suivi des modifications qui s’approche de celui de Word.

Un exemple de suivi des modifications (de l’écriture de ce fichier) avec RStudio. Ici, une comparaison de deux fichiers. En vert les ajouts, et s’il y avait des lignes supprimées elles seraient colorées en rouge. Deux boutons à droite permettent d’«accepter» ou «rejeter» les modifications. On peut en parallèle éditer le même fichier dans une autre fenêtre.

Entrer dans le détail de leur utilisation dépasse l’objet de cette présentation, et fera l’objet d’un prochain billet, mais si vous en voulez un aperçu vous pouvez essayer l’éditeur de texte en ligne Draft.

Compiler le document final avec RStudio

Enfin, on peut n’utiliser RStudio que pour la compilation des documents, que ce soit en Word pour les corrections, ou bien en PDF ou HTML pour la publication. Cela demande un simple clic, comme mentionné précédemment.

Conclusion

On a présenté ici de façon détaillée l’ensemble des opérations d’écriture en RMarkdown, pour que vous puissiez évaluer honnêtement les avantages mais aussi les coûts de transition par rapport à Word ou LaTeX. On n’est pas encore arrivé au point où on pourra se dispenser complètement de Word, mais on s’en approche rapidement.

Pour des versions plus résumées de cette présentation, n’hésitez pas à consulter cette référence de la syntaxe RMarkdown, Une présentation synthétique de Julien Barnier, et quelques explications pour clarifier ce que sont RMarkdown, knitr, Bookdown, etc..

Beaucoup d’autres options, qu’il est impossible de présenter ici, sont disponibles avec RMarkdown (et le Pandoc Markdown, dont il est dérivé). Pour les explorer, voir la documentation de Pandoc, ainsi que celle de RMarkdown pour la production de fichiers PDF, HTML ou Word, et plus simplement Google et StackOverflow. Il est également possible de faire sans RStudio, en cas de besoin. RStudio fait fonctionner ensemble plusieurs programmes «comme si de rien n’était», en masquant le processus. Pour qui voudrait s’en passer, par nécessité, goût ou volonté de customisation, il suffit d’installer et d’utiliser knitr, puis Pandoc, et LaTeX/BibLaTeX.

En tout cas vous êtes maintenant armés pour une utilisation généraliste de RMarkdown. N’hésitez pas à le tester, le Markdown et ses dérivés sont des formats qui se sont largement diffusés pour l’écriture sur le web, et commencent à s’imposer comme un des standards de l’écriture scientifique.