tsseg.algorithms.window package

Window — sliding-window discrepancy change point detection.

Description

Window-based detection slides two adjacent windows along the signal and computes a discrepancy measure $d(\cdot,\cdot)$ derived from the cost function:

\[d(y_{u..v},\,y_{v..w}) = c(y_{u..w}) - c(y_{u..v}) - c(y_{v..w})\]

When both windows fall inside the same segment their statistical properties are similar and the discrepancy is low. When they straddle a change point the discrepancy spikes. A sequential peak search on the discrepancy curve produces the final change points.

Complexity is $O(n\,w)$ where w is the window width — making Window one of the fastest methods. The jump parameter further speeds up prediction at the expense of positional precision.

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

Parameters

Name	Type	Default	Description
`width`	int	`100`	Width of each sliding window (in samples).
`n_cps`	int / None	`None`	Number of change points.
`pen`	float / None	`None`	Penalty threshold.
`epsilon`	float / None	`None`	Reconstruction-error tolerance.
`model`	str	`"l2"`	Ruptures cost model.
`min_size`	int	`2`	Minimum segment length.
`jump`	int	`5`	Sub-sampling factor for candidates.
`cost_params`	dict / None	`None`	Extra keyword arguments for the cost factory.
`axis`	int	`0`	Time axis.

Usage

from tsseg.algorithms import WindowDetector

detector = WindowDetector(width=50, model="l2", n_cps=3)
labels = detector.fit_predict(X)

# Penalty-based stopping
import numpy as np
detector = WindowDetector(width=50, model="l2", pen=np.log(n) * d * sigma**2)
labels = detector.fit_predict(X)

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

Reference: Basseville & Nikiforov (1993), Detection of Abrupt Changes, Prentice Hall.

Submodules

tsseg.algorithms.window.detector module

Window-based change point detector using the vendored ruptures implementation.

class tsseg.algorithms.window.detector.WindowDetector(*, width=100, n_cps=None, pen=None, epsilon=None, model='l2', min_size=2, jump=5, cost_params=None, axis=0)[source]

Bases: BaseSegmenter

Sliding window detector leveraging gain-based scoring.

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

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$') → WindowDetector

Configure whether metadata should be requested to be passed to the predict 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 predict 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 predict.
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 predict.
Returns:: self – The updated object.
Return type:: object

Module contents

Window-based change point detector.