Notebook Quarto & R

Création d’un Quarto

A. Créer un projet

Un fichier source de notebook peut être associé à plusieurs fichiers annexes (images, données, bibliographie, feuille de style…). Pour assurer la portabilité de l’ensemble des données sources du notebook, il est impératif de tout enregistrer dans le même répertoire (ou projet Rstudio).

Lancez l’IDE Rstudio
Cliquez sur File/New Project
Puis cliquez sur New Directory et New Project.

Choisissez un nom de projet (répertoire) et son emplacement sur votre machine.

Le fait de placer tous les éléments associés au notebook dans ce répertoire vous permettra de déplacer le dossier ou vous le souhaitez, même sur une autre machine, tout en gardant le notebook (potentiellement) rééxecutable.

B. Créer un ficher.qmd

Une fois dans votre projet :

Cliquez sur File/New File/Quarto Document
Choisissez un nom pour le document et gardez le format de sortie proposé par défaut (HTML).

Knitr ou Jupyter ?

Selon le langage utilisé dans le notebook. vous pouvez chosir le moteur de compilation adéquat : Knitr pour le langage R ou Jypyter pour les langages Julia, Python, R et Javascript. Pour cet exercice, nous utiliserons le moteur de compilation knitr.

Décochez l’option suivante :
Créez le document
Enregistrez le fichier qmd à la racine du repértoire (File/Save) sous le nom “index.qmd”.

index.qmd

Vous avez le choix de donner n’importe quel nom au fichier source de votre notebbok. Le même nom sera utilisé pour le fichier en sortie (notebook compilé). Par exemple : toto.qmd → toto.html

Parce que nous souhaitons déployé le fichier de sortie (.html) sur une page web, il est fortement recommandé de nommer ce fichier “index”. (Pourquoi ?)

C. Render un Quarto

Lorsqu’un document Quarto est compilé (render), les blocs de code sont automatiquement exécutés.
Les notebooks Quarto peuvent être compilés de différentes manières :

Solution 1 : Depuis l’interface Rstudio, cliquez sur
Solution 2 : Depuis le terminal en utilisant les commandes suivantes :

quarto render index.qmd # all formats
quarto render index.qmd --to pdf
quarto render index.qmd --to docx

Compilation des .ipynb avec Quarto

Quarto permet également de compiler les Jupyter notebooks (.ipynb) depuis le terminal :

quarto render index.ipynb

Solution 3 : il est possible de compiler un quarto depuis la console en utilisant le package R quarto :

library(quarto)
quarto_render("index.qmd") # all formats
quarto_render("index.qmd", output_format = "pdf")

Le fichier HTML généré s’enregistre à la racine de votre projet et s’affiche automatiquement dans l’onglet Viewer de Rstudio.

Rédaction d’un Quarto

A. En-tête d’un Quarto

L’en-tête (YAML) d’un notebook contient l’ensemble des métadonnées et variables générales du document. Dans un fichier notebook Quarto, l’en-tête est balisé par trois tirets :

---
title: "mon_quarto"
format: html
editor: visual
---

1. Complétez le YAML an ajoutant les variables suivantes :

Titre, sous-titre et résumé → documentation
Auteur(s) → documentation
Date → documentation
Langue → documentation

Exemple :

---
title: "Entre école tématique et AG de laboratoire"
subtitle: "Tranche de vie d'un professeur en Géographie"
authors: 
  - name: Raphaëlle Krummeich
    orcid: 0000-0002-6170-8243
    affiliations:
       - name: UMR IDEES, Université de Rouen Normandie
date: today
lang: fr
editor: source
---

Pour avoir une vue globale des métadonnées disponibles dans l’en-tête d’un document Quarto, vous pouvez consulter le site officiel de Quarto :

https://quarto.org

2. Gérez l’apparence de la table des matières (TOC) → documentation

Exemple :

---
title: "Entre école tématique et AG de laboratoire"
subtitle: "Tranche de vie d'un professeur en Géographie"

format: 
  html:
    code-fold: false
    number-sections: true
    number-offset: 2
    number-depth: 3
    toc: true
    highlight-style: github
    
---

YAML - Indentation et séparation

Il est impératif de respecter l’indentation attendue avec le langage YAML. Sinon.. ❌

B. Fichiers annexes liés

Différents types de fichier peuvent être liés à un notebook Quarto, comme une feuille de style ou un fichier contenant des références bibliographiques. Pour cela, il est nécessaire de renseigner des métadonnées dans le YAML de l’en-tête.

Par exemple, pour lié un fichier de références bibliographiques au notebook :

Téléchargez le fichier exemple biblio.bib qui contient des références en format BibTeX. Extrait :

@book{giraud_2024_10560265,
  author       = {Giraud, Timothée and
                  Pecout, Hugues},
  title        = {Géomatique avec R},
  publisher    = {Zenodo},
  year         = 2024,
  month        = jan,
  doi          = {10.5281/zenodo.10560265},
  url          = {https://doi.org/10.5281/zenodo.10560265},
}

Ajoutez ce fichier à la racine de votre projet.
Dans l’en-tête, indiquez le nom du fichier dans la variable bibliography :

---
bibliography: biblio.bib
---

Pour appeler une référence bibliographique renseignée dans le fichier BibTeX, utilser le symbol @ et l’ID de la référence bibliographique ciblée :

---
bibliography: biblio.bib
---

Le package `sf` permet la **gestion des données géographiques**
en langage R (@giraud_2024_10560265)

Ainsi, la référence bibliographique appelée sera correctement affichée dans le corps du document.
Exemple : “Giraud et Pecout (2024)” et automatiquement affichée en fin de document de la manière suivante.

C. Du fichier.r au .qmd

Téléchargez le script de code R mis à disposition : script.r, puis intégrez l’ensemble du code et des commentaires contenu dans le script dans votre fichier .qmd.

a. Texte balisé en markdown

Transposez les commentaires du script (+ explications, interprétations, déroulé de l’exploration..) en utilisant le langage de balisage markdown pour la mise en forme → documentation.

b. Code morcelé en plusieurs `chunk`

Transposez les lignes de code du script dans plusieurs blocs de code (appelés chunk).

Du script unique à plusieurs chunk

Morcelez les lignes de code par bloc comme indiqué en commentaire dans les scripts.

L’objectif est de construire un document intelligible qui permet de comprendre et d’apprécier toute la chaine de traitement présentée sans avoir à éxécuter le code. Transposez ainsi le script dans votre document Quarto en respectant le paradigme de la programmation lettrée !

Exemple :

---
title: "Entre école tématique et AG de laboratoire"
subtitle: "Tranche de vie d'un professeur en Géographie"
---

## Introduction

## Packages & données

### Liste des packages

Les packages utilisés pour réaliser cette analyse exploratoire sont les suivants :

- `sf` : pour manipuler des données géographiques vectorielles
- `tidygeocoder` : pour géocoder des adresses
- `mapview` : visualiser des données géo. sur un fond de carte interactif
- `osrm` : pour faire du routage (calcul d'itinéraire)
- `DT` : pour afficher des tableau interactif

Pour installer les packages :

```{r bloc_1}
#| eval: false
#| code-fold: false
install.packages("sf")
install.packages("tidygeocoder")
install.packages("mapview")
install.packages("osrm")
install.packages("DT")
```

Chargement des librairies :

```{r bloc_2}
#| code-fold: false
#| message: false
library(sf)
library(tidygeocoder)
library(mapview)
library(osrm)
library(DT)
```

### Les adresses des événements

Seule deux adresses vont être utilisées comme données pour réaliser cette exploration :

-   **Le lieux de l'école thématique** : 

> *140, route des Allards, 17310 Saint-Pierre-d'Oléron*

-   **Le lieux de l'Assemblée générale** : 

>*1, allée Momplaisir, 17370 Saint Trojan Les Bains*

c. Gérer les options des `chunks`

Plusieurs options peuvent être appliquées aux blocs de code du document. Cela permet par exemple de contrôler leur comportement au moment de leur éxecution, quelques exemples :

Option	Description
`eval`	Éxécution du bloc du code. Si `eval : false`, le code ne sera pas éxécuté, mais seulement affichés.
`echo`	`true` ou `false` : affichage ou non du bloc de code dans le document
`output`	`true`, `false` ou `asis` : affichage ou non des résultats générés par le bloc
`warning`	`true` ou `false` : inclusion des `warnings` dans le document
`error`	`true` ou `false` : inclusion des `errors` dans le document
`include`	`false` : permet d’exclure toute sortie dans le document (code + résultats)
`code-fold`	`true` : inclure le code dans une balise

Les options des chunks

De nombreuses options sont disponibles pour paramétrer le comportement des chunks et des résultats générés → voir la documentation

Pour ajouter des options à un chunk, utilisez la syntaxe #| en début de ligne :

```{r bloc_1}
#| eval: false
#| echo: true
#| message: false
#| warning: false
#| code-fold: true
#| code-summary: "Visualiser le code"

library(sf)
library(tidygeocoder)
library(mapview)
library(osrm)
library(DT)
```

Dans le cas ci-dessus, le code ne sera pas éxécuté et le bloc sera affiché de la manière suivante dans le document généré :

Visualiser le code

library(sf)
library(tidygeocoder)
library(mapview)
library(osrm)
library(DT)

Références bibliographiques

Giraud, Timothée, et Hugues Pecout. 2024. Géomatique avec R. Zenodo. https://doi.org/10.5281/zenodo.10560265.

Besoin d’aide ?

⚠️ Un exemple de notebook terminé est mis à disposition sur ce dépôt GitLab ⚠️

Création d’un Quarto

A. Créer un projet

B. Créer un ficher.qmd

C. Render un Quarto

Rédaction d’un Quarto

A. En-tête d’un Quarto

B. Fichiers annexes liés

C. Du fichier.r au .qmd

a. Texte balisé en markdown

b. Code morcelé en plusieurs chunk

c. Gérer les options des chunks

Références bibliographiques

b. Code morcelé en plusieurs `chunk`

c. Gérer les options des `chunks`