tsseg.algorithms.changefinder package

ChangeFinder — Online two-stage change-point detection via outlier scoring.

Description

ChangeFinder reduces change-point detection to outlier detection using a pair of sequentially discounting autoregressive (SDAR) models. The algorithm operates in two stages:

  1. Stage 1: An SDAR model is fitted online on the raw signal. Each observation receives an outlier score (logarithmic or quadratic loss), which is smoothed by a causal moving average of width T.

  2. Stage 2: A second SDAR model is fitted on the smoothed scores from Stage 1. A second moving average produces the final change-point score curve. Peaks in this curve are returned as change points.

The SDAR model maintains an AR(k) model with exponential discounting: older observations are progressively down-weighted at rate r, allowing the model to track non-stationary dynamics. AR parameters are updated at each step by re-solving a discounted Toeplitz system.

This online, single-pass design yields \(O(n \cdot k^2)\) time complexity, making ChangeFinder efficient for long time series.

Type: change point detection
Supervision: unsupervised or semi-supervised (n_cps)
Scope: univariate and multivariate
Complexity: \(O(n \cdot k^2)\) where k is the AR order

Parameters

Name

Type

Default

Description

order

int

5

AR order k for both SDAR stages.

discount

float

0.005

Discounting rate r in (0, 1). Smaller values retain longer memory.

smooth_window

int

7

Moving-average window length T after each SDAR stage.

score

str

"logarithmic"

Scoring function: "logarithmic" (neg. log-likelihood) or "quadratic" (squared prediction error).

n_cps

int / None

None

Number of change points to return. If None, all peaks above threshold are returned.

threshold

float / None

None

Minimum score for a peak. If None, uses mean + 2*std of the score curve.

min_distance

int

10

Minimum samples between successive change points.

multivariate_strategy

str

"l2"

"l2" (reduce via L2 norm) or "ensembling" (per-channel).

tolerance

float

0

Tolerance for aggregating change points in ensembling mode.

axis

int

0

Time axis.

Usage

from tsseg.algorithms import ChangeFinderDetector

detector = ChangeFinderDetector(order=5, discount=0.005, smooth_window=7)
cps = detector.fit_predict(X)

Reference: Takeuchi, J. and Yamanishi, K. (2006), A unifying framework for detecting outliers and change points from time series, IEEE TKDE, vol. 18, no. 4, pp. 482–492.

Submodules

tsseg.algorithms.changefinder.sdar module

SDAR (Sequential Discounting AR) learning algorithm.

Implements the online discounting AR model from:

Takeuchi & Yamanishi, “A Unifying Framework for Detecting Outliers and Change Points from Time Series”, IEEE TKDE, 2006.

class tsseg.algorithms.changefinder.sdar.SDAR(order, discount)[source]

Bases: object

Sequential Discounting AutoRegressive model.

Learns an AR(k) model incrementally with exponential discounting so that older observations are gradually forgotten. For each new observation the model produces a predicted mean and variance which can be used to compute an outlier score.

Parameters:

  • order (int) – AR order (k in the paper).

  • discount (float) – Discounting rate r in (0, 1). Larger values forget faster.

log_loss(x_new, x_hat, sigma)[source]

Logarithmic loss (negative log-likelihood under Gaussian).

Return type:

float

quadratic_loss(x_new, x_hat)[source]

Quadratic loss (squared prediction error).

Return type:

float

update(x_new)[source]

Ingest a new observation and return (predicted_mean, predicted_var).

Parameters:

x_new (float) – New observation.

Return type:

tuple[float, float]

Returns:

  • x_hat (float) – One-step-ahead prediction for x_new from the previous model.

  • sigma (float) – Current residual variance estimate.

tsseg.algorithms.changefinder.detector module

ChangeFinder: two-stage outlier-to-change-point detection.

Implements the ChangeFinder algorithm from:

Takeuchi & Yamanishi, “A Unifying Framework for Detecting Outliers and Change Points from Time Series”, IEEE TKDE, 2006.

The algorithm operates in two stages:

  1. An SDAR model learns the time series online. Each observation receives an outlier score (log-loss or quadratic loss). A moving average of these scores produces a smoothed score series.

  2. A second SDAR model learns the smoothed score series. A second moving average yields the final change-point score at each time step.

Change points are then selected by peak-picking on the final score curve.

class tsseg.algorithms.changefinder.detector.ChangeFinderDetector(order=5, discount=0.005, smooth_window=7, score='logarithmic', n_cps=None, threshold=None, min_distance=10, multivariate_strategy='l2', tolerance=0, axis=0)[source]

Bases: BaseSegmenter

ChangeFinder change-point detector (Takeuchi & Yamanishi, 2006).

Two-stage online method that reduces change-point detection to outlier detection. An AR model with exponential discounting (SDAR) computes outlier scores; a moving average smooths them; a second SDAR + moving average produces a change-point score curve. Peaks in the curve are returned as change points.

Parameters:

  • order (int) – AR order for both SDAR stages.

  • discount (float) – Discounting rate r in (0, 1). Controls how quickly the model forgets past observations.

  • smooth_window (int) – Length T of the moving-average windows applied after each SDAR stage.

  • score (str) – Scoring function: "logarithmic" (negative log-likelihood) or "quadratic" (squared prediction error).

  • n_cps (int | None) – Number of change points to return. If None, all peaks above threshold are returned.

  • threshold (float | None) – Minimum score for a peak to be accepted as a change point. When None, a data-driven threshold of mean + 2*std of the score curve is used.

  • min_distance (int) – Minimum number of samples between successive change points.

  • multivariate_strategy (str) – Strategy for multivariate inputs: "l2" reduces to univariate via L2 norm; "ensembling" runs independently per channel and aggregates.

  • tolerance (int | float) – Tolerance for aggregating change points across channels (ensembling strategy only).

  • axis (int) – Time axis.

References

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

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

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

ChangeFinder change-point detection algorithm.

class tsseg.algorithms.changefinder.ChangeFinderDetector(order=5, discount=0.005, smooth_window=7, score='logarithmic', n_cps=None, threshold=None, min_distance=10, multivariate_strategy='l2', tolerance=0, axis=0)[source]

Bases: BaseSegmenter

ChangeFinder change-point detector (Takeuchi & Yamanishi, 2006).

Two-stage online method that reduces change-point detection to outlier detection. An AR model with exponential discounting (SDAR) computes outlier scores; a moving average smooths them; a second SDAR + moving average produces a change-point score curve. Peaks in the curve are returned as change points.

Parameters:

  • order (int) – AR order for both SDAR stages.

  • discount (float) – Discounting rate r in (0, 1). Controls how quickly the model forgets past observations.

  • smooth_window (int) – Length T of the moving-average windows applied after each SDAR stage.

  • score (str) – Scoring function: "logarithmic" (negative log-likelihood) or "quadratic" (squared prediction error).

  • n_cps (int | None) – Number of change points to return. If None, all peaks above threshold are returned.

  • threshold (float | None) – Minimum score for a peak to be accepted as a change point. When None, a data-driven threshold of mean + 2*std of the score curve is used.

  • min_distance (int) – Minimum number of samples between successive change points.

  • multivariate_strategy (str) – Strategy for multivariate inputs: "l2" reduces to univariate via L2 norm; "ensembling" runs independently per channel and aggregates.

  • tolerance (int | float) – Tolerance for aggregating change points across channels (ensembling strategy only).

  • axis (int) – Time axis.

References

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

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

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