Avant-propos : comment utiliser ce guide?
Le format de fichier RMarkdown est extrêmement flexible et, pour s’y
retrouver, il faut savoir distinguer ses sous-composantes. Un script
RMarkdown peut-être subdivisé en trois types de contenus:
l’entête YAML (section 1), le texte
(section 2) et les blocs (ou chunks)
de code (section 3).
L’objectif de ce guide est de répertorier toutes les informations dont vous pourriez avoir besoin pour rédiger un script RMarkdown. Ainsi, vous n’aurez pas nécessairement besoin d’utiliser toutes les petites astuces qui s’y trouvent. Il existe bien entendu des guides plus exhaustifs pour apprendre à utiliser RMarkdown (ex.: R Markdown: The Definitive Guide ou R Markdown Cookbook) mais je tenais à regrouper et vulgariser un sous-ensemble d’éléments que je considère plus essentiels.
Pour parvenir à rédiger vous-même un script RMarkdown, je vous conseil de lire attentivement les sections principales (1, 2 et 3) de ce guide ainsi que la section 3.1. Vous pouvez vous permettre de lire un peu moins attentivement les sous-sections 1.1 à 1.3 et 2.1 à 2.5.
L’entête YAML réfère à la section de code située au tout début de
votre script entourée par 3 tirets (---). Cette entête
contient des métadonnées facultatives permettant de modifier l’affichage
de votre document final (c.-à-d. le « output » de votre script). Par
exemple, l’entête YAML permet de spécifier le type de fichier pour le
output, le titre de votre document, l’inclusion d’une table des
matières, etc..
Voici à quoi pourrait ressembler l’entête YAML d’un script RMarkdown destiné à créer un fichier html (comme celui que vous lisez en ce moment).
---
output: html_document
title: "Titre_de_votre_script"
author: "Votre_nom"
date: "la_date"
---Cette entête se lie assez intuitivement. Elle spécifie tout d’abord
le format du output (un fichier html dans ce
cas-ci), le titre, le nom de l’auteur.e et finalement la date de
création du document. L’ordre des arguments n’a pas d’importance si
ceux-ci ne sont pas définie de façon hiérarchique (voir prochaine
section).
Il est possible de modifier l’entête YAML pour bonifier le document final. À titre d’exemple, voici trois éléments pouvant être incorporés à un document html par l’intermédiaire de l’entête YAML
Voici comment inclure une table des matières et spécifier (optionnellement) des sous-options de la TDM :
toctoc_depth pour spécifier le nombre de sous-niveaux
affichés dans la TDM (3 par défaut)toc_float pour que la TDM soit toujours visible dans la
marge gauchecollapsed (TRUE par défaut) pour
déterminer si la table est étendue ou compacte par défaut (seulement
titres visibles)smooth_scroll (TRUE par défaut) détermine
si la TDM défile en même temps que le défilement de la page---
output:
html_document:
toc: true
toc_depth: 2
toc_float: true
collapsed: false
smooth_scroll: false
title: "Titre_de_votre_script"
author: "Votre_nom"
date: "la_date"
---L’option number_section permet de numéroter les titres
de votre script.
---
output:
html_document:
number_sections: true
title: "Titre_de_votre_script"
author: "Votre_nom"
date: "la_date"
---Il est possible d’ajouter le paramètre d’affichage
df_print: paged à l’entête YAML pour modifier l’affichage
des tableaux et rendre le document final plus agréable à regarder. Voici
comment faire :
---
output:
html_document:
df_print: paged
title: "Titre_de_votre_script"
author: "Votre_nom"
date: "la_date"
---Le texte écrit dans un fichier RMarkdown — c.-à-d. tout ce qui ne
fait pas partie d’un bloc de code ou de l’entête YAML — est formaté en
markdown. Cela signifie que vous pouvez utiliser certaines
astuces pour modifier l’affichage de votre texte dans le document final.
Voici quelques exemples :
Dans votre document final, les sauts de lignes et de paragraphe ne
reflèteront pas toujours exactement ceux que vous voyez dans votre
script. L’opérateur \ vous permet d’indiquer explicitement
un saut de ligne. Vous pouvez également indiquer un changement de
paragraphe en ajoutant deux espaces () à la fin de celui-ci
ou en laissant une ligne vide dans votre script.
Note: il est difficile de fournir un exemple de cette fonctionnalité.
#)Les titres sont créés avec le symbole #. Le nombre de
# détermine le « niveau hiérarchique » de votre titre. Les
titres apparaîtrons automatiquement dans votre table des matières (si
vous avez activé cette option).
Code :
### Exemple de sous-titre de niveau 3
#### Exemple de sous-titre de niveau 4
Résultat :
Le format markdown vous permet de modifier l’affichage
du texte en entourant les passages que vous souhaitez modifier avec
certains symboles. Voici quelques exemples :
Texte = Texte (aucune modification)
*Texte* = Texte (italique)
**Texte** = Texte (gras)
***Texte*** = Texte (italique +
gras)
`Texte` = Texte (code en verbatim)
~~Texte~~ = Texte (barré)
-)Les tirets (-) ou les chiffres suivies d’un point (ex.:
1., 2., etc.) permettent de créer des
listes.
Code :
Voici une liste non-ordonnée :
- Banane
- Poire
Voici une liste ordonnée :
1. Banane
2. PoireRésultat :
Voici une liste non-ordonnée :
Voici une liste ordonnée :
Mettre trois tirets (---) tout seul permet d’insérer une
ligne horizontale qui accentue la séparation entre différentes sections
de votre document. Il peut être pratique de mettre une ligne de
séparation directement avant un #Titre.
Code :
Paragraphe 1
Paragraphe 2
---
Paragraphe 3Résultat :
Paragraphe 1
Paragraphe 2
Paragraphe 3
chunks)Les blocs de code serve à incorporer de la syntaxe dans votre fichier
RMarkdown. Les blocs de code sont séparé du texte à l’aide de trois
accents graves (```) (de façon similaire aux trois tirets
--- de l’entête YAML). Les blocs de code ont la
particularité de pouvoir être dans n’importe quel langage de
programmation. C’est pourquoi il est nécessaire de spécifier quel
langage on utilise avec des accolades {r}.
Voici à quoi un bloc de code R vide devrait ressembler
dans votre fichier RMarkdown :
```{r}
```Pour ne pas avoir à ré-écrire ou copier-coller tout ça à chaque fois
que vous voulez créer un bloc de code, vous pouvez simplement utiliser
les raccourcis suivant :
Pour Windows = Alt (⎇) + Commande
(⊞) + i
Pour Mac = Option (⌥) + Commande
(⌘) + i
Note : Si ces raccourcis ne fonctionnent pas pour vous, vous
pouvez toujours consulter vos raccourcis dans les réglages. Voici
comment y accéder :
Preferences > Code >
Editing > Modify Keyboard Shortcuts...
Il est souvent utile d’inclure un bloc de code au tout début de votre
script (juste après l’entête YAML) pour spécifier certaines commandes R
nécessaires au bon fonctionnement de votre document final. Généralement,
on ajoute l’argument include=FALSE aux paramètres de ce
bloc de code afin que celui-ci ne s’affiche pas dans le document final.
Voici quatre éléments qu’il est pratique d’incorporer à votre bloc de
code setup :
Je vous recommande structurer vos blocs de code setup de
la façon suivante :
```{r setup, include=FALSE}
# Activation des packages :
library(knitr)
library(readr)
library(tibble)
# Affichage des blocs de code dans le document final :
opts_chunk$set(echo = TRUE)
# Importer les données :
donnees_brutes <- read_csv("folder path")
# Préparer les données :
df <- as_tibble(data.frame(id = nrow(donnees_brutes)))
```Note: les détails relatifs à cette syntaxe seront expliquer dans
les documents importer_les_donnees.html et
preparer_les_donnees.html sur Studium.