Machine Learning Refined: A Textbook Repository Where the Notebooks Are the Point

A textbook repository, not a package you install

The name suggests a code project. The README describes something else: a set of resources tied to the second edition of Machine Learning Refined, a university textbook. The repository holds chapter PDFs, Jupyter notebooks under notes, exercises, and lecture slides in presentations. There is no library to import, no package on an index, and no API surface. If you arrived expecting a framework, the README's own framing will correct you quickly. The stated prerequisites are a basic understanding of Python and matrix maths, which is the level the material is pitched at. The intended readers are named explicitly: independent learners working toward a foundation in machine learning, and instructors who want to use the text in a course. Instructors get a separate path through the repository, including PPTX slides per section and downloadable exercise wrappers and datasets. That split is the clearest signal of who the project is for. It is coursework infrastructure with a book attached, and the value sits in the ordering of the material rather than in any single artefact.

The three-question pedagogy and what it excludes

The README states the pedagogical position directly. Mastery of a topic is reached, in the authors' view, only when three questions can be answered affirmatively: can you describe the idea with a simple picture, can you express that intuition in mathematical notation and derive the models and cost functions, and can you code the derivation in Python without high-level libraries. That third condition is the one with consequences. The notes build models from scratch rather than calling into an existing estimator API, which is why the topics list includes numpy alongside machine-learning and deep-learning. The cost of this approach is that nothing here transfers directly into a production pipeline. A model written for a chapter on zero-order methods exists to make a derivation visible, not to handle messy input, missing values, or scale. Read the repository as a place to learn why an optimiser behaves the way it does, and the absence of convenience wrappers stops being a complaint.

How the material is organised across four directories

The README points to four locations. chapter_pdfs holds the book chapters for download, with a 2nd_ed subdirectory referenced in the chapter links. notes holds the source Jupyter notebooks, described as drafts of the second edition released as notebooks, and the README notes that the final draft expands on this content and is available as a PDF. That sentence matters: the notebooks and the PDF are not the same artefact, and the README itself says the final draft goes further. exercises holds exercise wrappers and datasets. presentations holds PPTX slides associated with each section. The chapter listing in the README shows the granularity: Chapter 2, on zero-order optimisation techniques, is broken into sections 2.1 through 2.6, each with its own notebook link. The section titles run from an introduction through the zero-order optimality condition, global methods, local methods, random search, and coordinate search and descent. That is a full arc through one family of methods before the next chapter begins, and it is the structure you are adopting when you work through the notes in order.

Running a notebook: Colab links versus a local install

The README offers two routes. The first is Colab. Each section link in the chapter listing points at a notebook path on the main branch, for example notes/2_Zero_order_methods/2_1_Introduction.ipynb, and carries a Colab badge that opens the same file in a hosted session. For a reader who wants to see a derivation run without setting up an environment, that is the shortest path, and it requires no local Python at all. The second route is local, and the README directs you to its installation instructions section for software installation and dependencies. The repository does not publish an explicit dependency list in the material available here, so the practical step is to read that section of the README and the notebook imports before assuming a specific environment will work. The notebooks are the source of truth for what each section needs. If you are setting up a course, the Colab route removes the support burden of students installing numpy and the notebook stack on their own machines, at the cost of depending on a hosted service for every session.

Where the repository stops being the right tool

Three limits are visible from the material. First, the notebooks are described as early drafts. The README says the final draft significantly expands on that content and is available as a PDF, so a reader who works only from the notebooks is working from a version the authors themselves characterise as incomplete relative to the book. If you want the full treatment, the PDF is the artefact to read and the notebooks are the interactive companion. Second, there is no maintenance story for the code. The repository is not archived, and the most recent release listed is v1.5 from December 2025, described as repository organisation and PDF access improvements. That release title is about structure and access, not about model code, which is consistent with a teaching resource that is finished rather than evolving. Third, the licence is unresolved. The repository reports NOASSERTION, and nothing in the README states terms for reuse. For an individual learner this rarely matters. For an instructor who wants to redistribute the notebooks or the slides inside a course platform, it is the first thing to settle, and the README's own instruction is to file an issue in the repository rather than to assume an answer.

Compared with scikit-learn's own documentation path

The obvious alternative for someone learning this material is the scikit-learn user guide and its examples. The difference is one of direction. scikit-learn's material starts from the estimator interface: you construct a model, call fit, call predict, and the guide explains the parameters and the trade-offs between them. The derivation behind the solver is documented but is not the thing you build. Machine Learning Refined inverts that. The README's third condition, coding derivations without high-level libraries, means the numpy implementation of the cost function and its gradient is the exercise, and the optimiser is something you write rather than select. If your goal is to ship a model this week, the scikit-learn path is shorter and the code you write transfers. If your goal is to understand why a random search and a coordinate descent method behave differently on the same cost surface, the notebook sequence in Chapter 2 has no equivalent in an API reference, because an API reference has no reason to make you implement both.

Upgrade cost, licence exposure and what to check first

Upgrade cost here is not a dependency problem. There is no version to pin and no breaking change to track. The cost is editorial: the PDFs and the notebooks can diverge, and the README already flags that the final draft expands on the released notebooks. If you build a syllabus around section numbers, verify those sections against the current chapter_pdfs rather than against the notebook list. The v1.5 release notes describe organisation and PDF access changes, which is the kind of release that can move files without changing content, so any link you have bookmarked to a notebook path is worth re-checking against the repository tree. On licensing, the NOASSERTION value means the repository does not declare a licence that automated tooling can identify. That is not the same as having no terms, and it is not the same as being permissively licensed. Treat redistribution, including putting the slides or notebooks on an internal course site, as something to confirm with the authors through the issue tracker before you do it. A physical copy of the text is sold through retailers, and instructors at verified institutions can request an examination copy through the Cambridge University Press page linked in the README, which is the sanctioned route for course adoption.

Editorial conclusion

Adopt this if you are teaching a course or working through classic machine learning and optimisation by hand, and you want the derivations and the numpy code in the same place. Do not adopt it if you need a maintained library, a production dependency, or code you can ship. Before relying on it, open the chapter_pdfs and notes directories to confirm the material matches the edition you intend to use, and resolve the licence question with the authors, because the repository reports NOASSERTION and nothing here tells you what you may redistribute.

Official sources

1. Issues
2. neonwatty/machine-learning-refined on GitHub
3. Project website
4. README
5. Releases