1 Objectifs et contextes

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.

2 Créer un document R Markdown avec RStudio

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.

Arborescence de fichiers contenant un fichier de projet, des dossiers Data, Script et Output.

Structure basique pour les projets. Source: https://martinctc.github.io/.

Création d’un projet

Dans RStudio :

Cliquez sur le menu File, puis sur New Project....
Cliquez sur New Directory, puis sur New Project.
Donnez un nom au nouveau projet, puis cliquez sur le bouton Browse...
Choisissez l’emplacement du projet, puis appuyez sur le bouton Open.
Cliquez sur le bouton 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 :
- assurez-vous d’être dans l’onglet “Document”
- donnez un titre au document que vous allez créer
- renseignez le champ “Author” avec vos noms et prénom(s)
- laissez le bouton radio sur l’option HTML pour que le rapport qui sera créé après soit un document html (langage conçu pour présenter des pages web).
- créer le document en cliquant sur le bouton 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 :

du YAML (des méta-données) ;
du texte ;
des morceaux de code (code chunks).

2.1 YAML

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 :

la fonction knit() du package {knitr} exécute les codes contenus dans les chunks et prépare un fichier Markdow (.md)
le logiciel Pandoc convertit le fichier .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é.

2.1.1 Table des matières

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

2.2 Textes

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).

2.3 Morceaux de code

Les morceaux de code contiennent deux parties :

du code à évaluer, dans un langage donné (nous utiliserons du R) ;
une liste d’options pour le morceau de code.

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.

2.4 Compilation

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} :
- en lui fournissant le chemin vers le fichier Rmd via l’argument input: rmarkdown::render(input = "votre_document_rmarkdown.Rmd")
- il faut ensuite aller dans l’explorateur de fichier / dans Finder pour ouvrir le fichier converti
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.

3 Ecriture du texte : syntaxe en Markdown

Les parties textuelles qui permettent d’ajouter une narration aux rapports peuvent être rédigées en markdown. La sytaxe est très simple.

3.1 Texte

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.

3.2 Styles de texte

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’~~aime~~ adore R
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 1^er janvier

3.3 Titres

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 :

il faut bien faire suivre le croisillon d’une espace ;
il est nécessaire d’insérer une ligne vide avant et après le titre.

3.4 Citations

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

3.5 Tirets longs, tirets moyens

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

3.6 Lignes horizontale

En inscrivant trois tirets --- et en passant immédiatement à la ligne, une ligne horizontale est insérée.

3.7 Points de suspension

Pour écrire des points de suspension, il suffit d’écrire trois points (...) à la suite…

3.8 Liens hypertextes

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 (()).

Regardez cette [vidéo épatante](https://www.youtube.com/watch?v=dQw4w9WgXcQ).

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}

On peut ainsi facilement faire un lien vers cette [section](#liens-hypertextes).

On peut ainsi facilement faire un lien vers cette section.

3.9 Notes de bas de page

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.

Une note de bas de page simple[^1] suivie d'une note plus longue[^longue-note].

[^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 simple¹ suivie d’une note plus longue².

3.10 Listes

On distingue deux types de listes : les listes ordonnées et les listes non ordonnées.

3.10.1 Listes 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.

Un premier élément ;
Un deuxième élément ;
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.

Un premier élément ;
Un deuxième élément ;
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.

Un premier élément ;
Un deuxième élément ;
Un troisième élément.

3.10.2 Listes non ordonnées

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 :

un premier élément ;
un deuxième élément ;
un troisième élément.

3.11 Listes imbriquées

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.

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.

Un premier élément :
- avec un sous-élément ;
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 :

un premier élément ;
un deuxième élément ;
un troisième élément.

Lorsque la liste est numérotée, il faut en revanche mettre une majuscule à chaque élément de la liste

Une liste comprenant :

Un premier élément ;
Un deuxième élément ;
Un troisième élément.

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 :
- avec un sous-élément de niveau 2,
- ainsi qu’un autre ;
un troisième élément de niveau 1.

3.12 Images

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 ({}).

![Un tigre](figs/tigre.JPG "Tigre en papier"){width="200px"}

Comment utiliser RMarkdown

Ewen Gallic

2021-2022

1 Objectifs et contextes

2 Créer un document R Markdown avec RStudio

2.1 YAML

2.1.1 Table des matières

2.2 Textes

2.3 Morceaux de code

2.4 Compilation

3 Ecriture du texte : syntaxe en Markdown

3.1 Texte

3.2 Styles de texte

3.3 Titres

3.4 Citations

3.5 Tirets longs, tirets moyens

3.6 Lignes horizontale

3.7 Points de suspension

3.8 Liens hypertextes

3.9 Notes de bas de page

3.10 Listes

3.10.1 Listes ordonnées

3.10.2 Listes non ordonnées

3.11 Listes imbriquées

3.12 Images