class: center, middle, inverse, title-slide # Aller vers une démarche documentée et reproductible avec rmarkdown ## .doana-title[<img src="img/logoDoAna.png" />] ### DoAna - Statistiques Réunion ### 2020 --- layout: true .my-footer[ .footer-title[Aller vers une démarche documentée et reproductible]] --- name: plan ## Sommaire *** .pull-left[ 1) Les bases de rmarkdown - Introduction - Comment ça marche - Interface de RStudio - Compiler le rapport 2) Le formatage du texte - markdown de Pandoc ] .pull-right[ 3)Les *chunks* de code - Créer un nouveau *chunk* - Nommer les *chunks* - Les options des *chunks* - Les options pour les graphiques - Régler `fig.width` - Les tables en sortie - Les options globales - Du code dans le texte - Débogage 4) L'en-tête YAML - Contrôle du document dans sa globalité - Les paramètres `params` - La biblioraphie ] --- class: inverse, center, middle # Les bases de rmarkdown --- background-image: url(img/rmarkdown_script-html.png) --- ## Introduction *** ### Intérêt - Code, résultats et prose combinés dans un seul fichier - Reproductibilité assurée - Sortie adaptable : PDF, page web, Word, présentation, document interactif (type shiny), site Internet -- ### Usages possibles 1. Communiquer aux décisionnaires : focus sur les résultats et non sur le code sous-jacent 2. Collaborer avec d'autres scientifiques : focus sur le chemin pour arriver aux conclusions 3. Conserver une trace de ses travaux et de ses pensées dans ce cahier de laboratoire moderne --- ## Comment ça marche *** .pull-left[ Package **rmarkdown** installé et chargé automatiquement grâce à RStudio. Un fichier .Rmd contient 3 types de contenu : - l'en-tête (*YAML*) optionnelle entourée de `---` - le code R (*chunks*) entourées de ` ``` ` - du texte simple avec un formatage de type markdown **Aide** : - Help > Cheatsheets > R Markdown Cheat Sheet, - Help > Cheatsheets > R Markdown Reference Guide. ] .pull-right[  ] ??? Aide spécifique rmarkdown non accessible via `?` Sources : - https://r4ds.had.co.nz/ - https://rmarkdown.rstudio.com --- ## Interface de RStudio *** - Créer un nouveau rapport : File > New file > Rmarkdown... - Lancer le code d'un *chunk* : `Ctrl + Maj + Entrer` ou la flèche verte en haut à gauche du chunk - Lancer une partie du *chunk* : `Ctrl + Entrer` - Lancer tous les *chunk* : `Ctrl + Alt + R` > On ne se sert plus de la console comme lorsque l'on travaille avec des scripts. -- ### Nouveau ! Pour les versions de RStudio > 1.4 : mode éditeur accessible via .inlineimg[]. La barre .inlineimg[] permet de formater le texte très simplement ! --- ## Compiler le rapport *** .pull-left[ Il suffit de cliquer sur .inlineimg[] ou de faire `Ctrl + Maj + K`. La sortie dépend de ce qui est indiqué dans l'option `output` dans le YAML. En ligne de commande : ```r library(rmarkdown) render("rapport.Rmd") ``` ### En coulisse  ] .pull-right[  ] ??? 2 étapes de compilation : - Rmd -> md via **knitr**, https://yihui.name/knitr/ : md inclue les sorties du code - md -> fichier final via **pandoc**, https://pandoc.org/ (hors de R) --- template: plan --- class: inverse, center, middle # Le formatage du texte --- ## markdown de Pandoc (sans le R) *** .pull-left[ - langage simple à écrire à lire et à apprendre - chercher de l'aide sur le site de [Pandoc](https://pandoc.org/) - exemples : ```md _italique_ ou *italique* __gras__ **gras** `code` exposant^2^ et indice~2~ # Titre de niveau 1 ## Titre de niveau 2 ### Titre de niveau 3 - Liste simple item 1 - Item2 - Item 2a - Item 2b ``` ] .pull-right[ ```md 1. Liste numérotée item 1 1. Item 2. Incrémentation automatique en sortie <http://example.com> [texte en lien](http://example.com)  Colonne1 | Colonne2 ------------- | ------------- Cellule | Cellule Cellule | Cellule ``` ] ??? n'oubliez pas le mode éditeur, qui permet de faire pas mal de formatage sans rien apprendre ! **Exercice** : Avec le R Markdown quick reference, trouve comment : - Ajouter une note de bas de page - Ajouter une ligne horizontale - Ajouter une citation --- template: plan --- class: inverse, center, middle # Les *chunks* de code --- ## Créer un nouveau *chunk* *** - Raccourci clavier : Ctrl + Alt + I (recommandé) - Bouton : .inlineimg[] - Manuellement écrire : ` ```{r} ` et ` ``` `. > Un chunk = une seule tâche (en général) --- ## Nommer les *chunks* *** Le nom est optionnel : ` ```{r mon-nom} `. Avantages : - Navigation plus aisée avec le menu déroulant en bas à gauche - Noms pertinents pour les graphiques en sortie - Le résultat des chunks peut être mis en mémoire cache (notion avancée) <br> > Le chunk qui s'appelle `setup` a un comportement spécial : il est lancé une seule fois avant tous les autres. --- ## Les options des *chunks* *** Liste complète : http://yihui.name/knitr/options/ Ecriture : ` ```{r mon-nom, une-option=qqch} ` ou ` ```{r une-option=qqch} ` Options qui gèrent si le code est executé et quelles sont les sorties affichées : Option | Lance code | Montre code | Sortie | Graphique | Messages | Warnings -------|:-----------:|:------------:|:------:|:----------:|:--------:|:--------: `eval = FALSE`| x | o | x | x | x | x `include = FALSE` |o | x | x | x | x | x `echo = FALSE` | o | x |o |o |o | o `results = "hide"` |o | o | x | o |o | o `fig.show = "hide"` |o |o |o | x | o | o `message = FALSE` |o |o |o | o | x | o `warning = FALSE` |o |o |o | o | o | x --- ## Les options pour les graphiques *** Les *chunk options* pour contrôler la taille des graphiques en sortie sont : `fig.width`, `fig.height`, `fig.asp`, `out.width` et `out.height`. **Attention** : taille de la figure créée par R (`fig`) vs. taille que prend l'image dans le fichier en sortie (`out`) -- 3/5 options suffisent à régler les deux autres : - Largeur uniforme : ex `fig.width = 6` et `fig.asp = 0.618` (le nombre d'or) dans les options globales (voir plus loin). Au cas par cas, changer `fig.asp` -- - Emplacement de la figure : `out.width = "70%"` (pourcentage de la largeur de la page) et `fig.align = "center"` laissent de l'air aux figures -- - Pour plusieurs graphiques sur une même ligne : `out.width = "50%"` pour 2 graphiques, `33%` pour 3 graphiques ou `25%` pour 4 graphiques, avec `fig.align = "default"` --- ## Régler `fig.width` *** Les `fig.width` sont réglés à 4, 6 et 8 : .colonnes3[ <img src="rmarkdown_files/figure-html/width4-1.png" width="100%" style="display: block; margin: auto;" /> <img src="rmarkdown_files/figure-html/width6-1.png" width="100%" style="display: block; margin: auto;" /> <img src="rmarkdown_files/figure-html/width8-1.png" width="100%" style="display: block; margin: auto;" /> ] Pour une taille de police cohérente entre figures qui n'ont pas le même `out.width` : règle de 3 avec `fig.width`. Exemple : si le défaut est `fig.width = 6` et `out.width = 0.7`, quand `out.width = "50%"` il faudra mettre `fig.width = 4.3` (6 * 0.5 / 0.7) --- ## Les tables en sortie *** .pull-left[ Par défaut : ```r cars[1:5, ] # # speed dist # # 1 4 2 # # 2 4 10 # # 3 7 4 # # 4 7 22 # # 5 8 16 ``` ] -- .pull-right[ Avec la fonction `kable()` : ```r knitr::kable(cars[1:5, ]) ``` | speed| dist| |-----:|----:| | 4| 2| | 4| 10| | 7| 4| | 7| 22| | 8| 16| Possibilité de le faire systématiquement en indiquant dans le YAML (attention aux espaces) : ``` output: html_document: df_print: kable ``` ] ??? Aide supplémentaire : `?knitr::kable` Voir aussi les packages : xtable, stargazer, pander, tables et ascii --- ## Les options globales *** Pour changer une option de chunk dans TOUT le document, appeler `knitr::opts_chunk$set()` dans un chunk (dans le `setup` par exemple). Cette présentation a les options suivantes : ```r knitr::opts_chunk$set( collapse = TRUE, fig.asp = 0.618, out.width = "70%", fig.align = "center" ) ``` Si c'est un rapport destiné à un non-lecteur de R : ```r knitr::opts_chunk$set( echo = FALSE # cache le code par défaut ) ``` Pour montrer délibérément le code d'un chunk : `echo = TRUE` dans l'en-tête du chunk en question --- ## Du code dans le texte *** Le *inline code* s'écrit entre ``` ` ``` : ```md On a les données de `r nrow(diamonds)` diamants. Seuls `r nrow(diamonds) - nrow(smaller)` font plus que 2,5 carats. ``` Et cela donne en sortie : > On a les données de 53940 diamants. Seuls 126 font plus que 2,5 carats. Attention aux nombres réels, la fonction `format()` est votre amie pour gérer le nombre de décimales et le séparateur de milliers: ```r format(x, digits = 2, big.mark = " ") ``` --- ## Débogage *** Trouvez les erreurs est plus difficile car compiler avec **Knit** nécessite qu'il n'y ait aucune erreur nulle part. Conseils : - Lancer **Knit** souvent - Restart R `Ctrl + Maj + F10` puis Run all chunks `Ctrl + Alt + R` pour localiser l'erreur et travailler interactivement (avec la console) - Parfois l'environnement de la console et celui de rmarkdown sont différents (souvent problème de chemin relatif : lancer `getwd()` dans un chunk) - Mettre `error=TRUE` comme option dans le chunk qui pose problème --- template: plan --- class: inverse, center, middle # L'en-tête YAML --- ## Contrôle du document dans sa globalité *** .pull-left[ - YAML : *yet another markup language* représente des données hiérarchiques - Attention aux indentations ### Format de sortie - Avec le bouton Knit (to HTML, to PDF, to Word) - Programmatiquement : `render("rapport.Rmd", output_format = "word_document")` - Avec le YAML (recommandé) : `html_document`, `pdf_document`, `word_document`, `ioslides_presentation`, ... ### Options des formats Voir `?rmarkdown::html_document` par exemple. ] .pull-right[  ] ??? Liste complète des formats ici : https://rmarkdown.rstudio.com/lesson-9.html --- ## Les paramètres `params` *** Compiler plusieurs rapports avec une valeur qui change pour chacun.  Voir aussi `Knit with Parameters` dans le menu **Knit**... ??? ou programmatiquement, faire une boucle avec la fonction `render(fichier.rmd, params = list(...))` --- ## La bibliographie *** Dans le YAML : `bibliography: chemin/rmarkdown.bib` Formats pris en charge : BibLaTeX, BibTeX, endnote, medline. Dans le texte pour citer : ```md Séparer plusieurs citations par `;`: Bla bla [@smith04; @doe99]. Citation dans le texte : @smith04 dit bla, ou @smith04 [p. 33] dit bla. A la fin # Bibliographie ``` Pour modifier le style de la bibliographie (styles courant [ici](http://github.com/citation-style-language/styles)) : ```md bibliography: rmarkdown.bib csl: apa.csl ``` --- class: inverse, bottom, center ### Vous allez aimer la reproductibilité ! -- &nbsp; -- &nbsp; -- ### ☺ -- &nbsp; -- &nbsp; -- [Accueil](/)