pyharbinger
Python port of the R 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 (foundation) and pytspredit (time series prediction) — its regressors power the forecasting-based anomaly detectors.
Installation
pip install pyharbinger
On Python 3.14,
ruptures1.1.x has no prebuilt wheel yet; install withpip install --prefer-binary pyharbingerso pip uses the pure-Pythonruptures1.0.6 wheel. Python 3.9–3.13 install directly.
Quickstart
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
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, HanrFftAmoc, HanrFftBinseg, HanrFftAmocCusum, HanrFftBinsegCusum, HanrHistogram, HanrFbiad |
| Change point | HcpAmoc, HcpBinseg, HcpPelt (via ruptures), HcpKswin, HcpPageHinkley, HcpCfLr, HcpScp, HcpJoinpoint |
| Clustering | HanctKmeans (anomalies / discords) |
| Classification | HancMl (supervised; wraps a pydaltoolbox classifier) |
| Multivariate | HmuPca (PCA reconstruction error) |
| Datasets | datasets.examples_anomalies(), datasets.examples_changepoints() |
Detectors accept a univariate series or, for the multivariate ones, a
DataFrame with one column per variable.
Roadmap
Later releases expand coverage toward feature parity with R in two cycles. The
low-dependency cycle adds the FFT-hybrid anomaly detectors, the extended
change-point family (ChangeFinder, Chow, GFT, join-point, BOCPD, ...), native
SAX motif/discord, ensembles, plotting, and the streaming runners. The
heavy-dependency cycle then adds — each behind an optional extra — matrix
profile (stumpy), GARCH (arch), EMD (EMD-signal), wavelets (PyWavelets),
DTW clustering, and the autoencoder detectors (deep-learning backend). See
develop/planejamento.md for the full plan.
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:
HanrMlwith a rank-reduced ELM (nhid < input_size,purelin) depends on the hidden-weight RNG.HanctKmeansandHcpKswindepend on initialization / random-subsample RNG.HcpAmoc/HcpBinseg/HcpPeltuseruptures(Gaussian cost); R useschangepoint::cpt.meanvarwith the MBIC penalty, so agreement is approximate.HancMldetections match R (e.g. thehanc_mlk-NN example flags the same positions), but class probabilities can differ because scikit-learn and R'sclass::knnbreak ties differently.HmuPcamatches R exactly (same events and residuals) after fixing a latent degeneracy in R'shmu_pca, which kept all principal components; both now reconstruct from a reduced set (90% variance by default, capped atn_features - 1).HcpCfLr,HcpScpand the FFT-hybrid anomaly detectors match R exactly on the example series.HcpJoinpointmatches R on well-conditioned series; on a perfectly piecewise-linear series its segment residuals collapse to round-off, so the exact break positions are numerically ill-conditioned (the dominant change point is still recovered).
Related DAL projects
- pydaltoolbox — foundation (Python)
- pytspredit — time series prediction (Python)
- daltoolbox / tspredit / harbinger — R originals
- Data Analytics Lab
License
MIT
Metadata
Release files for pyharbinger 0.4.0
For a detailed explanation of source distributions (sdists) and built distributions (wheels), please see the package formats documentation.
Source distribution (sdist)
| File | Size | Uploaded | Provenance | Actions |
|---|---|---|---|---|
| pyharbinger-0.4.0.tar.gz | 93.9 kB | Without provenance | Details for pyharbinger-0.4.0.tar.gz |
Built distribution (wheel)
| File | Interpreter | ABI | Platform | Actions Reset |
|---|---|---|---|---|
| pyharbinger-0.4.0-py3-none-any.whl | Python 3 | none | any | Details for pyharbinger-0.4.0-py3-none-any.whl |
Total release size: 189.0 kB
Release files / pyharbinger-0.4.0.tar.gz
| Download URL | pyharbinger-0.4.0.tar.gz |
|---|---|
| Size | 93.9 kB |
| Tags | Source |
|
SHA-256 checksum How to use checksums |
87047e581464557d6b1582da78528185983849729d60dc2557c2be7f36d78df4
|
|
BLAKE2b-256 checksum How to use checksums |
b5dfc6d8e40124535149d0f922dab5aae51c03a87939450e42c2d5b35277bf64
|
| Upload date | |
|
Uploaded using Trusted Publishing? What is trusted publishing? |
No |
| Uploaded via |
twine/7.0.0 CPython/3.14.0
|
Release files / pyharbinger-0.4.0-py3-none-any.whl
| Download URL | pyharbinger-0.4.0-py3-none-any.whl |
|---|---|
| Size | 95.1 kB |
| Tags | Python 3 |
|
SHA-256 checksum How to use checksums |
066a31f7f99d80fe6bf1eb6541d0a45486eb76fb964f1b8748110eb7a0dfa925
|
|
BLAKE2b-256 checksum How to use checksums |
35d06335e0073fc35342d5272df596f0dfdc45ee00da6db1bb882c1786e4bd8f
|
| Upload date | |
|
Uploaded using Trusted Publishing? What is trusted publishing? |
No |
| Uploaded via |
twine/7.0.0 CPython/3.14.0
|
Security for pyharbinger 0.4.0
Provenance
Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.
No provenance found
None of the files in this release were uploaded with provenance metadata.
A note on package security
PyPI is a repository for distributing packages, not a service for auditing them. While third-party security researchers and our staff do their best to detect and remove malicious packages, PyPI cannot guarantee the quality, security or suitability of any given package.
To learn more about protecting yourself from malicious actors, visit our package security documentation.