tsseg.algorithms.binseg package

Binary Segmentation (BinSeg) — fast sequential change point detection.

Description

Binary segmentation is a greedy, top-down procedure: it first detects a single change point in the full signal, then splits the series at that point and repeats the operation on each sub-signal until a stopping criterion is met.

The benefits include low complexity — $O(C\,n\log n)$ where n is the number of samples and C the cost of evaluating the cost function on one sub-signal — and the ability to work whether the number of regimes is known beforehand or not.

Type: change point detection
Supervision: unsupervised or semi-supervised
Scope: univariate and multivariate
Complexity: \(O(C\,n\log n)\)

Parameters

Name	Type	Default	Description
`n_cps`	int / None	`None`	Number of change points. When `None`, uses `penalty` or `epsilon`.
`model`	str	`"l2"`	Ruptures cost model (`"l2"`, `"l1"`, `"rbf"`, `"linear"`, `"normal"`, `"ar"`).
`min_size`	int	`2`	Minimum segment length.
`jump`	int	`5`	Sub-sampling factor for candidate breakpoints.
`penalty`	float / None	`10`	Penalty value (BIC-style). Mutually exclusive with `n_cps` / `epsilon`.
`epsilon`	float / None	`None`	Reconstruction-error tolerance. Mutually exclusive with `n_cps` / `penalty`.
`custom_cost`	BaseCost / None	`None`	Pre-instantiated ruptures cost object.
`cost_params`	dict / None	`None`	Additional keyword arguments forwarded to the cost factory.
`axis`	int	`0`	Axis representing time.

Usage

from tsseg.algorithms import BinSegDetector

detector = BinSegDetector(model="l2", n_cps=3)
labels = detector.fit_predict(X)

# Unknown number of change points — use a penalty
detector = BinSegDetector(model="l2", penalty=10)
labels = detector.fit_predict(X)

Implementation: Vendored from ruptures v1.1.8. BSD 2-Clause.

Reference: Bai (1997), Econometric Theory; Fryzlewicz (2014), The Annals of Statistics.

Submodules

tsseg.algorithms.binseg.detector module

BinSeg detector aligned with the tsseg BaseSegmenter API.

class tsseg.algorithms.binseg.detector.BinSegDetector(*, n_cps=None, model='l2', min_size=2, jump=5, penalty=10, epsilon=None, custom_cost=None, cost_params=None, axis=0)[source]

Bases: BaseSegmenter

Binary Segmentation change-point detector using ruptures’ implementation.

This wrapper fits the single-change Binseg solver on the provided data and repeatedly splits the series to obtain multiple change points.

Parameters:

n_cps (int | None) – Number of change points to return. When None, ruptures stops according to its internal criteria (pen or epsilon).
model (str) – Cost model passed to ruptures. Examples include “l2”, “l1”, “rbf”.
min_size (int) – Minimum segment length enforced during the binary search.
jump (int) – Sub-sampling factor for candidate breakpoints.
penalty (float | None) – Penalty threshold supplied to predict. Mutually exclusive with n_cps and epsilon. Provide at least one of n_cps, penalty or epsilon.
epsilon (float | None) – Reconstruction error tolerance. Mutually exclusive with n_cps and penalty.
custom_cost (BaseCost | None) – Pre-instantiated ruptures cost object.
cost_params (dict | None) – Additional keyword arguments forwarded to cost_factory when building the cost from model.
axis (int) – Axis representing time in the input array.

get_fitted_params()[source]

set_fit_request(*, axis: bool | None | str = '$UNCHANGED$') → BinSegDetector

Configure whether metadata should be requested to be passed to the fit method.

Note that this method is only relevant when this estimator is used as a sub-estimator within a meta-estimator and metadata routing is enabled with enable_metadata_routing=True (see sklearn.set_config()). Please check the User Guide on how the routing mechanism works.

The options for each parameter are:

True: metadata is requested, and passed to fit if provided. The request is ignored if metadata is not provided.
False: metadata is not requested and the meta-estimator will not pass it to fit.
None: metadata is not requested, and the meta-estimator will raise an error if the user provides it.
str: metadata should be passed to the meta-estimator with this given alias instead of the original name.

The default (sklearn.utils.metadata_routing.UNCHANGED) retains the existing request. This allows you to change the request for some parameters and not others.

Added in version 1.3.

Parameters:: axis (str, True, False, or None, default=sklearn.utils.metadata_routing.UNCHANGED) – Metadata routing for axis parameter in fit.
Returns:: self – The updated object.
Return type:: object

set_predict_request(*, axis: bool | None | str = '$UNCHANGED$') → BinSegDetector

Configure whether metadata should be requested to be passed to the predict method.