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 updaterefreshes its list of software,apt installinstalls. 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: truemakes 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: autoa 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.gitignoredoes 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 --onelinegives 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.lockthat 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
apton 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
-Pneeds 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:valuereplaces 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.ymlfile 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.csvor..; it means something else from another folder. See Paths. - render
-
To build a document’s outputs from its source;
quarto renderexecutes, 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,/clearor/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
.venvup to date withuv.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.