regimecast

Regime detection without religion — six algorithms, one harness, reproducible leaderboard.

regimecast is a benchmark suite and reference library for change-point and regime detection on time series. It ships six well-known algorithms behind a single uniform API, plus a synthetic-data harness with known ground-truth regimes that produces a head-to-head leaderboard.

The goal is not to invent a new detector. It is to make the existing ones directly comparable on the same generator, the same metrics, and the same scoring rules — so you can stop arguing about which method is "best" on Twitter and look at a table.

---

Why regimecast

Existing tools each pick a side:

Capability	regimecast	ruptures	hmmlearn	ad-hoc rolling-vol
Change-point detectors (CUSUM, BinSeg, BOCPD)	yes	yes	no	no
State-space detectors (HMM, GMM)	yes	no	yes	no
Unified fit_predict API across both	yes	no	no	no
Built-in synthetic ground-truth generator	yes	partial	no	no
Benchmark harness with leaderboard	yes	no	no	no
F1-with-tolerance, latency, FAR, ARI together	yes	partial	partial	no
Pure-Python, no compiled deps	yes	no	no	yes
MIT, < 1k LOC, readable in one sitting	yes	no	no	yes

If you only need one algorithm, use the specialist library. If you want to choose an algorithm with evidence, use regimecast.

---

Sample leaderboard

Generated by examples/01_run_benchmark.py (50 runs, n=2000, 5 segments, tolerance=5):

detector	f1_mean	f1_std	latency_mean	far_mean	ari_mean
BOCPD	0.84	0.05	2.31	0.42	—
GaussianHMM	0.81	0.06	2.95	0.55	0.78
Ensemble	0.79	0.05	2.60	0.30	—
BinarySegmentation	0.74	0.07	3.10	0.61	—
OnlineGMM	0.69	0.08	4.42	0.88	0.66
CUSUM	0.62	0.10	3.85	1.20	—

(Numbers above are illustrative placeholders. Run the benchmark for your own table.)

---

Quickstart

pip install -e .

from regimecast import run_benchmark, GaussianHMM, BOCPD, CUSUM, OnlineGMM, BinarySegmentation, Ensemble

detectors = [GaussianHMM(), BOCPD(), CUSUM(), OnlineGMM(), BinarySegmentation(), Ensemble()]
print(run_benchmark(detectors, n_runs=50, seed=0))

That is the entire interface. Four lines, one DataFrame, sorted by F1 descending.

---

Methodology

Synthetic data. Series are piecewise-Gaussian. generate_changing_means_series samples n_segments segment means uniformly from mu_range, holds variance constant, and concatenates segments of roughly equal length with i.i.d. Gaussian noise. Change-points are the boundaries between segments.

F1 with tolerance. A predicted change-point is a true positive if there is an unmatched true change-point within tolerance bars (default 5). Each true change-point can be matched at most once, greedily by nearest distance.

Detection latency. Mean signed distance from a true change-point to its earliest matched prediction. Lower is better.

False alarm rate. Predicted change-points with no true change-point within tolerance bars, per 1000 bars.

ARI. Adjusted Rand Index, computed only for label-emitting detectors against the ground-truth segment-id labels. ARI is invariant to label permutation.

---

Algorithms

Detector	Type	Reference
GaussianHMM	labels	Baum & Petrie (1966); Rabiner (1989)
BOCPD	changepoints	Adams & MacKay (2007)
CUSUM	changepoints	Page (1954)
OnlineGMM	labels	Hamilton (1989) (regime concept)
BinarySegmentation	changepoints	Scott & Knott (1974)
Ensemble	changepoints	majority vote over the above

GaussianHMM is implemented from scratch (forward-backward + Baum-Welch EM) on purpose, so the package has no compiled dependencies and the algorithm is auditable.

---

Roadmap

• PELT (Killick et al. 2012) for exact penalised segmentation
• Neural change-point detection (TCN / transformer scorer)
• Multivariate HMM with full covariance
• Real-data benchmark suite (FX, equity returns, sensor streams)
• Online streaming API (partial_fit / update)
• Hyperparameter sweeps with Pareto fronts on F1 vs latency

---

License

MIT. See LICENSE. (c) 2026 thechifura and regimecast contributors.

Sibling project to quantflow and synthflow.