BIO500

class: title-slide, middle

# Bloc 4

## Documents dynamiques <br> avec Rmarkdown

.instructors[
**BIO500** - Victor Cameron
]

---

# Aujourd'hui

1. Documents dynamiques avec Rmarkdown
2. Arrimage avec l'automatisation du projet

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

---

# Structure du répertoire projet

.left[
```

Projet
│
├── 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
│   ├── analyse.R                   # Fonction
│   ├── figure.R                    # Fonction
│
├── resultats                       # Contient les résultats 
│   ├── resultats_modele.csv        # Résultats
│   ├── plot_lm.pdf                 # Figure
│
├── rapport                         # Contient le rapport et fichiers associés
│   ├── rapport.Rmd                 # Rapport
│   ├── pnas-sample.bib             # Fichier de bibliographie
│
├── _projet.R                       # Fichier qui défini le pipeline

```
]

---

# 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

.center[
![:scale 90%](assets/img/rstudio_rticles.png)
]

---

# Exemple `rticles`

.center[
![:scale 90%](assets/img/rapport_template.png)
]

---

# Exemple `rticles`

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

---

# Exemple `rticles`

.left[

- Template `PNAS Journal Article`
- Principaux fichiers: .Rmd, .bib, .csl
  ]

.right[
![:scale 30%](assets/img/pnas_generatedfiles.png)
]

---

# 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 (dont les paramètres)
- La syntaxe est `key: value`
- Commence et se termine entre trois tirets `---`
- Toujours au début du document

---

# Le YAML

.font70[

```r
---
title: "Exemple de rapport `Rmarkdown` en sortie d'un pipeline"

params:
  donnees: NULL

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

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

## 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

Utiliser dans le rapport les données produites dans les étapes précédentes : les paramètres.

1- Ajouter l'objet aux paramètres dans le YAML du fichier `_projet.R` :

```r
---
title: "Exemple de rapport `Rmarkdown` en sortie d'un pipeline"

params :
  donnees: NULL
---
```

2- Exécuter le rapport `RMarkdown` avec les données en paramètre depuis le pipeline dans le fichier `_projet.R` :

```r
data <- read.table("data/data.txt", header = TRUE)

rmarkdown::render('rapport.Rmd', params = list(donnees = data))
```

---

# Présenter une figure

Structure du bloc de code :

- `fig.cap` : Légende
- `\\label{fig1}` : Label pour référencer dans le texte
- `fig.width` : Commandes pour ajuster les dimensions

```r
'''{r figs, fig.cap="\\label{fig1}Légende figure.", fig.width=7, fig.height=6}
resultat_modele <- read.table("results/resultats_modele.txt", header = TRUE)
data <- read.table("data/data.txt", header = TRUE)

# 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{fig1}]("../resultats/plot_lm.pdf"){width=50% height=40%}
```

]

---

# 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{fig1}.
```

.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}
}
```

]

*Créez votre propre fichier .bib avec les références de votre projet!*

---

# 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

.center[
![:scale 90%](assets/img/googlescholar.png)
]

---

# À 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é.

---

class: inverse, center, middle

# Travail final

---

# Objectif

Écrire un rapport sous forme d'article scientifique

---

# Consignes

Vous devez remettre les résultats de vos analyses.

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 `source` pour tout exécuter automatiquement.

Néanmoins, l'ensemble de ce matériel doit se trouver sur votre dépôt git d'équipe. Dans ce dépôt se trouveront les fichiers de données originaux en csv, les scripts, le document Rmd ainsi que la bibliographie.

.content-box-red[Pour cette évaluation, ce sera la responsabilité de l'utilisateur d'installer

les librairies requises pour exécuter le code.]

---

# É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 (pipeline)
  - 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