This chapter is the only part of the material that is not machine-learning content. It documents the conventions that keep the structure stable while the chapters are filled in.
0.1 Purpose and Scope
A single, complete classical-ML reference — deep enough to learn from the first time, and structured enough to look something up in later.
- The chapter list (top level) is meant to stay stable.
- Sub-sections are meant to be split, renamed and deepened as chapters are written.
- Nothing here is a syllabus to be raced through — it is a set of containers to be filled properly.
0.2 What This Material Covers, and What It Does Not
| In scope | Out of scope |
|---|---|
| Supervised learning on tabular data — regression and classification | Neural networks, backpropagation, CNNs, RNNs, transformers |
| Unsupervised learning — clustering, anomaly detection, association rules | Computer vision and audio |
| The full data pipeline — EDA, preprocessing, feature engineering, selection | Large-scale NLP and language models |
| Evaluation, validation, tuning, interpretability, deployment basics | Reinforcement learning beyond a one-paragraph definition (1.3) |
| The mathematics each algorithm actually needs (Chapter 2) | Distributed / big-data training (Spark, Dask) |
Where a deep-learning method is the honest answer to a problem, the material says so and points at it rather than pretending a classical model is better (1.7).
0.3 Per-Concept Documentation Template
Full style guide: the repository style guide. Summary — every concept is explanation + runnable demo, never one alone:
- A markdown cell with a real explanation — not a one-liner. Use whatever fits best: a small table (metrics,
kernels, encoders, linkage criteria), a short "why it matters" note, a named callout for a nuance or gotcha
(
**Common mistake** — ...), or a contrast with a related/confusable concept. - One or more actual code cells (not fenced
```pythonblocks inside markdown), each minimal and focused on one thing, with an inline#comment on the lines whose output matters. - A concept-specific gotcha or a second angle worth showing gets its own small markdown note + its own small code cell, rather than one giant cell for everything.
Make abstract ideas tangible. For every algorithm the order is fixed:
the objective, written out -> a from-scratch NumPy implementation -> the scikit-learn equivalent
-> an assertion that the two agree
The from-scratch version is what makes the mechanism visible; the scikit-learn version is what gets used everywhere afterwards. Neither one alone is enough.
0.4 Cell Rhythm for Each Concept
The cell sequence when a concept is written up:
Markdown -> explanation (table / prose / "why it matters")
Code -> minimal runnable demo, inline # comments on the lines that matter
Markdown -> (optional) a named gotcha or second angle
Code -> (optional) its own small demo cell
Repeat per concept/sub-concept. Each chapter ends with a scratch cell for ad-hoc experiments — promote anything worth keeping into a proper section instead of leaving it there.
Every chapter's last numbered section is In Practice, and it always has the same three parts:
| Part | What it is |
|---|---|
| A worked case | A concretely stated problem solved end to end with the chapter's tools, on data/*.csv or a bundled dataset |
| When to reach for this — and when not to | A decision table, including the honest rows about when the technique is the wrong choice |
| What goes wrong in production | The failures that appear after deployment rather than during fitting |
For the foundations chapters (1–3) and the theory chapters (9–10), where a case study would be artificial, the first part becomes where this actually shows up in real work instead. The section is a landing, not a summary — it introduces no new techniques.
0.5 Numbering and Insertion Rules
Conventions that avoid renumbering everything every time something is added:
- Chapter numbers are frozen. New major domains are appended, never inserted.
- The last numbered section of every chapter is
In Practice(0.4). New sub-sections are appended before it, never after. - Deeper levels are free-form.
17.3.2,17.3.3etc. can be created and reordered without touching anything above them. - Moving, renaming or removing a section means fixing every pointer that referenced the old location — in other chapters and in the Appendix (§25.1, §25.2) — rather than leaving it dangling.
0.6 Running the Notebooks
Dependencies are managed with uv; pyproject.toml and uv.lock are committed,
so the environment is reproducible exactly.
uv sync # create .venv and install the locked dependency set
uv run jupyter lab # open the notebooks
To re-execute a chapter from a terminal:
uv run jupyter nbconvert --to notebook --execute --inplace 11_linear_regression.ipynb
Every notebook in this repository is committed with its outputs, so plots and tables render on GitHub without running anything. Every stochastic call is seeded (0.7), so re-executing a chapter reproduces the committed output rather than a slightly different one.
0.7 Datasets and Determinism
No notebook downloads anything. Data comes from exactly three places:
| Source | Used for | Examples |
|---|---|---|
sklearn.datasets bundled loaders |
Realistic small problems | load_iris, load_wine, load_breast_cancer, load_diabetes, load_digits |
sklearn.datasets generators |
Controlled shapes where the right answer is known | make_classification, make_regression, make_blobs, make_moons, make_circles |
data/ in this repository |
Messy realistic tabular data for Chapters 4–6 | customers.csv, transactions.csv |
Determinism. Every split, generator, resampler, initializer and optimizer that can take a seed is given
one — the constant RANDOM_STATE = 42 is defined at the top of each chapter that needs it. Two consequences:
a committed output can be trusted as the output the code actually produced, and any difference on re-execution
is a real change, not noise.
0.8 File Layout
00_index.ipynb this file — Chapter 0 conventions, Chapter 25 Appendix
NN_<slug>.ipynb one notebook per chapter, 01–24
CLAUDE.md the full style guide
README.md repository overview and chapter table
pyproject.toml dependency declaration (uv)
uv.lock the exact locked dependency set
data/ small CSVs used by Chapters 4–6
In-notebook see also pointers (e.g. "see 8.3") refer to a section number, not a file path; resolve them
by chapter number to the matching NN_*.ipynb.
0.9 Reading Order
The chapters are written to be read in order — each one assumes the vocabulary of the ones before it. Two useful shortcuts for a reader who already knows some of this:
- Already comfortable with NumPy/pandas and the maths? Start at Chapter 4. Chapters 2 and 3 exist to be referred back to, not necessarily read first.
- Only want a specific algorithm? Chapters 11–21 are individually readable, but each one reports its results using Chapter 8's metrics and reasons about fit using Chapter 9's vocabulary. Read those two first.
Chapters 22–24 are the ones that turn a working notebook into a trustworthy result; they are the easiest to skip and the most expensive to have skipped.