14 Reports That Run Themselves
Quarto, reproducible publishing, coding agents, Markdown, Python, EPUB, data analysis, k-means clustering
Much of what an organisation publishes is the same document with different numbers: the monthly update for investors, one report per customer, region, team or model, a feedback sheet for every class. Built by hand, each copy is a chance to paste last month’s figure into this month’s file. Built from one source with a parameter, a value given at render time, each copy is the same tested document run on a different value, and a script can make every one of them and check it.
This chapter makes three: Acme’s monthly investor update, a one-page report for each customer segment, and, for teachers, a feedback sheet for each section of a course. The update carries the company’s business figures, which in this book are synthetic and labelled so on every number; the model’s figures beside them are the real evaluation’s.
- Explain what a parameter is, where its default lives, and how a value is passed at render time.
- Ask for a parameterised document that validates its value and chooses its value-dependent words by code, with guards.
- Render one document for every value with a script that names and checks each output.
- Say where the outputs of a parameterised document land in a website project, and why.
14.1 One document, many values
| Ask for | Quarto calls it | Check |
|---|---|---|
| a value set at render time, with a default | a cell tagged parameters, #| tags: [parameters] |
the defaults render on their own |
| this value, now | quarto render update.qmd -P month:2026-06 |
the output shows that month |
| many values from a file | --execute-params params.yml |
each value reaches the document |
| an output named by its value | -M output-file:update-2026-06 |
one file per value, none overwritten |
| the engine that injects the values | papermill, in the project’s environment | without it the render stops |
The defaults are part of the document: the finished update’s month defaults to “latest”, which it reads as the last month in its data, so its default never goes stale; the segment report defaults to age_band 60+, and the feedback sheet to section A. Passing -P month:2026-06 replaces a default for one render: Quarto adds a cell after the parameters cell that sets the new value, and the document runs as before. That cell is executed through papermill, a Python package the project must have: without it, a render with -P stops with “The papermill package is required for processing –execute-params”.
Two rules make a parameterised document safe. Validate the value: a month or a segment that is not in the data should stop the render with a message that lists the valid ones, not produce a report about nothing. Let code choose every word that depends on the value, from the numbers as they are printed: “up” or “down”, “above” or “below”, “the first month in the data, so no change”. Chosen from the printed numbers, the word cannot disagree with them; guard what code cannot choose, such as a typed caption, and check that the printed text agrees, as the finished update does. A guard that repeats the comparison that chose the word can never fail, and protects nothing. A document rendered for a dozen values is a dozen chances for a typed word to be wrong.
14.2 The investor update
Add papermill with `uv add papermill`, then create update.qmd, a monthly investor update parameterised by `month` (a cell tagged `parameters` whose default is "latest", meaning the last month in data/synthetic_business.csv): that month's business figures, each labelled synthetic, the release live that month and its real model metrics from outputs/, and the change from the month before with its wording chosen by code and guarded. Stop with a clear message if the month is not in the data. Formats html, docx and typst; render it for 2026-06 with `-P month:2026-06` and tell me where the files went.uv add papermill · writes update.qmd · uv run quarto render update.qmd -P month:2026-06
Check it as an investor would, and as an auditor would. Every business figure says it is synthetic, here; in your own update, every figure names its source. The model’s figures come from outputs/ and are the real evaluation’s. A month before the first release says so, rather than inventing a model figure. And a month that is not in the data stops the render: try -P month:2027-01.
Where the files went is the trap. The project is a website, but the update is not in its render list, and should not be: a site page shows one value, and an investor update is not a public page. So Quarto renders it as a single file, beside its source, not in _site/, and the site’s post-render steps do not run for it. In the test run, --output-dir reports was refused for such a file, and --output accepted a file name but not a folder, so the script below moves each file into reports/ itself.
14.3 One report per segment
The same pattern makes the per-customer, per-region or per-team report: one document, one parameter per dimension.
Create segment.qmd: a one-page report for one customer segment, parameterised by `factor` (age_band or job) and `segment` (default 60+), with the best release's metrics for that segment from outputs/segments.csv against the whole list, wording guarded, and a note when the segment has few subscribers. Render it with `-P factor:job -P segment:student`.A segment’s numbers deserve more caution than the whole list’s: a segment with few subscribers has wide, noisy rates. The finished report adds its note below 50 subscribers, a named setting, FEW_SUBSCRIBERS, in the project’s code; the right threshold is your call, and belongs in a setting like that, not in a sentence.
14.4 Every value, checked
Write scripts/render_params.py: render update.qmd for every month in data/synthetic_business.csv and segment.qmd for every age band, in html, docx and typst, each file named by its value, into reports/; check that every file exists and contains its value; print a table.For the finished project that is ten months and five age bands in three formats: 45 files, each named by its value and each checked for it. The check is what makes a batch trustworthy: one file that silently shows the default month, because a value was not passed, would otherwise go out with the rest.
From the test run: a PDF check for the age band “18-29” failed, because the PDF’s text gave the hyphen back as a soft hyphen; the finished script strips soft hyphens and treats every kind of dash as a hyphen before it compares. And self-contained HTML, which carries its libraries inside it, is far larger than the same report as a PDF; send the PDF, and keep the HTML for the site.
14.5 The educator’s case: a sheet per section
The same method serves a teacher with several sections of one course: one feedback sheet per section, comparing the section with the course, from one gradebook. The example’s gradebook is synthetic, generated with a fixed seed, three sections of students identified only by number.
Create feedback.qmd: one feedback sheet per section of data/gradebook.csv, parameterised by `section`, with that section's mean and spread for each assignment against the course, a chart with alt text, every sentence labelled synthetic and its wording guarded, and no student identifiers. Then write scripts/render_sections.py to render feedback-<section>.pdf for every section and check each one. Run it.Marks are personal data, so the sheet shows section totals only, never a student, and never a group so small that a reader could work out who it is; the finished sheet stops if any group it describes, each assignment’s submissions included, has fewer than 5. With real marks, the rules of Section 2.10 and your institution’s data policy come first: build the document on a synthetic gradebook with the same columns, as this one is, and render the real one yourself.
Stuck for two minutes? Paste this into your agent. It backs up your work and brings the project to this point; then carry on from here.
Catch me up: follow ../quarto-workshop/checkpoints/19-eval-params/README.mdSummary
- A parameter is a value given at render time; its default lives in a cell tagged
parameters, and-P name:valuereplaces it, through papermill. - Validate every value, let code choose every word that depends on it from the numbers as printed, and guard what code cannot choose.
- Name every output by its value, and render and check them all with one script.
- A parameterised document left out of a site’s render list renders beside its source; move its outputs where they belong.
- Label synthetic figures on every number, and keep personal data to group totals.
Further reading
- Quarto, Parameters (checked 2026-11-18).
- papermill, documentation (checked 2026-11-18).