tsseg.algorithms.espresso package

ESPRESSO — Entropy and Shape-aware Time Series Segmentation.

Description

ESPRESSO exploits both entropy and temporal shape properties to segment multi-dimensional time series. The method builds a semantic density matrix from the matrix profile using an arc-curve expansion procedure:

Compute the matrix profile with stumpy.
Iteratively expand arc sets (controlled by chain_len) to accumulate segment-boundary evidence.
Detect peaks in the resulting density curve; peaks signal change points.

ESPRESSO differs from methods that focus exclusively on statistical or temporal properties.

Type: change point detection
Supervision: semi-supervised (n_segments required)
Scope: univariate and multivariate

Parameters

Name	Type	Default	Description
`window_size`	int	`64`	Subsequence length for the matrix profile (>= 4).
`chain_len`	int	`3`	Iterations for expanding arc sets.
`n_segments`	int / None	`None`	Target number of segments (>= 2 at predict time).
`peak_distance_fraction`	float	`0.01`	Minimum spacing between peaks as a fraction of the series length.
`axis`	int	`0`	Time axis.
`random_state`	int / None	`None`	Seed for the internal RNG.

Usage

from tsseg.algorithms import EspressoDetector

detector = EspressoDetector(window_size=64, chain_len=5, n_segments=4)
labels = detector.fit_predict(X)

Implementation: Reimplemented from the original ESPRESSO paper. Origin: new code.

Reference: Deldari, Smith, Sadri & Salim (2020), ESPRESSO: Entropy and ShaPe awaRe timE-Series SegmentatiOn, UbiComp.

Submodules

tsseg.algorithms.espresso.detector module

ESPRESSO change-point detector implemented purely in Python.

class tsseg.algorithms.espresso.detector.EspressoDetector(window_size=64, chain_len=3, *, n_segments=None, peak_distance_fraction=0.01, axis=0, random_state=None)[source]

Bases: BaseSegmenter

Segment time series using the ESPRESSO change-point detection algorithm.

Parameters:

subsequence_length (int, default=64) – Length of the subsequences used to compute the matrix profile; must be at least 4.
chain_len (int) – Number of iterations used when expanding arc sets to build the semantic density matrix.
n_segments (int | None) – Target number of segments to produce during prediction. Must be supplied and be greater than or equal to 2 when calling predict.
peak_distance_fraction (float) – Fraction of the input length that enforces a minimum spacing between detected peaks (matches the MATLAB reference implementation).
axis (int) – Axis corresponding to the time dimension in the input array.
random_state (int | None) – Seed for the internal random number generator used when sampling subsequences for the matrix profile.

get_fitted_params()[source]

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

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

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