Skip to main content

pyharbinger

PyPI Python versions License: MIT

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, ruptures 1.1.x has no prebuilt wheel yet; install with pip install --prefer-binary pyharbinger so pip uses the pure-Python ruptures 1.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, HcpChow, HcpGft (native structural change), HcpCfArima, HcpCfEts (ChangeFinder, native forecast replacement), HcpBocpd (Bayesian online, "++" ocp re-engineering)
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:

  • 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.
  • HancMl detections match R (e.g. the hanc_ml k-NN example flags the same positions), but class probabilities can differ because scikit-learn and R's class::knn break ties differently.
  • HmuPca matches R exactly (same events and residuals) after fixing a latent degeneracy in R's hmu_pca, which kept all principal components; both now reconstruct from a reduced set (90% variance by default, capped at n_features - 1).
  • HcpCfLr, HcpScp and the FFT-hybrid anomaly detectors match R exactly on the example series. HcpJoinpoint matches 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).
  • HcpChow and HcpGft are re-engineered "++" versions of R's strucchange backend: the least-squares (mean-only) Chow sup-F / Bai & Perron breakpoints are generalised to a Gaussian mean + variance segmentation cost (with the conservative LWZ penalty for the break count in HcpGft), so they also catch scale/variance-regime changes the mean-shift model misses. They deliberately diverge from strucchange, so the gate is detection quality vs ground truth, not R parity: on the example series the summed SoftED-F1 rises from the faithful ports' 3.40 / 2.44 (R 3.31 / 2.20) to 3.73 / 3.17 (develop/benchmark_backimpl.py).
  • HcpCfArima and HcpCfEts are re-engineered "++" versions of R's forecast backend. They are a native, pure-numpy robust ChangeFinder: the canonical two-stage online SDAR surprise score (Takeuchi & Yamanishi, 2006 — strong on abrupt/variance/multi-change regimes) fused (union) with a Gaussian mean+variance structural break (which recovers smooth trend/slope changes). HcpCfArima uses an autoregressive SDAR predictor, HcpCfEts a discounted Holt predictor — no forecast, no statsmodels. The gate is detection quality vs ground truth, not R parity: on the example series the summed SoftED-F1 rises from the faithful ports' 2.78 / 2.66 (R forecast 2.92 / 2.66) to 3.84 / 3.64 (develop/benchmark_backimpl.py).
  • HcpBocpd is a re-engineered "++" version of Bayesian Online Change Point Detection (Adams & MacKay, 2007), not a port of R's ocp backend. Three advances over ocp: (1) a conjugate Bayesian autoregressive UPM (a linear regression of x_t on its lags per run length) in place of ocp's i.i.d. Gaussian UPM, so it detects changes in dynamics (slope, trend, autocorrelation), not only level/variance; (2) a log-space, eps-pruned streaming run-length recursion (bounded state, O(n·R̄) instead of O(n²)); and (3) change points read from the Bayesian predictive surprise via a robust local z-score, replacing ocp's noisy three-list voting. It deliberately diverges from ocp, so the gate is detection quality vs ground truth, not R parity: on the example series the summed SoftED-F1 rises from the faithful port's 1.12 (= R ocp) to 3.59 (develop/benchmark_backimpl.py) — the AR UPM recovers the trend/slope change points the mean/variance model misses.

License

MIT

Metadata

Release files for pyharbinger 0.4.6

For a detailed explanation of source distributions (sdists) and built distributions (wheels), please see the package formats documentation.

Source distribution (sdist)

Source distribution for pyharbinger 0.4.6
File Size Uploaded Provenance Actions
pyharbinger-0.4.6.tar.gz 105.3 kB Without provenance Details for pyharbinger-0.4.6.tar.gz

Built distribution (wheel)

Table of built distributions (wheels) for pyharbinger 0.4.6
File Interpreter ABI Platform Actions
pyharbinger-0.4.6-py3-none-any.whl Python 3 none any Details for pyharbinger-0.4.6-py3-none-any.whl

Total release size: 212.3 kB

Release files / pyharbinger-0.4.6.tar.gz

Download URL pyharbinger-0.4.6.tar.gz
Size 105.3 kB
Tags Source
SHA-256 checksum
How to use checksums
571ffb1bf4f5e5081576ff4f3d677e03439ee44ebf48582359dd6d95c3b6d87f
BLAKE2b-256 checksum
How to use checksums
d2a73a383684dbf5f4a86fdbea9a7293ecfd3da150bddcf6da188c3a519fd4bc
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.6-py3-none-any.whl

Download URL pyharbinger-0.4.6-py3-none-any.whl
Size 107.0 kB
Tags Python 3
SHA-256 checksum
How to use checksums
64289009d596e53cd03aed58be4e80b5d92de02dc28637643a9ebc83676ee0fc
BLAKE2b-256 checksum
How to use checksums
6dd47d6fbf203b32827bae33ec457953399eebcf965a8b0c757834e13b924aa0
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.6

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.

Anthropic, PBC Visionary sponsor Bloomberg Visionary sponsor Hudson River Trading Visionary sponsor Meta Visionary sponsor NVIDIA Visionary sponsor Microsoft Sustainability sponsor Depot Continuous Integration AWS Cloud computing and Security Sponsor Datadog Monitoring Fastly CDN Google Download Analytics Sentry Error logging StatusPage Status page