1. Objectifs

Se familiariser avec l’environnement de RStudio pour la création de documents dynamiques.
Comprendre l’anatomie d’un document R Markdown.
Comprendre les différents formats et paramétrages de base.
Apprendre les bases du balisage Markdown.
Apprendre à structurer un document .rmd pour le compiler en différents formats.
Apprendre comment partager son document en ligne (avec URL).

1. Objectifs

Ce que l’on ne fera pas:

LaTeX pour compiler des documents pdf: nécessite installation d’une distribution TeX comme MiKTeX, TinyTeX…
Git et Github pour archiver et partager en ligne
Apprendre R!

https://r-bio.github.io/

2. Ce dont on aura besoin (le minimum nécessaire)

R
RStudio
Packages/outils de RStudio:
- knitr
- R Markdown
- Pandoc

3. RStudio (et autres IDE)

Interface du R de base pas très intuitive donc peu utilisée telle quelle

Installe généralement en plus un IDE, Integrated Development Environment: éditeur de script - environnement beaucoup plus convivial qui facilite le travail (gestion des fichiers, objets et commandes, historique de fonctions, autocomplétion,…)
L’IDE le plus utilisé est RStudio (mais il y en a d’autres comme Tinn-R).
Les commandes et fonctions sont les mêmes pour R et RStudio.

4. Installation

Télécharger et installer R de base - choisir son système d’exploitation et suivre les étapes.
Télécharger et installer RStudio (ou autre interface) – Choisir la version gratuite et son système d’exploitation.
Télécharger et installer (“charger”) des packages dans RStudio.

À noter
- Pas de mises à jour automatiques, il faut installer une nouvelle version et retélécharger les packages (ou déplacer le répertoire de l’ancienne version et faire update.packages). RStudio utilisera par défaut la version la plus récente sur le poste (peut se faire manuellement). L’ancienne version peut être désinstallée. Il est recommandé de mettre à jour sa version R et RStudio annuellement.
- Certains besoins plus spécialisés peuvent nécessiter l’installation d’outils supplémentaires comme RTools (Windows) et LaTeX.
- Package utile pour la mise à jour de R et autres outils sous Windows via RStudio: installr

5. Qu’est-ce qu’un package?

Un package est un module (ou extension, librairie, bibliothèque) qui contient un ensemble de fonctions (souvent liées à une méthode ou un domaine particulier)
À l’installation, R vient avec un ensemble de fonctions de base {base} et de modules par défaut (built in packages).
Des packages composés de fonctions spécialisées sont constamment développés par la communauté.
On en trouve plus de 15 000 sur le site officiel de R CRAN. D’autres se trouvent aussi ailleurs (Github, …).
Les packages doivent être téléchargés(install.packages() ou via le menu du haut Tools > Install Packages) une seule fois, mais chargés (library() ou require()) à chaque session.
Une fonction (ex: corrélation, tableaux contingences…) peut se retrouver dans plusieurs packages avec variantes plus ou moins importantes (procédures, options, arguments, résultats).
Les packages nécessitent aussi une mise à jour périodique via: Tools -> Check for Package Updates

6. Qu’est-ce R Markdown et pourquoi l’utiliser ?

R Markdown est un package installé par défaut dans RStudio.
Outils de programmation lettrée créé pour assurer la reproductibilité de la recherche en intégrant dans un seul document du texte balisé en Markdown, le code (R ou autre) et résultats de ses analyses.
C’est la version “moderne” et simplifiée d’autres outils utilisés depuis plusieurs décennies par les chercheurs adeptes du litterate programming: LaTeX, Sweave et S.
Permet donc d’éviter toutes les étapes de copier-coller de tableaux, de graphiques… et de créer des documents et présentations faciles à mettre à jour en différents formats: word, pdf, ppt, html…
Optimisé pour la création de documents html (donc format qui profite du plus d’options intéressantes).

6. Qu’est-ce R Markdown et pourquoi l’utiliser ?

7. Comment ça marche?

R Markdown combine différents processus pour créer à partir d’un seul fichier des documents en différents formats:

7. Comment ça marche?

Tout commence par la création d’un document .Rmd dans RStudio.
Un fichier R Markdown est un simple fichier texte avec une extension .Rmd. (on pourrait le créer dans Notepad).
Pour générer un rapport, utilise la commande render ou encore mieux, le bouton knit qui active la fonction rmarkdown::render() qui exécute les blocs de code du fichier .Rmd et prépare les résultats à inclure dans le document final. Ces résultats sont convertis dans un fichier temporaire .md (contenant code et résultats).
- bloc de code pour compiler un document et définir le format de sortie avec l’argument output_format de la fonction render:

library(rmarkdown)
render("1-example.Rmd", output_format = "word_document")

Ensuite ce fichier .md est traité par l’outil Pandoc qui permet de convertir le contenu d’un langage de balisage (markup) en différents formats (“couteau suisse” de la conversion de formats de documents). Les paramètres de conversion sont précisés dans l’entête YAML du document .Rmd où entre autres le format final est spécifié.
Si le format final désiré est pdf, une étape de traitement supplémentaire s’ajoute: Pandoc transformera le fichier .md dans un autre fichier intermédiaire .tex. Ce fichier .tex sera ensuite traité par LaTeX vers sa forme pdf finale.
À noter, LaTeX est un outil très puissant pour la structuration de documents mais cette personnalisation spécifique au pdf fait que l’on perd la flexibilité multiformat du R Markdown.

8. Formats d’exportation de base disponibles

Formats de présentation:
- ioslides_presentation (slides html)
- slidy_presentation (slides html)
- revealjs::revealjs_presentation (slides html + js)
- powerpoint_presentation
Formats de document:
- html_document
- odt_document
- rtf_document
- word_document
- github_document
- md_document
- pdf_document (LaTeX/pdf)
- latex_document (LaTeX/pdf)
- beamer_presentation (LaTeX/pdf)

9. Packages utiles pour multiplier les formats possibles

Il existe un très grand nombre de packages et de templates pour créer différents types de documents avec des styles prédéfinis très variés : modèles de présentation, articles de périodiques, livres, thèse, sites web, blogs, widgets, dashboards, cartes et autres présentations interactives …
- prettydoc
- bookdown
- blogdown
- distill
- xaringan
- htmlwidgets
- shiny
- leaflet
- flexdashboard
- revealjs
- rmdshower
- Hugo
- Voir la galerie
Attention car l’utilisation de ces différents outils nécessite l’apprentissage de paramétrages/balisages particuliers ce qui peut nuire à l’interopérabilité des formats.
On peut également créer ses propres gabarits et style de documents

10. Créer un fichier R Markdown

11. Anatomie d’un document R Markdown

Contient 3 types de contenu:

Une entête de métadonnées (YAML header): entête facultative écrite en YAML entouré de 3 tirets
Texte: formaté en markdown
Blocs de code: code chunks entourés de ``` (raccourci ctrl +alt + i)

11. Anatomie d’un document R Markdown

12. Métadonnées

Métadonnées de base et champs Ouput pour définir le format et ses options pour paramétrer la présentation finale
Syntaxe YAML

Chaque format de sortie possède des options spécifiques pour personnaliser la présentation finale avec des arguments comme sous-valeurs du champ output: (les sous-options doivent être indentées).
Pour connaitre ces options, aller voir l’aide: ?rmarkdown::html_document.
Si un format est fourni par un package spécifique, il faut le nommer dans le champ YAML output: tufte::tufte_html.

12. Métadonnées

Il est aussi possible de modifier les arguments de formattage du document final grâce aux options du menu knit de RStudio. Les champs de l’entête YAML du document seront automatiquement modifiés.

13. Texte formaté en Markdown

13.1. Qu’est-ce que le Markdown?

Le markdown est un langage de balisage, version simplifiée du html, créé par John Gruber en 2004.
Sert à structurer du contenu textuel et produire des documents à partir de texte brut balisé.

“Markdown reflects the philosophy of Stoicism: the “natural world” consists of plain text, and you should not be controlled by the desire for (visual) pleasure." — Yihui

Souvent comparé à LaTeX; autre langage de balisage plus puissant mais beaucoup plus complexe pour la production de documents pdf.
Il existe plusieurs versions de Markdown développé par différents programmeurs. Celle utilisée par R Markdown est la version Pandoc qui rend aussi possible conversion de documents en différents formats.
Sa très grande simplicité en fait un outil plus limité en terme de structuration de documents par rapport au html, à LaTeX et à un logiciel de traitement de texte. (voir Gruber)
Il est donc utile de connaitre ces langages (html, css, javascript, LaTeX) si l’on veut personnaliser le format de ses documents (mais attention car l’inclusion de balises html et LaTeX peut poser problème lors de l’exportation vers certains formats).

13. Texte formaté en Markdown

13.1. Qu’est-ce que le Markdown?

13. Texte formaté en Markdown

13.2. Syntaxe de base de Markdown

Reference Guide

Markdown Tutorial

14. Code

14.1. Insérer des sections de code

On peut inclure du code de 2 façons :

En blocs de code: débutant par ```{r} (où r indique le langage utilisé, il peut y en avoir d’autres: python, sql, …)

```{r}
mean(23, 65, 43, 34, 56) # Le style des blocs est défini par l'option "highlight" dans le YAML
```

Les balises de blocs peuvent être insérées grâce au bouton insert ou avec le raccourci ctrl + alt + i
Il est préférable de diviser le code qui génère différents outputs dans blocs différents

Dans le texte (Inline code) débutant par `r et se terminant par un accent grâve `. Donc:

Résultat: La moyenne d’âge de nos participants étaient 23 …

14. Code

14.2. Paramétrer le fonctionnement des blocs de code

Le “comportement” des blocs de code et la présentation des résultats peuvent être paramétrés de plusieurs façons.
Knitr propose de nombreuses options (chunck options) que l’on peut ajouter comme arguments entre les accolades de chaque bloc (chaque option doit être séparée par une virgule).

```{r, chunk-label, results='hide', fig.height=4}
```

Chaque bloc optionnellement peut avoir un nom (label), doit être la première option.
Ces options contrôlent essentiellement la façon dont sera compilé (ou non) le code de chaque bloc et la façon dont sera présenté (ou non) les résultats de chaque bloc de code.
Plusieurs des arguments ont des valeurs logiques: TRUE OU FALSE (avec une valeur par défaut qu’il faudra changer si elle ne convient pas)
Options globales: Il est possible de définir les valeurs des arguments pour tous les blocs dès le départ en incluant le bloc suivant au début du document (par défaut à la création d’un nouveau fichier .rmd) :

14. Code

14.2. Paramétrer le fonctionnement des blocs de code

14. Code

Pour présenter et souligner des extraits de code sans l’exécuter, comme du texte, l’insérer entre 2 accents graves :

r mean(23, 65, 43, 34, 56)

Insérer du texte dans des blocs: entourer le texte de ``` au début et à la fin

Du texte dans un bloc

        Du texte avec indentation

Sinon les espaces en début de ligne ne sont jamais pris en compte

Quelques détails finals:

Il est préférable d’ajouter une ligne vide entre différents éléments, comme un titre et un paragraphe.
Pour faire un saut de ligne: terminer la ligne par deux espaces + Entrée.
Pour ajouter des espaces supplémentaires entre les lignes/sections, utiliser la balise html: <br>.
Pour inclure des commentaires qui ne sortiront pas dans le document final, utiliser commentaires html: .

Atelier RMarkdown

1. Objectifs

1. Objectifs

Ce que l’on ne fera pas:

2. Ce dont on aura besoin (le minimum nécessaire)

3. RStudio (et autres IDE)

4. Installation

5. Qu’est-ce qu’un package?

6. Qu’est-ce R Markdown et pourquoi l’utiliser ?

6. Qu’est-ce R Markdown et pourquoi l’utiliser ?

7. Comment ça marche?

7. Comment ça marche?

8. Formats d’exportation de base disponibles

9. Packages utiles pour multiplier les formats possibles

10. Créer un fichier R Markdown

11. Anatomie d’un document R Markdown

11. Anatomie d’un document R Markdown

12. Métadonnées

12. Métadonnées

13. Texte formaté en Markdown

13.1. Qu’est-ce que le Markdown?

13. Texte formaté en Markdown

13.1. Qu’est-ce que le Markdown?

13. Texte formaté en Markdown

13.2. Syntaxe de base de Markdown

14. Code

14.1. Insérer des sections de code

On peut inclure du code de 2 façons :

14. Code

14.2. Paramétrer le fonctionnement des blocs de code

14. Code

14.2. Paramétrer le fonctionnement des blocs de code

14. Code

15. Pour aller plus loin

Suite:

15. Pour aller plus loin