tsanomaly 0.1.0

A Python library for autonomous, explainable, real-time anomaly detection on time-series metrics

tsanomaly

A Python library for autonomous, explainable, real-time anomaly detection on time-series metrics.

pip install tsanomaly

Why tsanomaly

• Zero configuration - seasonality, model choice, and the expected-range "envelope" are learned per metric.
• Calibrated - envelope coverage is enforced by adaptive conformal inference; tail rarity comes from extreme value theory, not Gaussian assumptions.
• Comparable scores - magnitude × duration × persistence, judged against the metric's own history: a 90 means the same rarity on any metric.
• Regime-aware - a permanent level shift becomes one "new normal" finding and a re-anchored baseline, not endless alerts.
• Incidents - concurrent anomalies group into one finding, ordered by who moved first: the root-cause hint.
• Real-time - O(1) streaming updates, out-of-order tolerance, alert lifecycle with pluggable sinks, stall detection, checkpoint/restore.
• Explainable - every anomaly carries its expected range, score breakdown, provenance, and a counterfactual.

Quickstart

import pandas as pd
import tsanomaly as tsa

# any long frame with metric / timestamp / value columns
history = pd.read_csv("payments.csv", parse_dates=["ts"])

det = tsa.Detector.auto()
det.fit(history)                      # learn normal, per metric
result = det.detect(new_data)         # scored, explained anomalies

print(result.summary())
for anomaly in result.alerts(min_score=70):
    print(anomaly.explain().to_text())

Output (NYC taxi ridership around the January 2015 blizzard):

learned seasonality: day (strength 0.67), week (strength 0.84)

`nyc.taxi.passengers` dropped to 7076 (expected 18060 to 25606)
    for 33.0 h starting 2014-11-27 05:30 UTC - score 100.   # Thanksgiving
`nyc.taxi.passengers` spiked to 23848 (expected 15488 to 19792)
    for 6.0 h starting 2015-01-18 09:30 UTC - score 100.    # MLK weekend
`nyc.taxi.passengers` dropped to 570 (expected 15629 to 22110)
    for 39.0 h starting 2015-01-26 11:30 UTC - score 100.   # blizzard travel ban

Examples

• quickstart.py
• cnc_vibration.py
• streaming_alerts.py
• traffic_incident.py
• root_cause.py
• gallery.py
• adaptive_envelopes.py

Documentation

• Usage guide - data formats, batch & streaming APIs, configuration, persistence, incidents, events, feedback, evaluation utilities.
• Architecture - the full pipeline.
• Examples

How it works

 samples --> [ clean ] --> [ profile ] --> [ seasonality ] --> [ baseline ]
                                                                   |
                       expected value + self-calibrating envelope <--+
                                                                   |
             [ episodes ] <-- outside the envelope? <----------------+
                  |
                  +--> [ regime check ]  "new normal" vs anomaly
                  |
                  +--> [ score 0-100 ]   magnitude x duration x persistence
                            |
                            +--> [ incidents ]  related episodes, lead/lag
                            +--> [ explain ]    provenance + counterfactual

For more details, refer to docs/architecture.md.

Acknowledgements

The architecture of tsanomaly - autonomous per-metric baselines, anomaly scoring against a metric's own history, automatic seasonality detection, and condensing concurrent anomalies into incidents - is inspired by the system described in Anodot's published patents:

• US 10,061,632 - System and method for transforming observed metrics into detected and scored anomalies
• US 10,061,677 - Fast automated detection of seasonal patterns in time series data
• US 2016/0210556 A1 - Heuristic inference of topological representation of metric relationships
• US 2020/0233774 A1 - Efficient estimation of high-cardinality time-series models
• US 12,101,343 - Event-based machine learning for a time-series metric

tsanomaly borrows the ideas and implements them with different, modern mechanisms - adaptive conformal calibration, extreme-value tail modeling, Bayesian online changepoint detection, harmonic-mean evidence combination, and effective-signal correction - detailed in docs/architecture.md.

License

Apache-2.0