Find the moments a signal's behaviour shifts — in mean, variance, slope, or whole distribution. Every detector is built from three parts: a cost function (what kind of change), a search method (how to find it), and a constraint (how many). Fit on a NumPy array, predict a list of breakpoints. Learn the recipe once and mix & match.
Distilled & cross-checked against: centre-borelli.github.io/ruptures-docs · github.com/deepcharles/ruptures · Truong, Oudre & Vayatis, "Selective review of offline change point detection methods" (Signal Processing, 2020) · pypi.org/project/ruptures
pip install ruptures★conda install -c conda-forge rupturesimport ruptures as rpt★rpt.from ruptures.metrics import precision_recallhausdorff, randindex, meantime.# shape (n_samples,) or (n_samples, n_dim)★signal, bkps = rpt.pw_constant(n, dim, n_bkps, noise_std=2)★rpt.pw_linear(n, dim, n_bkps)rpt.pw_normal(n, n_bkps)rpt.pw_wavy(n, n_bkps)# offline only — whole signal at oncenotealgo = rpt.Pelt(model="rbf").fit(signal)★bkps = algo.predict(pen=10)★bkps = algo.fit_predict(signal, pen=10)rpt.display(signal, bkps); plt.show()★rpt.Pelt(model=…)★pen.rpt.Dynp(model=…)n_bkps. Slowest.rpt.Binseg(model=…)★rpt.BottomUp(model=…)rpt.Window(width=40, model=…)rpt.KernelCPD(kernel="rbf")★linear·rbf·cosine.model="l2"★model="l1"model="normal"model="rbf"★model="linear"model="ar"model="rank" · "mahalanobis".predict(n_bkps=5)★.predict(pen=10)★.predict(epsilon=100)pen = np.log(n) * dim * sigma**2# pass exactly ONE of the threemustrpt.Pelt(min_size=2)★rpt.Pelt(jump=5)★k, 2k, 3k… — ↑ = faster, coarser.params={"gamma": 1.0}params={"order": 4}model="ar".# KernelCPD: jump is fixed at 1notebkps = [120, 250, 480, 500]★bkps[-1] == len(signal)★# segments = len(bkps); changes = len(bkps) - 1np.split(signal, bkps[:-1])rpt.display(signal, bkps)★rpt.display(signal, true_bkps, pred_bkps)★fig, axes = rpt.display(signal, bkps, figsize=(10,6))precision_recall(true, pred, margin=10)★margin of a true cp.hausdorff(true, pred)randindex(true, pred)[0, 1].meantime(true, pred)# all take bkps lists ending in nnotepredict() returns.class MyCost(rpt.base.BaseCost):model = "" ; min_size = 2def fit(self, signal): … ; def error(self, s, e):rpt.Pelt(custom_cost=MyCost())# higher pen ⇒ fewer breakpoints★pen0 = np.log(n) * dim * sigma**2# sweep pen, plot n_bkps vs pen# or just fix n_bkps if you know it# know the # of changes# don't know the count# need speed / long signal# need the exact optimum# mean shiftmodel="l2"# distribution / non-linearmodel="rbf" (or KernelCPD)One definition and three ideas carry the library — a change point, the cost×search×constraint recipe, how the search methods explore, and what each cost is tuned to notice.
An index where the signal's statistics shift. Breakpoints split the series into homogeneous regimes — exactly what rpt.display shades.
The modular framework: any detector is one choice from each column. Swap parts freely to match the change you expect and the budget you have.
Binary segmentation splits greedily & recursively; a sliding window scans a discrepancy score. Exact methods (Dynp/Pelt) instead optimise globally.
The cost model decides which kind of shift counts. Same search, different lens — pick the one that matches your change.
len(signal)pen or epsilonjump fixed at 1; kernels linear/rbf/cosine