Anomaly Detection Toolkit

A comprehensive Python library for detecting anomalies in time series and multivariate data using multiple detection methods including statistical, machine learning, and deep learning approaches.

📚 Full Documentation

Features

• Statistical Methods: Z-score, IQR, seasonal baseline detection
• Machine Learning: Isolation Forest, Local Outlier Factor (LOF), Robust Covariance
• Wavelet Methods: Wavelet decomposition and denoising for time series
• Deep Learning: LSTM and PyTorch autoencoders for anomaly detection
• Ensemble Methods: Voting and score combination ensembles
• Easy to Use: Scikit-learn compatible API
• Well Documented: Comprehensive docstrings and examples

Installation

Basic Installation

pip install anomaly-detection-toolkit

With Deep Learning Support

For LSTM and PyTorch autoencoders:

pip install anomaly-detection-toolkit[deep]

Development Installation

git clone https://github.com/kylejones200/anomaly-detection-toolkit.git
cd anomaly-detection-toolkit
pip install -e ".[deep]"

Building Documentation

pip install -e ".[docs]"
cd docs
make html

Quick Start

Statistical Methods

from anomaly_detection_toolkit import ZScoreDetector, IQROutlierDetector
import numpy as np

# Generate sample data
data = np.random.randn(1000)
data[100:105] += 5  # Inject anomalies

# Z-score detector
detector = ZScoreDetector(n_std=3.0)
detector.fit(data)
predictions, scores = detector.fit_predict(data)

print(f"Anomalies detected: {(predictions == -1).sum()}")

Machine Learning Methods

from anomaly_detection_toolkit import IsolationForestDetector, LOFDetector
import pandas as pd

# Load your data
df = pd.read_csv('your_data.csv')
features = ['feature1', 'feature2', 'feature3']
X = df[features]

# Isolation Forest
iso_detector = IsolationForestDetector(contamination=0.05, n_estimators=200)
iso_detector.fit(X)
predictions, scores = iso_detector.fit_predict(X)

# Local Outlier Factor
lof_detector = LOFDetector(contamination=0.05, n_neighbors=20)
lof_detector.fit(X)
predictions, scores = lof_detector.fit_predict(X)

Time Series Anomaly Detection

Wavelet-Based Detection

from anomaly_detection_toolkit import WaveletDetector
import pandas as pd

# Time series data
df = pd.read_csv('time_series.csv', parse_dates=['date'])
ts = df['value'].values

# Wavelet detector
wavelet_detector = WaveletDetector(wavelet='db4', threshold_factor=2.5, level=5)
wavelet_detector.fit(ts)
predictions, scores = wavelet_detector.fit_predict(ts)

Seasonal Baseline Detection

from anomaly_detection_toolkit import SeasonalBaselineDetector

# DataFrame with date and value columns
df = pd.DataFrame({
    'date': pd.date_range('2020-01-01', periods=365, freq='D'),
    'value': np.random.randn(365) * 10 + 50
})

# Seasonal baseline detector (weekly seasonality)
seasonal_detector = SeasonalBaselineDetector(seasonality='week', threshold_sigma=2.5)
seasonal_detector.fit(df, date_col='date', value_col='value')
predictions = seasonal_detector.predict(df, date_col='date', value_col='value')

Deep Learning Methods

LSTM Autoencoder

from anomaly_detection_toolkit import LSTMAutoencoderDetector
import numpy as np

# Time series data
ts = np.sin(np.linspace(0, 50, 1000)) + np.random.randn(1000) * 0.1
ts[450:460] += 3  # Inject anomalies

# LSTM autoencoder
lstm_detector = LSTMAutoencoderDetector(
    window_size=20,
    lstm_units=[32, 16],
    epochs=50,
    threshold_std=3.0
)
lstm_detector.fit(ts)
predictions, scores = lstm_detector.fit_predict(ts)

PyTorch Autoencoder

from anomaly_detection_toolkit import PyTorchAutoencoderDetector

# PyTorch autoencoder
pytorch_detector = PyTorchAutoencoderDetector(
    window_size=24,
    hidden_dims=[64, 16, 4],
    epochs=200,
    threshold_std=3.0
)
pytorch_detector.fit(ts)
predictions, scores = pytorch_detector.fit_predict(ts)

Ensemble Methods

from anomaly_detection_toolkit import (
    IsolationForestDetector,
    LOFDetector,
    RobustCovarianceDetector,
    VotingEnsemble
)

# Create multiple detectors
detectors = [
    IsolationForestDetector(contamination=0.05),
    LOFDetector(contamination=0.05),
    RobustCovarianceDetector(contamination=0.05)
]

# Voting ensemble (flags if 2+ detectors agree)
ensemble = VotingEnsemble(detectors, voting_threshold=2)
ensemble.fit(X)
predictions, scores = ensemble.fit_predict(X)

API Reference

Statistical Methods

• ZScoreDetector: Z-score based anomaly detection
• IQROutlierDetector: Interquartile Range (IQR) based outlier detection
• SeasonalBaselineDetector: Seasonal baseline anomaly detection for time series

Machine Learning Methods

• IsolationForestDetector: Isolation Forest anomaly detection
• LOFDetector: Local Outlier Factor (LOF) anomaly detection
• RobustCovarianceDetector: Robust Covariance (Elliptic Envelope) anomaly detection

Wavelet Methods

• WaveletDetector: Wavelet-based anomaly detection for time series
• WaveletDenoiser: Wavelet-based signal denoising

Deep Learning Methods

• LSTMAutoencoderDetector: LSTM autoencoder-based anomaly detection (requires TensorFlow/Keras)
• PyTorchAutoencoderDetector: PyTorch autoencoder-based anomaly detection (requires PyTorch)

Ensemble Methods

• VotingEnsemble: Voting ensemble that combines predictions from multiple detectors
• EnsembleDetector: General ensemble detector with customizable combination methods

Examples

See the examples/ directory for complete examples:

• examples/statistical_example.py: Statistical methods
• examples/ml_example.py: Machine learning methods
• examples/time_series_example.py: Time series anomaly detection
• examples/ensemble_example.py: Ensemble methods

Development

Setting Up Pre-commit Hooks

This project uses pre-commit hooks to ensure code quality before commits and pushes:

# Install pre-commit hooks
./setup-pre-commit.sh

# Or manually:
pip install pre-commit
pre-commit install
pre-commit install --hook-type pre-push

The pre-push hooks will automatically:

• Check code formatting (Black)
• Sort imports (isort)
• Lint code (flake8)
• Type check (mypy)
• Security scan (bandit)
• Run tests (pytest)

To run checks manually:

pre-commit run --all-files

Contributing

Contributions are welcome! Please feel free to submit a Pull Request.

1. Fork the repository
2. Create your feature branch (git checkout -b feature/AmazingFeature)
3. Commit your changes (git commit -m 'Add some AmazingFeature')
4. Push to the branch (git push origin feature/AmazingFeature)
5. Open a Pull Request

License

This project is licensed under the MIT License - see the LICENSE file for details.

Citation

If you use this library in your research, please cite:

@software{anomaly_detection_toolkit,
  title={Anomaly Detection Toolkit},
  author={Kyle Jones},
  year={2025},
  url={https://github.com/kylejones200/anomaly-detection-toolkit}
}

Acknowledgments

• Built with scikit-learn, PyWavelets, and other excellent open-source libraries
• Inspired by various anomaly detection research and implementations

Support

For issues, questions, or contributions, please open an issue on GitHub.