1 Avant-propos

1.1 Qu’est ce que R Markdown ?

En 2012, Yihui Xie publit un package nommé knitr (Xie 2020), facilitant l’incorporation de blocs de code R, éventuellement accompagné du résultat de leur exécution, dans des fichiers dédiés à l’édition, dont le format .md associé au (méta)-langage Markdown1. Il utilise un format de fichier baptisé R Markdown, d’extension .rmd ou .Rmd, autorisant l’adjonction à un fichier Markdown de blocs de codes R (ou d’autres langages de programmation) grâce à un balisage spécifique. Les blocs de code R peuvent être configurés de sorte que lors de la compilation du document R Markdown, le code et/ou le résultat de son exécution soi(en)t incorporés à un fichier Markdown.

Le package rmarkdown (Allaire et al. 2020) apparu en 2014, permet la conversion du fichier .mdproduit à l’issue de la compilation d’un fichier R Markdown en divers formats dont les extensions .html, .pdf, .docx, .odt. Il repose sur le logiciel Pandoc2, puissant outil de conversion entre langages à balises.

L’appellation R Markodwn désigne maintenant l’ensemble du processus consistant à éditer un fichier d’extension .Rmd puis à le convertir en un fichier prêt à être publié. De nombreux packages sont venus enrichir les possibilités initialement offertes. Aujourd’hui, l’ensemble des outils mis à disposition permet l’édition de documents divers, de la plus grande qualité et garantissant la reproductibilité des résultats présentés ; voir la Partie 1.2.

L’environnement de développement intégré Rstudio facilite grandement ce processus grâce aux nombreuses fonctionnalités dédiées qu’il offre ; son utilisation pour la création de documents avec R Markdown est donc vivement recommandée.

1.2 Quel intérêt ?

Les intérêts de R Markdown sont multiples :

  • il repose sur un langage à balises très simple de prise en main, lisible ;
  • un même document d’extension .Rmd peut être utilisé pour générer des documents en divers formats dont les plus usuels sont .html, .pdf ou .docx. La liste des extensions de fichier pouvant être produites est consultable ici ;
  • il permet de garantir la reproductibilité des résultats présentés dans les documents de sortie : d’une part, l’ensemble des instructions R exécutées pour arriver au résultat présenté est incluse dans le document - un lecteur avisé pourra donc reporduire à l’identique les résultats, qui sont donc mis à l’abri de fautes de frappe ou d’imprécision de l’auteur sur les méthodologies employées. D’autre part, l’ensemble de l’analyse effectuée est robuste aux modifications des données d’entrées ou du code exécuté : les changements sont immédiatement répercutés sur le document de sortie lors de la compilation. La vidéo ci-dessous (https://youtu.be/s3JldKoA0zw) est particulièrement parlante.

En outre, les nombreuses ressources développées ces dernières années pour R Markdown permettent son utilisation pour diverses tâches, pour un rendu de la plus grande qualité. Quelques exemples, empruntés à l’ouvrage (Xie, Allaire, and Grolemund 2018) :

  • la rédaction de mémoires, de thèses ou toute autre production étudiante ;
  • la rédaction d’articles en vue de leur publication dans des revues internationales ;
  • la rédaction de livres académiques ;
  • la rédaction de slides pour un exposé ;
  • la rédaction de notices de documentation accompagnant un package ;
  • l’automatisation de tâches régulières de reporting ;
  • la création d’un site web, d’une page professionnelle, d’un blog ;
  • la création de tests pour la plate-forme d’enseignement Moodle ;
  • la création d’applications interactives.

La table des matières de l’ouvrage (Xie, Allaire, and Grolemund 2018) donne un aperçu des possibilités offertes. Le titre de cet ouvrage n’est pas usurpé : on y trouve toutes les informations nécessaires pour la prise en main de R Markdown et la personnalisation des ressources produites. Il est en outre consultable librement ici.

1.3 Pré-requis logiciels

L’utilisation de R Markdown nécessite à minima l’installation de R et du package rmarkdown (avec ses dépendances, potentiellement nombreuses). L’installation et l’utilisation de Rstudio n’est pas obligatoire mais fortement recommandée.

L’installation de LaTeX est nécessaire pour la création de documents d’extension .pdf. Si une telle installation est déjà présente sur l’ordinateur utilisée, elle sera reconnue. Dans le cas contraire, le package tinytex, qui a normalement été installé lors de l’installation du package rmarkdown, permet une installation minimale depuis R en tapant dans la console de R :

L’utilisation du template cr-urca, qui est présentée dans les parties suivantes, nécessite également l’installation des packages bookdown, formatR et kableExtra.

Il pourra être nécessaire d’installer d’autres packages, voire d’autres logiciels, selon les besoins de chacun. Arrivé à ce stade, il sera nécessaire de faire preuve d’autonomie en explorant le web à la recherche des ressources nécessaires.

1.4 Le template cr-urca

Sous la dénomination de template cr-urca, on désigne un ensemble de ressources simplifiant la mise en page de compte-rendus ou de mémoires au format pdf par les étudiants de l’URCA désireux d’utiliser R Markdown.

Le template cr-urca est contenu dans un package, en cours de développement, nommé urcadown3, que l’on peut télécharger et installer depuis le dépôt GitHub du projet en exécutant le bloc d’instructions suivant dans la console R :

Pour créer un fichier R Markdown selon ce template, procéder comme suit :

  • dans la barre de menu de la fenêtre de Rstudio, cliquer sur File, puis New file > R Markdown... ;
  • une boîte de dialogue s’ouvre. Dans le menu de gauche, cliquer sur From Template. Dans la partie droite, apparaît la liste des templates disponibles (fournis par les packages actuellement installés). Choisir cr-urca ;
  • choisir un emplacement dans l’arborescence du système de fichiers puis un nom évocateur (par exemple REGNAULT_CR_MA0606 pour un compte-rendu en MA0606 produit par Regnault) pour le dossier destiné à contenir les documents sources, intermédiaires et de sortie (le nom de ce dossier sera également utilisé come nom pour les documents produits, dont le fichier .Rmd et le document de sortie). Cliquer sur le bouton OK ;
  • un document d’extension .Rmd s’ouvre dans l’éditeur de Rstudio. Celui-ci est un fichier exemple qui pourra servir de base à la rédaction du compte-rendu. Pour compiler ce fichier et obtenir le document PDF final, cliquer simplemement sur le bouton Knit dans la barre d’outils en haut de l’éditeur de Rstudio.

L’idée est maintenant de modifier ce fichier .Rmd pour y incorporer son travail personnel. La partie suivante donne quelques éléments pour l’édition de fichiers Rmd.

  1. Markdown est un langage à balises créé en 2004 par John Gruber dont la syntaxe particulièrement simple rend son utilisation aisée pour l’édition. Conçu pour faciliter l’édition de pages html, il peut être aisément converti en d’autres langages à balises tels que html ou LaTeX. Consulter la page officielle du langage ici.↩

  2. Pandoc est un puissant logiciel de conversion entre langages à balises largement utilisé dans l’univers de l’édition. Il a été développé par John MacFarlane en 2006. Consulter la page officielle du logiciel ici.↩

  3. Le package urcadown a vocation a fournir des templates R Markdown pour la rédaction de documents (polycopiés, feuilles de TD, TP, devoirs, examens, rapports, mémoires, etc) respectant la charte graphique de l’URCA.↩