# Anomaly Detection Tutorials

> A structured curriculum of 14+ runnable Jupyter notebooks teaching time-series anomaly detection from statistical foundations to state-of-the-art deep learning models.

Anomaly Detection Tutorials is an open-source GitHub repository by Julien Audibert that provides a structured, progressive curriculum for learning time-series anomaly detection. The project covers everything from classical statistical methods like z-scores to modern deep learning architectures, with every notebook designed to run top-to-bottom on CPU in minutes, seeded and reproducible. Originally started in 2016 as one of the early autoencoder anomaly detection tutorials, the repo was rebuilt from scratch in 2026 with a higher bar for evaluation rigor.

## What It Is

This is a self-contained educational resource — a sequence of Jupyter notebooks that teaches anomaly detection as a coherent discipline rather than a collection of isolated techniques. The core differentiator, as the README states, is the focus on honest evaluation: every method is paired with its failure modes, not just its wins, and results are measured with ground-truth labels where they exist. The project targets data scientists, ML engineers, and researchers who want a principled path from beginner to production-ready methods.

## The Curriculum Structure

The repo organizes 14 available notebooks (plus one planned case study) in a recommended reading order, each of which also stands alone:

- **Foundations** (01): z-scores, moving statistics, STL residuals
- **Classic ML** (02): Isolation Forest, One-Class SVM, LOF
- **Autoencoders** (03): reconstruction error as an anomaly signal
- **USAD** (04): adversarially trained autoencoders (KDD 2020)
- **Matrix Profile** (05): training-free anomaly detection
- **Forecasting-based detection** (06): predict-then-surprise approach
- **Probabilistic reconstruction** (07): VAEs, Donut, and likelihood
- **TadGAN** (08): GAN-based detection and critic limitations
- **Graph Neural Networks** (09): multi-sensor dependency learning
- **Transformers** (10): reconstruction cheating problem
- **Self-supervised representations** (11): detecting without reconstructing
- **Streaming detection** (12): Robust Random Cut Forest
- **Foundation models** (13): zero-shot detection with Chronos/MOMENT
- **Evaluation done right** (14): the point-adjust trap and alternatives

## Design Philosophy and Tradeoffs

The project is explicit about what most anomaly detection material skips: evaluation methodology. Notebook 14 specifically addresses the "point-adjust trap," a common evaluation pitfall that inflates reported performance. The consistent colorblind-safe visual language and shared `adtuto` package (holding plotting themes, datasets, and windowing helpers) keep individual notebooks focused on their methods rather than boilerplate. The tradeoff is that this is a learning resource, not a production library — it provides understanding and reproducible experiments, not a plug-and-play API.

## Setup Path

Users can clone the repo and run locally using `uv` for environment management, or open any notebook directly in Google Colab via the badge links in the curriculum table. The Colab path requires no local setup — the first cell installs dependencies automatically. Local setup requires Python 3.10+ and uses `uv venv` with an editable install of the `adtuto` package.

## Update: Rebuilt in 2026

The README documents that the repo started in 2016 and reached 190 stars in its first life before being rebuilt from scratch in 2026. The rebuild retained the original mission but applied ten years of hindsight and significantly raised the bar for evaluation rigor. As of the last push in August 2026, all 14 planned notebooks are marked available, with one case study (detecting silent regressions in LLM telemetry) listed as planned. The repository is MIT-licensed and actively maintained under the GitHub Actions CI pipeline.

## Features
- 14 runnable Jupyter notebooks covering z-scores to deep learning
- Runs on CPU in minutes, seeded and reproducible
- Google Colab badges for zero-setup access
- Honest evaluation with ground-truth labels and failure mode analysis
- Notebook 14 addresses the point-adjust evaluation trap
- Shared adtuto package for plotting, datasets, and windowing helpers
- Consistent colorblind-safe visual language
- Covers Isolation Forest, One-Class SVM, LOF, Autoencoders, VAEs, TadGAN, GNNs, Transformers, RRCF, and foundation models
- MIT licensed and open source

## Integrations
Google Colab, Jupyter Lab, Python 3.10+, uv (package manager), GitHub Actions CI

## Platforms
WEB, API, CLI

## Pricing
Open Source

## Version
main

## Links
- Website: https://github.com/JulienAu/anomaly-detection-tutorials
- Repository: https://github.com/JulienAu/anomaly-detection-tutorials
- EveryDev.ai: https://www.everydev.ai/tools/anomaly-detection-tutorials