Exercises for the Water Analysis

Keywords

Quarto, reproducible publishing, coding agents, Markdown, Python, EPUB, data analysis, k-means clustering

The water analysis’s exercises come in three kinds. The eight numbered ones rebuild the project in order; those that end at a checkpoint give the lines that catch you up. The transfer tasks after them supply no prompt: you write the prompt and the check. The review questions test the ideas rather than the commands, and their answers are at the end.

Start the agent in ~/water-quality/, next to ~/quarto-workshop/. The water checkpoints hold sources only, so each catch-up also copies examples/water/data/ into your folder if data/ is missing. From Exercise III.3 on, the normal route copies each chapter’s finished scripts/analysis.py; writing the analysis yourself is optional. Appendix E — Checkpoints at a Glance, and Answers has the whole table.

Exercise III.1: Rules, environment and a first look

From 17  The Question, the Data and the Rules and 18  Look Before You Model. Copy the data, write AGENTS.md from the data’s README, create the uv environment, and build explore.qmd.

You’re done when explore.html shows missing values by zone and IRCA by band, zone and year for 2010–2023.

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/05-water-explore/README.md

Exercise III.2: Features

From 19  From Table to Features. Write prepare() in scripts/analysis.py: select, transform, impute with flags and standardise within year, and save outputs/prepared.parquet.

You’re done when the printed number of kept rows matches Table 19.1 and outputs/prepared.parquet exists.

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/06-water-prepare/README.md

Exercise III.3: Clusters

From 20  Finding Kinds of Places: k-Means. Copy (or build) the k-means step, and create clusters.qmd.

You’re done when outputs/clusters.parquet exists, you can say what k is and why, and clusters.html shows the elbow, the silhouette and the PCA picture.

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/07-water-cluster/README.md

Exercise III.4: Interpretation

From 21  Interpreting Clusters. Copy (or build) the outcome rules, profiles and names, and add the heatmap and the outcome lines to clusters.qmd.

You’re done when the script prints one name per cluster, and clusters.html shows the heatmap and the outcomes by cluster and year.

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/08-water-interpret/README.md

Exercise III.5: The within-cluster check

From 22  Correlation Is Not Causation. Copy (or build) the check, and add it to the clusters page with its descriptive-only sentence.

You’re done when clusters.html shows \(\rho\) and n for every cluster and says the check is descriptive, and you can say how one confounder could bias it.

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/09-water-causation/README.md

Exercise III.6: Report, slides and e-book

From 23  Publish Many. Build report.qmd (HTML, Word, Typst PDF), slides.qmd (Reveal.js and PowerPoint) and, optionally, the report’s EPUB.

You’re done when report.docx and report.pdf open with the heatmap, the outcomes and the within-cluster figure; slides.html and slides.pptx both have six slides; and, if you made it, report.epub opens with the three figures and the sources.

There is one catch-up for each step: use the one for the step you are stuck on, the report, the slides or the optional e-book.

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/10-water-report/README.md

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/11-water-slides/README.md

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/12-water-epub/README.md

Exercise III.7: The website, published

From A website with a blog and Publish it. Make the folder a website with a blog post titled with the real k, put it on GitHub, and publish it with an interactive uv run quarto publish gh-pages.

You’re done when https://<your-github-username>.github.io/water-quality/ opens, and its home page lists one post whose title states the real k.

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/13-water-website/README.md

Exercise III.8: Change an input, explain the rebuild

From Change an input, explain the rebuild, with no prompt supplied: change MAX_MISSING, predict, rebuild, explain, and undo with git restore scripts/analysis.py.

You’re done when you can name the outputs that changed, the ones that did not, what happened to Tunja’s two zones, and the mechanism that links them (pre-render, outputs/, freeze: false). The model answer is in Appendix E — Checkpoints at a Glance, and Answers.

Transfer tasks: your prompt, your check

Each task applies one of the water analysis’s rules to something the chapters did not do. Write the prompt yourself, one task with concrete file and column names, and write the check before you run it: what will you look at, and what would tell you the agent got it wrong?

  1. Follow another municipality. Choose one you know, or another department’s capital, and list each of its zones’ clusters by year from outputs/clusters.parquet, with every flag that marks a filled value.

    You’re done when you can say which kind each zone falls in, whether either moves between kinds, and which of its values were filled rather than measured.

  2. Dropout within each kind. Repeat the within-cluster check (Worse water, more infant deaths?) for school dropout instead of infant mortality, and add it to clusters.qmd. The prompt has to carry the rules that apply to dropout: the years OUTCOME_YEARS gives it, and the level at which it is measured.

    You’re done when the page shows \(\rho\) and n per cluster beside a sentence saying the check is descriptive, and you can explain why its n differs from the infant-mortality check’s.

  3. Guard a sentence. Find a sentence in report.qmd or the blog post whose words, not only its numbers, depend on the data, such as one naming the kind with the lowest coverage. Make the page fail its render if the data stop supporting it, as assert k == 4 does for the post’s title.

    You’re done when the page renders with the guard, and fails with a message naming the sentence when you temporarily reverse the guard’s condition.

  4. Another reader. Suppose a regional health office asks for one page: a PDF with one figure, one table and the sentence saying what the comparison does not show. Build it from outputs/ only.

    You’re done when brief.pdf renders, every number in brief.qmd is inline code, the IRCA is labelled utility-supplied, and the last sentence says the comparison does not establish a causal effect of water safety.

Review questions

  1. A colleague suggests adding infant mortality to the features, since it says more about health risk than altitude does. Why does the water analysis never cluster on an outcome?
  2. Why is the IRCA called “utility-supplied” every time it appears, and where does the label matter most?
  3. Most rural rows have no IRCA, and the analysis drops them. What can the rural cluster’s results claim, and what can they not?
  4. Why does the analysis cluster z-scores standardised within each year, rather than the raw values?
  5. The silhouette at the chosen k is only 0.19. Did the clustering fail?
  6. Tunja’s rural zone had medium-risk water in some of the analysis’s years, yet sits in a cluster named for no-risk water. Is the name wrong?
  7. Two draft titles for the council’s last slide: “Safer water lowers infant mortality” and, after the within-cluster check (Worse water, more infant deaths?), “Water quality makes no difference to infant mortality”. What is wrong with each, and what would you write instead?
  8. In the within-cluster check, each of Tunja’s municipality-years carries the mean IRCA of its two zones. Why is that not the water Tunja’s infants drank, and what is it called to read it as if it were?
  9. After you change MAX_MISSING and rebuild, the clusters page, the report and the post show new numbers, but the explore page and the live site do not. Why? And what would go wrong if the site used freeze: auto?

Going further

  1. Optional pieces. Build the dashboard and the white paper (A dashboard and a white paper (optional)); the finished project, examples/water/, is their checkpoint:

    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/examples/water/README.md
  2. Change the seed. Repeat Exercise III.8 with SEED instead of MAX_MISSING. Clusters are numbered by their centre’s IRCA, so the names and colours should stay; check whether anything else moves, and why very little does (Choosing k, on stability).

  3. Freeze it. Switch the site to freeze: auto, change MAX_MISSING, render, and find a page that kept its old numbers. Then write the invalidation rule into the project’s AGENTS.md, apply it, and undo both changes.

  4. The challenges in Further challenges: moves between kinds as a Sankey diagram, positive deviants, and other clustering methods.

Answers to the review questions

  1. Because the analysis then compares outcomes between the kinds. If infant mortality helped define them, they would differ in infant mortality by construction, and the comparison would find exactly what was put in (Features and outcomes). Outcomes describe the clusters; they never define them.
  2. The open table holds the IRCA of systems run by water utilities, not the national figure. Self-supplied systems, which have no utility, score far worse (Scoring water risk: the IRCA), so the data understate the risk wherever people rely on self-supply, and say nothing where no utility exists. Without the label, a reader would take the figure for the national one, and think water safer than it is wherever self-supply is common.
  3. They describe sampled rural systems only: those run by a utility and tested. The gaps are not missing at random. They depend on the zone, and perhaps on the risk itself, since the zones least often scored are the riskiest where they are scored, so every rural result should say which systems it covers (Rural: less data, more risk, What the steps keep).
  4. k-means groups rows by straight-line distance, where a feature counts in proportion to its variance. In raw units, rainfall and altitude would decide the clusters on their own, and the kinds would be climate zones. z-scores give every feature the same weight, and computing them within each year removes shifts that move every place at once, such as transfers in pesos not adjusted for inflation, so a cluster means the same relative position in every year (Why scale?, Four steps from table to features).
  5. No, but the kinds overlap: they summarise a continuum rather than separate islands of data. That is why k is chosen by a rule written down before seeing the result, and why the kinds are described, not treated as natural types. Refits from other seeds agree, which shows only that the result does not depend on the start, not that it would survive other data or features (Choosing k).
  6. Right about the kind, wrong about this member: Tunja’s rural water was never in the no-risk band in 2016–2023. The risk word is the band of the cluster’s median IRCA, not a claim about every zone-year in it, and k-means places a row by all nine features, several of which Tunja’s two zones share as one municipality (Name them by a rule, Where Tunja lands). A statement about Tunja needs Tunja’s rows.
  7. Both read a description as an effect. The first turns a difference between kinds into a cause, though poverty, rurality, health-service access and reporting differ between the kinds too. The second reads a weak association as no effect, though weak reporting can hide deaths and small municipalities add noise (What else could explain it). Instead, say what was compared over which rows, with verbs of association, and add one sentence saying the comparison does not establish a causal effect of water safety (Writing it honestly).
  8. The mean weighs the two zones equally, though only a small share of Tunja’s people live in the rural one, and it lies between two values that neither zone had. IRCA is measured per zone and infant mortality per municipality, so a pattern across places need not hold for the people in them; reading it as if it did is the ecological fallacy (What else could explain it).
  9. pre-render re-runs the analysis, which rewrites outputs/, and freeze: false re-executes every page, so every page that reads outputs/ is fresh. The explore page re-runs too, but it reads only data/water_municipal.csv, which did not change (Table 23.1). The live site is the last _site/ you published, and changes only when you publish again (Publish it). With freeze: auto, Quarto would re-execute a page only when its own source changed: it does not see outputs/ or data/, so pages would keep their old numbers until the cache was cleared (A website with a blog).