tsseg.algorithms.ticc package

TICC — Toeplitz Inverse Covariance-based Clustering.

Description

TICC simultaneously segments and clusters multivariate time series by modelling each cluster as a Markov Random Field (MRF) defined over a short window of length window_size. The MRF is characterised by a block-Toeplitz inverse covariance matrix that captures temporal and cross-variable partial correlations.

The algorithm alternates between:

1. Assignment step — dynamic programming assigns each time step to the cluster maximising a log-likelihood + switching penalty \(\beta\).

2. Update step — ADMM updates the Toeplitz inverse covariance of each cluster subject to a sparsity penalty \(\lambda\).

Type: state detection

Supervision: semi-supervised (n_states required)

Scope: multivariate (transductive)

Parameters

Name	Type	Default	Description
window_size	int	10	Sliding window size.
n_states	int	5	Number of states (clusters).
lambda_parameter	float	0.11	Sparsity parameter for the inverse covariance.
beta	float	400	Switching penalty (temporal consistency).
maxIters	int	100	Maximum EM iterations.
threshold	float	2e-5	Convergence threshold.
num_proc	int	1	Number of parallel processes.
axis	int	0	Time axis.

Usage

from tsseg.algorithms import TiccDetector

detector = TiccDetector(n_states=4, window_size=10, beta=200)
states = detector.fit_predict(X)

Implementation: Adapted from the original TICC code by Hallac et al.

Reference: Hallac, Vare, Boyd & Leskovec (2017), Toeplitz Inverse Covariance-Based Clustering of Multivariate Time Series Data, KDD.

Submodules

tsseg.algorithms.ticc.detector module

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

class tsseg.algorithms.ticc.detector.TiccDetector(window_size=10, n_states=5, lambda_parameter=0.11, beta=400, maxIters=100, threshold=2e-05, num_proc=1, axis=0)

Bases: BaseSegmenter

An aeon-compatible wrapper for the TICC (Toeplitz Inverse Covariance-based Clustering) algorithm for time series segmentation.

Parameters:

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

• n_states (int, default=5) – The number of states (clusters) to find.

• lambda_parameter (float, default=11e-2) – Sparsity parameter.

• beta (float, default=400) – Switching penalty, controls the temporal consistency.

• maxIters (int, default=100) – Maximum number of iterations for the TICC solver.

• threshold (float, default=2e-5) – Convergence threshold.

• num_proc (int, default=1) – Number of processes to use for parallel computation.

• axis (int, default=0) – The axis of the input series to segment.

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

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

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

class tsseg.algorithms.ticc.ticc.ADMMSolver(lamb, num_stacked, size_blocks, rho, S, rho_update_func=None)

Bases: object

ADMM_u()

ADMM_x()

ADMM_z(index_penalty=1)

CheckConvergence(z_old, e_abs, e_rel, verbose)

Prox_logdet(S, A, eta)

ij2symmetric(i, j, size)

upper2Full(a)

class tsseg.algorithms.ticc.ticc.TICC(window_size=10, number_of_clusters=5, lambda_parameter=0.11, beta=400, maxIters=1000, threshold=2e-05, write_out_file=False, prefix_string='', num_proc=1, compute_BIC=False, cluster_reassignment=20, biased=False)

Bases: object

compute_f_score(matching_EM, matching_GMM, matching_Kmeans, train_confusion_matrix_EM, train_confusion_matrix_GMM, train_confusion_matrix_kmeans)

compute_matches(train_confusion_matrix_EM, train_confusion_matrix_GMM, train_confusion_matrix_kmeans)

fit_transform(series)

Main method for TICC solver. :param - input_file: location of the data file

load_data(input_file)

log_parameters()

optimize_clusters(computed_covariance, len_train_clusters, log_det_values, optRes, train_cluster_inverse)

predict_clusters(test_data=None)

Given the current trained model, predict clusters. If the cluster segmentation has not been optimized yet, than this will be part of the interative process.

Parameters:

• data (numpy array of data for which to predict clusters. Columns are dimensions of the)

• is (each row)

• timestamp (a different)

Returns:

vector of predicted cluster for the points

prepare_out_directory()

smoothen_clusters(cluster_mean_info, computed_covariance, cluster_mean_stacked_info, complete_D_train, n)

stack_training_data(Data, n, num_train_points, training_indices)

train_clusters(cluster_mean_info, cluster_mean_stacked_info, complete_D_train, empirical_covariances, len_train_clusters, n, pool, train_clusters_arr)

tsseg.algorithms.ticc.ticc.computeBIC(K, T, clustered_points, inverse_covariances, empirical_covariances)

empirical covariance and inverse_covariance should be dicts K is num clusters T is num samples

tsseg.algorithms.ticc.ticc.compute_confusion_matrix(num_clusters, clustered_points_algo, sorted_indices_algo)

computes a confusion matrix and returns it

tsseg.algorithms.ticc.ticc.find_matching(confusion_matrix)

returns the perfect matching

tsseg.algorithms.ticc.ticc.getTrainTestSplit(m, num_blocks, num_stacked)

Compute the training indices for the TICC model.

Parameters:

• m (int) – Number of observations.

• num_blocks (int) – window_size + 1.

• num_stacked (int) – window_size.

Returns:

Sorted list of training indices.

Return type:

list[int]

tsseg.algorithms.ticc.ticc.updateClusters(LLE_node_vals, switch_penalty=1)

Takes in LLE_node_vals matrix and computes the path that minimizes the total cost over the path Note the LLE’s are negative of the true LLE’s actually!!!!!

Note: switch penalty > 0

tsseg.algorithms.ticc.ticc.upperToFull(a, eps=0)

Module contents