Motivation

«Finalement, comme plusieurs d'entre-vous n'ont pas beaucoup de temps pour (…) reprendre tout ce que vous venez de produire en R pour en faire un rapport avec de multiple copier/coller/effacer/modifier/jeter/recommencer, il serait peut-être intéressant pour vous de commencer à utiliser R Markdown.»

Samuel Cabral Cruz, analyste en actuariat chez DGAG, promotion 2015

Sommaire

  • Concept de programmation lettrée
  • Comparaison entre deux systèmes populaires
  • Markdown
  • R Markdown
  • Mathématiques
  • Évaluation

Matériel pédagogique

Ces diapositives et les fichiers nécessaires pour les exercices sont distribués séparément dans une archive laboratoire-rmarkdown.zip.

Téléchargez le matériel pédagogique depuis le site du projet «Programmation lettrée et R Markdown» dans GitHub.

Concept de
programmation lettrée

Programmation lettrée

  • Une autre idée de Donald Knuth, lorsqu'il a créé TeX pour rédiger The Art of Computer Programming

  • Idée: combiner un programme et sa documentation dans un même fichier dans un format facile à consulter pour un humain

    • balises spéciales pour délimiter les parties
    • tangle pour produire le code source dans le bon ordre
    • weave pour produire la documentation
  • Recherche reproductible

  • Plusieurs systèmes au fil du temps: WEB (Knuth, 1984), CWEB (Knuth et Levy, 1987), noweb (Ramsey, 1989), Sweave (Leisch, 2002), knitr (Xie, 2012)

Processus de création d'un document
avec R Markdown

R Markdown est construit autour de knitr et Pandoc.

Avertissement

R Markdown et Shiny sont des technologies très liées à RStudio (la compagnie)

  • Créateur de knitr travaille chez RStudio
  • Shiny développé par RStudio
  • Documentation officielle dans site de RStudio
  • RStudio (l'éditeur) vous encourage à utiliser ces formats
  • «Communauté» très active dans les réseaux sociaux, Stack Overflow, etc.

Comparaison entre deux
systèmes populaires

Sweave + LaTeX

Orienté vers la création de documents PDF

Avantages

  • Qualité typographique du document, en particulier les équations mathématiques
  • Simplicité de Sweave
  • Universel et stable

Inconvénients

  • Courbe d'apprentissage de LaTeX abrupte au début
  • Peu d'intégration avec les outils de partage en ligne

R Markdown

Orienté vers la création de pages web et de documents PDF

Avantages

  • Prise en main aisée grâce à la syntaxe simplifiée
  • Nombreux formats de sortie
  • Formidable intégration avec RStudio et GitHub

Inconvénients

  • Nombreuses couches logicielles (Markdown, YAML, knitr, Pandoc, LaTeX, HTML, …)
  • Prise en charge limitée des équations mathématiques
  • LaTeX requis pour équations complexes ou mise en forme particulière

Markdown

Langage de balisage léger

Markdown a été créé pour simplifier l'édition de pages web.

  • Créé par John Gruber en 2004
  • Dernière mise à jour en 2004 (!)
  • Syntaxe simple à lire et à écrire pour titres, tableaux, liens, images, etc.
  • Utilisé par Stack Overflow et Stack Exchange, GitHub, blogues, …

Utilisation dans Stack Overflow

Utilisation dans Stack Overflow (suite)

Utilisation dans Stack Exchange

Utilisation dans Stack Exchange (suite)

Documentation

Exercice

  • Ouvrir avec RStudio le fichier exercice-markdown.md.

  • Copier et l'intégralité du texte du fichier et le coller dans Markdown Live Preview.

R Markdown

Idée

Faciliter la création de documents avec la programmation lettrée en combinant

  • la syntaxe simple de Markdown
  • des extraits de code R (chunks)

Exercice

  • Ouvrir avec RStudio le fichier exercice-introduction.Rmd.

  • Faire du répertoire dans lequel se trouve le fichier le répertoire de travail de R (menu Session|Set Working Directory).

  • Si ce n'est déjà fait, charger le paquetage rmarkdown dans la session R.

library(rmarkdown)
  • Compiler le document en format PDF.
render("exercice-introduction.Rmd")
  • Répéter l'étape précédente après avoir changé pdf_document à la ligne 5 du fichier pour html_document.

Anatomie d'un fichier

  • Entête YAML (YAML Ain't Markup Language) pour la configuration de R Markdown
---
title: "Mon premier exercice avec R Markdown"
author: "Auteur"
date: ""
output: pdf_document
---
  • Texte en format Markdown

  • Blocs (chunks) de code R

```{r}
summary(cars)
```

Sorties R au fil du texte

Je vois 5 pommes.

Je vois `r 2 + 3` pommes.

Options des blocs de code R

Différentes options placées dans {r } permettent de contrôler le traitement d'un bloc de code.

echo : affiche le code source si TRUE (par défaut)

eval : exécute le code et affiche la sortie si TRUE (par défaut)

include: affiche le contenu du bloc si TRUE (par défaut)

```{r echo = TRUE, eval = TRUE}
2 + 3
```
2 + 3
## [1] 5

Options des blocs de code R (suite)

  • Afficher une expression sans l'évaluer
```{r echo = TRUE, eval = FALSE}
2 + 3
```
2 + 3
  • Cacher un calcul
```{r include = FALSE}
2 + 3
```

Exemple

Extrait d'un rapport de travail pratique.

Exemple (suite)

Solution simple pour afficher les résultats: afficher le data frame.