Metadata-Version: 2.4
Name: madwatch
Version: 0.1.0
Summary: Robust anomaly detection on MAD and the Modified Z-Score, with seasonal baselines
Project-URL: Repository, https://github.com/efekckk/madwatch
Project-URL: Why MAD?, https://efekckk.github.io/blog/why-mad
Author-email: Efecan Küçük <efe.kckk@gmail.com>
License: MIT License
        
        Copyright (c) 2026 Efecan Küçük
        
        Permission is hereby granted, free of charge, to any person obtaining a copy
        of this software and associated documentation files (the "Software"), to deal
        in the Software without restriction, including without limitation the rights
        to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
        copies of the Software, and to permit persons to whom the Software is
        furnished to do so, subject to the following conditions:
        
        The above copyright notice and this permission notice shall be included in all
        copies or substantial portions of the Software.
        
        THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
        IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
        FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
        AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
        LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
        OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
        SOFTWARE.
License-File: LICENSE
Keywords: anomaly-detection,mad,modified-z-score,monitoring,time-series
Classifier: Development Status :: 3 - Alpha
Classifier: Intended Audience :: Developers
Classifier: Intended Audience :: Science/Research
Classifier: License :: OSI Approved :: MIT License
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.10
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: Programming Language :: Python :: 3.13
Classifier: Topic :: Scientific/Engineering :: Information Analysis
Requires-Python: >=3.10
Requires-Dist: numpy<3,>=1.24
Provides-Extra: cli
Requires-Dist: matplotlib>=3.7; extra == 'cli'
Requires-Dist: pandas>=2.0; extra == 'cli'
Provides-Extra: dev
Requires-Dist: matplotlib>=3.7; extra == 'dev'
Requires-Dist: pandas>=2.0; extra == 'dev'
Requires-Dist: pytest>=8; extra == 'dev'
Requires-Dist: ruff>=0.4; extra == 'dev'
Description-Content-Type: text/markdown

# madwatch

[![CI](https://github.com/efekckk/madwatch/actions/workflows/ci.yml/badge.svg)](https://github.com/efekckk/madwatch/actions/workflows/ci.yml)
[![PyPI](https://img.shields.io/pypi/v/madwatch)](https://pypi.org/project/madwatch/)
[![Python](https://img.shields.io/pypi/pyversions/madwatch)](https://pypi.org/project/madwatch/)
[![License: MIT](https://img.shields.io/badge/License-MIT-green.svg)](LICENSE)

Robust anomaly detection that doesn't panic at paydays.

`madwatch` scores time-series values with the **Modified Z-Score over MAD**
(Median Absolute Deviation) instead of mean/standard deviation. Medians don't
care about your whale transaction: one huge outlier can't inflate the baseline
and mask the next real anomaly.

![demo](docs/assets/demo.png)

## Install

```bash
pip install madwatch        # core, numpy only
pip install 'madwatch[cli]' # + CLI, pandas, matplotlib
```

## Quickstart

```python
from madwatch import RollingDetector

det = RollingDetector(window=40, threshold=3.5, min_samples=10)
for value in stream:
    score = det.update(value)
    if score.is_anomaly:
        alert(value, score.z)
```

## Why MAD?

Standard deviation has a design flaw for anomaly detection: the anomaly you are
trying to catch is *inside* the calculation. One spike inflates sigma, the
threshold stretches, and the next three real anomalies walk through undetected.
MAD is median-based, so a single outlier in the window barely moves the
baseline. The `0.6745` constant makes the score comparable to a classic z-score
on normal data, so the usual "flag at 3.5" rule still reads naturally.

Longer version: [Why MAD instead of standard deviation?](https://efekckk.github.io/blog/why-mad)

## Seasonal baselines

Mondays don't look like Saturdays and 9 AM doesn't look like midnight. Comparing
a value against a global baseline produces false alarms at every weekly rhythm.
`SeasonalBaseline` buckets history by day-of-week and/or hour and scores each
point against its own bucket:

```python
from madwatch import SeasonalBaseline

sb = SeasonalBaseline(granularity="dow_hour").fit(timestamps, values)
z = sb.score(new_timestamps, new_values)
```

In production use on financial streams, this combination cut false positives by
roughly 60% compared to a naive z-score.

## CLI

```bash
madwatch data.csv --column amount --window 40 --threshold 3.5 --plot out.png
madwatch data.csv --column amount --timestamp ts --seasonal dow_hour
```

```
where                        value         z
2026-02-07T12:00:00         512.00      9.41
1 anomalies in 312 points
```

## API

| Name | What it does |
|---|---|
| `mad(x)` | Median Absolute Deviation of an array |
| `modified_zscore(x, scale=0.6745)` | Per-element robust z-score |
| `RollingDetector(window, threshold, min_samples)` | Streaming detection over a trailing window |
| `SeasonalBaseline(granularity)` | Per-bucket (dow/hour) baselines with global fallback |

Behavior notes: constant windows (MAD = 0) score `z = 0`; the detector stays
silent until `min_samples` values have arrived; `NaN` input raises `ValueError`
(the CLI skips NaN rows with a warning).

## Development

```bash
uv venv && uv pip install -e '.[dev]'
pytest
ruff check src tests
```

## License

MIT
