BIO500

# Bloc 4

## Documents dynamiques <br> avec Rmarkdown

---

# Aujourd'hui

1. Documents dynamiques avec Rmarkdown
2. Arrimage avec `targets`

Voir les [diapositives du cours 2](https://econumuds.github.io/BIO500/bloc2/#33) et les [chapitres 8 et 9](https://econumuds.github.io/BIO500/markdown1.html) pour un rappel approfondi

---

# Pourquoi Rmarkdown?

<br>
.center[
  <img src="assets/img/why_rmarkdown.png" width="60%"></img>
]

---

# Pourquoi Rmarkdown?

- Documentation (dynamique) des analyses
- Facilite la partage/communication des résultats
- Utilisable sur les systèmes de controle de version (Git)
- Reproductible!
- Dans un environnement avec lequel vous êtes familier.ères

---

# Librairie `rticles`

```r
install.packages("rticles")
```

- Fournit une multitude de gabarits `Rmarkdown` (.Rmd)
- Différents types (articles/rapports)

---

# Via Rstudio

---

# Exemple `rticles`

---

# Exemple `rticles`

Un exemple complet, dans un répertoire type, est disponible sur [Moodle](https://github.com/EcoNumUdS/BIO500/tree/master/bloc4/exemple_targets)

---

# Exemple `rticles`

---

# Anatomie du gabarit .Rmd

Même anatomie que présentée dans le bloc2, mais générée automatiquement.

<br>
.center[
![:scale 90%](assets/img/Rmarkdown_anatomie.png)
]

---

# Le YAML - Rappel

- Les métadonnées et les options du document sont définies ici
- La syntaxe est `key: value`
- Commence et se termine entre trois tirets `---`
- Toujours au début du document

---
# Le YAML

# Use letters for affiliations, numbers to show equal authorship (if applicable) and to indicate the corresponding author
author:
  - name: "Benjamin Mercier"
    affiliation: "a"

address:
  - code: "a"
    address: "Université de Sherbrooke, Départment de biologie, 2500 Boulevard de l'Université, Sherbrooke, Québec, J1K 2R1"

abstract: |
  Eurytus auris. Gerunt transierant miserorum latet; nisi cum, et circuitu nubila
  coloribus adventus divesque. Loca partibus breve et unum maior stellis inpia et
  luporum.

keywords:
  - Mot-clé
  - Mot-clé
  - Optionel
  - Optionel
  - Optionel

## must be one of: pnasresearcharticle (usual two-column layout), pnasmathematics (one column layout), or pnasinvited (invited submissions only)
pnas_type: pnasresearcharticle

bibliography: pnas-sample.bib
csl: pnas.csl

## change to true to add optional line numbering
lineno: false

output: rticles::pnas_article
---
```
]

---

# Le YAML

D'un gabarit à l'autre, les champs du YAML vont changer.

Ce qui fait que chaque gabarit sera différent:
- Le champ `csl`
- Le champ `output`

---

# Gabarits "génériques"

**Deux colonnes:**<br>
Le gabarit 'PNAS Journal Article' est pratique.
<br><br>
**Une colonne:**<br>

Vous pourriez essayer le gabarit PNAS Journal Article avec la clé `pnas_type: pnasmathematics`

---

# Accéder aux données

Lire les données produites dans les targets précédentes avec `tar_read` et `tar_load`

Portion du fichier `_targets.R`
```r
list(
  tar_target(name = data,            command = read.csv("./data.csv")),
  tar_target(name = data_prep,       command = prep_donnees(data)),
  tar_target(name = resultat_modele, command = mon_modele(data)),
  tar_render(name = rapport,         path = "rapport/rapport.Rmd")
)
```

Présenter une figure à partir des données produites à la target `resultat_modele` dans le rapport `RMarkdown` et établir la dépendance du rapport à la target

```r
data_2_plot <- tar_read(resultat_modele)
plot(data_2_plot)
```

---

# Présenter une figure

Structure du bloc de code : 
- `fig.cap` : Légende
- `\\label{fig:plot1}` : Label pour référencer dans le texte
- `fig.width` : Commandes pour ajuster les dimensions

```r
'''{r figs, fig.cap="\\label{fig:plot1}Légende figure.", fig.width=7, fig.height=6}
# tar_read() permet de lire l'objet créé par la target
resultat_modele <- tar_read(resultat_modele)
data <- tar_read(data)

# Créer la figure
plot(data$X, data$Y)
abline(resultat_modele)
'''
```

---

# Insertion d'images

Insertion de figures préalablement générées via un script R.

Structure: 
- Légende
- Label pour référencer dans le texte
- Chemin pour accéder à la figure dans l'ordinateur
- Commandes pour ajuster les dimensions

.font90[
```r
![Légende figure. \label{fig:plot1}]("../results/plot_lm.pdf"){width=50% height=40%}
```
]

Attention ! De cette façon, le rapport ne se met pas à jour s'il y a un changement dans la figure.

---

# Référencer une figure

Utiliser la même balise que lorsque la figure a été créée et que son `\label` a été généré:

```r
Je fais référence à la Figure \ref{fig:plot1}.
```
.center[&darr;]

```r
Je fais référence à la Figure 1
```

---

# Bibliographie et références

Les références se font à l'aide du fichier .bib, lequel contient les références.

Le fichier .bib est spécifié dans le YAML du document .Rmd à la clé:

`bibliography: pnas-sample.bib`

.font70[
```bib
@inproceedings{belkin2002using,
  title={Using manifold stucture for partially labeled classification},
  author={Belkin, Mikhail and Niyogi, Partha},
  booktitle={Advances in neural information processing systems},
  pages={929--936},
  year={2002}
}

@article{berard1994embedding,
  title={Embedding Riemannian manifolds by their heat kernel},
  author={B{\'e}rard, Pierre and Besson, G{\'e}rard and Gallot, Sylvain},
  journal={Geometric \& Functional Analysis GAFA},
  volume={4},
  number={4},
  pages={373--398},
  year={1994},
  publisher={Springer}
}
```
]

---

# Bibliographie et références

Pour utiliser une référence dans le texte il suffit d'utiliser sa clé unique:

```r
Je fais référence à la première entrée du fichier.bib @belkin2002using.
```

Pour référencer plusieurs références:

```r
Je fais référence à plusieurs références [@belkin2002using;@berard1994embedding]
```

---

# Générer le fichier .bib

**Optimal et rapide**:<br>
- Logiciel de gestion des références comme Zotero, Mendeley, EndNote etc.
- Générer le fichier .bib selon votre liste d'articles

**Alternative**:<br>
- Générer le fichier manuellement via un fichier `plain text`
- Copier-coller les références bib de chacun des articles via par exemple GoogleScholar

---

# Fichier .bib manuellement

---

# À vous de jouer

## Créez un rapport `Rmarkdown` avec le gabarit `PNAS Journal Article` puis compilez-le

Modifiez certains éléments et vérifiez le résultat dans le fichier PDF généré.

---

# Arrimer targets et Rmarkdown

---

# Un exemple compréhensif

Un exemple de répertoire avec `targets` et `rmarkdown` est disponible. Le lien se trouve sur Moodle sous la section "Bloc 4" et la rubrique "Exemple *complet* d'un pipeline targets"

- Explicite les dépendances aux multiples fichiers de données
- Compile un rapport RMarkdown
- Explicite les dépendances du rapport

---

# `targets` + rapport `rmarkdown`

Structure du dossier principal :

├── data                            # Dossier de données
│   ├── data.txt                    # Jeu de données 1
│   ├── data_2.txt                  # Jeu de données 2

├── R                               # Dossier de scripts R
│   ├── prep_donnees.R              # Fonction utilisér comme targets
│   ├── analyse.R                   # Fonction utilisée comme targets
│   ├── figure.R                    # Fonction utilisée comme targets

├── resultats                       # Contient les résultats 
│   ├── resultats_modele.csv        # Résultats

├── rapport                         # Contient le rapport et fichiers associés
│   ├── rapport.Rmd                 # Rapport
│   ├── pnas-sample.bib             # Fichier de bibliographie

├── _targets.R                      # Fichier targets qui définie le pipeline

```
]

---

# Fichier _targets.R

.font80[
```r
# Version bonnifiée du bloc 2
library(targets)
library(tarchetypes)
source("R/analyse.R")
tar_option_set(packages = c("rmarkdown","knitr"))
list(
  tar_target(
    name = path, # Cible
    command = "./data", # Dossier contenant les fichiers de données
    format = "file" # Format de la cible
  ),
  tar_target(
    name = file_paths, # Cible
    command = list.files(path, full.names = TRUE) # Liste les fichiers dans le dossier
  ),
  tar_target(
    name = data, # Cible pour le modèle 
    command = prep_donnees(file_paths) # Jointure des jeux de données
  ),
  tar_target(
    name = resultat_modele, # Cible pour le modèle 
    command = mon_modele(data) # Exécution de l'analyse
  ),
  tar_render(
    name = rapport, # Cible du rapport
    path = "rapport/rapport.Rmd" # Le path du rapport à renderiser
  )
)
```
]

---

# Suivre un ensemble de fichiers de données

1. Une target pour suivre le dossier contenant les données
.font80[
```r
tar_target(
  name = path, # Cible
  command = "./data", # Dossier contenant les fichiers de données
  format = "file" # Format de la cible
)
```
]
2. Une target qui liste tous les fichiers du dossier
.font80[
```r
tar_target(
    name = file_paths, # Cible
    command = list.files(path, full.names = TRUE) # Liste les fichiers dans le dossier
  )
```
]
3. Une target qui charge les données et les assemblent
.font80[
```r
tar_target(
  name = data, # Cible 
  command = prep_donnees(file_paths) # Jointure des jeux de données
)
```
]

---

# Compilation du Rmarkdown

La librarie `tarchetypes` simplifie la compilation du fichier .Rmd.<br>
Même syntaxe que les autres target `tar_target()`

```r
install.packages("tarchetypes")
```

```r
tar_render(cible, "path/to/file.Rmd")
```

<br>

L'instruction de compilation du fichier .Rmd sera toujours la dernière opération.

---

# Travail final

---

# Objectif

Écrire un rapport sous forme d'article scientifique

---

# Consignes

Vous devez remettre les résultats de votre analyse des données de collaboration entre les étudiants de la classe.

Le rapport doit contenir :

- 3 figures
- Un titre et un résumé
- Une courte introduction spécifiant les questions
- Une courte description de la méthode et des résultats
- Une discussion, enrichie de citations provenant de la littérature scientifique
- Références internes (figures, bibliographie)
- L'ensemble du texte doit faire 1000-1500 mots max
- Une bibliographie

---

# Consignes

Nous vous demandons de remettre les scripts permettant de générer l'ensemble du document, incluant :

- La création de la base de données
- La correction des données originales
- L'injection des données
- Les requêtes
- La production des figures et tableaux
- Le document RMarkdown (en format Rmd) incluant des citations
- Le fichier de bibliographie

---

# Évaluation

À terme, selon les principes de science reproductible, nous devrions pouvoir exécuter l'ensemble de votre analyse sur un autre ordinateur, sans avoir à changer le code.

Nous utiliserons la commande `tar_make` pour tout exécuter automatiquement.

Néanmoins, l'ensemble de ce matériel doit se trouver sur un dépôt git auquel vous nous donnerez accès. Dans ce dépôt se trouveront les fichiers de données originales en csv, les scripts, le document Rmd ainsi que la bibliographie.

---

# Évaluation

- Respect des consignes
  - Présence et clarté des éléments du rapport
  - Pertinence des visualisations
  - Qualité du français
- Reproductibilité
  - Utilisation appropriée du versionnage
  - Validation des données et conception de la base de données
  - Requêtes
  - RMarkdown
  - Automatisation (targets)
  - structure du répertoire GitHub

Le contenu du rapport n'est pas d'une grande importance, il est prétexte à faire toutes les étapes du travail. Ne vous attardez pas à la rédaction, l'objectif est seulement de décrire rapidement votre démarche et d'utiliser `RMarkdown` pour la préparation d'un rapport.

---
class: inverse, center, middle

# Discussion

## Le rôle de la reproductibilité pour la prévension des fraudes