Appendix J — Glossary

Keywords

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

The terms in this book that a newcomer may not know, each with a short definition and the section that explains it in context, where it comes with its reasons and an example. Code and file names are listed by their letters, without punctuation.

A

absolute path
A path that starts at the top folder, /, so it names the same place from any folder: /home/ana/first-report. See Paths.
adjusted Rand index (ARI)
A score of how far two groupings agree beyond chance: 1 means identical, 0 no better than chance. See Section 20.2.
AGENTS.md
A plain Markdown file of rules at the top of a project, which the agent reads at the start of every session. See Section 2.5.
alt text
The description that screen readers announce, and that appears if an image cannot load. See Section 6.7.
ALVA
The Association of Leading Visitor Attractions, the source of the London visitor counts; it counts only its member sites. See Section 1.1.
API
The vendor’s programming interface; API prices are what a program pays per token when it calls a model directly. See Section 2.2.
API key
A secret string that identifies your account to a vendor’s programming interface, which bills each request. Keep it out of files you share or commit. See Section 4.1.
apt
Ubuntu’s package manager: apt update refreshes its list of software, apt install installs. See Section 4.2.
artifact
A file a CI run makes and keeps for download from the run’s page, such as the month’s PDF reports. See Section 15.6.

B

blank line
A line with nothing on it. In Markdown it starts a new paragraph, and a list needs one above it. See Section 6.1.
block quote
A quotation set off from the text beside a bar, typed with > at the start of each line. See Section 6.1.
bootstrap
Refitting on rows drawn again at random, to test whether a result survives other data. See Section 20.2.
box plot
A box holding the middle half of a group’s values, with lines at the median and the mean, and whiskers spanning the middle 90%. See Section 21.5.
branch
A movable label on a line of commits. See Section 9.1.
brand file
_brand.yml: a company’s colours, fonts and logo, stated once; Quarto applies it to web pages, Reveal.js decks, Typst PDFs and dashboards. See Section 12.1.

C

calibration
How far a model’s predicted probabilities match the rates observed: of contacts given 20%, about one in five should subscribe. See Section 10.3.
catch-up box
The one line to paste into your agent where the book reaches a checkpoint; after catching up, you carry on reading from the box. See Section 6.11 and Figure 2.
cell options
Instructions for a code cell in its first lines, written as comments that start with #|. See Section 7.1 and Section 7.4.
checkpoint
A folder in the workshop’s checkpoints/ holding a project as it should be at the end of a hands-on block, with a README of catch-up steps. See Section 6.11 and Figure 2.
choropleth
A map whose areas are coloured by a value. See Section 23.7.
CI job
A build that a host such as GitLab runs on each push. See Section 9.2.
cited copy
Facts typed into a source from a cited file; they do not follow the file when it changes. See Section 6.8.
citeproc
The citation processor Pandoc uses to format citations and the reference list in a CSL style; citeproc: true makes a Typst PDF use it too. See Section 13.3.
clone
To copy a repository, with its history, to your computer. See Section 4.6.
cluster
A group of zone-years that are similar to each other on the chosen variables, found by k-means. See Section 17.1.
code cell
A fenced block of code whose language is in braces, such as {python}; it runs when the document renders. See Section 1.2 and Section 7.1.
code fence
Three backticks that open and close a block of code; the word after them names the language, and the text inside is shown exactly as typed. See Section 6.9.
codespace
A computer that GitHub runs for you, opened in your browser, set up from a repository’s dev container file. See Section 4.8.
coding agent
A program that writes files and runs commands at your request, acting in your project folder in a loop until the step is done, where a web chat hands you text to copy. See Figure 1 and Section 2.1.
command-line program
A program you run by typing a command in a terminal. See Section 1.2.
commit
A recorded state of the project’s files, with a message saying why it changed. See Section 5.4 and Section 9.1.
CommonMark
A precise specification of Markdown, which GFM extends. See Section 6.1.
confounder
A third variable that affects both the exposure and the outcome, so the two move together even if one has no effect on the other. See Section 22.2.
context
Everything sent to the model with a request: the conversation so far, the files read and the project’s rules. See Section 2.3.
continuous integration (CI)
Rebuilding and checking a project automatically, on a clean machine, for every proposed change; here, a GitHub Actions workflow that runs the project’s own rebuild commands on every pull request. See Chapter 15.
contrast ratio
How far text stands out from its background, from 1:1 to 21:1; WCAG 2.2 asks for at least 4.5:1 for normal text. See Section 11.4.
control
Comparing like with like, so a third variable cannot explain a difference; the clusters offer a partial control. See Section 22.1.
correlation coefficient (r)
A measure from −1 to 1 of how two variables move together; 1 would mean they rise together along a straight line. See Section 19.3.
cron
A five-field line (minute, hour, day of the month, month, day of the week) that says when a scheduled job runs; GitHub Actions reads it in UTC by default. See Section 15.6.
cross-reference
A link to a numbered section, table or figure, written @sec-…, @tbl-… or @fig-…, which renders as “Section 2” or “Table 1” in every format. See Section 10.3.
CSL
The Citation Style Language: a citation style written as a file, such as APA’s or a journal’s, named with csl:. See Section 13.3.
CSV
A table in plain text, one line per row, with commas between the columns. See Section 6.8.
curl
A small program that downloads a file from a web address. See Section 4.2.

D

dashboard
A page of charts and key numbers arranged in a grid. See Section 8.1.
description
A page’s one-sentence summary in its front matter, which feeds listings, search, the page’s meta tag and social cards; it cannot compute. See Section 12.4.
dev container
A file, .devcontainer/devcontainer.json, that lists what a ready-made environment installs, so a codespace or a container starts with the right tools. See Section 4.8.
diff
The lines a change added and removed. See Section 2.6 and Section 5.5.
difference-in-differences
Comparing places before and after a change with comparable places that did not change. See Section 22.2.
display-only fence
A code fence whose language is not in braces, such as python: the code is shown and never run. See Section 7.1.
div
A block of Markdown between two lines of three colons, whose class in braces tells Quarto what to make of it. See Section 8.1.
DIVIPOLA
DANE’s list of Colombia’s municipalities, which gives each a five-digit code: two digits for the department and three for the municipality. See Section 17.4.
DOI
A document’s permanent identifier; https://doi.org/ followed by it opens the publisher’s page. See Section 23.7.

E

ecological fallacy
Drawing conclusions about people from data about places. See Section 22.2.
effort
How long a model reasons before answering. See Chapter 2.
elbow
The k after which inertia stops falling much. See Section 20.2.
environment
A folder holding one version of Python and the packages one project uses, kept apart from every other project’s. See Section 6.10.
EPUB
An e-book format: a zipped set of web pages whose text reflows to fit the reader’s screen. See Section 7.6 and Section 23.3.
escape
A backslash before a Markdown mark, such as \*, which keeps the mark as typed. See Section 6.1.
Euclidean distance
Straight-line distance: the square root of the sum of squared differences across the features. See Section 19.3.
execute-dir
A project setting that makes every page read files from the project folder. See Section 23.4.

F

feature
A variable the clustering sees, and so one that defines the kinds. See Section 17.5.
flag column
A column that marks every value that was filled. See Section 19.1.
fragment
Part of a slide revealed one step at a time, written with . . . or ::: {.fragment}. See Section 11.2.
freeze
Quarto’s cache of computed results; with freeze: auto a page re-runs only when its own source changes, not when the data it reads change. See Section 1.4 and Section 23.4.
front matter
A block of settings in YAML between two lines of three dashes at the very top of a file. See Section 7.1 and Section 7.2.

G

gh
The GitHub command-line tool. See Section 4.5.
Git
The version-control tool: something like Track Changes for a whole folder, with a lasting history. See Section 1.4 and Section 9.1.
git add
Chooses what goes into the next commit; git add . takes every file in the folder that .gitignore does not leave out. See Section 5.4.
git diff
Shows the lines changed since the last commit: a line starting - was removed, one starting + added. See Section 5.5.
git log
Lists the commits, newest first; git log --oneline gives one line to each. See Section 5.4.
git restore
Puts a file back as it was at the last commit. See Section 5.5 and Section 9.5.
git status
Says which files have changed since the last commit, and which ones Git does not track. See Section 5.4.
GitHub
The website that keeps a copy of a repository online. See Section 9.1.
GitHub Flavored Markdown (GFM)
The dialect of Markdown GitHub uses for README files and issues: CommonMark with tables, task lists, strikethrough and automatic links. See Section 6.1.
.gitignore
The list of files and folders Git should not track. See Section 5.4 and Section 9.3.
guard
A line that stops the render when a sentence’s words, not only its numbers, no longer match the data. See Section 23.4.

H

harness
The program on your computer that gives a model its tools, carries out its requests and asks you first. See Section 2.1.
home folder
Your own folder, written ~. See Section 4.3.
Homebrew
A package manager for the Mac, which installs command-line tools; not needed for this book. See Section 4.5.
horizontal rule
A line across the page, typed as --- between blank lines. See Section 6.1.
hyperparameter
A setting an algorithm cannot learn from its own objective, such as k. See Section 20.2.

I

impute
To fill a missing value with an estimate. See Section 19.1.
index.qmd
The source of a website’s home page. See Section 9.3.
inertia
The sum of squared distances from each point to its cluster’s centre. See Section 20.1.
infant mortality
Deaths under one year of age per 1,000 live births. See Section 17.5.
inline code
Code in a sentence, such as {python} name, whose value Quarto writes into the sentence when the document renders. See Section 1.2 and Section 7.1.
IPM
The multidimensional poverty index: the share of a zone’s people who are poor in several respects at once, from the 2018 census. See Section 17.5.
IRCA
Colombia’s risk index for drinking water, from 0, every test passed, to 100, every test failed. See Section 17.2.
IRCA risk bands
Resolución 2115’s five ranges of the IRCA: no risk, low, medium, high and unfit. See Section 17.2.

J

join
Matching the rows of two tables by a column they share. See Section 17.4.
Jupyter
The computation engine that runs Python code cells (knitr does the same for R). See Section 1.2.

K

k
How many clusters k-means is asked to find. See Section 20.1.
kernel
The running Python process that executes a document’s cells, top to bottom. See Section 7.7.
k-means++
scikit-learn’s way of choosing starting centres that are spread out, which makes a stuck start less likely. See Section 20.1.

L

lead
The agent session that starts sub-agents, waits for them and checks their results. See Section 8.2.
line break
A new line inside a paragraph, made by ending the line with a backslash. See Section 6.1.
listing
A page that lists other pages, such as every post of a blog, made by Quarto. See Section 23.4.
loadings
The weights of a principal component, which say what it measures. See Section 20.3.
lockfile
A file such as uv.lock that records the exact version of every package, for every system. See Section 6.10.
logarithm
A scale that measures ratios rather than differences: every doubling adds the same amount. See Section 19.1.
low-coverage
In a cluster’s name, half a standard deviation or more below the year’s average coverage: a relative position, not an absence of service. See Section 21.2.

M

Markdown
A way of writing structured text with a few punctuation marks, such as # before a heading. See Section 1.2 and Section 6.1.
MDM
DNP’s score of a municipality’s management and results, from 0 to 100. See Section 17.5.
median
The middle value, with half the values below it. See Section 18.1.
missing not at random
Gaps that depend on the unmeasured value itself, which no fill can repair. See Section 18.2.
model
A large language model: it reads and writes text and can reply with a request to use a tool. See Section 2.1.
model card
A short document that travels with a model: what it is and is for, how it performs overall and for the groups it affects, and its known limits (Mitchell and colleagues, 2019). See Section 10.2.
monotonic
A relation in which one variable tends to rise as the other rises, though not necessarily along a straight line. See Section 22.1.
municipality-year
One municipality in one year: the unit of the municipal outcomes, infant mortality and dropout. See Section 21.4.

N

naming rule
A written rule that names each cluster from its profile: setting, relative coverage and the band of its median IRCA. See Section 21.2.
nano
The terminal’s own simple text editor: Ctrl+O and Enter save, Ctrl+X leaves. See Section 5.5 and Section 6.5.
nominal pesos
Pesos not adjusted for inflation. See Section 19.1.
notebook
A Jupyter file (.ipynb) of code, outputs and text; Quarto renders one as saved, or runs it first with --execute. See Section 3.4.

O

outcome
A variable the analysis only compares between the kinds and never clusters on. See Section 17.5.

P

package
An add-on library that Python code imports, such as pandas for tables or matplotlib for charts. See Section 6.10.
package manager
A program that installs software from a collection and keeps it up to date, such as apt on Ubuntu or Homebrew on a Mac. See Section 4.2.
Pandoc
The document converter inside Quarto that turns the executed Markdown into each output format. See Section 1.2.
Pandoc’s Markdown
The Markdown Quarto reads: GFM’s core marks, plus attributes in braces, footnotes, definition lists, citations and mathematics. See Section 6.1.
papermill
The Python package that puts a render’s parameter values into a document; a render with -P needs it in the project’s environment. See Section 14.1.
parameter
A value a document takes at render time, with a default in a cell tagged parameters; -P name:value replaces it for one render. See Section 14.1.
Parquet
A file format for tables that keeps each column’s type, so a code such as 05001 stays text. See Section 17.6.
path
The name of a file or folder through the folders that lead to it, separated by /: data/visits.csv. See Paths and Section 5.1.
PATH
The list of folders a terminal searches for programs, read when the terminal starts. See Section 4.4.
percentile
The value below which a given share of the values lies; the 5th and 95th bound the middle 90%. See Section 21.5.
platform tag
The part of a package file’s name that says which system and processor it was built for. See Section 6.10.
pre-render
A script Quarto runs before every render of a project, even of a single page. See Section 23.4.
principal component
A direction in which the data vary: a weighted sum of the features. See Section 20.3.
principal component analysis (PCA)
A method that finds the directions in which the data vary most and projects the rows onto them. See Section 20.3.
print view
Reveal.js’s layout for printing a deck, one slide per page (press E); a browser then saves it as a PDF. See Section 11.5.
profile
A cluster’s mean of each feature over its rows, in z units. See Section 21.1.
prompt
The request you type into the agent. See Section 2.6.
Prompt, Check, Publish
The loop this book teaches: prompt an agent for one small step, check what it did, and let Quarto rebuild every output from the checked source. See Figure 1.
prompt (terminal)
The line ending in $ (or % on a Mac) that shows the terminal is ready, and who and where you are. See Section 4.3.
protected branch
A branch, usually main, that GitHub lets change only through a pull request whose required checks have passed. See Section 15.4.
proxy
A server that a company network sends all web traffic through; it can block downloads. See Section 4.1.
pull request
A proposal to merge a branch, which shows the difference line by line. See Section 9.1.
push
Copying commits to the shared repository on GitHub. See Section 9.1.

Q

quarto preview
Renders a file, serves it on a local address and renders it again every time the file is saved; Ctrl+C stops it. See Section 6.1 and Section 6.4.
Quarto project
A folder that a _quarto.yml file at its top turns into one website or book. See Section 9.3.

R

random seed
The number that starts the computer’s random-number generator, so random starts are the same on every run. See Section 1.4 and Section 20.1.
raw block
A block that Quarto passes untouched to one format, such as a raw Typst block. See Section 8.4.
reference document
A Word or PowerPoint file whose styles, theme and layouts Quarto copies into its output, set with reference-doc. See Section 11.6.
relative path
A path that starts from the folder you are in, such as data/visits.csv or ..; it means something else from another folder. See Paths.
render
To build a document’s outputs from its source; quarto render executes, converts and typesets. See Section 1.2 and Section 6.1.
repository
A project folder with its Git history. See Section 1.4 and Section 5.4.
reproducible
Someone else, or you later, can rebuild the same results from the same files with one command, and see where every number came from. See Section 1.4.
ROC AUC
The probability that a model ranks a random positive case above a random negative one: 0.5 is a random ranking, 1 a perfect one. See Section 3.5.
root folder
The folder you start an agent in, where it reads, edits and runs commands. See Section 2.4.
runner
The clean machine a CI workflow runs on, such as ubuntu-24.04; it starts with nothing of the project installed. See Section 15.1.
rural zone
A municipality’s smaller settlements and dispersed countryside. See Section 17.4.

S

Saber 11
ICFES’s national exam for students finishing upper secondary school, with a global score from 0 to 500. See Section 17.3.
selection on the outcome
Keeping or dropping rows by the value being measured, so the rows kept are not typical. See Section 21.4.
self-supplied system
A water system that no utility runs. See Section 17.2.
SGP
Colombia’s system of national transfers to municipalities; the feature is its allocation for drinking water and sanitation, per person. See Section 17.5.
ShareAlike
The condition of a CC BY-SA licence that anything built from the data is shared under the same licence. See Section 23.5.
shell
The program behind the terminal that runs your commands. See Section 4.4.1.
silhouette
A score from −1 to 1 of how much closer each point is to its own cluster than to the next one, averaged over the points. See Section 20.2.
SIVIGILA
Colombia’s public-health surveillance system. See Section 23.8.
skewed
Mostly moderate values with a few very large ones. See Section 19.1.
slash command
A command such as /model, /clear or /exit, typed into the agent itself. See Section 2.3.
slice
A subgroup of the test data, such as an age band, for which a model’s metrics are reported separately. See Section 10.2.
small numbers
In small places a handful of deaths moves a rate a long way, so extreme rates are fragile. See Section 21.4.
social card
The title, description and image a chat app or social site shows when a link is shared, from a page’s Open Graph tags. See Section 12.4.
speaker notes
What a presenter will say about a slide, written in a ::: {.notes} block: shown in speaker view (press S), not on the screen. See Section 11.2.
Spearman’s ρ
A measure, from −1 through 0 to +1, of whether two variables rise and fall together in rank order. See Section 22.1.
spending limit
A monthly cap on what an API account may spend, set on the vendor’s site; requests stop when it is reached. See Section 4.1.
stack trace
The list of what was running inside a program when it stopped, printed after some errors; it is for the program’s developers, and the error’s first line is what to read. See Section 5.6.
standard deviation
Roughly, the typical distance of a value from the mean, in the variable’s own unit. See Section 19.1.
static site
A folder of HTML, CSS, JavaScript, images and documents, with no program running on a server. See Section 9.2.
status check
A CI result shown on a pull request and its commits: a green tick or a red cross, with the run’s log behind it. See Section 15.3.
strikethrough
Text crossed out, written between two tildes on each side, ~~Car~~. See Section 6.1.
sub-agent
A separate agent session that your agent starts for one task, with its own context. See Section 8.2.
sudo
Runs a command as the administrator, after asking for your password. See Section 4.2.
SVG
A drawing written as text, which a model writes as it writes code. See Chapter 2.

T

Tab completion
Pressing Tab in the terminal to finish a file or folder name; twice lists the names that fit. See Section 5.1.
task list
A bulleted list whose items start with a box, [ ] empty or [x] ticked. See Section 6.1.
template partial
A named part of the template Quarto writes a format from, such as Typst’s typst-show.typ, which a project can replace with its own. See Section 13.5.
terminal
A window where you type commands instead of clicking. See Section 4.3.
theme
Where a document’s or deck’s colours and fonts live; for Reveal.js, a built-in theme plus your own Sass file. See Section 11.4.
three checks
What every change passes: before it is committed, scope (which files changed) and correctness (one number against its source row); after, rebuild (what was committed renders on its own, from a fresh clone). See Section 5.7.1.
token
A fragment of text a few characters long: the unit models read, write and are priced by. See Section 2.2.
Typst
A modern typesetting system that ships inside Quarto and makes its PDFs. See Section 1.2.

U

untracked
A file Git can see in the folder but does not yet record. See Section 5.4.
urban zone
A municipality’s head town (cabecera municipal). See Section 17.4.
utility-supplied IRCA
The IRCA of samples from systems a water utility runs (“prestadores”), which understates risk where people supply themselves. See Section 17.2.
uv
The tool that installs Python and manages each project’s packages. See Section 4.5 and Section 6.10.
uv run
Runs one command in the project’s environment, first bringing .venv up to date with uv.lock. See Section 6.10.

V

value box
A dashboard box that shows one key number with a label. See Section 8.1.
variance
The square of the standard deviation. See Section 19.3.
VPN
A virtual private network, which sends your traffic through another network; it can slow or block downloads. See Section 4.1.

W

WebGL
The browser’s built-in 3-D graphics. See Section 8.5.
workflow
In GitHub Actions, a YAML file in .github/workflows/ that says when a build runs (its trigger) and what it does, step by step. See Section 15.1.
working tree
The project’s files as they are now; “clean” means they match the last commit. See Section 5.4.
WSL
The Windows Subsystem for Linux, which runs Ubuntu inside Windows. See Chapter 4.

Y

YAML
A format for settings in which indentation is meaning. See Section 1.2 and Section 7.1.

Z

zero data retention
A vendor arrangement, usually for qualified business customers, under which prompts and outputs are not kept after the response. See Section 16.1.
zone variable
A variable measured separately for a municipality’s urban and rural zones; a municipal variable has one value for the whole municipality, repeated on both rows. See Section 17.5.
zone-year
One municipality’s urban or rural zone in one year: one row of the water data, and the water analysis’s unit of analysis. See Section 17.4.
z-score
A value’s distance from its year’s mean, in standard deviations; it has no unit. See Section 19.1.