Introduction à Rmarkdown

De EduTech Wiki
Aller à la navigation Aller à la recherche

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.

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.

Installation

La création de document avec Rmarkdown utilise le paquet knitr. Ce paquet est déjà disponible dans le logiciel RStudio, dont l'utilisation n'est pas obligatoire, mais conseillée, notamment pour suivre le contenu de cet article qui utilise l'interface du logiciel pour compiler les documents.

Avec RStudio

Si vous utilisez RStudio, le paquet knitr est déjà installé de base. De plus, l'interface du logiciel s'adapte lors de l'utilisation de fichiers avec extension .Rmd afin de faciliter la compilation du document, l'exécution des bouts de code mélangés à la narrative du document (voir plus bas), ou encore la navigation dans les parties du document. L'image ci-dessous signale les éléments dans l'interface qui peuvent être utiles à ces effets :

  • Le bouton knitr permet de compiler l'ensemble du document et créer le(s) fichier(s) nécessaire(s) au format de output (e.g. HTML5, PDF, Microsoft Word, etc.). Le menu déroulant dans le bouton permet d'afficher différentes options de compilation. Si vous utilisez un projet RStudio (conseillé), le output figure directement à l'intérieur du dossier du projet.
  • Le bouton Insert permet d'ajouter des bouts de code. Le menu déroulant dans le bouton permet d'afficher différents langages pour le bout de code (R, Python, ...).
  • Sur la droite du panneau d'un document .Rmd, il est possible d'afficher le outline du document en fonction des titres-
  • En bas du panneau, il est possible d'afficher un menu contextuel pour voir la liste des titres ainsi que les bouts de code présents dans le document.
Interface de RStudio avec un document Rmarkdown ouvert.

Lors de la première utilisation de knitr en RStudio, il est possible que le logiciel demande une mise à jour du paquet à la dernière version. Mais si non, les fonctionnalités liées à Rmarkdown sont disponibles out of the box, à l'exception de la transformation en PDF, pour laquelle il est nécessaire de disposer d'un interprète LaTeX. La manière la plus simple consiste à installer TinyTeX.

Sans RStudio

L'installation du paquet se fait de la manière habituelle :

install.packages("knitr")

Pour compiler les documents, il faudra connaître les commandes du paquet et les exécuter selon l'interface de programmation que vous utilisez.

Exemple de base

Markdown

Markdown est un langage de marquage créé par John Gruber qui se différencie d'autres langages de marquage, comme par exemple HTML5 ou LaTeX, pour sa simplicité. L'avantage est principalement celui de rendre la lecture du document de travail, c'est-à-dire celui avec le marquage, plus fluide. La complexité du document final est déléguée à des règles de transformation qui peuvent varier en fonction de (1) le format de sortie du document (PDF, HTML, ...), ou (2) le template qui est utilisé pour la mise en page.

Il existe différentes implémentations de Markdown ou qui ressemblent à Markdown. Rmarkdown utilise la version Pandoc's Markdown, c'est-à-dire la version de pandoc, le moteur qui permet de migrer entre différents formats. Si vous utilisez RStudio, pandoc est directement installé avec le logiciel.

Dans cette section, nous proposons une liste non exhaustive des éléments de marquage les plus utilisés. Certains formatages disponibles en Markdown peuvent être gérés également avec des fonctions de R, comme par exemple pour les images ou les tables. Voir plus bas dans cet article pour plus d'informations.

Formatage du texte

Pour créer des paragraphes, laissez une ligne blanche entre les deux blocs de texte :

Ceci est le premier paragraphe du document. Il est très court.

Et voici le deuxième. Il est encore plus court.

On peut appliquer des formatages à une partie du texte en contournant les éléments avec *texte* pour l'italique, et **texte** pour le gras :

Ce *texte est en italique*, tandis que **celui-ci est en gras**. On peut combiner les deux pour avoir un ***texte en gras et italique***.

Titres

Les titres se forment en utilisant un nombre de # relatifs au niveau du titre. Le texte du titre doit laisser un espace après le # :

# Titre de premier niveau

## Titre de deuxième niveau

### Titre de troisième niveau

Listes

Pour une liste non ordonnée, utilisez le * au début de chaque item :

Voici une liste d'éléments  :

* Item
* Item
* Item

Pour une liste ordonnée, il faut mettre un chiffre suivi par un point. Il est important de noter que seulement le premier chiffre utilisé dans la liste joue un rôle important, car il détermine le début du comptage. Les chiffres suivants n'ont aucune influence :

Cette liste :

1. Lire
2. Écrire
3. Imprimer

Est égale à cette liste :

1. Lire
1. Écrire
1. Imprimer

Mais pas à celle-ci qui commence à 4 :

4. Lire
2. Écrire
1. Imprimer

Il existe une notation alternative #., mais que nous déconseillons, car elle peut se confondre assez facilement avec les titres :

Notation alternative, mais qui peut se confondre avec les titres

#. Lire
#. Écrire
#. Imprimer

Images

Liens

Pour créer un lien hypertextuel à une ressource sur le web, utile surtout dans l'output de type HTML5 mais valable aussi pour d'autres formats, la notation est la suivante :

[Label du lien](url de la ressource)

Par exemple :

[EduTech Wiki en français](https://edutechwiki.unige.ch/fr/Accueil)

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.

Code inline

Le code inline s’insère en contournant le code avec deux accents graves ` (i.e. des backticks en anglais) et en utilisant la lettre r au début :

`r [code à exécuter]`

Voici quelques exemples de notation suivi par le résultat qui s'affiche dans le document compilé :

  • La somme de 19 et 54 est `r 19 + 54`
    
    La somme de 19 et 54 est 73
  • Ce document a été mis à jour `r format(Sys.Date(), "%A %d %B %Y")`.
    
    Ce document a été mis à jour dimanche 27 septembre 2020. (n.b., la date va varier)
  • L'alphabète a `r length(letters)` lettres : `r letters`.
    
    L’alphabète a 26 lettres : a, b, c, d, e, f, g, h, i, j, k, l, m, n, o, p, q, r, s, t, u, v, w, x, y, z.

Bouts de code

Importer du code source

Ressources