Skip to content

A plot or widget in every notebook (three figures are already written but commented out) #9

Description

@project-delphi

The problem

Twelve notebooks about the shape of data, and almost nothing is ever drawn. matplotlib appears in exactly three places and all three are commented out:

  • scripts/content.py:639 — §04, "Optional, and worth doing once", showing the reshape-vs-transpose scramble
  • scripts/content.py:1317 — §09, original / sobel / blurred side by side
  • scripts/content.py:1656 — §11, the PCA scatter

The §04 one is the clearest loss. The entire section argues that reshape and transpose give identical shapes and completely different data — and the one thing that makes that undeniable in half a second, seeing the scrambled image, is behind a comment marker that most students will not uncomment.

The ask

One visual per notebook. A plot where a plot is the point; an ipywidgets slider where interaction is the point. Not decoration — each one should replace a paragraph of explanation.

  • 00 setup-and-data — thumbnails of the datasets being loaded, confirming visually that the download worked (see Add CLAUDE.md, fix the checker's numbering, pin line endings to LF #3)
  • 01 what-a-tensor-is — a slice and a fiber highlighted on the same image
  • 02 thinking-in-n-dimensions — this one is a discussion block with no code by design; a diagram may fit better than a plot, or skip it
  • 03 indexing-and-broadcasting — slider over the tumour feature index; the zero-variance pixels made visible
  • 04 reshape-and-transposeuncomment the existing figure (content.py:639) and make it non-optional
  • 05 video-pipeline-design — shape diagram per pipeline stage
  • 06 contraction-with-einsum — which axis gets summed, drawn
  • 07 inverses-and-pseudoinverse — residuals of the least-squares fit
  • 08 recursion-with-matrices — the airline forecast against the actual series; eigenvector directions under repeated application
  • 09 convolution-and-deconvolutionuncomment the existing figure (content.py:1317), plus a slider over kernel size
  • 10 tucker-decomposition — slider over rank k (pairs with PCA is not a factorization — remove it from the map of factorizations #4)
  • 11 wrap-up-and-take-homesuncomment the existing PCA scatter (content.py:1656); scree plot showing the standardisation trap

Take these as a starting list, not a specification. If a section is better served by no plot, say so and tick it off.

Constraints — this one touches every file, so read carefully

  • All twelve edits are in scripts/content.py. The .ipynb files are generated by scripts/gen_notebooks.py; hand-editing them is caught by CI (which reruns both generators and fails if the tree changes) but only after you push.
  • No committed outputs. scripts/check_links.py fails on any cell with outputs or an execution count. A widget that renders only when executed is fine; a widget whose state gets serialised into the .ipynb on save is not. Check git diff --stat before committing — a stray figure or widget blob shows up as a suspiciously large diff on a file you only added ten lines to.
  • ipywidgets in Colab: works, but some widget types need google.colab.output.enable_custom_widget_manager() first. Put that in the cell with a comment rather than assuming the student's runtime is configured. Students are on Colab, not local Jupyter — test there.
  • Nothing here changes the built site. _quarto.yml serves notebooks/*.ipynb as raw resources:, never rendered — Quarto does not execute them. So CI checks validity and nothing more. The only real verification is opening a couple in Colab and clicking the sliders.
  • Bilingual prose on every new markdown cell — 🇪🇸 blockquote alongside the English, matching the existing pattern.
uv run --with pyyaml,nbformat python scripts/gen_notebooks.py
uv run --with pyyaml,nbformat python scripts/check_links.py --notebooks-only

Please split this up

Twelve sections in one PR is unreviewable and will sit open. Several PRs, grouped by two or three sections each. The three already-written-but-commented-out figures (§04, §09, §11) are a good first PR on their own — small, obviously correct, and it unblocks the pattern for the rest.

Activity

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Metadata

Metadata

Assignees

Labels

enhancementNew feature or requestnotebooksnotebooks/ and scripts/content.py

Projects

No projects

    Milestone

    No milestone

    Relationships

    None yet

    Development

    No branches or pull requests

    Issue actions