Metadata-Version: 2.5
Name: pyharbinger
Version: 0.1.0
Summary: A unified time series event detection framework (Python port of the R harbinger framework)
Project-URL: Homepage, https://github.com/cefet-rj-dal/pyharbinger
Project-URL: Repository, https://github.com/cefet-rj-dal/pyharbinger
Project-URL: Bug Tracker, https://github.com/cefet-rj-dal/pyharbinger/issues
Author-email: Eduardo Ogasawara <eogasawara@ieee.org>
License: MIT
License-File: LICENSE
Keywords: anomaly detection,change point,event detection,experiment line,scikit-learn,time series
Classifier: Development Status :: 3 - Alpha
Classifier: Intended Audience :: Science/Research
Classifier: License :: OSI Approved :: MIT License
Classifier: Programming Language :: Python :: 3
Classifier: Topic :: Scientific/Engineering :: Artificial Intelligence
Requires-Python: >=3.9
Requires-Dist: numpy>=1.23
Requires-Dist: pandas>=1.5
Requires-Dist: pydaltoolbox>=0.1.0
Requires-Dist: pytspredit>=0.1.0
Requires-Dist: ruptures>=1.0
Requires-Dist: scikit-learn>=1.2
Requires-Dist: scipy>=1.9
Provides-Extra: dev
Requires-Dist: build; extra == 'dev'
Requires-Dist: pytest>=7; extra == 'dev'
Requires-Dist: ruff>=0.1; extra == 'dev'
Requires-Dist: twine; extra == 'dev'
Provides-Extra: docs
Requires-Dist: ipykernel>=6; extra == 'docs'
Requires-Dist: jupytext>=1.16; extra == 'docs'
Requires-Dist: nbclient>=0.9; extra == 'docs'
Requires-Dist: nbconvert>=7; extra == 'docs'
Description-Content-Type: text/markdown

# pyharbinger

Python port of the R [harbinger](https://github.com/cefet-rj-dal/harbinger) — a **framework
for time series event detection** (anomalies, change points, and motifs/discords), built on
the DAL Toolbox *Experiment Line*.

`pyharbinger` unifies many detection methods under one interface (`fit` → `detect` →
`evaluate`) and a common evaluation protocol, so different detectors can be compared fairly —
reusing classic libraries (scikit-learn, numpy, pandas, scipy, ruptures) through thin
adapters.

It is the capstone of the DAL Python family:

- Builds on **[pydaltoolbox](https://github.com/cefet-rj-dal/pydaltoolbox)** (foundation) and
  **[pytspredit](https://github.com/cefet-rj-dal/pytspredit)** (time series prediction) — its
  regressors power the forecasting-based anomaly detectors.

## Installation

```bash
pip install pyharbinger
```

## Quickstart

```python
from pyharbinger import HanrFft, HarEval, datasets

# a labeled example series (one injected anomaly)
dataset = datasets.examples_anomalies()["simple"]
serie, event = dataset["serie"], dataset["event"]

# fit -> detect -> evaluate
model = HanrFft().fit(serie)
detection = model.detect(serie)
print(detection[detection["event"]])

metrics = model.evaluate(detection, event)
print(metrics["confMatrix"])
print("F1:", metrics["F1"])
```

## What's included (v1)

Every detector extends `Harbinger` and returns a detection table with columns
`idx` / `event` / `type` (`"anomaly"`, `"changepoint"`, `"discord"` or `""`).

| Group | Classes |
|---|---|
| **Core** | `Harbinger` (base contract), deviation / filter / candidate-selection utilities |
| **Evaluation** | `HarEval` (hard), `HarEvalSoft` (SoftED, soft matching via the Hungarian algorithm) |
| **Anomaly** | `HanrMl` (forecasting residuals, wraps a pytspredit regressor), `HanrFft`, `HanrHistogram`, `HanrFbiad` |
| **Change point** | `HcpAmoc`, `HcpBinseg`, `HcpPelt` (via `ruptures`), `HcpKswin`, `HcpPageHinkley` |
| **Clustering** | `HanctKmeans` (anomalies / discords) |
| **Datasets** | `datasets.examples_anomalies()`, `datasets.examples_changepoints()` |

### Deferred to a future release (0.2.0 / Block B)

ML-classification detector (`hanc_ml`), motif/discord via matrix profile
(`hdis_mp`/`hmo_mp`), ARIMA/GARCH/EMD/wavelet anomaly detectors, DTW clustering,
SAX representations, ensembles, streaming/online runners, and plotting helpers.

## Faithfulness to R

The port is validated against the R package on the same data at every step.
Deterministic components match R to numerical precision (deviation measures,
filters, candidate selection, hard/soft evaluation, FFT/histogram/FBIAD
detectors, `HanrMl` with a deterministic regressor, `HanctKmeans` centroids
count, and `HcpPageHinkley`). Where the backend or RNG differs, the tolerance is
documented:

- `HanrMl` with a rank-reduced ELM (`nhid < input_size`, `purelin`) depends on
  the hidden-weight RNG.
- `HanctKmeans` and `HcpKswin` depend on initialization / random-subsample RNG.
- `HcpAmoc`/`HcpBinseg`/`HcpPelt` use `ruptures` (Gaussian cost); R uses
  `changepoint::cpt.meanvar` with the MBIC penalty, so agreement is approximate.

## Related DAL projects

- [pydaltoolbox](https://github.com/cefet-rj-dal/pydaltoolbox) — foundation (Python)
- [pytspredit](https://github.com/cefet-rj-dal/pytspredit) — time series prediction (Python)
- [daltoolbox](https://github.com/cefet-rj-dal/daltoolbox) / [tspredit](https://github.com/cefet-rj-dal/tspredit) / [harbinger](https://github.com/cefet-rj-dal/harbinger) — R originals
- [Data Analytics Lab](https://eic.cefet-rj.br/~dal/)

## License

MIT
