An educational collection of anomaly-detection implementations, paper notes, and reproducible experiments originally written and maintained by MaXiao.
This repository is being revived incrementally in 2026. The goal is to improve documentation, reproducibility, and compatibility without replacing the original handwritten work with a wholesale rewrite. Historical scripts and explanations remain available while tested interfaces are introduced in small, reviewable steps.
Maintenance status: revival in progress. Most current scripts are historical learning or research implementations, not a production-ready library. See the roadmap before relying on an API.
The current repository focuses mainly on point anomalies in tabular data. It covers several complementary ideas:
- isolation-based detection;
- global and local distance or density methods;
- PCA and Kernel PCA reconstruction error;
- principal-component deviation methods;
- learning with partially observed anomalies;
- positive-unlabeled learning;
- KADOA, an experimental variation proposed by the repository author.
Time-series, image, graph, and streaming anomaly detection are outside the first revival scope.
| Learning setting | Method | Current form | Status |
|---|---|---|---|
| Unsupervised | Isolation Forest | Paper notes and a scikit-learn example | Legacy |
| Unsupervised | PCA / Kernel PCA reconstruction error | Handwritten implementations and experiments | Legacy |
| Unsupervised | RobustPCC | Paper-inspired implementation | Experimental |
| Unsupervised | Mahalanobis distance | Handwritten implementation and equivalence experiment | Legacy |
| Unsupervised | Local Outlier Factor | Paper notes and a scikit-learn example | Legacy |
| Semi-supervised | ADOA | Paper-inspired implementation | Experimental |
| Semi-supervised | KADOA | Author-proposed experimental variation | Experimental |
| Semi-supervised | Positive-Unlabeled Learning | Research implementations and notes | Experimental |
Legacy means that the material is preserved for learning and historical reference but is not yet covered by the planned compatibility and continuous-integration matrix.
Experimental means that the implementation or empirical conclusion is preliminary. It should not be treated as a generally validated performance claim.
The repository does not yet provide a locked environment or an installable package. To run the Mahalanobis equivalence example from a fresh clone:
git clone https://github.com/Albertsr/Anomaly-Detection.git
cd Anomaly-Detection
python -m pip install numpy pandas scikit-learn
python "UnSupervised-Mahalanobis Distance/verify_mahal_equivalence.py"Dependencies vary by module. Some semi-supervised comparison scripts also require optional libraries such as LightGBM or XGBoost. A reproducible dependency definition and tested package interface are planned for the next maintenance phase.
The existing figures and comparisons are educational experiments, not universal rankings:
- when ground-truth labels are available, metrics such as F1 or ROC AUC can evaluate predictions under the stated experimental setup;
- when labels are unavailable, agreement with Isolation Forest is only detector agreement, not proof of correctness;
- results from a small set of synthetic datasets should not be generalized to all anomaly types or data domains;
- thresholds, contamination assumptions, random seeds, and data construction can materially change the outcome.
The benchmark revival will make these boundaries explicit and add public labeled datasets, repeated seeds, runtime measurements, and uncertainty reporting.
The following figures preserve the original comparison outputs for ten synthetic datasets. The data-generation settings, dependency versions, hardware, and complete evaluation protocol have not yet been fully reconstructed, so treat them as historical snapshots—not current benchmarks or universal algorithm rankings.
Historical F1 snapshot across ten synthetic datasets. Variation across datasets is the intended reading; individual levels should not be treated as a general ranking of the methods.
View the corresponding historical runtime snapshot
Runtime depends on the original hardware, software environment, parameters, and implementation details. These values should not be used as current performance estimates.
The historical figures include linear- and RBF-kernel One-Class SVM configurations, but the code revision that generated those two series has not yet been reconstructed. A dedicated method page, tested baseline, and stable repository interface for One-Class SVM remain planned.
KADOA is presented in this repository as an original experimental idea by MaXiao. It adapts the ADOA workflow by replacing its Isolation Forest component with Kernel PCA reconstruction error while retaining the broader clustering-and-weighting idea.
KADOA has not been described here as a peer-reviewed standalone method. The published repository experiment is preliminary and does not establish universal superiority over ADOA. If you use or discuss KADOA, please describe it as an experimental repository method, acknowledge its relationship to ADOA, and cite this repository using CITATION.cff.
- Preserve the original Git history, explanations, and recognizable implementation style.
- Add characterization tests before changing algorithm behavior.
- Keep historical paths available while a stable package API is introduced.
- Separate documentation, compatibility fixes, API extraction, benchmarks, and new algorithms into reviewable changes.
- Prefer scoped empirical claims over broad statements of superiority.
- Add a small number of representative methods with explanations and tests, rather than maximizing the algorithm count.
The first planned additions are One-Class SVM and ECOD. Autoencoder, Deep SVDD, and Deep SAD are later candidates after the classical benchmark is stable.
Bug reports, reproducibility notes, documentation corrections, and carefully scoped algorithm contributions are welcome through GitHub Issues.
Please include the Python and dependency versions, the script or method used, a minimal input example, and the observed traceback or result.
Use the repository citation metadata in CITATION.cff. A DOI, release version, and publication reference have not been claimed.
This project is licensed under the MIT License.