AnomalyKit

Anomaly detection toolkit — a Python library for detecting anomalies in time series and tabular data using statistical methods.

---

Architecture

graph TD
    A[Input Data] --> B[AnomalyDetector]
    B --> C{Detection Method}
    C --> D[Z-Score]
    C --> E[IQR]
    C --> F[Moving Average Deviation]
    C --> G[Isolation Score]
    D --> H[Anomaly Results]
    E --> H
    F --> H
    G --> H
    H --> I[Report Generator]
    I --> J[Summary Report]

Loading

Features

• Z-Score Detection — flag points that deviate beyond a configurable number of standard deviations
• IQR Detection — interquartile-range fencing for robust outlier identification
• Moving Average Deviation — sliding-window smoothing to catch local anomalies in time series
• Isolation Scoring — lightweight isolation-like scoring without full tree ensembles
• Report Generation — structured summaries of detection results
• Pydantic Configuration — type-safe, validated configuration via Pydantic models

Quickstart

Installation

pip install -e .

Usage

import numpy as np
from anomalykit import AnomalyDetector, DetectorConfig

# Generate sample data with anomalies
data = np.random.normal(loc=0, scale=1, size=200)
data[50] = 15.0   # inject anomaly
data[120] = -12.0  # inject anomaly

# Create detector
config = DetectorConfig(z_threshold=3.0, iqr_multiplier=1.5)
detector = AnomalyDetector(config=config)

# Fit on training data and detect
detector.fit(data[:100])
results = detector.detect(data)
print(results)

# Or use individual methods
z_anomalies = detector.z_score_detect(data, threshold=3.0)
iqr_anomalies = detector.iqr_detect(data, multiplier=1.5)
ma_anomalies = detector.moving_avg_detect(data, window=10, threshold=3.0)
scores = detector.isolation_score(data)

# Get anomaly indices and generate a report
anomalies = detector.get_anomalies(data)
report = detector.generate_report(results)
print(report)

Configuration

AnomalyKit uses Pydantic for configuration. Set defaults via DetectorConfig or environment variables (see .env.example).

from anomalykit import DetectorConfig

config = DetectorConfig(
    z_threshold=2.5,
    iqr_multiplier=1.5,
    moving_avg_window=10,
    moving_avg_threshold=3.0,
)

Development

make install    # install in editable mode with dev dependencies
make test       # run tests
make lint       # run linter
make format     # auto-format code

Contributing

See CONTRIBUTING.md for guidelines.

---

Inspired by anomaly detection and observability trends.

---

Built by Officethree Technologies | Made with love and AI