The chart and the sentence come from the same file

Slide 1 / 22

What this lesson covers

• The failure this prevents
• What this platform does
• The four properties worth copying
• Doing it in matplotlib or ggplot2
• What to commit and what to ignore
• The three-line habit for a report with no pipeline
• Report it whole
• What comes next

Slide 2 / 22

The failure this prevents

• Nothing in any build can detect it — The figure is a valid image, the report is a valid document, and the number in the…
• The fix is structural rather than procedural — If the figure is generated from the dataset by a script that runs on…

Slide 3 / 22

What this platform does — In Python

def food_security_instruments() -> Figure:
    survey = read("food-security-survey-2024.v1.csv")
    coping = {row["household_id"]: row for row in read("livelihood-coping-2024.v1.csv")}

    # ... compute the four prevalences from the rows ...

    return Figure(
        slug="food-security-instruments",
        kind="bar",
        title={"en": "Four instruments, one set of households", "fr": "..."},
        caption={"en": "Four food security instruments applied to the same 1,955 "
                       "households. The highest prevalence is seven times the lowest...",
                 "fr": "..."},
        x_label={"en": "Households flagged (%)", "fr": "Ménages signalés (%)"},
        bars=bars,
    )

Slide 4 / 22

What this platform does — In R

# The same shape in R: a function returning data plus its labels, rendered once.

Slide 5 / 22

What this platform does

• No number is typed — The 7.4% in the caption is not written into the caption — the caption states the relationship and…
• Two outputs from one description — SVG for the web, TikZ for the PDF handout and the Beamer deck
• Standard library only — The generators need a stock Python and no install step, so a contributor can regenerate every…

Slide 6 / 22

The four properties worth copying

• One description, many renderings — The chart is data plus labels, and the renderer is separate
• Bilingual by construction — Title, caption and axis label are dictionaries keyed by locale, so a figure cannot exist in…
• Committed output — The SVG and TikZ files are in the repository, so the site builds with no Python on the deploy path…
• A test that fails when they diverge — figures.test.ts checks that every figure referenced by a lesson exists, that a…

Slide 7 / 22

The four properties worth copying — In Python

# The check that matters most, in one line:
assert (OUT / f"{figure.slug}.{locale}.svg").exists()

Slide 8 / 22

The four properties worth copying — In R

# A test is what turns a convention into a constraint.

Slide 9 / 22

Doing it in matplotlib or ggplot2 — In Python (cont.)

import pathlib
import pandas as pd
import matplotlib.pyplot as plt

FIGURES = pathlib.Path("outputs/figures")

def gam_by_commune() -> None:
    screening = pd.read_csv("data/muac-screening-artibonite-2024.v1.csv")
    summary = (screening.assign(case=screening["muac_mm"] < 125)
               .groupby("commune")["case"].agg(["mean", "size"])
               .sort_values("mean"))

    fig, ax = plt.subplots(figsize=(6.5, 4))
    ax.barh(summary.index, summary["mean"])
    ax.set_xlabel("GAM (%)")
    fig.savefig(FIGURES / "gam-by-commune.svg", bbox_inches="tight")

Slide 10 / 22

Doing it in matplotlib or ggplot2 — In Python (cont.)

    plt.close(fig)

    summary.to_csv(FIGURES / "gam-by-commune.csv")     # the numbers, beside the chart

if __name__ == "__main__":
    FIGURES.mkdir(parents=True, exist_ok=True)
    gam_by_commune()

Slide 11 / 22

Doing it in matplotlib or ggplot2 — In R

gam_by_commune <- function() {
  summary <- screening |>
    mutate(case = muac_mm < 125) |>
    summarise(gam = mean(case), n = n(), .by = commune)

  ggsave("outputs/figures/gam-by-commune.svg", width = 6.5, height = 4)
  write_csv(summary, "outputs/figures/gam-by-commune.csv")
}

Slide 12 / 22

Doing it in matplotlib or ggplot2

• Write the numbers out beside the chart — A CSV next to every figure is what lets a reviewer check the chart without…
• One function per figure, one script that runs them all — Not a notebook where the chart is cell 34 and depends on cell…
• Save as SVG, not PNG — wherever the destination allows it: it stays sharp when someone scales it, and it is text, so it…

Slide 13 / 22

What to commit and what to ignore

Slide 14 / 22

What to commit and what to ignore

• Deterministic output or nothing — A figure that embeds the generation date changes on every run, and the diff becomes…

Slide 15 / 22

The three-line habit for a report with no pipeline

• One script that produces every figure in the report — run before the report is sent, in one command
• No chart made by hand in a spreadsheet — because that is the one that will not be regenerated
• The caption generated with the figure — or at least the numbers in it read from the same object the chart was drawn from

Slide 16 / 22

The three-line habit for a report with no pipeline — In Python

caption = (f"Global acute malnutrition by commune, {summary['size'].sum():,} children "
           f"screened. {(summary['mean'] > 0.10).sum()} of {len(summary)} communes "
           f"are above the 10% emergency threshold.")

Slide 17 / 22

The three-line habit for a report with no pipeline — In R

# If the caption is an f-string, it cannot disagree with the chart.

Slide 18 / 22

The three-line habit for a report with no pipeline

• That single line is most of the benefit — A caption computed from the data is a caption that cannot survive the dataset…

Slide 19 / 22

Report it whole — Example

Figure production for this report

  All figures are generated from the committed dataset files by
  scripts/figures.py, run as part of the report build. No figure is drawn by
  hand and no number in a caption is typed.

  Each figure writes its underlying values to a CSV of the same name, so any
  figure can be checked without rerunning the analysis.

  Figures are produced in English and French from one description, so a
  figure cannot exist in only one language.

  Output is deterministic: rerunning the script on unchanged data produces
  byte-identical files, so a diff shows only real changes.

Slide 20 / 22

Report it whole

• The last paragraph is what makes the rest verifiable — A pipeline whose output churns on every run cannot be used to…

Slide 21 / 22

What comes next

• That is the course.

Slide 22 / 22

Where this goes next

Read the full lesson, with runnable code Back to the lesson