Créer un notebook avec Quarto: principes, fonctionnalités

SAGEO, 2023 - Québec, Canada

Nicolas Lambert, Timothée Giraud, Matthieu Viry, Ronan Ysebaert

07 Jun 2023

Evolution des pratiques en SHS (FR)


Avant 2011 : des “black-boxes” méthodologiques

Logiciels payants, ruptures logicielles dans les chaines de traitements, stockage et partage des données et méthodes non optimisé, univers “clic-bouton”.

Evolution des pratiques en SHS (FR)


2011 - récemment : vers des chaines de traitement intégrées

Solutions open source, gratuites, qui couvrent l’ensemble de la chaîne de traitement de l’information, univers de programmation.

Une pratique qui tend aujourd’hui à se diffuser au sein de la communauté (formation, enseignement, recherche).

Evolution des pratiques en SHS (FR)


Depuis peu… : vers l’ouverture à de nouveaux langages ?

Usage de langages de développement variés en fonction des usages désirés (performance de certaines libs, interactivité, …) et des échanges interdisciplinaires (dataviz).

Comment passer d’un langage à l’autre dans des mêmes chaînes de traitement ?

Evolution des pratiques en SHS (FR)

La réplication en question

  • Où sont stockées les données ?
  • Sur quoi reposent ces protocoles méthodologiques ?
  • Comment les documenter ?
  • Comment les restituer / mettre à jour / adapter ?
Qui pour reprendre ces programmes ?


Qui pour comprendre ce code et ses intentions ?

Recherche reproductible

Ouverture des protocoles de recherche dans l’objectif de confirmer et rendre répétable des résultats de recherche :

  • Mise à disposition des données et du code, exécutable.
  • Documentation de l’environnement logiciel nécessaire à son exécution.
  • Transparence dans la collecte de données, ses traitements, analyses et sorties graphiques.
  • Réutilisable par d’autres : documentation du code, de ce qu’il produit et dans quel but.
  • Ouvert aux retours, commentaires, suggestions, critiques, révisions.

Jon Claerbout (sismologue, Univ. Stanford). Il utilise avec son groupe pour la première fois le terme de “recherche reproductible” lors du congrès de la Society of Exploration Geophysics en 1992.

Programmation lettrée & notebooks

Paradigme de programmation qui consiste à associer code source (pour les ordinateurs) et documentation (pour les humains) :

  • Donner les informations suffisantes pour répliquer l’expérimentation, à la manière d’un essai.
  • Vérifier que les conclusions sont valides.
  • Améliorer les programmes / rendre les mauvaises décisions de conception plus évidentes.
  • Utile pour reprendre les programmes ultérieurement.
  • Transmettre et partager les connaissances sous des formes appropriées (tutoriels, manuels).

Un gain général en reproductibilité de la démarche et en ouverture des méthodes scientifiques.

Donald Knuth (mathématicien, Univ. Stanford). Pose les bases de la programmation lettrée dans un premier environnement de literate programming : le WEB qui combine du Pascal et du TeX, appliqué aux nombres premiers (1984).

Notebooks : Principes fondamentaux

Le Notebook est une solution opérationnelle et adaptée pour arriver à ces fins

Source : Pecout, 2022

Les Notebooks du moment

Source : Pecout, 2022

Quarto : un des derniers nés des notebooks (2022)


  • Open source, basé sur Pandoc.
  • Moins dépendant de R : pas d’installation obligatoire de packages R, comme c’était le cas avec R Markdown.
  • Peut fonctionner ailleurs que dans l’IDE RStudio : pas d’utilisation exclusive de Knitr (Jupyter, Observable également).
  • Permet d’exécuter différents langages de programmation : R, Python, Julia ou JavaScript (interactivité ++).
  • Possibilité de mises en page customisées avancées (templates ++)
  • Fonctionnalités d’auto-complétion très utiles.

Des sorties multiples




Restituer des analyses reproductibles menées lors d’un projet.

Exemple : Sortie (site Web) // Dépôt GitLab




Générer des présentations interactives (iframe, animations, slides interactifs) avec le format revealjs.

Exemple : Sortie (Présentation) // Dépôt GitHub // Code








Créer des raports interactifs combinant (éventuellement) plusieurs langages de programmation.

Exemple : Sortie (Rapport interactif) // Dépôt GitHub // Code (Quarto)




Produire des manuels ou des sections pédagogiques collaboratifs au format Book.

Sortie (Book) // Dépôt GitHub






Soumettre des publications suivant les prérequis (modèle LaTeX) de plusieurs revues de référence (Public Library of Science, Elsevier, JSS, etc.)

Journal Articles (Quarto doc)

Squelette d’un notebook (Quarto)





Source : Pecout, 2022

Initier un document Quarto dans RStudio

RStudio propose plusieurs modèles pour initier aisément un notebook.




Initier un document Quarto dans RStudio

Le document est généré en cliquant sur render.

Paramétrer son document grâce au YAML



Le YAML permet de définir :

  • Le format de sortie désiré : HTML
---
title: "My document"
author: "Me"
format: html
---

Paramétrer son document grâce au YAML



Le YAML permet de définir :

  • Le format de document désiré : HTML, PDF (distribution TeX requise)


---
title: "My pdf document"
author: "Me"
format: pdf
---

Paramétrer son document grâce au YAML



Le YAML permet de définir :

  • Le format de document désiré : HTML, PDF (distribution TeX requise), docx (requiert Microsoft Office ou Libre/Open Office).



---
title: "My docx document"
author: "Me"
format: docx
---

Paramétrer son document grâce au YAML



Le YAML permet de définir :

  • Le format de document désiré : HTML, PDF (distribution TeX requise), docx (requiert Microsoft Office ou Libre/Open Office).

  • Le type de sortie souhaité : Document, Présentation (revealjs / beamer, PowerPoint)





---
title: "My presentation"
author: "Me"
format: revealjs / beamer / pptx
---

Paramétrer son document grâce au YAML

On peut jouer sur ces paramètres pour créer des documents uniques.
  • choix d’un thème
  • table des matières
  • numérotation des parties du document
  • gestion des couleurs
  • style de la typo : police, couleurs, taille.
  • affichage des blocs de code
  • dimensionnement des figures et tables
  • gestion des urls
  • ajout d’une bibliographie (BibTeX)
  • affichage des notes de bas de page
  • métadonnées associées au document
  • associer une feuille de style css
  • …

Exemple d’un modèle suivant les consignes éditorales d’un projet européen…

Paramétrer son document grâce au YAML

On peut jouer sur ces paramètres pour créer des documents uniques.
  • choix d’un thème
  • table des matières
  • numérotation des parties du document
  • gestion des couleurs
  • style de la typo : police, couleurs, taille.
  • affichage des blocs de code
  • dimensionnement des figures et tables
  • gestion des urls
  • ajout d’une bibliographie (BibTeX)
  • affichage des notes de bas de page
  • métadonnées associées au document
  • associer une feuille de style css
  • …

Consulter la documentation Quarto

… Et son YAML associé :

---
title: "OpenStreetMap data and associated routing engine to produce novel data on rural areas in Europe"
subtitle: "Review data and methods" 
author:
  - name: "Ronan Ysebaert, Marianne Guérois\n, Timothée Giraud, Nicolas Lambert, Matthieu Viry" 
    affiliation: UAR RIATE (CNRS,  Université Paris Cité) 
    affiliation-url: https://riate.cnrs.fr/
date: "2023-06-01"
description: "This review of the literature and data availability aims at providing an overview of possible solutions and limitations for creating accessibility indicators at European context. Whatever the solution retained, computing accessibility indicators requires relevant origins / destination pairs and routing engines for computing travel-time indicators. It is afterward possible to propose a large set of indicators derived from these measures. The first part of the document presents at European scale the policy context and the main initiatives developed so far for proposing harmonized indicators on accessibility. The second one reminds the main issues to be considered when calculating accessibility indicators (origin-destination pairs, routing engines, accessibility indicators computation). The third section makes an overview of existing databases and possibilities that could be considered in a European context for the selection of origins / destinations pairs. The fourth part highlights existing solutions for routing engines according to several transportation modes (road, cycle, transport-transit). Finally, the last section discusses on possibilities offered in term of indicator creation when the travel time matrix is calculated with a case-study on hospitals in France. This case-study could be extended in a cross-border context to test this framework within GRANULAR activities. At the end, this report aims at providing a general research framework on the activities that will be held on task 3.3.1 of the GRANULAR project: Crowd-sources data based on OpenStreetMap."
title-block-banner: "#27445C"
bibliography: bib.bib
format:
  html:
    theme: sandstone
    embed-resources: true
    smooth-scroll: true
    fontsize: 0.9em
    code-tools: true
    code-fold: true
    toc: true
    toc-title: Summary
    toc-depth: 2
    toc-location: left
    css: "styles.css"
    linkcolor: "#d52420"
---

Décrire simplement son cheminement en markdown

Permet de gérer les blocs de textes entre les blocs de code dans les notebooks Quarto.


  • Un langage de balisage léger basé sur une syntaxe simple largement utilisé dans les blogs, forums et outils collaboratifs.

  • Permet de gérer le formatage du texte, des en-têtes, importer simplement des images ou des URL, gérer des énumérations, des tables, etc.

Se reporter au Markdown Guide ou à la synthèse proposée par Quarto pour en savoir plus.

Markdown Syntax Output 
 ### Titre de niveau 3

Titre de niveau 3

 
*italics* and **bold**
 italics and bold 
superscript^2^ / subscript~2~
 superscript2 / subscript2 
~~strikethrough~~
 strikethrough 
`verbatim code`
 verbatim code 
* unordered list
    + sub-item 1
    + sub-item 2
        - sub-sub-item 1

  • unordered list

    • sub-item 1

    • sub-item 2

      • sub-sub-item 1
 
 [named hyperlinks](url)
 named hyperlinks

Optimiser sa mise en page avec des classes préformatées

Ceci :

::: columns

::: {.column width="40%"}

::: {.callout-tip}
## 5 types de callouts disponibles
`note`, `warning`, `important`, `tip`, and `caution`.
:::

::: {.callout-note appearance="simple"}
## Pay Attention

Using callouts is an effective way to highlight content that your reader give special consideration or attention.
:::

::: 

::: {.column width="60%"}
![](fig/callout.png)
:::

:::

Optimiser sa mise en page avec des classes préformatées

Rend cela :

5 types de callouts disponibles

note, warning, important, tip, and caution.

Pay Attention

Using callouts is an effective way to highlight content that your reader give special consideration or attention.

Paramétrer ses blocs de code grâce aux chunks

Le code est à placer dans des chunks (tronçons), délimités par des triples backticks (Code > Insert Chunk dans RStudio).

Un même document Quarto peut combiner plusieurs langages de programmation :

Voici un chunk en Julia pour créer un joli cercle.


```{julia}
radius = 10
using Markdown
Markdown.parse("""
The radius of the circle is $radius.
""")
```

Puis un graphique créé avec la librairie python matplotlib.


```{python}
import matplotlib.pyplot as plt
plt.plot([1,2,3,4])
plt.show()
```

Paramétrer ses blocs de code grâce aux chunks

Le code est à placer dans des chunks (tronçons), délimités par des triples backticks (Code > Insert Chunk dans RStudio).

Un même document Quarto peut combiner plusieurs langages de programmation :

Un graphique avec la librarie ggplot de R peut être ?

```{r}
library(ggplot2)
ggplot(airquality, aes(Temp, Ozone)) + 
  geom_point() + 
  geom_smooth(method = "loess", se = FALSE)
```

Paramétrer ses blocs de code grâce aux chunks

Le code est à placer dans des chunks (tronçons), délimités par des triples backticks (Code > Insert Chunk dans RStudio).

Un même document Quarto peut combiner plusieurs langages de programmation :

Soyons fous ! Initions un joli graphique interactif en Observable JavaScript !

```{ojs}
pdata = FileAttachment("palmer-penguins.csv").csv({typed: true})

Plot.plot({
  facet: {
    data: pdata,
    x: "sex",
    y: "species",
    marginRight: 80
  },
  marks: [
    Plot.frame(),
    Plot.rectY(pdata, 
      Plot.binX(
        {y: "count"}, 
        {x: "body_mass_g", thresholds: 20, fill: "species"}
      )
    ),
    Plot.tickX(pdata, 
      Plot.groupZ(
        {x: "median"}, 
        {x: "body_mass_g",
         z: d => d.sex + d.species,
         stroke: "#333",
         strokeWidth: 2
        }
      )
    )
  ]
})
```

Paramétrer ses blocs de code grâce aux chunks

En initiant le chunk par un hash pipe #| on peut paramétrer son exécution / affichage. Les arguments les plus usuels sont :

  • label: toto : nommer le chunk
  • eval: true/false : le bloc de code est joué ou non.
  • echo: true/false : le bloc de code s’affiche ou non dans le document de sortie.
  • cache: true/false : les résultats sont mis en cache et ne sont pas rejoués tant que le bloc de code reste inchangé.
  • warning: true/false : affiche les messages d’alerte ou non.
  • fig-height: 4 / fig-width: 6 : hauteur / largeur du plot de sortie, en pouces.
  • dpi: 150 : densité de pixels par pouce.

Paramétrer ses blocs de code grâce aux chunks / Exemples

Ceci dans le .qmd :


```{r}
plot(1:10)
```

Rendra cela dans le fichier de sortie :

plot(1:10)

Paramétrer ses blocs de code grâce aux chunks / Exemples

Ceci dans le .qmd :


```{r}
#| eval: false
#| echo: false
plot(1:10)
```

Ne rendra rien dans le fichier de sortie…

Et c’est bien normal :)

Paramétrer ses blocs de code grâce aux chunks / Exemples

Ceci dans le .qmd :


```{r}
#| echo: false
plot(1:10)
```

Rendra cela dans le fichier de sortie :

Paramétrer ses blocs de code grâce aux chunks / Exemples

Ceci dans le .qmd :


```{r}
#| fig-height: 4
#| fig-width: 3
#| fig-cap: Fig.1 - Un graphique très basique ! 
#| code-fold: true
plot(1:10)
```

Rendra cela dans le fichier de sortie :

Code 
plot(1:10)

Fig.1 - Un graphique très basique !

Paramétrer ses blocs de code grâce aux chunks

A noter…

  • Générez (render) le document fréquemment pour veiller à la cohérence / bonne exécution de vos blocs de code.
  • Pour vous comme pour les autres, évitez les blocs de code trop volumineux ou longs.
  • Les paramètres des chunks peuvent aussi être spécifiés dans le YAML (setup chunk).
  • L’usage de Knitr rend disponible encore davantage d’options.
  • Ces paramètres peuvent légèrement changer si l’on compile le document avec Jupyter ou Observable JS.

Paramétrer ses blocs de code grâce aux chunks

A noter…

  • Générez (render) le document fréquemment pour veiller à la cohérence / bonne exécution de vos blocs de code.
  • Pour vous comme pour les autres, évitez les blocs de code trop volumineux ou longs.
  • Les paramètres des chunks peuvent aussi être spécifiés dans le YAML (setup chunk).
  • L’usage de Knitr rend disponible encore davantage d’options.
  • Ces paramètres peuvent légèrement changer si l’on compile le document avec Jupyter ou Observable JS.
  • Possibilité d’intégrer aisément des librairies JavaScript de visualisation intéractive grâce aux Jupyter Widgets ou htmlwidgets pour R.
```{r}
#| out-width: "300px"
#| out-height: "300px"
library(leaflet)
leaflet() %>%
  addProviderTiles(providers$Stamen.TonerHybrid) %>%  
  addMarkers(lng = -71.2818, lat = 46.7809, 
             popup="Sageo 2023")
```

Association puissante Notebooks + Git

Un système gestion de version (Torvald, 2005) distribué pour :

  • Tracer des changements dans les fichiers textes.
  • Gérer l’historique et les versions du code source.
  • Partager le code dans des dépôts distants.

Des services Web d’hébergement et de gestion de développement de logiciels basés sur Git (2008, 2011). Ils proposent :

  • Une interface de gestion de projets : inviter des collaborateurs, gérer des accès, assigner des tâches, visualiser l’historique des modifications, etc.
  • CI/CD (Intégration et déploiement continus) : compilation, tests immédiats des modifications.
  • Fonctionnalités de réseaux sociaux: suivre des personnes / projets, contribuer.

= Projets collaboratifs + outils pour déployer des ressources sur le Web + visibilité extérieure.

Ressources pour aller plus loin

Supports utiles

Enjeux de la reproductibilité

A vous de jouer !

[To do] : Initier un document Quarto

  • Créez un document Quarto à partir des modèles proposés par RStudio.
  • Jouez avec les métadonnées (YAML) pour paramétrer le document (nom de l’auteur, ajout table des matières, etc.)
  • Exportez au format html le document que vous venez de produire (render).

Ctrl + espace pour activer l’autocomplétion et envisager les possibilités