cassionAnalyse de données

Retour à la leçonLeçon 8 sur 8Quelqu'un d'autre l'exécute

L'étude de cas est ce que vous êtes en train de lire

Le même diaporama que les téléchargements, rendu sous forme de page. Lancez le diaporama pour le présenter en plein écran — les flèches ou un clic avancent d'une diapositive, Échap quitte.

Diapositives · PDFDiapositives · PowerPoint

  1. Diapositive 1 / 19

    Ce que couvre cette leçon

    • Pourquoi la plateforme est l'exemple
    • Des données brutes produites, non collectées
    • Une sortie commitée, pour une raison qui nomme sa condition
    • Des vérifications à trois endroits, et la contrainte qui a décidé où
    • La vérification qu'un graphe de références ne peut pas exprimer
    • Ce que le dépôt refuse de contenir
    • La reproductibilité au niveau du langage
    • Ce que ce dépôt ne fait pas
    • Rapportez-le en entier
    • La suite
    Notes du présentateur
    Vingt jeux de données issus de dix-sept scripts à graine fixe qui se régénèrent à l'octet près, vingt fichiers de tests et 4 212 assertions, sept vérifications qui font échouer la compilation, et un schéma qui refuse les données non synthétiques. Chaque affirmation de ce cours se vérifie dans ce dépôt.

  2. Diapositive 2 / 19

    Pourquoi la plateforme est l'exemple

    • Tous les autres cours d'ici emploient un jeu de données.
    Notes du présentateur
    Tous les autres cours d'ici emploient un jeu de données. Celui-ci emploie le dépôt, pour une raison qui vaut d'être énoncée : une chaîne reproductible est une affirmation sur un artefact, et la seule démonstration convaincante est un artefact que vous pouvez vérifier. Tout ce qui suit se vérifie depuis un clone.

  3. Diapositive 3 / 19

    Des données brutes produites, non collectées — Shell

    pnpm datasets:generate
git status --short apps/data-analysis/public/datasets/files
# (nothing)

  4. Diapositive 4 / 19

    Des données brutes produites, non collectées

    • Vingt fichiers CSV, dix-sept scripts générateurs, et les régénérer tous ne change rien — Chaque générateur a une graine…
    • C'est une propriété plus forte que « la chaîne se réexécute » — Cela signifie que réexécuter est une étape de…
    • Et les défauts sont délibérés — Chaque entrée de la liste knownIssues d'un jeu de données correspond à un bloc de son…
    Notes du présentateur
    Vingt fichiers CSV, dix-sept scripts générateurs, et les régénérer tous ne change rien. Chaque générateur a une graine fixe — SEED = 20240622, dans le fichier — si bien que la sortie est une fonction du seul code. C'est une propriété plus forte que « la chaîne se réexécute ». Cela signifie que réexécuter est une étape de vérification : si git status n'est pas vide après une régénération, ou bien le générateur a changé, ou bien le fichier commité a été édité à la main, et vous voulez savoir l'un comme l'autre. Et les défauts sont délibérés. Chaque entrée de la liste knownIssues d'un jeu de données correspond à un bloc de son générateur — les quatre orthographes de Nord-Ouest, les onze erreurs d'unité, les deux élèves en double. Changez l'un et vous changez l'autre, ce qui est la même discipline que celle des figures produites depuis les données.

  5. Diapositive 5 / 19

    Une sortie commitée, pour une raison qui nomme sa condition

    • Parce que le déploiement tourne sur Cloudflare Pages sans TeX, sans Python et sans pandoc — La compilation copie des…
    • C'est la règle générale de la leçon 1, appliquée — Commitez un artefact produit quand le reconstruire n'est pas à la…
    • Et cela fonctionne parce que la sortie est déterministe — SOURCE_DATE_EPOCH fixe l'horodatage de pdfTeX et celui de…
    Notes du présentateur
    Le dépôt commite des choses qu'il pourrait reconstruire : CSV de données, PDF de cours, diaporamas, figures, carnets. Parce que le déploiement tourne sur Cloudflare Pages sans TeX, sans Python et sans pandoc. La compilation copie des fichiers statiques, si bien que LaTeX n'est jamais sur le chemin critique du déploiement et qu'un contributeur sans la chaîne d'outils peut quand même livrer un changement de contenu. C'est la règle générale de la leçon 1, appliquée. Commitez un artefact produit quand le reconstruire n'est pas à la portée de tous ceux qui en ont besoin. Non parce que reconstruire est lent — parce que reconstruire est indisponible. Et cela fonctionne parce que la sortie est déterministe. SOURCE_DATE_EPOCH fixe l'horodatage de pdfTeX et celui de pandoc, si bien qu'un .pptx — une archive dont les dates d'entrée bougeraient sinon — se reconstruit à l'octet près. Sans cela, commiter la sortie produite donnerait un diff à chaque compilation et personne n'en relirait aucun.

  6. Diapositive 6 / 19

    Des vérifications à trois endroits, et la contrainte qui a décidé où

    OùQuoiPourquoi là
    Schéma ZodTypes de champs, énumérations, champs requisS'exécute sur une entrée, sans système de fichiers
    astro buildSept vérifications de niveau grapheA besoin de toute la collection
    pnpm testVérifications de système de fichiersLa compilation n'a pas node:fs

  7. Diapositive 7 / 19

    Des vérifications à trois endroits, et la contrainte qui a décidé où

    • La compilation Astro pré-rend dans un worker Cloudflare sans node:fs — si bien qu'une vérification qui doit regarder…
    • Placez la vérification là où elle peut s'exécuter — C'est une contrainte d'ingénierie réelle, et elle a produit un…
    Notes du présentateur
    La compilation Astro pré-rend dans un worker Cloudflare sans node:fs, si bien qu'une vérification qui doit regarder un fichier sur le disque ne peut pas y vivre. dataset-files.test.ts vérifie que les lignes et octets déclarés correspondent aux fichiers ; course-pdfs.test.ts vérifie que chaque cours publié livre ses deux éditions PDF. Placez la vérification là où elle peut s'exécuter. C'est une contrainte d'ingénierie réelle, et elle a produit un meilleur agencement que l'élégance ne l'aurait fait : les vérifications rapides sont dans le schéma, celles de graphe dans la compilation, et celles de système de fichiers dans une suite de tests qui passe en premier en intégration continue.

  8. Diapositive 8 / 19

    La vérification qu'un graphe de références ne peut pas exprimer — Exemple

    REFERENCE_RULES verifies that a declared slug resolves.
It cannot verify that an entry is pointed at.

  9. Diapositive 9 / 19

    La vérification qu'un graphe de références ne peut pas exprimer

    • Un cours pourrait donc être livré sans laboratoire ni exercice, et chaque barrière resterait verte — C'est pour cela…
    • Toute règle du type « chaque X a au moins un Y » exige un test de cette forme — et reconnaître lesquelles de vos…
    Notes du présentateur
    Un cours pourrait donc être livré sans laboratoire ni exercice, et chaque barrière resterait verte. C'est pour cela qu'existe course-practice.test.ts — il compte à rebours depuis chaque cours publié vers la pratique qui doit le nommer. Toute règle du type « chaque X a au moins un Y » exige un test de cette forme, et reconnaître lesquelles de vos contraintes sont de ce genre constitue l'essentiel de la conception d'une suite de vérifications.

  10. Diapositive 10 / 19

    Ce que le dépôt refuse de contenir — Exemple

    .refine((d) => d.dataQuality.synthetic === true, {
  message: "Only synthetic or fully de-identified datasets may be published.",
})

  11. Diapositive 11 / 19

    Ce que le dépôt refuse de contenir

    • Un jeu de données non déclaré synthétique fait échouer la compilation — Ce public modélise des données de…
    • Cela va de pair avec produire les données plutôt que les collecter — La garantie est structurelle aux deux bouts : le…
    Notes du présentateur
    Un jeu de données non déclaré synthétique fait échouer la compilation. Ce public modélise des données de bénéficiaires, de protection, de VBG et cliniques, et « aucun enregistrement ne remonte à une personne réelle » devient une propriété du dépôt plutôt qu'une promesse dans une note. Cela va de pair avec produire les données plutôt que les collecter. La garantie est structurelle aux deux bouts : le générateur ne peut pas produire une personne réelle, et le schéma n'acceptera pas une affirmation contraire.

  12. Diapositive 12 / 19

    La reproductibilité au niveau du langage — Exemple

    { "packageManager": "pnpm@11.9.0", "engines": { "node": ">=22" } }

  13. Diapositive 13 / 19

    La reproductibilité au niveau du langage

    • Le gestionnaire de paquets est figé, non seulement les paquets — Un pnpm différent résout le fichier de verrouillage…
    • TypeScript est maintenu en 6.x avec la raison écrite — TypeScript 7 n'expose pas encore l'API programmatique dont…
    Notes du présentateur
    Le gestionnaire de paquets est figé, non seulement les paquets. Un pnpm différent résout le fichier de verrouillage différemment, et c'est la couche en dessous de celle que la plupart des projets figent. TypeScript est maintenu en 6.x avec la raison écrite : TypeScript 7 n'expose pas encore l'API programmatique dont dépend astro check, si bien que pnpm typecheck échoue purement et simplement en 7. Le verrou nomme la condition de sa levée, ce qui sépare une contrainte réfléchie d'une contrainte héritée.

  14. Diapositive 14 / 19

    Ce que ce dépôt ne fait pas

    • Pas de conteneur — Un fichier de verrouillage plus un gestionnaire de paquets figé reproduit le côté JavaScript ; les…
    • Pas de test de déterminisme de bout en bout en intégration continue — La régénération des jeux de données est…
    • La documentation de passation est mince — CLAUDE.md et docs/DEFINITION_OF_DONE.md portent les décisions, ce qui est…
    • Nommer les lacunes est l'essentiel — Une étude de cas qui revendique tout est une étude de cas dont personne ne peut…
    Notes du présentateur
    Être honnête sur les lacunes fait partie de l'étude de cas. Pas de conteneur. Un fichier de verrouillage plus un gestionnaire de paquets figé reproduit le côté JavaScript ; les côtés Python et TeX dépendent de ce que le contributeur possède. pnpm figures:build n'a besoin que d'un Python d'origine, et pnpm course:pdf avertit au lieu d'échouer quand TeX est absent — un arbitrage délibéré pour qu'un contributeur sans chaîne d'outils puisse quand même livrer du contenu. Pas de test de déterminisme de bout en bout en intégration continue. La régénération des jeux de données est déterministe et vérifiée à la main ; il n'existe pas de tâche d'intégration continue qui régénère tout et échoue sur un diff. Ce serait la prochaine chose à ajouter. La documentation de passation est mince. CLAUDE.md et docs/DEFINITION_OF_DONE.md portent les décisions, ce qui est plus que la plupart des dépôts et moins que ce qu'exige la leçon 7. Nommer les lacunes est l'essentiel. Une étude de cas qui revendique tout est une étude de cas dont personne ne peut apprendre, et les trois ci-dessus sont l'état honnête d'un dépôt par ailleurs inhabituellement strict avec lui-même.

  15. Diapositive 15 / 19

    Rapportez-le en entier — Exemple (suite)

    Reproducibility of this platform

  Data          20 CSV files generated by 17 seeded scripts. Regenerating all
                of them produces byte-identical output; `pnpm datasets:generate`
                followed by `git status` is the verification.

  Checks        7 fail the build (schema, references, locale, translation
                parity, topic-sector, synthetic-only, programme spine).
                20 test files and 4,212 assertions run first in CI.

  Output        Course PDFs, slide decks, figures and notebooks are committed
                and deterministic. SOURCE_DATE_EPOCH pins pdfTeX and pandoc.

  Environment   pnpm 11.9.0 and Node 22 pinned. TypeScript held at 6.x with
                the reason and the removal condition documented.

  16. Diapositive 16 / 19

    Rapportez-le en entier — Exemple (suite)

      Refused       A dataset not declared synthetic fails the build.

  Not done      No container; no CI job that regenerates everything and fails
                on a diff; handover documentation thinner than this course
                asks for.

  17. Diapositive 17 / 19

    Rapportez-le en entier

    • La dernière ligne est celle à copier dans votre propre version — Une déclaration de reproductibilité sans section « pas…
    Notes du présentateur
    La dernière ligne est celle à copier dans votre propre version. Une déclaration de reproductibilité sans section « pas fait » est une déclaration que personne n'a auditée.

  18. Diapositive 18 / 19

    La suite

    • Le fil qui traverse les vingt est le même — Un nombre dans un rapport de programme est une affirmation, et tout ce que…
    • La dernière est celle qui rend les autres vérifiables — Une analyse que personne ne peut réexécuter est une analyse…
    Notes du présentateur
    C'est le cours, et c'est le dernier de l'ossature du programme. Le fil qui traverse les vingt est le même. Un nombre dans un rapport de programme est une affirmation, et tout ce que cette plateforme enseigne porte sur ce qui doit être vrai pour que l'affirmation tienne — un dénominateur défendable, un intervalle qui dit votre degré de certitude, un groupe de comparaison qui en est un, un graphique qui n'en dit pas plus que les données, et une chaîne qui produit la même réponse quand quelqu'un d'autre l'exécute. La dernière est celle qui rend les autres vérifiables. Une analyse que personne ne peut réexécuter est une analyse dont les autres propriétés doivent être prises sur parole, et ce public est jugé sur sa capacité à défendre un nombre en revue plutôt qu'à le produire.

  19. Diapositive 19 / 19

    La suite

    Lire la leçon complète, avec le code exécutable Retour à la leçon