tsseg.algorithms.clap package

ClaSP and CLaP — classification-based time series segmentation.

Description

This package contains two related algorithms that share core routines:

ClaSP (Classification Score Profile) is a parameter-free method for change point detection. It hierarchically splits a time series by training a binary classifier (k-NN by default) for each possible split point and selecting the point that best separates the two halves. The number of change points and the window size are both learned automatically from the data. ClaSP is fast, domain-agnostic, and requires no distributional assumptions.

CLaP (Classification Label Profile) extends ClaSP from change point detection to state detection. Instead of a k-NN classifier, CLaP uses a time series classifier (e.g. ROCKET) and cross-validates segment-labelled subsequences. Segments with high confusion are iteratively merged, producing a set of state labels that can be reused across non-contiguous time regions.

Both algorithms support three usage modes:

  • Fully unsupervised — the number of segments is learned automatically.

  • Guided semi-supervised — provide n_segments or n_change_points.

  • Exact semi-supervised — provide pre-computed change_points.

Type: change point detection (ClaSP) / state detection (CLaP)
Supervision: unsupervised or semi-supervised
Scope: univariate and multivariate

ClaSP parameters

Name

Type

Default

Description

n_segments

str / int

"learn"

Number of segments ("learn" = auto-detect).

n_change_points

int / None

None

Exact number of change points (semi-supervised mode).

n_estimators

int

10

Number of ClaSPs in the ensemble.

window_size

str / int

"suss"

Window size or auto method ("suss", "fft", "acf").

k_neighbours

int

3

Number of nearest neighbours for ClaSP.

excl_radius

int

5

Exclusion radius (multiples of window size).

distance

str

"znormed_euclidean_distance"

Distance function for k-NN.

score

str

"roc_auc"

Scoring function for the profile.

early_stopping

bool

True

Stop early when no significant split is found.

validation

str

"significance_test"

Validation method for change point significance.

threshold

str / float

"default"

Threshold for the validation test.

n_jobs

int

-1

Number of parallel jobs.

CLaP parameters

Name

Type

Default

Description

window_size

str / int

"suss"

Window size or auto-detection method.

classifier

str

"rocket"

Time series classifier ("rocket", "knn", "svm").

merge_score

str

"cgain"

Scoring function for segment merging.

n_splits

int

5

Cross-validation folds.

n_jobs

int

1

Parallel jobs (-1 = all CPUs).

sample_size

int

1000

Samples for classifier training.

n_change_points

int / None

None

Number of change points (overrides n_segments).

change_points

list / None

None

Pre-computed change points for exact mode.

n_segments

int / None

None

Number of segments.

Usage

from tsseg.algorithms import ClaspDetector, ClapDetector

# --- ClaSP (change point detection, fully unsupervised) ---
clasp = ClaspDetector()
cps = clasp.fit_predict(X)                    # dense labels

# --- CLaP (state detection, guided) ---
clap = ClapDetector(n_segments=4, classifier="rocket")
states = clap.fit_predict(X)                  # sparse state labels

Implementation: Adapted from original ClaSP code by Arik Ermshaus. BSD 3-Clause.

Reference: Ermshaus, Schäfer & Leser (2023), ClaSP: parameter-free time series segmentation, DMKD; Ermshaus, Schäfer & Leser (2024), CLaP — State Detection from Time Series.

Submodules

tsseg.algorithms.clap.clap module

class tsseg.algorithms.clap.clap.CLaP(window_size='suss', classifier='rocket', merge_score='cgain', n_splits=5, n_jobs=1, sample_size=1000, random_state=2357)[source]

Bases: object

fit(time_series, change_points, labels=None)[source]
get_change_points()[source]
get_segment_labels()[source]
random_f1_score(y_true)[source]
score()[source]

tsseg.algorithms.clap.clap_detector module

This module provides a wrapper for the CLaP algorithm to integrate it with the tsseg library’s API.

class tsseg.algorithms.clap.clap_detector.ClapDetector(window_size='suss', classifier='rocket', merge_score='cgain', n_splits=5, n_jobs=1, sample_size=1000, random_state=42, axis=0, n_change_points=None, change_points=None, n_segments=None)[source]

Bases: BaseSegmenter

A wrapper for the CLaP (Classification Label Profile) algorithm for time series state detection, compatible with aeon.

Parameters:

  • window_size (str or int, default="suss") – The window size or the method to determine it (‘suss’, ‘fft’, ‘acf’).

  • classifier (str, default="rocket") – The classifier to use for state detection.

  • merge_score (str, default="cgain") – The scoring function to decide on merging segments.

  • n_splits (int, default=5) – Number of splits for cross-validation.

  • n_jobs (int, default=1) – The number of jobs to run in parallel. -1 means using all processors.

  • sample_size (int, default=1000) – The number of samples to use for training the classifier.

  • random_state (int, default=42) – Random seed for reproducibility.

  • axis (int, default=0) – The axis of the time series data.

  • change_points (np.ndarray, optional) – Pre-computed change points. Used if semi_supervised is True.

  • n_segments (int, optional) – The number of segments to find. Used if semi_supervised is False to guide the unsupervised change point detection.

  • semi_supervised (bool, default=False) – If True, uses provided change points for fitting. Change points can be provided via the change_points parameter at initialization or via y in the fit method. If False, detects change points automatically.

Notes

The detector requires a list of change points to segment the series. Three usage patterns are supported:

  • Exact semi-supervised – enable semi_supervised=True and supply

    the true change points via the change_points parameter at initialisation or as y during fit(). The semi-supervised tag is set accordingly so the test suite can forward labels.

  • Guided semi-supervised – keep semi_supervised=False but pass

    n_segments. The provided segment count is forwarded to the underlying change-point estimator (BinaryClaSPSegmentation by default), acting as a coarse constraint that typically sharpens the predicted breakpoints.

  • Fully unsupervised – the default behaviour, where no prior change

    point information is given. The change-point detector estimates breakpoints without guidance.

states_

An array of state labels for each time point. Available only after calling the fit or fit_predict method.

Type:

np.ndarray

change_points_

The change points used for fitting the model.

Type:

np.ndarray

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

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

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

tsseg.algorithms.clap.clasp_detector module

This module provides a wrapper for the ClaSP algorithm to integrate it with the tsseg library’s API.

class tsseg.algorithms.clap.clasp_detector.ClaspDetector(n_segments='learn', n_change_points=None, n_estimators=10, window_size='suss', k_neighbours=3, excl_radius=5, distance='znormed_euclidean_distance', score='roc_auc', early_stopping=True, validation='significance_test', threshold='default', n_jobs=-1, axis=0)[source]

Bases: BaseSegmenter

A wrapper for the ClaSP (Classification Score Profile) algorithm for time series segmentation, using binary segmentation, compatible with aeon.

Parameters:

  • n_segments (str or int, default="learn") – The number of segments to split the time series into. If “learn”, the number is inferred automatically.

  • n_estimators (int, default=10) – The number of ClaSPs in the ensemble.

  • window_size (str or int, default="suss") – The window size or the method to determine it (‘suss’, ‘fft’, ‘acf’).

  • k_neighbours (int, default=3) – The number of nearest neighbors to use in the ClaSP algorithm.

  • excl_radius (int, default=5) – The exclusion radius, in multiples of the window size.

change_points_

The indices of the detected change points, sorted in ascending order. Available only after calling the fit or fit_predict method.

Type:

list of int

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

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

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

tsseg.algorithms.clap.clasp_knn module

tsseg.algorithms.clap.distance module

tsseg.algorithms.clap.nearest_neighbour module

tsseg.algorithms.clap.scoring module

tsseg.algorithms.clap.segmentation module

tsseg.algorithms.clap.utils module

tsseg.algorithms.clap.validation module

tsseg.algorithms.clap.window_size module

Module contents