tsseg.algorithms.e2usd package

E2USD — Efficient-yet-Effective Unsupervised State Detection.

Description

E2USD combines two key ideas for scalable, accurate unsupervised state detection in multivariate time series:

1. DDEM (Decomposed Dual-view Embedding Module) — a lightweight encoder that compresses sliding windows into low-dimensional representations using FFT-based compression and a decomposed contrastive learning objective.

2. DPGMM clustering — a Dirichlet Process Gaussian Mixture Model that automatically determines the number of states from the learned embeddings.

A False Negative Cancellation Contrastive Learning method (FNCCLearning) is used to counteract false negatives and produce cluster-friendly embedding spaces.

Type: state detection

Supervision: unsupervised or semi-supervised

Scope: multivariate

Requires: PyTorch

Parameters

Name	Type	Default	Description
window_size	int	256	Size of the sliding window.
step	int	50	Step size of the sliding window.
n_states	int	20	Maximum number of states for DPGMM clustering.
alpha	float	1e3	Concentration parameter for DPGMM.
batch_size	int	1	Training batch size.
nb_steps	int	20	Number of optimisation steps.
lr	float	0.003	Learning rate.
depth	int	1	Depth of the DDEM encoder network.
out_channels	int	4	Number of output channels of the encoder.
reduced_size	int	80	Dimension of the CNN output before the final linear layer.
kernel_size	int	3	Kernel size for CNN convolutions.
use_gpu	bool / None	None	Force GPU usage (None = auto-detect).
random_state	int / None	None	Random seed.
axis	int	0	Time axis.

Usage

from tsseg.algorithms import E2USDDetector

detector = E2USDDetector(window_size=256, n_states=10, nb_steps=20)
states = detector.fit_predict(X)

Implementation: Adapted from AI4CTS/E2Usd. No licence found in original repository.

Reference: Lai, Zhao, Li, Qian, Zhang & Jensen (2024), E2Usd: Efficient-yet-effective Unsupervised State Detection for Multivariate Time Series, WWW.

Submodules

tsseg.algorithms.e2usd.detector module

This module provides an aeon-compatible wrapper for the E2USD algorithm.

class tsseg.algorithms.e2usd.detector.E2USDDetector(axis=0, window_size=256, step=50, n_states=20, alpha=1000.0, batch_size=1, nb_steps=20, lr=0.003, depth=1, out_channels=4, reduced_size=80, kernel_size=3, use_gpu=None, random_state=None)

Bases: BaseSegmenter

A wrapper for the E2USD algorithm, compatible with the aeon library.

E2USD uses a deep learning based encoder to learn representations of time series windows, which are then clustered to identify states.

Parameters:

• axis (int) – Axis along which to segment if passed a multivariate series (2D input). Default is 0, assuming shape (n_timepoints, n_channels).

• window_size (int, default=256) – The size of the sliding window.

• step (int, default=50) – The step size of the sliding window.

• n_states (int, default=20) – The maximum number of states for the DPGMM clustering.

• alpha (float, default=1e3) – The concentration parameter for the DPGMM clustering.

• batch_size (int, default=1) – Batch size for training the neural network.

• nb_steps (int, default=20) – Number of optimization steps for training.

• lr (float, default=0.003) – Learning rate for the optimizer.

• depth (int, default=1) – Depth of the DDEM Network.

• out_channels (int, default=4) – Number of output channels of the encoder.

• reduced_size (int, default=80) – Size of the output of the CNN before the final linear layer.

• kernel_size (int, default=3) – Kernel size for the convolutions in the CNN.

• use_gpu (bool, optional) – Whether to use GPU if available. If None, it will be auto-detected.

• random_state (int, optional) – Random state for reproducibility.

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

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

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.e2usd.e2usd module

class tsseg.algorithms.e2usd.e2usd.BasicClusteringClass(params)

Bases: object

abstractmethod fit(X)

class tsseg.algorithms.e2usd.e2usd.BasicEncoder

Bases: object

encode(X)

load(X)

save(X)

class tsseg.algorithms.e2usd.e2usd.BasicEncoderClass(params)

Bases: object

abstractmethod encode(X, win_size, step)

abstractmethod fit(X)

class tsseg.algorithms.e2usd.e2usd.DDEM(win_size, batch_size, nb_steps, lr, channels, depth, reduced_size, out_channels, kernel_size, in_channels, cuda, gpu, M, N, win_type)

Bases: BasicEncoder

encode(X, batch_size=500)

encode_window(X, win_size=128, batch_size=500, window_batch_size=10000, step=10)

fit(X, save_memory=False, verbose=False)

set_params(compared_length, batch_size, nb_steps, lr, channels, depth, reduced_size, out_channels, kernel_size, in_channels, cuda, gpu)

class tsseg.algorithms.e2usd.e2usd.DPGMM(n_states, alpha=1000.0)

Bases: BasicClusteringClass

fit(X)

class tsseg.algorithms.e2usd.e2usd.Dataset(*args: Any, **kwargs: Any)

Bases: Dataset

class tsseg.algorithms.e2usd.e2usd.E2USD(win_size, step, encoder, clustering_component, verbose=False)

Bases: object

property change_points

property embedding_label

property embeddings

fit(X, win_size, step)

fit_encoder(X)

load_encoder()

load_result(path)

online_threshold_cluster(X, win_size, step, tau, ratio)

plot(path)

predict(X, win_size, step)

predict_without_encode(X, win_size, step)

save_encoder()

save_result(path)

set_clustering_component(clustering_obj)

set_step(step)

property state_seq

property velocity

class tsseg.algorithms.e2usd.e2usd.E2USD_Adaper(params)

Bases: BasicEncoderClass

encode(X, win_size, step)

encode_one(X, win_size, step)

fit(X)

class tsseg.algorithms.e2usd.e2usd.NetworkDDEM(*args: Any, **kwargs: Any)

Bases: Module

forward(x)

tsseg.algorithms.e2usd.e2usd.add_noise(data, mean=0, std=0.05)

tsseg.algorithms.e2usd.e2usd.all_normalize(data_tensor)

tsseg.algorithms.e2usd.e2usd.apply_scaling(data, mean=1.0, std=0.1)

tsseg.algorithms.e2usd.e2usd.compact(series)

class tsseg.algorithms.e2usd.e2usd.fncc_loss(*args: Any, **kwargs: Any)

Bases: _Loss

forward(batch, encoder, save_memory=False)

class tsseg.algorithms.e2usd.e2usd.moving_avg(*args: Any, **kwargs: Any)

Bases: Module

forward(x)

tsseg.algorithms.e2usd.e2usd.remove_duplication(series)

tsseg.algorithms.e2usd.e2usd.reorder_label(label)

class tsseg.algorithms.e2usd.e2usd.series_decomp(*args: Any, **kwargs: Any)

Bases: Module

forward(x)

Module contents