Rapports : Markdown et Quarto

L3 économie-finance

Auteur·rice
Affiliation

Elias Bouacida

Université Paris 8

Date de publication

15 octobre 2024

Paquets

Installer des extensions (paquets)

  • En plus de l’installation de base : extensions, appelées paquet (package en anglais) ou librairie
  • En majorité : développées et maintenues par la communauté des utilisateurs et utilisatrices de R
  • Diffusées via un réseau de serveurs nommé CRAN (Comprehensive R Archive Network).
  • Pour installer une extension, si on dispose d’une connexion Internet, on peut :
    • Cliquer sur le bouton Install Packages de l’onglet Tools de RStudio. Il suffit alors d’indiquer le nom de l’extension dans le champ Package et de cliquer sur Install.
    • Utiliser la fonction install.packages() directement dans la console. Par exemple, pour installer le paquet ggplot2 on peut exécuter la commande
install.packages(ggplot2)

Charger des extensions

Une fois installée, il faut la “charger” avant de pouvoir utiliser les fonctions qu’elle propose. Ceci se fait avec la fonction library(). Pour pouvoir utiliser les fonctions de ggplot2, vous devrez exécuter la commande suivante :

library(ggplot2)

Vous avez déjà rencontré ces commandes quand nous avons installé et utilisé le paquet swirl.

En pratique

On regroupe en général en début de script toute une série de commandes library() qui permettent de charger tous les paquets utilisés dans le script. Quelque chose comme :

library(ggplot2)
library(haven)
library(tidyr)

Créer des documents avec du code : R Markdown

Introduction

  • Un atout important de R et Rstudio est R Markdown.
  • Format qui combine code et explications
  • Aide disponible ici Changer
  • Nécessite l’utilisation de Rstudio pour fonctionner correctement

Cette partie est largement inspirée de (Wickham et Grolemund 2016, chap. 27)

Structure d’un document

Un document Quarto Markdown est un fichier texte avec une extension .qmd qui ressemble à ceci :

cat(readr::read_file("Diamants.qmd"))

Ce document est compilé afin de créer un document final, en général au format web .html ou au format .pdf ou encore au format .docx

Principaux éléments

  1. L’en tête YAML, comprise entre les ---
  2. Des morceaux de code R, qui commencent par ```
  3. Du texte normal en (R) Markdown (avec des balises de formatages)

Actions possibles

  1. Lancer le code seul en cliquant sur la petite icône run en haut à droite de la fenêtre.
  2. Compiler tout le document en cliquant sur knit en haut.
  3. Utiliser le raccourci Cmd/Ctrl + Shift + K pour compiler tout le document.

Le document produit est par défaut en .html est apparaîtra à droite dans Rstudio.

Montrer ici aux étudiants les 3 possibilités à l’aide d’un document .qmd

L’en-tête

YAML

---
title: "Diamond sizes"
date: 2016-08-25
format: html
---

Contient les options du documents, spécifie titre (title), auteur (author), date (date), format de sortie (output), etc.

Code R dans l’en-tête : doit être dans des morceaux de code, avec des guillemets en plus " ", par exemple " Tue Oct 15 14:49:01 2024 "

Corps du texte

Formatage du texte

Le langage utilisé pour le texte écrit dans les .qmd est le Markdown. C’est un ensemble de règles de formatage pour des fichier texte qui est simple à lire et à écrire. En voici les principales possibilités :

Text formatting 
------------------------------------------------------------

*italique*  ou _italique_
**gras**   __gras__
`code`
exposant^2^ et indice~2~

Titres
------------------------------------------------------------

# Titre de 1er niveau

## De 2eme niveau

### 3eme niveau

Listes
------------------------------------------------------------

*   Liste avec des points item 1

*   Item 2

    * Item 2a

    * Item 2b

1.  Liste énuméré item 1

1.  Item 2. Les nombres sont automatiquement incrementé à la compilation

Liens et images
------------------------------------------------------------

<http://example.com>

[Phrase avec un lien](http://example.com)

![Légende d'une image (optionnelle)](chemin/de/image.png)

Tableaux 
------------------------------------------------------------

Titre 1  | Titre 2
-------- | ----------
Contenu  | Contenu
Contenu  | Contenu

Une version complète est résumé est disponible ici. Changer

Morceaux de code

3 façons d’insérer un morceau de code dans un document .qmd :

  1. Avec le raccourci clavier Cmd/Ctrl + Alt + I
  2. Dans l’onglet “Code”, “Insert Chunk”
  3. En tapant manuellement les délimiteurs ```{r} et ```

Titre d’un morceau de code :

```{r suivi d’un nom (optionnel)}.

Le bloc de code est fini par ```.

Conseil : donnez un nom à chaque morceau de code (ce nom doit être unique).

Options du morceau de code

Que supprime chaque option ?
Option Lancer le code Montrer le code Sortie Graphique Messages Warnings
eval: false – – – – –
include: false – – – – –
echo: false –
results: "hide" –
fig.show: "hide" –
message: false –
warning: false –

Revoir ces options

Tableaux

  • Par défaut, les dataframes ont le style de la console.
  • Pour les formater, on peut utiliser knitr::kable et des en-têtes débutants par #|
#| label: tbl-demo
#| tbl-cap: "Un tableau produit à l'aide de `knitr::kable`."
knitr::kable(
  mtcars[1:5, ]
)
Table 1: Un tableau produit à l’aide de knitr::kable.
mpg cyl disp hp drat wt qsec vs am gear carb
Mazda RX4 21.0 6 160 110 3.90 2.620 16.46 0 1 4 4
Mazda RX4 Wag 21.0 6 160 110 3.90 2.875 17.02 0 1 4 4
Datsun 710 22.8 4 108 93 3.85 2.320 18.61 1 1 4 1
Hornet 4 Drive 21.4 6 258 110 3.08 3.215 19.44 1 0 3 1
Hornet Sportabout 18.7 8 360 175 3.15 3.440 17.02 0 0 3 2
  • La fonction knitr::kable a de multiples options que vous pouvez consulter à l’aide ?knitr::kable

Options globales

  • Parfois utile de changer les options par défaut des morceaux de code : cela peut se faire dans l’en-tête yaml.

Par exemple,

execute:
  echo: false

Cachera le code dans le rapport.

  • On le fait en général au début du document, on peut les modifier indépendammant pour chaque morceau de code.

Code en ligne

  • Possible de mettre du code en ligne dans votre texte, à l’aide de `r `
  • Permet de présenter les caractéristiques de vos données dans le corps du texte (nombre de ligne d’un tableau, par ex)

Nous avons les données de nrow(diamonds) diamants. Seulement nrow(diamonds) - nrow(smaller) font plus que 2,5 carats. La répartition du reste est montrée ci-dessous :

Le résultat est compilé et apparaît ainsi dans le document final :

Nous avons les données de 53940 diamants. Seulement 126 font plus que 2,5 carats. La répartition du reste est montrée ci-dessous :

  • format() permet de contrôler l’apparence des nombres :
    • L’option digits contrôle le nombre de décimales
    • L’option big.mark contrôler les indicateurs de grand nombres

Bibliographie et citations

Bibliographie

Génération automatique des bibliographies à partir de fichier de bibliographie à indiquer dans l’option bibliography de l’en-tête :

bibliography: rmarkdown.bib

Types de fichiers reconnus : BibLaTex, BibTex, endnote, medline

Citations

Pour citer, il faut utiliser @ suivi de la clé d’identification de la citation dans le fichier bibliographique.

On peut ensuite mettre la citation entre crochets.

Séparation de citations multiples par `;`: Blah blah [@smith04; @doe99].

Vous pouvez ajoutez n'importe quel commentaire dans les crochets :
Blah blah [see @doe99, pp. 33-35; also @smith04, ch. 1].

Pour obtenir une citation en ligne, enlever les crochets : @smith04 
dit blah, ou @smith04 [p. 33] dit blah.

Ajoutez un `-` avant la citation afin d'enlever le nom de l'auteur : 
Smith dit blah [-@smith04].

R Markdown mettra automatiquement la bibliographie à la fin de votre document.

Montrer ici un fichier de bibliographie avec la clé de citation.

Références

Wickham, Hadley, et Garrett Grolemund. 2016. R for data science: import, tidy, transform, visualize, and model data. " O’Reilly Media, Inc.". https://r4ds.had.co.nz/index.html.