This page is for readers outside ESS 469/569 at UW: an instructor standing up their own course, a lab lead onboarding new group members, an advisor deciding whether to assign it, or a program officer judging what it teaches. The book’s machinery — leaderboard, quizzes, hidden test sets — assumes nothing UW-specific, though the calendar around it and the data inside the exercises are firmly Pacific Northwest; here is how to run it elsewhere, what to substitute, and how to read the book without running any of it.
Stand up your own course instance¶
Fork the repository (githubmlgeo_synth synthetic-data package, and the grading infrastructure live in this one repo. pixi install then pixi run build reproduces the book locally.
Leaderboard CI. Students submit predictions by pull request; a GitHub Actions workflow scores each PR and updates the standings page on merge. The recipe, including the private-seed system, is in leaderboard/INSTRUCTOR.md (not rendered in the book). Three tracks: classification, scored against a canonical public split of a Zenodo seismic dataset with a private re-split as the hidden set; a forecast diagnostic track against public CO2 data, deliberately exploitable and carrying no grading weight; and a graded hidden forecast track on an mlgeo_synth series whose truth file lives only on the instructor’s machine (leaderboard/private/, gitignored), so public CI shows the section as pending and your local scoring run produces the real table. Any mlgeo_synth generator accepts a seed, so homework variants regenerate for free.
Regenerate the hidden seeds yearly. Once a cohort has seen a test set, it is a validation set. The rotation checklist in INSTRUCTOR.md covers it: new private seeds stored outside the repo, a refreshed CO2 holdout horizon, a regenerated hidden forecast series (the generator recipe is in the file), cleared submissions, and a dry run of the scoring script before week one. Report both public and hidden scores to your class; the gap between them is the lesson.
Quizzes on any LMS. The concept-check MCQ banks (outcome 1) are instructor-private source files, one per chapter, in a plain format that converts to Canvas via text2qti or pastes into any LMS. They are deliberately kept out of the public repository so answer keys do not circulate; adopting instructors can request the banks from the authors (see the contact in the README) or write their own from the chapter learning outcomes — scenario-based questions that test judgment about a situation, not recall. Nothing else requires Canvas: submissions arrive by PR, and anything that does not (reports, presentations) works over whatever your institution uses.
What is UW-specific, and what to substitute¶
Course scaffolding. The delivery layer is a ten-week UW autumn quarter, three 80-minute meetings a week in a named room, with quizzes authored for Canvas and a Veterans Day / Thanksgiving calendar. The 469/569 pairing is a US undergraduate/graduate distinction that may have no equivalent in your system, and the grading weights (including the final project’s 35/30/35 report–repository–presentation split) are set for that pairing and for UW credit rules. A semester adopter has roughly four extra weeks; the usual choice is to slow Chapters 2 and 4 rather than to add material. Replace the schedule page wholesale — it is meant to be thrown away and rewritten — and keep the chapter order.
Data. Most exercises that use real data use US, and specifically Pacific Northwest, data:
- Pacific Northwest seismic waveforms: miniPNW, hosted on a UW server (2.11, 4.3, 4.6), and the UW.RATT station in Puget Sound, fetched live from FDSN (2.8, 2.9, 2.10);
- Pacific Northwest seismic event features from a Zenodo deposit, motivated by Mt Hood (3.3, 3.5, 3.9, 4.1, 4.2) — also the leaderboard’s classification track;
- Cascadia and northern-California GNSS from the Nevada Geodetic Laboratory (1.7, 2.6);
- Mauna Loa CO2 (4.10, and the leaderboard’s forecast diagnostic track);
- US tables and grids: the NCEDC Northern California channel list and an IRIS global catalog (2.3), a Cascade volcanoes GeoJSON (2.2), the xarray tutorial reanalysis field whose domain is North America (2.5), and a Pacific-Northwest shelf subset of a global SST store (5.5).
The rest — everything generated by mlgeo_synth or by the synthetic geochemistry, discharge, and GNSS series, which is roughly half the notebooks — carries no geography and travels unchanged. A handful of pages localize with a word: the “Seattle-like” framings in 2.7 and 3.7 are labels on synthetic data, and the Cascadia and USGS mentions in 6.1 and 7.2 are prose examples.
How to substitute. Change the data, not the lesson. The cheapest swaps keep the same loader and the same physics and only change an identifier: a GNSS station code, an FDSN network and station, a catalog query region. The expensive ones — miniPNW, the Zenodo feature tables — need an equivalent labelled dataset in your region and a fresh look at whether the classes still make sense; budget re-execution and a pedagogical judgment call, not a find-and-replace. If you swap the leaderboard’s classification data, regenerate the hidden split as well (above). Whatever you substitute, keep the sampling rates, the sample counts, and the class balance in the same range, or the training times and the diagnostic figures in the surrounding prose stop matching what students see.
A worked example. The French and Spanish editions of this book localize prose everywhere but data in exactly one place, notebook 1.7: the GNSS lesson pulls a French station for the French edition and a Mexican one for the Spanish edition, from the same global Nevada Geodetic Laboratory archive — same loader, same physics, local ground, notebook re-executed so the outputs are the ones that station actually produces. Everything else in those editions still runs on the US data, deliberately. The two-tier policy behind that choice, and the process for contributing a regional dataset, are in translations/README.md. If you build a regional substitution we would like to hear about it.
Compute and AI-access floor¶
Hardware. An 8 GB RAM laptop with about 10 GB free disk is the baseline. No GPU is required: Chapters 1–3 are lightweight, and Chapter 4’s models are deliberately small and train on CPU in bounded time (minutes per notebook, not hours). Chapter 5.5 streams a remote Zarr store and needs internet plus a few tens of MiB of transfer; everything else runs from local or downloaded-once data. Windows users have a sanctioned path through WSL2 or GitHub Codespaces (1.9).
AI assistant. 1.8 assumes each student has an agentic coding assistant by the end of week one. Free tiers change too fast to enumerate here, but the invariant holds: student and education programs from the major providers (GitHub Copilot’s education tier is the longest-standing) have kept a no-cost agentic option available, and the course needs only one working assistant per student, not a specific product.
The fully free path. Where hosted assistants are unavailable or disallowed, an open-weights model runs locally: OLMo 2 via Ollama needs about 4.5 GB of disk and 8 GB of RAM, and works (slowly) on CPU. Chapter 6 is built so this is never a blocker: every graded notebook there runs offline against recorded transcripts and simulated agents, and the live-model sections are optional.
Restricted networks. For national labs, enclaves, and industry networks that block outbound internet, the “Restricted environments” section of 5.4 gives the four substitutions: package mirrors and offline pixi installs, container transfer through an approved gateway, self-hosted CI, and self-hosted experiment tracking.
Reader pathways¶
Advisor / code-free path (for a supervisor who wants the concepts and the standards without running a notebook): the chapter readmes end to end, plus Chapter 1 including 1.8, 2.1, 3.1, 6.4, and Chapter 7. Prose and figures only; enough to supervise a student through the pipeline, set disclosure expectations, and read their evaluation critically.
Six-week onboarding track (a lab lead training a new hire who already programs): week 1, Chapter 1 through the workbench setup; weeks 2–3, the Chapter 2 core (2.1–2.6 and 2.13); week 4, 3.8 — the cross-validation and leakage material pays for the whole track; week 5, Chapter 5; week 6, 6.3 and 6.4. The new hire ends able to build a defensible dataset, split it honestly, keep work reproducible, and evaluate the AI assistance they will inevitably use.
Standard quarter path: the book in order, Chapters 1–7, with the final project running from week one and the reading arc staged across the term. The undergraduate (469) delivery dilutes expectations, not content: Apply-level rather than Create-level on the synthetics and agent-evaluation outcomes, and assisting rather than leading final projects.
Licenses and attribution¶
The text and figures are CC-BY-4.0; the code, including notebook source, is MIT. Both allow reuse and adaptation, including commercial, with attribution. For reused or adapted material, cite the book and link the source, for example:
Adapted from Machine Learning in the Geosciences (Denolle et al., GeoSMART / University of Washington), https://
github .com /geo -smart /mlgeo -book, CC-BY-4.0.
If you adopt the book for a course, an issue or note on the repository saying so helps us count adoptions and tell you when hidden-seed recipes or datasets change.