Cette fiche de travail vise à présenter R Markdown, un environnement de travail permettant de créer des documents en data science.
Dans un unique fichier R Markdown, il est possible d’écrire du code et de l’exécuter, puis de produire des rapports (mêlant textes, codes, et résultats des évaluations des codes) visant à être partagés. Les codes peuvent être du R, mais pas uniquement : il est possible d’évaluer des instructions d’autres langages tels python ou SQL, entre autres. Les formats de sortie possible sont nombreux. Parmi les plus utilisés : html, pdf, Word, notebook, ioslides.
Le package {rmarkdown} peut être installé à l’aide de l’instruction suivante.
install.packages("rmarkdown")
Le document de référence principal sur lequel s’appuie cette fiche est l’ouvrage R Markdown Cookbook, rédigé par Yihui Xie, Christophe Dervieux et Emily Riederer (Chapman & Hall/CRC, 2020). Une version électronique est disponible gratuitement à l’adresse suivante : https://bookdown.org/yihui/rmarkdown-cookbook/.
Une antisèche de deux pages sur le R Markdown a été réalisée par RStudio : https://www.rstudio.com/wp-content/uploads/2015/02/rmarkdown-cheatsheet.pdf.
Pour conserver la prise de bonnes habitudes initiée lors des premières séances, créez dans un premier temps un projet RStudio, en respectant l’arborescence présentée sur l’image ci-dessous.
Structure basique pour les projets. Source: https://martinctc.github.io/.
Création d’un projet
Dans RStudio :
File
, puis sur New Project...
.New Directory
, puis sur New Project
.Browse...
Open
.Create Project
pour créer le projet. Une nouvelle session RStudio s’ouvre alors. Le répertoire courant devient celui dans lequel vous avez créé le projet. Un fichier d’extention .Rproj
a été créé dans ce répertoire. Il suffira d’ouvrir ce fichier à l’avenir pour ouvrir RStudio pour travailler sur ce projet.Sur les ordinateurs de l’Université, vous veillerez à créer le projet dans le dossier C:/Workout
. La compilation sur les VDI (virtual desktop infrastructure) semble être impossible pour le moment.
Attention : à la fin de la séance, il faudra penser à copier/coller l’ensemble du répertoire contenant votre projet dans votre dossier Documents
. Les contenus du dossier C:/Workout
sont effacés à la fermeture de session.
À présent que le projet est créé, il est temps de créer un document R Markdown.
Création d’un document R Markdown
Dans RStudio :
Cliquez sur le menu File
, puis sur New File...
.
Cliquez sur R Markdown...
.
Dans la fenêtre qui s’affiche :
HTML
pour que le rapport qui sera créé après soit un document html (langage conçu pour présenter des pages web).OK
.Sauvegardez le fichier créé en lui donnant le nom de votre choix (par exemple : `premier_rapport.Rmd``).
Fenêtre de création d’un nouveau document R Markdown.
Un document R Markdown, dont l’extension est .Rmd
est alors créé. Ce document est composé de trois parties :
Dans le document que vous venez de créer, l’en-tête YAML indique :
title: "Mon premier document R Markdown"
author: "Ewen Gallic"
date: "2/7/2022"
output: html_document
Le titre du document, l’auteur et la date sont précisés dans cette en-tête. Lors de la conversion du fichier Rmd en fichier html par Pandoc (un logiciel de conversion de documents), ces informations seront stockées dans des variables et apparaîtront à un ou plusieurs endroits du fichier html (selon le modèle – template – utilisé). La ligne output: html_document
indique quant à elle que le document de sortie sera un document html. D’autres éléments peuvent être indiqués, notamment dans la partie output
: présence d’une table des matières, numérotation des sections, ajout d’une feuille de style, etc.
En quelques mots, les étapes de conversion sont les suivantes :
knit()
du package {knitr
} exécute les codes contenus dans les chunks et prépare un fichier Markdow (.md
).md
dans un format de sortie (html, pdf, etc.)Si le format de sortie est le pdf, une étape supplémentaire est ajoutée : le fichier .md
est converti en un fichier LaTeX (.tex
). Une compilation du fichier .tex
est alors effectuée par LaTeX pour obtenir le fichier pdf final. Cela nécessite de fait d’installer LaTeX ou TinyTeX sur son système.
Dans le cadre de ce cours, nous ne produirons pas de documents au format html sur les ordinateurs de l’Université.
Pour ajouter une table des matières dans un fichier html, on ajoute des paires de clés-valeurs :
toc: yes
: on désire la création d’une table des matières (table of contents) ;toc_depth: 3
: l’entier donné en valeur définit la profondeur de la table des matières (1 : uniquement les sections, 2 : sections et sous-sections, 3 : sections, sous-sections et sous-sous sections, etc.)toc_float: true
: la table des matières sera insérée comme objet flotant et visible en permanence tout le long du document.---
title: "Mon premier document R Markdown"
author: "Ewen Gallic"
date: "2/7/2022"
output: html_document:
toc: yes
toc_depth: 3
toc_float: true
---
Attention, il faut respecter les indentations, comme dans l’exemple précédent.
Pour une table des matières sur un document final en pdf, le YAML doit contenir les paires toc: yes
et toc_depth:3
.
---
title: "Mon premier document R Markdown"
author: "Ewen Gallic"
date: "2/7/2022"
output: pdf_document:
toc: yes
toc_depth: 3
---
Le fichier .Rmd
peut contenir du texte que l’on rédige en markdown. Davantage d’informations seront données dans la suite de cette fiche concernant la syntaxe markdown (qui est très simple).
Les morceaux de code contiennent deux parties :
Pour être exécuté, le code fait appel à un environnement (dans lequel des variables peuvent être créées). Cet environnement peut être modifié après l’exécution du code.
Pour compiler un document R Markdown, une fois le YAML bien spécifié, il suffit au choix :
d’appeler la fonction render()
du package {rmarkdown
} :
Rmd
via l’argument input
: rmarkdown::render(input = "votre_document_rmarkdown.Rmd")
de cliquer sur le bouton Knit
(on le repère facilement avec son icone d’aiguille à tricoter et sa pelote de laine) ;
d’appuyer simultanément sur les touches du clavier Ctrl / Cmd + Shift + K
.
Les deux dernières solutions conduisent à un affichage du résultat dans une fenêtre qui s’ouvre à l’issue de la compilation.
Compilez votre premier fichier R Markdown avec l’une des trois manières indiquées, puis regardez le résultat.
Les parties textuelles qui permettent d’ajouter une narration aux rapports peuvent être rédigées en markdown. La sytaxe est très simple.
Il suffit d’écrire comme dans un bloc note pour que le texte soit affiché dans le rapport final.
Terminer une ligne par deux espaces permet d’aller à la ligne.
Laisser une ligne vide entre deux textes permet de créer un nouveau paragraphe.
Style | Syntaxe | Exemple | Rendu |
---|---|---|---|
Gras | ** ** ou __ __ |
Du texte **en gras** |
Du texte en gras |
Italique | * * ou _ _ |
Un mot en *italique* |
Un mot en italique |
Barré | ~~ ~~ |
J'~~aime~~ adore R |
J’ |
Une partie en italique dans du gras | **- -** |
Un **texte _très_ important** |
Un texte très important |
Tout en gras et italique | *** *** |
***新年快樂*** (Xin nian kuai le) |
新年快樂 (Xin nian kuai le) |
Exposant | ^ ^ |
Le 1^er^ janvier |
Le 1er janvier |
Il existe six niveaux de titres dans les documents R Markdown. On fait précéder le texte du titre par autant de croisillons (#
) que de niveau désiré.
# Titre de niveau 1
## Titre de niveau 2
### Titre de niveau 3
#### Titre de niveau 4
##### Titre de niveau 5
###### Titre de niveau 6
Notes :
Pour effectuer une citation dans un bloc, il convient de faire précéder la citation du symbole >, que l’on place en début de ligne. Exemple avec> chúc mừng năm mới
:
chúc mừng năm mới
Pour faire en sorte qu’une citation comporte plusieurs paragraphes, un chevron (>
) doit être ajouté au début de lignes vides.
> “How can two people hate so much without knowing each other?”
>
> --- Alan Moore, _The Killing Joke_
“How can two people hate so much without knowing each other?”
— Alan Moore, The Killing Joke
Pour insérer un tiret long (cadratin), on utilise trois tirets : ---
; pour un tiret court (ou demi-cadratin), on utilise deux tirets : --
.
Symbole voulu | Syntaxe | Exemple | Rendu | |
---|---|---|---|---|
Tiret long (cadratin) | --- |
--- une réplique |
— une réplique | |
Tiret moyen (demi-cadratin) | -- |
La frontière France--Italie |
La frontière France–Italie |
En inscrivant trois tirets ---
et en passant immédiatement à la ligne, une ligne horizontale est insérée.
Pour écrire des points de suspension, il suffit d’écrire trois points (...
) à la suite…
La création d’un lien hypertexte se fait en utilisant deux éléments : un texte sur lequel on clique, qui doit être entouré par des crochets []
et une adresse vers laquelle le lien point, qui doit être entourée par des parenthèses (()
).
[vidéo épatante](https://www.youtube.com/watch?v=dQw4w9WgXcQ). Regardez cette
Regardez cette vidéo épatante.
Pour créer un lien sans définir de texte spécifique en remplacement de l’URL, il est possible de simplement écrire l’URL. Il est toutefois préférable d’encadrer l’URL par des chevrons. Il en va de même pour une adresse email.
<https://www.youtube.com/watch?v=oavMtUWDBTM>
<ewen.gallic@univ-amu.fr>
https://www.youtube.com/watch?v=oavMtUWDBTM
ewen.gallic@univ-amu.fr
Pour créer une ancre (un lien vers un endroit précis de la page déjà affichée) vers un titre du document, il faut connaître la référence vers le point d’ancrage. Un moyen simple consiste à la définir soi-même, en utilisant la syntaxe suivante :
# Le titre {#nom-de-la-reference}
Le nom de la reference ne doit pas contenir d’espaces ni de traits de soulignement (_
). Il peut en revanche, comme dans l’exemple, contenir des tirets (-
).
Dans ce document, la sous section dans laquelle ce texte est inscrit, est définie comme suit :
## Liens hypertextes {#liens-hypertextes}
[section](#liens-hypertextes). On peut ainsi facilement faire un lien vers cette
On peut ainsi facilement faire un lien vers cette section.
L’insertion de notes de bas de page numérotées s’effectue à l’aide de crochets ([]
) contenant un accent circonflèxe et une référence qui peut être soit un nombre, soit un texte (mais sans espace ou autre caractère blanc).
Le numéro de la note de bas de page est un lien qui renvoie vers la note. Une flèche de retour est proposée pour ramener au texte lorsque le document créé est un document html.
[^1] suivie d'une note plus longue[^longue-note].
Une note de bas de page simple
[^1]: la note de bas de page.
[^longue-note]: une note de bas de page plus longue.
Dans laquelle on peut écrire un paragraphe.
`{ du code }`
Plusieurs paragraphes, même.
Une note de bas de page simple1 suivie d’une note plus longue2.
On distingue deux types de listes : les listes ordonnées et les listes non ordonnées.
Pour créer une liste ordonnée, on place en début de ligne, devant chaque élément de la lique, un nombre immédiatement suivi d’un point et d’une espace.
1. Un premier élément ;
2. Un deuxième élément ;
3. Un troisième élément.
Il n’est pas nécessaire de respecter la numérotation :
1. Un premier élément ;
10. Un deuxième élément ;
5. Un troisième élément.
Le numéro du premier élément de la liste ordonnée définit la valeur du compteur :
4. Un premier élément ;
10. Un deuxième élément ;
5. Un troisième élément.
Pour insérer une liste non ordonnée, on fait précéder chaque élément du symbole -
ou du symbole *
.
Une liste comprenant :
* un premier élément ;
* un deuxième élément ;
* un troisième élément.
Une liste comprenant :
Pour ajouter une liste à l’intérieur d’une liste, il faut ajouter avant le tiret ou l’étoile soit un taquet de tabulation, soit 4 espaces.
- un premier élément ;
- un deuxième élément :
- qui contient un sous-élement,
- ainsi qu'un deuxième sous-élément,
- et un troisième ;
- puis un troisième élément.
Pour écrire un paragraphe à l’intérieur d’une liste, une identation (taquet de tabulation ou 4 espaces) doit être ajoutéé, pour préserver la continuité de la liste. Il faut également faire précéder le paragraphe d’une liste vide (on peut aussi ajouter une ligne vide après le paragraphe, mais celle-ci est optionnelle).
- un premier élément ;
- un deuxième élément :
qui contient un paragraphe.
- puis un troisième élément.
un premier élément ;
un deuxième élément :
qui contient un paragraphe.
puis un troisième élément.
Il est tout à fait possible d’imbriquer une liste ordonnée dans une liste non ordonnée et vice-versa.
1. Un premier élément :
- avec un sous-élément ;
2. Un deuxième élément.
Règles de typographie :
En français, les listes sont généralement introduites par une phrase se terminant par deux tirets (:
). Les éléments de la liste ne commencent alors pas par une majuscule. Les éléments sont séparés par un point virgule (;
), et le dernier élément se termine par un point.
Une liste comprenant :
Lorsque la liste est numérotée, il faut en revanche mettre une majuscule à chaque élément de la liste
Une liste comprenant :
Lorsqu’une liste se compose de plusieurs phrases, chaque élément commence par une majuscule et se termine par un point.
Les personnes pouvant postuler :
Pour les personnes ayant validé une Licence 2 mention “Économie-Gestion” à Aix-Marseille Université ou dans une autre Université française : entrée de droit dans le parcours.
Pour les personnes ayant validé un niveau équivalent à la Licence 2 en Économie ou en Économie-Gestion (Licence 2 mention Économie, DUT, CPGE, etc.) : une commission pédagogique évalue les dossiers notamment sur la base des pré-requis mentionnés plus haut ainsi que sur la base des projets de Master des étudiantes et étudiants.
les règles de typographie françaises indiquent qu’il est d’usage de placer un point virgule à la fin des éléments de niveau 1 ou au dernier élément de niveau supérieur à 1 si celui-ci est immédiatement suivi par un élément de niveau 1 ;
pour les éléments de niveau 2, une
En cas de listes imbriquées, la virgule est utilisée en fin de ligne, sauf pour le dernier élément de la liste imbriquée qui lui, s’achève par un point virgule ou un point s’il s’agit du dernier élément de la liste.
Une liste qui comprend :
un élément de niveau 1
un autre élément de niveau 1 :
un troisième élément de niveau 1.
L’ajout d’une image se fait en insérant un point d’exclamation (!
), suivi d’une d’un titre entre crochets, puis du chemin vers l’image, entre parenthèses (()
). Une description de l’image peut être ajoutée entre guillemets (""
) après le chemin, toujours dans les parenthèses (cette description est visible au survol de l’image, lorsque le pointeur de la souris reste quelques secondes au-dessus de l’image, et peut être lue à voix haute par les systèmes destinés aux personnes en situation de handicap). Enfin, pour spécifier des paramètres de taille de l’image, il est possible d’ajouter des informations entre crochets ({}
).
{width="200px"}