tsseg.algorithms.vqtss package

VQ-TSS — Vector Quantized Time Series Segmentation.

Description

VQ-TSS is a predictive segmentation model that learns discrete state codes via a VQ-VAE bottleneck:

Encoder — dilated residual convolutions map sliding windows to a continuous latent space.
Vector Quantisation — an EMA-updated codebook discretises the latent vectors into a finite set of state codes.
Predictor — an InfoNCE objective trains the predictor to match the next-step continuous latent, encouraging the codebook to capture semantically meaningful states.

A temporal-smoothness regulariser discourages rapid label switching.

Type: state detection
Supervision: fully unsupervised
Scope: univariate and multivariate
Requires: PyTorch

Parameters

Name	Type	Default	Description
`window_size`	int	`128`	Sliding-window length for training.
`stride`	int	`1`	Stride for sliding-window extraction.
`hidden_dim`	int	`64`	Latent / codebook dimension.
`num_embeddings`	int	`64`	Number of VQ codebook entries (max discrete states).
`commitment_cost`	float	`0.25`	VQ commitment-loss coefficient.
`decay`	float	`0.99`	EMA decay for codebook updates.
`smoothness_weight`	float	`0.1`	Temporal-smoothness regularisation weight.
`contrastive_temperature`	float	`0.07`	Temperature for InfoNCE logits.
`neg_temporal_margin`	int	`5`	Timesteps within +/- margin masked from negatives.
`learning_rate`	float	`1e-3`	Adam learning rate.
`batch_size`	int	`64`	Mini-batch size.
`epochs`	int	`10`	Training epochs.
`max_grad_norm`	float	`1.0`	Gradient clipping (0 = disable).
`device`	str / None	`None`	PyTorch device (auto-detected if `None`).
`random_state`	int / None	`None`	Random seed.
`axis`	int	`0`	Time axis.

Usage

from tsseg.algorithms import VQTSSDetector

detector = VQTSSDetector(window_size=128, num_embeddings=32, epochs=20)
states = detector.fit_predict(X)

Implementation: Origin: new code.

Reference: —

Submodules

tsseg.algorithms.vqtss.detector module

class tsseg.algorithms.vqtss.detector.VQTSSDetector(*, window_size=128, stride=1, hidden_dim=64, num_embeddings=64, commitment_cost=0.25, decay=0.99, smoothness_weight=0.1, contrastive_temperature=0.07, neg_temporal_margin=5, learning_rate=0.001, batch_size=64, epochs=10, max_grad_norm=1.0, device=None, random_state=None, axis=0)[source]

Bases: BaseSegmenter

Vector Quantized Time Series Segmentation (VQ-TSS).

A predictive segmentation model that learns discrete state codes by optimising a contrastive future-prediction task through a VQ-VAE bottleneck. The encoder uses dilated residual convolutions, quantises the latent via EMA-updated codebook vectors, and trains a predictor to match the next-step continuous latent (InfoNCE objective).

Parameters:

axis (int) – Time axis. axis=0 means (n_timepoints, n_channels).
window_size (int) – Sliding-window length used during training.
stride (int) – Stride for the sliding-window extraction.
hidden_dim (int) – Latent / codebook dimension.
num_embeddings (int) – Number of VQ codebook entries (maximum number of discrete states).
commitment_cost (float) – VQ commitment-loss coefficient.
decay (float) – EMA decay for codebook updates.
smoothness_weight (float) – Weight of the temporal-smoothness regularisation on quantised latents.
contrastive_temperature (float) – Temperature for the InfoNCE logits.
neg_temporal_margin (int) – Timesteps within ±neg_temporal_margin of the positive are masked out as negatives (they are trivially similar in continuous signals).
learning_rate (float) – Adam learning rate.
batch_size (int) – Mini-batch size.
epochs (int) – Number of training epochs.
max_grad_norm (float) – Gradient clipping (max L2 norm). Set 0 to disable.
device (str | None) – PyTorch device. Auto-detected if None.
random_state (int | None) – Random seed for reproducibility.

get_active_states()[source]

Return the unique codebook indices used on the training data.

Return type:: ndarray

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

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

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