tsseg.algorithms.tire package

TIRE — Time-Invariant Representation for change point detection.

Description

TIRE learns a compact representation by training ensembles of parallel autoencoders in both the time domain (TD) and frequency domain (FD). The shared latent dimensions across autoencoders capture the time-invariant signal statistics while the private dimensions capture time-varying noise. A dissimilarity curve is computed from the shared representations and peaks in this curve indicate change points.

By tuning the loss weights and latent dimensions for each domain you can control whether the detector focuses on amplitude changes (TD) or spectral changes (FD) or both.

Type: change point detection

Supervision: unsupervised or semi-supervised

Scope: univariate and multivariate

Requires: PyTorch

Parameters

Name	Type	Default	Description
window_size	int	20	Sliding window size (>= 4).
stride	int	1	Stride between consecutive windows.
domain	str	"both"	Domain(s) for representation learning ("TD", "FD", "both").
intermediate_dim_td	int	0	Hidden dim of TD autoencoder (0 = skip intermediate layer).
latent_dim_td	int	1	Latent dim of TD autoencoder.
nr_shared_td	int	1	Number of shared latent dims (TD).
nr_ae_td	int	3	Number of parallel TD autoencoders.
loss_weight_td	float	1.0	Loss weight for TD component.
intermediate_dim_fd	int	10	Hidden dim of FD autoencoder.
latent_dim_fd	int	1	Latent dim of FD autoencoder.
nr_shared_fd	int	1	Number of shared latent dims (FD).
nr_ae_fd	int	3	Number of parallel FD autoencoders.
loss_weight_fd	float	1.0	Loss weight for FD component.
nfft	int	30	FFT size for frequency-domain windows.
norm_mode	str	"timeseries"	Normalisation scope ("window" or "timeseries").
peak_distance_fraction	float	0.01	Min fraction of series length between peaks.
max_epochs	int	20	Maximum training epochs.
patience	int	5	Early-stopping patience.
learning_rate	float	1e-3	Optimiser learning rate.
n_segments	int / None	None	Number of segments (overrides peak detection).
axis	int	0	Time axis.
random_state	int / None	None	Random seed.

Usage

from tsseg.algorithms import TireDetector

detector = TireDetector(window_size=30, domain="both", n_segments=5)
labels = detector.fit_predict(X)

Implementation: Origin: new code.

Reference: De Ryck, De Vos, Bertrand & Verhoest (2021), Change Point Detection in Time Series Data Using Autoencoders with a Time-Invariant Representation, IEEE TSIPN.

Submodules

tsseg.algorithms.tire.detector module

class tsseg.algorithms.tire.detector.TireDetector(window_size=20, stride=1, domain='both', intermediate_dim_td=0, latent_dim_td=1, nr_shared_td=1, nr_ae_td=3, loss_weight_td=1.0, intermediate_dim_fd=10, latent_dim_fd=1, nr_shared_fd=1, nr_ae_fd=3, loss_weight_fd=1.0, nfft=30, norm_mode='timeseries', peak_distance_fraction=0.01, max_epochs=20, patience=5, learning_rate=0.001, *, n_segments=None, axis=0, random_state=None)

Bases: BaseSegmenter

TIRE (Time-Invariant Representation) change point detector.

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

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

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.tire.utils module

tsseg.algorithms.tire.utils.calc_fft(windows, nfft=30, norm_mode='timeseries')

Calculates the DFT for each window and transforms its length

Parameters:

• windows – time series windows

• nfft – number of points used for the calculation of the DFT

• norm_mode – ensure that the timeseries / each window has zero mean

Returns:

frequency domain windows, each window having size nfft//2 (+1 for timeseries normalization)

tsseg.algorithms.tire.utils.combine_ts(list_of_windows)

Combines a list of windows from multiple views to one list of windows

Parameters:

list_of_windows – list of windows from multiple views

Returns:

one array with the concatenated windows

tsseg.algorithms.tire.utils.cp_to_timestamps(changepoints, tolerance, length_ts)

Extracts time stamps of change points

Parameters:

• changepoints

• tolerance

• length_ts – length of original time series

Returns:

list where each entry is a list with the windows affected by a change point

tsseg.algorithms.tire.utils.distance(data, window_size)

Calculates distance (dissimilarity measure) between features

Parameters:

• data – array of of learned features of size (nr. of windows) x (number of shared features)

• window_size – window size used for CPD

Returns:

Array of dissimilarities of size ((nr. of windows)-stride)

tsseg.algorithms.tire.utils.matched_filter(signal, window_size)

Matched filter for dissimilarity measure smoothing (and zero-delay weighted moving average filter for shared feature smoothing)

Parameters:

• signal – input signal

• window_size – window size used for CPD

Returns:

filtered signal

tsseg.algorithms.tire.utils.minmaxscale(data, a, b)

Scales data to the interval [a,b]

tsseg.algorithms.tire.utils.new_peak_prominences(distances)

Adapted calculation of prominence of peaks, based on the original scipy code

Parameters:

distances – dissimarity scores

Returns:

prominence scores

tsseg.algorithms.tire.utils.parameters_to_cps(parameters, window_size)

Preparation for plotting ground-truth change points

Parameters:

• parameters – array parameters used to generate time series, size Tx(nr. of parameters)

• window_size – window size used for CPD

Returns:

Array of which entry is non-zero in the presence of a change point. Higher values correspond to larger parameter changes.

tsseg.algorithms.tire.utils.tpr_fpr(bps, distances, method='prominence', tol_dist=0)

Calculation of TPR and FPR

Parameters:

• bps – list of breakpoints (change points)

• distances – list of dissimilarity scores

• method – prominence- or height-based change point score

• tol_dist – toleration distance

Returns:

list of TPRs and FPRs for different values of the detection threshold

tsseg.algorithms.tire.utils.ts_to_windows(ts, onset, window_size, stride, normalization='timeseries')

Transforms time series into list of windows

Module contents