Du code
au rapport Quarto

Calculer, expliquer et reproduire

Aurélien Nicosia · 14 octobre 2026
STT-4230 / STT-6230

Ce qu’on construit aujourd’hui

Un rapport court dont le texte, le tableau et la figure concordent.

  • Une question et une source de données explicites.
  • Des résultats calculés par R au moment du rendu.
  • Une interprétation qui précise les limites.
  • Un fichier HTML lisible et une source .qmd reproductible.

La semaine dernière : construire une figure. Aujourd’hui : l’intégrer à une explication vérifiable.

Un code qu’on peut relire

Difficile à suivre

x<-read_csv("donnees/seismes-fidji.csv")
y<-x|>filter(mag>=5);nrow(y)

Les étapes sont visibles

seismes <- read_csv(
  "donnees/seismes-fidji.csv"
)

seismes_magnitude_5 <- seismes |>
  filter(mag >= 5)

nrow(seismes_magnitude_5)

Nommer les objets, séparer les étapes et commenter les décisions de traitement.

Organiser les fichiers et les chemins

portfolio/
  data/
    processed/
      seismes.csv
  reports/
    rapport.qmd
  README.md

Depuis reports/rapport.qmd :

read_csv("../data/processed/seismes.csv")

.. remonte d’un dossier.

Dans le paquet de démonstration, le rapport et donnees/ sont au même niveau.

Par défaut, les blocs R utilisent le dossier du .qmd.

Trois parties dans un fichier .qmd

YAML

Titre, langue,
format et options.

→

Markdown

Question, méthode,
lecture des résultats.

+

Blocs R

Données, calculs,
tableaux et figures.

Quarto assemble ces éléments pour produire le document final.

Le YAML configure le document

---
title: "Mon rapport"
author: "Votre nom"
lang: fr
format:
  html:
    toc: true
    code-fold: true
embed-resources: true
execute:
  echo: true
  warning: true
  message: false
---

format: html choisit la sortie.

toc ajoute un sommaire.

code-fold permet de replier le code.

L’indentation en espaces indique quelles options vont ensemble.

Le Markdown structure l’explication

Dans la source

## Question

Comment se répartissent les magnitudes?

- Une ligne représente un séisme.
- La profondeur est mesurée en km.

La variable `mag` contient la magnitude.

À la lecture

Une section, une question, des précisions sur les données.

La variable mag contient la magnitude.

Le texte aide le lecteur à comprendre les résultats sans parcourir tout le code.

Les accolades rendent le bloc exécutable

Afficher du code

```r
nrow(seismes)
```

Ce bloc montre le code sans l’exécuter.

Exécuter du code

```{r}
nrow(seismes)
```

Ce bloc calcule le nombre de lignes au rendu.

Dans les blocs R exécutables, les lignes #| placées au début règlent les options Quarto.

Pendant le rendu, qui fait quoi?

Quarto pilote le rendu. Pour les blocs R, il utilise knitr.

Source .qmd

Texte et
blocs de code.

→

knitr + R

Exécuter les blocs
et récupérer les résultats.

→

HTML final

Texte, tableaux
et figures assemblés.

ggplot2 produit les figures; knitr fait exécuter les blocs R pendant le rendu.

Render reconstruit le rapport

  1. Enregistrer le .qmd et vérifier les fichiers requis.
  2. Utiliser le bouton Render dans l’éditeur, ou le terminal :
quarto render rapport-semaine-07.qmd
  1. Ouvrir le HTML produit et lire les résultats.

Avec le cache désactivé, les blocs R sont réexécutés dans leur ordre. Le rapport doit charger ses bibliothèques, lire ses données et créer ses objets.

Tous les objets utilisés doivent être créés dans le document.

Afficher et exécuter : deux décisions

Option du bloc Le code s’exécute? Le lecteur voit quoi?
echo: false Oui Les résultats, sans le code
eval: false Non Le code, si echo: true
include: false Oui Ni le code, ni ses sorties

Pour cacher le code et garder une figure : quelle option choisir?

echo: false. Avec include: false, la figure serait aussi cachée.

Une règle globale, une exception locale

Dans le YAML

execute:
  echo: false
  warning: true

Le code est masqué par défaut.

Dans un bloc précis

```{r}
#| label: verification
#| echo: true

nrow(seismes)
```

Ici, le lecteur voit le code et le résultat.

Choisir les options selon le public du rapport. Les contrôles de préparation peuvent rester dans un bloc include: false.

Reprendre un exemple connu

datasets::quakes contient 1000 événements près de Fidji.

Variable Signification
lat, long Coordonnées de l’événement
depth Profondeur, en kilomètres
mag Magnitude
stations Nombre de stations ayant rapporté l’événement

Question descriptive : comment se répartissent les magnitudes dans ce tableau?

Lire les données et vérifier la variable

library(readr)
library(dplyr)
library(ggplot2)
library(knitr)

seismes <- read_csv(
  "donnees/seismes-fidji.csv",
  show_col_types = FALSE
)

stopifnot(!anyNA(seismes$mag))

Le contrôle arrête le rendu si une magnitude est manquante. Il faut alors décider du traitement avant de poursuivre.

Calculer le résumé une seule fois

seismes <- seismes |>
  mutate(classe_magnitude = cut(
    mag, breaks = c(4, 5, 6, 7), right = FALSE
  ))

repartition <- seismes |>
  count(classe_magnitude, .drop = FALSE) |>
  mutate(proportion = n / sum(n))

stopifnot(sum(repartition$n) == nrow(seismes))

right = FALSE inclut la borne de gauche et exclut celle de droite.

Le même objet repartition alimente le tableau, le graphique et l’interprétation.

Produire un tableau dans le rapport

```{r}
#| label: tbl-repartition
#| tbl-cap: "Effectifs par classe de magnitude."

kable(repartition, digits = 3)
```
Classe de magnitude Effectif Proportion
[4,5) 802 0.802
[5,6) 193 0.193
[6,7) 5 0.005

Une figure avec une légende et un texte alternatif

```{r}
#| label: fig-repartition
#| fig-cap: "Effectifs par classe de magnitude."
#| fig-alt: "Barres des trois classes; [4,5) est la plus fréquente."
#| fig-width: 8
#| fig-height: 4.5

ggplot(repartition, aes(classe_magnitude, n)) +
  geom_col(fill = "#087d85") +
  labs(x = "Classe de magnitude", y = "Nombre de séismes") +
  theme_minimal()
```

La légende accompagne la figure. Le texte alternatif en décrit le contenu pour une lecture assistée.

Lire la figure, puis préciser sa portée

Trois barres avec 802, 193 et 5 événements pour les classes [4,5), [5,6) et [6,7).

Ces effectifs décrivent seulement le tableau fourni.

Référencer sans taper les numéros

Le préfixe indique le type de résultat :

Identifiant du bloc Renvoi dans le texte
label: fig-repartition @fig-repartition
label: tbl-repartition @tbl-repartition

Dans la source

La @fig-repartition représente les effectifs du @tbl-repartition.

Quarto ajoute les numéros et les liens. Utiliser des identifiants uniques et une légende fig-cap ou tbl-cap.

Des nombres qui suivent les données

Dans le texte du .qmd

Le tableau contient `r nrow(seismes)` séismes.

Dans le HTML

Le tableau contient 1000 séismes.

L’expression R entre accents graves est recalculée au rendu. Le texte reste cohérent si le nombre de lignes change.

Lire le HTML et refaire l’analyse

Pour lire le résultat Pour refaire les calculs
Le HTML avec embed-resources: true Le .qmd et les données sources
Un navigateur, sans R pour ce HTML statique R, Quarto et les bibliothèques
Images et styles intégrés Les chemins et l’ordre des traitements

embed-resources n’installe pas R et n’embarque pas automatiquement les fichiers de données.

Partager le HTML permet de lire le résultat. Refaire l’analyse demande le dossier reproductible et un environnement adapté.

Quand le rendu échoue

Symptôme Première vérification
Erreur YAML Espaces, indentation, deux-points et guillemets
Fichier introuvable Chemin depuis le .qmd, nom exact et extension
Objet introuvable Bloc qui crée l’objet, ordre et eval
Fonction introuvable Bibliothèque chargée dans le document
Renvoi non résolu Identifiant, préfixe et légende

Lire le premier message d’erreur et le bloc concerné. Corriger la cause, puis refaire le rendu.

Revenir sur votre premier rendu

  1. Nommer un résultat obtenu ou le premier message d’erreur.
  2. Repérer le bloc, le fichier ou l’option concernés.
  3. Expliquer ce qui reste à vérifier ou à reprendre au laboratoire.

Un rendu réussi ne suffit pas : vérifier aussi qu’un résultat du HTML concorde avec les données et le calcul.

Démonstration : suivre un rapport complet

Ouvrir la source du rapport, puis son HTML.

  1. Repérer le YAML et le bloc de préparation.
  2. Suivre l’objet repartition jusqu’au tableau et à la figure.
  3. Retrouver les renvois et les nombres calculés dans le texte.
  4. Refaire le rendu et vérifier le code repliable.

Changer le titre pour tester le rendu, puis une option d’affichage pour comprendre son effet.

À vous : construire un rapport court

À partir du rapport de démonstration et de l’atelier :

  1. Choisir une question descriptive sur la profondeur.
  2. Créer un résumé et une figure qui répondent à cette question.
  3. Ajouter un nombre calculé dans le texte et un renvoi à la figure.
  4. Expliquer un résultat et une limite, puis rendre le document.

On doit pouvoir relier chaque nombre écrit à un calcul du rapport.

Avant de considérer le rapport terminé

  • Je peux rendre le .qmd sans objet créé auparavant dans la console.
  • Je connais la source, l’unité d’observation et les unités des variables.
  • Mon texte, mon tableau et ma figure donnent des résultats cohérents.
  • Mes figures ont des axes lisibles, une légende et un texte alternatif.
  • Mes renvois fonctionnent et mes conclusions respectent les données.
  • J’ai ouvert le HTML final et documenté comment reproduire le rapport.

Le rendu réussi est un contrôle technique. La lecture du résultat est un contrôle supplémentaire.

Garder une trace dans le portfolio

Toujours conserver et versionner la source .qmd.

Choix pour le HTML Pourquoi et comment
Le suivre dans Git Le dépôt sert à remettre ou lire directement le résultat
L’exclure de Git Le résultat est régénéré; fournir la procédure et les dépendances

Documenter cette décision dans le README.md et suivre les consignes de remise.

Si l’IA influence significativement le travail, documenter son usage et les vérifications dans docs/ai-log.md, selon les règles du cours.

Faire avancer le projet d’équipe

Transformer la proposition en premières réalisations :

  • une source de données accessible et documentée;
  • un premier traitement qu’une autre personne peut relancer;
  • une question reliée à un tableau ou à une figure;
  • une prochaine tâche claire pour chaque membre.

Si le produit retenu est un rapport, le .qmd devient une première version du livrable. Adapter ce travail au format approuvé de l’équipe.

Défi 2 : simulation de tarifs douaniers

Mercredi 21 octobre · 13 h 30 à 14 h 30
Travail individuel · 10 % du cours

  • Travailler sur une commande fictive et des tables documentées.
  • Choisir les bonnes périodes et relier les tables avec les bonnes clés.
  • Produire un pipeline R, une figure et un court rapport Quarto.
  • Utiliser l’IA si vous le souhaitez, en déclarant son aide.

Les vrais lots et scénarios, l’énoncé et le canevas Quarto sont donnés à 13 h 30. Le travail évalué commence à ce moment.

Avant la séance : prendre en main le dépôt

  • Cloner le dépôt privé attribué par l’équipe enseignante.
  • Lire les trois CSV et leur dictionnaire : colonnes, codes, unités et périodes.
  • Vérifier l’environnement, puis tester un commit et un push.
  • Se familiariser avec les données; le code et le rapport évalués seront rédigés pendant le défi.

Le dépôt anticipé contient les tableaux tarifaires, des fichiers d’essai et un guide des données. Les fichiers de l’épreuve sont fournis à 13 h 30.

IA : une trace précise de l’aide reçue

Créer docs/ai-log.md, même sans utilisation d’IA.

Rubrique Ce qu’il faut préciser
Usage ou non-usage Outils, dates et ressources
1 à 3 contributions significatives, si IA Passage influencé, décision et vérification
Décision personnelle Un choix relié au travail et une attestation

Déclarer aussi une aide reçue avant la séance si elle influence la remise.

À 14 h 30 : remettre la version finale

  1. Terminer les calculs, le rendu HTML et les vérifications.
  2. Enregistrer le commit final et le pousser sur GitHub.
  3. Remettre l’adresse du dépôt et le SHA du commit dans le canal annoncé.
  4. Arrêter les modifications; les entretiens suivent la remise figée.

Le rendu et la transmission font partie des 60 minutes.

Entretien individuel après la remise

Cinq minutes, avec votre code et votre rapport visibles, sans IA ni aide extérieure.

  1. Expliquer comment un lot reçoit le taux du bon scénario.
  2. Prévoir l’effet d’une petite modification des données.
  3. Faire ou décrire l’adaptation et une vérification.

0,6 point sur les 10 du défi : compréhension, prédiction et vérification.

Se préparer avant le défi

  • Lire les fichiers, leurs colonnes, unités et périodes.
  • Réviser les clés et le choix de la bonne version d’une table.
  • Prévoir l’effet d’une jointure sur le nombre de lignes.
  • Distinguer une valeur nulle d’une valeur inconnue dans une figure.
  • Tester Git et un rendu Quarto sur l’entraînement distinct.

Lire les directives, puis faire l’entraînement.

Joindre la bonne version d’une table

prix_v2 <- prix_demo |>
  filter(version == "v2")

resultat <- lots_demo |>
  left_join(prix_v2, by = "code")

stopifnot(nrow(resultat) == nrow(lots_demo))

Choisir la version, puis vérifier l’effectif et les clés.

Deux lots peuvent porter le même code et rester distincts.

Lot Code Quantité Prix
A 001 10 6
B 001 20 6
C 002 5 8

Données de stock entièrement fictives.

Fichiers et liens utiles