21 janvier 2019

Qui suis-je ?

Pourquoi utiliser R Markdown ?

Pourquoi utiliser R Markdown ?

Pourquoi utiliser R Markdown ?

Un principe : Keep it simple

Prise en main dans RStudio

  • RStudio : compagnon idéal
    • Menu File > New File > R Markdown...
    • Conseil : désactiver le mode notebook
      Tools > Global Options
  • pour les pdf, si vous n’avez pas \(\LaTeX\) d’installé, utilisez le package tinytex demo…

Concepts de base de R Markdown

  1. En-tête YAML : indications données au package rmarkdown (type de document souhaité, options, méta-données…)

  2. Chunks : code dont le résulat sera inséré dans le document final (➡️ knitr)

  3. Markdown : une façon simple d’écrire du texte (➡️ pandoc)

Introduction en 🇫🇷

En-tête du document

---
title: Créez vos documents avec R Markdown
author: Romain Lesur
date: 21 janvier 2019
output: 
  ioslides_presentation:
    widescreen: true
    self_contained: false
    logo: "assets/meetuprnantes.jpeg"
    keep_md: true
---

Attention à l’indentation

Multipliez les format de sortie

Avec output, vous pouvez produire plusieurs formats à partir du même fichier source :

---
title: Créez vos documents avec R Markdown
author: Romain Lesur
date: 21 janvier 2019
output: 
  html_document: default
  pdf_document: default
---

Exécuter dans la console :

rmarkdown::render("monfichier.Rmd", output_format = "all")

Type de documents

Vous pouvez produire :

  • des documents HTML
  • des documents paginés (articles, livres, thèses) : pdf avec \(\LaTeX\), docx, odt…
  • des présentations : HTML et pptx
  • des tableaux de bord
  • des cours et sujets d’examens
  • des sites internet statiques

Modèles prêts à l’emploi

De nombreux packages fournissent des modèles prêts à l’emploi : rmarkdown, flexdashboard, hrbrthemes, komadown, komaletter, learnr, linl, memor, papaja, pinp, prettydoc, radix, revealjs, rmdformats, rmdshower, rticles, tufte, unilur, vitae, xaringan…

Pour les livres et thèses : bookdown

Pour les sites web : blogdown

Des packages pour aider sur des taches spécifiques

Tout un écosystème de packages pour aider :

  • l’incroyable officer de David Gohel pour MS Office
  • tinytex pour installer facilement \(\LaTeX\)
  • pour les tableaux : flextable (David Gohel), kableExtra, gt…

Des documents paramétrés

A partir du même fichier R Markdown, produire des rapports sur différentes zones géographiques, différentes périodes…

---
title: My Document
output: html_document
params:
  annee: 2018
  region: Europe
---

Disponible depuis le bouton Knit de RStudio ou

rmarkdown::render("monfichier.Rmd", params = list(annee = 2018, region = Europe))

knitr chunks

Deux façons d’insérer du code dans son document

  1. Code chunk

    ```{r, eval=TRUE, echo=FALSE}
head(mtcars)
```

    De nombreuses options ! yihui.name/knitr/options

  2. Inline code

    La moyenne est de `r mean(mtcars$cyl)`.

Différents langages autorisés

names(knitr::knit_engines$get())
##  [1] "awk"       "bash"      "coffee"    "gawk"      "groovy"   
##  [6] "haskell"   "lein"      "mysql"     "node"      "octave"   
## [11] "perl"      "psql"      "Rscript"   "ruby"      "sas"      
## [16] "scala"     "sed"       "sh"        "stata"     "zsh"      
## [21] "highlight" "Rcpp"      "tikz"      "dot"       "c"        
## [26] "fortran"   "fortran95" "asy"       "cat"       "asis"     
## [31] "stan"      "block"     "block2"    "js"        "css"      
## [36] "sql"       "go"        "python"    "julia"

Exemple : python avec le package reticulate

  1. Initialisation de la configuration

    ```{r, include=FALSE}
library(reticulate)
use_python("usr/local/bin/python")
use_virtualenv("r-reticulate")
py_install(c("pandas", "numpy"))
```

  2. Script python

    ```{python}
a = 1
print(a)
```
    ## 1

Communication entre R et python

```{python}
import pandas as pd
import numpy as np

dates = pd.date_range('20130101', periods=6)
df = pd.DataFrame(np.random.randn(6,4), index=dates, columns=list('ABCD'))
```
```{r}
head(py$df, n = 2L)
```
A B C D
2013-01-01 0.2952525 -1.126555 0.9311392 1.3895048
2013-01-02 0.4104249 -1.201973 -0.1641902 -0.7289867

Exemple : node.js avec un script externe

Vous voulez écrire un cours sur node.js.
Vos scripts sont dans des fichiers .js.

Vous pouvez écrire :

```{node, code=readLines('node/example.js')}
```
const hi = (name) => {
  console.log("Hello " + name + "!");
};

hi("Bob");
## Hello Bob!

Voir le repo source : https://github.com/RLesur/meetup-r-nantes-rmd

Exemple : SQL avec scripts externes

Etape 1 : connexion à la base de données

```{r, include=FALSE}
conn <- DBI::dbConnect(RSQLite::SQLite(), path = ":memory:")
```
```{sql, connection=conn, code=readLines('sql/list_tables.sql')}
```
SELECT name FROM sqlite_master WHERE type='table';
1 records
name
mtcars 

```{sql, connection=conn, code=readLines('sql/data.sql')}
```
SELECT mpg, cyl, disp FROM mtcars
       LIMIT 2;
2 records
mpg cyl disp
21 6 160
21 6 160

Se déconnecter :

```{r, echo=FALSE}
DBI::dbDisconnect(conn)
```

Markdown : simple mais puissant

R Markdown Cheat Sheet

Le fonctionnement de R Markdown

Le package rmarkdown assure la bonne exécution des étapes suivantes :

  • fichier .Rmd ➡️ fichier .md = knitr
    Exécution des chunks et insertion du résultat

  • fichier .md ➡️ fichier .html ou .tex, .docx, .odt… = Pandoc

Pour les pdf avec \(\LaTeX\), étape supplémentaire :

  • fichier .tex ➡️ fichier .pdf = \(\LaTeX\)

Hacker R Markdown

On peut aller très loin dans l’adaptation de R Markdown

  • Hacker RStudio

  • Hacker R Markdown

  • Hacker knitr

  • Hacker pandoc

Hacker RStudio

Exemple : Hacker le bouton knit de RStudio

Rajouter dans l’en-tête YAML du fichier Rmd une ligne qui renvoie une fonction \(\lambda\) ayant pour arguments (inputFile, encoding)

knit: (function(inputFile, encoding){...})

Si en plus la fonction comprend message("Output created: ", outputFile), le viewer de RStudio l’ouvrira.

Voir https://github.com/rstudio/rmarkdown/issues/277

Hacker R Markdown

On peut créer des nouveaux formats avec rmarkdown::output_format() :

function (knitr, pandoc, keep_md = FALSE, clean_supporting = TRUE, 
    df_print = NULL, pre_knit = NULL, post_knit = NULL, pre_processor = NULL, 
    intermediates_generator = NULL, post_processor = NULL, on_exit = NULL, 
    base_format = NULL)

  • knitr et pandoc : options passées à knitr et pandoc

  • pre_knit, post_knit, pre_processor, intermediates_generator, post_processor et on_exit : des fonctions appelées à chaque étape de la génération du document

Hacker knitr

Des dizaines d’options…
Exemple : hooks

`r pi` donne par défaut : 3.1415927.
Mais on voudrait avoir des , à la place des .

Avec le hook suivant, on peut modifier le comportement des inlines codes :

default_hook <- knitr::knit_hooks$get()$inline
knitr::knit_hooks$set(inline = function(x) {
  default_text <- default_hook(x)
  if (!is.numeric(x))
    return(default_text)
  gsub("\\.", ",", default_text)
})

Et maintenant `r pi` donne 3,1415927.

Hacker pandoc

Lorsque pandoc transforme un document d’un format vers un autre, il passe par une représentation sous forme arbre syntaxique abstrait (qu’on peut sérialiser en JSON, par ex.).
On peut modifier cet AST grâce à des filtres, voir https://pandoc.org/filters.html.

Langages acceptés : tous (!)
lua privilégié depuis pandoc 2

Egalement la possibilité de développer son propre sérialiseur : https://pandoc.org/MANUAL.html#custom-writers

Références