ethen8181/machine-learning: a notebook collection that implements algorithms from scratch and then shows the library version

What the repository is for, and who it is not for

The README states the goal directly: introduce machine learning content in Jupyter Notebook format, striking a balance between mathematical notation, educational implementation from scratch using numpy, numba, scipy, pandas and matplotlib, and open-source library usage such as scikit-learn, fasttext, huggingface, onnx, xgboost, lightgbm, pytorch, keras, tensorflow, gensim, h2o, ortools and ray tune. That sentence is the whole product description. The repository is a personal learning log that was kept public, and it is described as continuously updated rather than finished.

The audience follows from that. If you are preparing a lecture on byte pair encoding and want a worked implementation next to a sentencepiece walkthrough, the subword notebook is aimed at you. If you need a maintained library that tokenizes text in production, nothing here is packaged for that. There is no setup.py, no pyproject.toml mentioned, no importable module name, and no release. The README badge shows Python 3.10, 3.9 and 3.8, which tells you the author checked those interpreters at some point, not that every notebook in the tree runs on all three.

The topics list is broad in a way that is itself informative. Deep learning, model deployment, operation research, reinforcement learning, advertising, search, time series, A/B tests, model selection, dimensionality reduction, recommender systems, trees, clustering, text classification, regularization, networkx, association rules, big data, genetic algorithms and unbalanced data all appear as sections. Breadth like that usually means shallow coverage somewhere. In this case the shallow spots are the categories with one or two entries, and the deep spots are the ones with several notebooks that build on each other, such as the RNN and seq2seq sequences.

The from-scratch-then-library pattern, and why it changes how you read the notebooks

Look at the deep learning listing and the structure repeats. Softmax regression appears twice: once from scratch, once as a TensorFlow hello world. Vanilla RNN and LSTM appear as TensorFlow notebooks, and then an RNN and LSTM PyTorch hello world follows. Word2vec with skipgram and negative sampling is done in Gensim. Byte pair encoding is implemented from scratch and then sentencepiece is walked through. Multi-label text classification uses fasttext with Huggingface tokenizers. Product quantization for model compression and approximate nearest neighbour search with navigable small world both sit under the multi-label heading, which is an odd filing choice but tells you they came out of the same project.

That pairing is the actual mechanism of the repository. A notebook is not a tutorial that hides the maths behind an estimator call, and it is not a pure derivation with no runnable code. It is both, in sequence, so you can read the from-scratch version to see what the update rule or the data structure actually is, then read the library version to see what the production-shaped call looks like. The cost is duplication: two notebooks to keep in sync, and the from-scratch one will not track upstream API changes at all.

The library spread is the other half of the picture. TensorFlow, PyTorch, Keras, DGL, fasttext, Gensim, Huggingface, onnx, xgboost, lightgbm, h2o, ortools and ray tune are all named in the README. A repository that touches that many frameworks cannot keep every notebook current. Expect the older TensorFlow notebooks to be the first to break, and the PyTorch seq2seq and transformer notebooks to be closer to runnable, purely because PyTorch has changed its training loop conventions less aggressively. That is an inference from the framework list, not a measurement.

Getting a notebook running: nbviewer first, clone second

The README gives two links per notebook: an nbviewer URL and a rendered HTML page hosted on GitHub Pages. For example, the softmax from-scratch notebook is at nbviewer.jupyter.org/github/ethen8181/machine-learning/blob/master/deep_learning/softmax.ipynb, and the rendered version is at ethen8181.github.io/machine-learning/deep_learning/softmax.html. The HTML page is the cheapest way to check whether a notebook covers what you need before you install anything, because it renders the stored outputs. Note the caveat: those outputs were produced by the author on the author's machine, so they show what the notebook did, not what it will do for you.

To run one yourself, the standard path applies. Clone the repository, create an environment, install the libraries that particular notebook imports, and launch Jupyter. The README does not list a requirements file or a conda environment file, so there is no single install command to quote. The badge names Python 3.10, 3.9 and 3.8 as supported interpreters. The notebook path in the URL is the path in the clone, so deep_learning/softmax.ipynb and deep_learning/seq2seq/torch_transformer.ipynb are where you would point Jupyter.

This is the weakest part of the repository and worth stating plainly. Dependency installation is per notebook and undocumented. A notebook that imports DGL, torchtext and Huggingface Datasets together will need three separate installs at versions you have to guess, and torchtext in particular has had breaking releases. If you are evaluating this repository for a team, the honest workflow is: read the rendered HTML, decide the notebook is worth it, then budget time for dependency archaeology before you budget time for the content itself.

Where the collection stops being the right tool

The failure mode is not a bug, it is the format. A notebook is a poor unit of reuse. There is no function you can import, no test suite described in the README, and no changelog. When the author updates a notebook, the diff is a JSON file full of cell outputs, which makes review unpleasant. When you want the from-scratch softmax in your own code, you copy cells, and you inherit whatever global state those cells assumed.

The second limitation is scope drift by topic. The README's own table of contents includes a clustering section and a clustering old section, and an operation research section alongside reinforcement learning. Sections like these read as an archive of past interests rather than a curriculum. If you arrive looking for a guided path from regression to neural networks, you will not find one. You will find a list. The ordering in the README is a table of contents generated from headings, not a syllabus.

Third, the repository is a single-author project with no releases retrieved. There is no version to pin, so there is no reproducible snapshot. If you cite a notebook in a course, cite the commit hash you read, because master will keep moving. That is a normal property of a learning log and an unacceptable property of a dependency, which is the distinction that decides whether this repository is for you.

How this differs from scikit-learn's own documentation and from a course

The obvious alternative for the classical material is scikit-learn's user guide and example gallery. The difference in approach is real. Scikit-learn documents the library's behaviour: what the estimator does, which parameters exist, what the API guarantees. This repository documents the author's understanding, which means it shows the derivation and a hand-written implementation before it shows the estimator call. If you want to know which solver to pass and why, scikit-learn is the reference. If you want to see the update rule written out and then see the same thing as three lines of library code, the notebook pairing here does something scikit-learn's gallery generally does not attempt.

For deep learning the alternative is a structured course or a textbook with exercises. Those give you a sequence and graded difficulty. This repository gives you a menu, and the menu is uneven: the seq2seq and transformer notebooks sit next to a softmax hello world, with no indication of which to read first. The trade is depth in specific places against coherence across the whole. For someone who already knows what they want to learn, the menu is fine and the depth is the point. For someone starting from zero, it is the wrong shape.

A third comparison point is the library documentation for the specific frameworks named, PyTorch tutorials, Huggingface course material, DGL examples. Those are maintained by the projects themselves and track their own API changes. This repository cannot, and does not claim to.

Maintenance, licence and the cost of keeping a clone

The repository is MIT licensed, which is permissive and imposes essentially no condition beyond keeping the copyright notice when you redistribute substantial portions. For a notebook collection that people mostly read and copy snippets from, that is the right licence. It is not legal advice, and if you plan to lift a substantial portion of a notebook into a course or a product, read the LICENSE file in the repository rather than this paragraph.

The maintenance cost falls mostly on the author, and it is the cost of breadth. Every framework named in the README, from TensorFlow through ortools to ray tune, releases on its own cadence. A notebook that pins nothing will drift. The last push recorded is 2026-07-10, so the repository is active rather than abandoned, but active is not the same as verified across the whole tree. Nothing in the material says which notebooks were re-run at that date.

Your own cost is smaller and mostly one-off: clone, install, run, and then decide whether to keep the environment. If you only need one notebook, the rendered HTML at ethen8181.github.io/machine-learning/ plus the nbviewer link may be enough, and you never install anything. That is the cheapest way to consume this repository and, for most readers, the correct one.

Who should clone it and what to check before you do

Clone it if you learn by reading an implementation and then seeing the library version of the same idea, and if you already have a specific algorithm in mind. The seq2seq sequence, the transformer notebook, the byte pair encoding notebook and the word2vec notebook are the entries where the from-scratch-then-library pattern looks most developed, based on how the README presents them with multiple linked notebooks each.

Do not clone it if you need a maintained dependency, a guided curriculum, or a single install command. None of those exist here. Do not clone it if you cannot afford to debug an environment, because the README does not document one.

Before you commit time, open the rendered HTML page for the notebook you want and check two things: whether the stored outputs match the code in the cells, and which framework versions the imports imply. Then check the notebook's imports against the Python version you intend to use, given the README badge lists 3.8 through 3.10. If the notebook predates the current API of its framework, the from-scratch half is still worth reading and the library half is not. That split is the practical test, and it is the reason this repository works better as a reference you consult than as a project you adopt.

Editorial conclusion

Adopt it as a reading and teaching companion if you already know which algorithm you want to understand, and start by opening the nbviewer link for that notebook before cloning anything. Do not adopt it as a dependency: there is no package, no API surface and no versioned release to pin. Verify first that the notebook you care about still runs on your Python version, because the README badge lists 3.8, 3.9 and 3.10 while the notebooks span TensorFlow, PyTorch, DGL, fasttext, onnx and ortools, and each of those moves on its own schedule.

Official sources

1. ethen8181/machine-learning on GitHub
2. Issues
3. License: MIT
4. README