Introduction à Rmarkdown

Cet article est en construction: un auteur est en train de le modifier.

En principe, le ou les auteurs en question devraient bientôt présenter une meilleure version.

---

Introduction

Rmarkdown (ou R Markdown) est une syntaxe qui permet de créer des documents en appliquant le principe de la programmation lettrée, ou literate programming en anglais, qui permet de combiner l'écriture et exécution de code avec des passages de texte normal. En Data Science, ceci permet notamment de créer des reports scientifiques qui combinent des éléments textuels écrits par les auteurs avec des éléments computés, comme par exemple les représentations visuelles ou les résultats d'une analyse statistique ou modélisation de données.

Dans cet article nous proposons un aperçu du fonctionnement de Rmarkdown appliqué au contexte de la Pensée computationnelle avec R, en sachant que le même principe peut être adopté avec des technologies différentes, comme par exemple le projet juypter. Nous aborderons d'abord quelques éléments techniques qui permettent d'intégrer du code dans la génération d'un document, pour ensuite fournir quelques exemples de référence. Pour des applications plus poussées, des liens à d'autres ressources plus spécifiques seront fournis.

Cadres d'utilisation de Rmarkdown

Rmarkdown peut être utilisé pour générer différents types et formats de documents, comme par exemple :

• Article scientifiques déjà mise en page, souvent avec le template correspondant à des normes (e.g. APA) ou le layout d'un journal spécifique
• Pages, site ou blog web qui présentent des éléments scientifiques ou académiques (e.g. citations, ...)
• Documentation technique, par exemple pour un paquet de R
• Livres numériques en différents formats (Epub, HTML5, ...)
• Tutoriels interactifs
• Mémoires ou thèses académiques

Ce type d'approche favorise la transparence et reproductibilité des report scientifiques, car tous les passages nécessaires à leur création sont directement documentés à l'intérieur du document source, qui présente les passages computationnels correspondant. De cette manière, les auteurs eux-mêmes peuvent regrouper toutes les informations nécessaires et peuvent y accéder dans le temps, tandis que les reviewers peuvent scruter les différents éléments qui composent une contribution scientifique dans un seul endroit.

Prérequis

Rmarkdown peut être utilisé indépendamment de l'expérience préalable avec R. La complexité des documents créés ne dépend cependant pas seulement de la maîtrise de Rmarkdown en soi, mais également - et surtout - de la capacité de créer les contenus à insérer (e.g. analyses, graphiques, ...). Une expérience limitée avec R ne doit donc pas décourager la découverte et l'adoption précoce de Rmarkdown, mais les bénéfices de cette technique sont plus évidents avec une certaine maîtrise de l'écosystème R.

L'utilisation de RStudio n'est pas obligatoire pour utiliser Rmarkdown, mais elle est conseillée, notamment pour suivre le contenu de cet article qui utilise l'interface du logiciel pour compiler les documents.

Pour créer des documents en formats PDF, il est nécessaire d'installer un compilateur de LaTeX (voir la page correspondante ou directement le site TinyTeX). Dans l'article, nous utiliserons davantage des exemples en HTML5 pour contourner cette nécessité, et aussi parce que la transformation en HTML5 est plus rapide. La connaissance de HTML5 n'est cependant pas nécessaire pour comprendre ou visualiser les documents.

Intégration du code R

Le code R à exécuter dans un ficher Rmarkdown peut être inséré de différentes manières :

1. Dans du code inline

   Il s'agit en général de brefs instructions qui consistent, souvent, tout simplement à imprimer une référence symbolique ou le résultat d'une fonction à l'intérieur d'un passage de texte.

2. Dans des bouts de code, ou code chunks en anglais

   Il s'agit de bloc de code qui peuvent être nommés et définis avec des options. Ils incluent normalement plusieurs instructions de code.

3. Importer du code source depuis d'autres fichiers RScript

   Dans le cas de projets complexes, il est utile d'organiser le code dans des fichiers séparés et les importer au besoin.

Les différentes stratégies sont très souvent combinées. Par exemple, le bout de code importe un script plus complexe depuis un ficher et applique quelques transformations nécessaires dans le cadre du report scientifique, par exemple pour calculer un indice d'intérêt (e.g. le résultat d'un test statistique). Cet indice est associé à une référence symbolique qui est ensuite utilisée dans du code inline pour imprimer l'indice à l'intérieur d'une phrase du report scientifique.

Ressources

• R Markdown Cookbook par Yihui Xie, Christophe Dervieux et Emily Riederer
• R Markdown: The Definitive Guide par Yihui Xie, J. J. Allaire et Garrett Grolemund