Spectral

polars_ts.clustering.spectral

Spectral clustering (K-Spectral Centroid) for time series.

Computes pairwise distances via the existing Rust-accelerated distance engine, converts to an affinity matrix using a Gaussian kernel, and clusters on the eigenvectors of the graph Laplacian.

_build_square_matrix(dist_dict, ids)

Convert symmetric distance dict to a square numpy matrix.

_compute_distance_matrix(df, method, id_col, target_col, **distance_kwargs)

Compute pairwise distances and return (sorted ids, square matrix).

spectral_cluster(df, k=3, method='sbd', sigma=1.0, id_col='unique_id', target_col='y', seed=42, **distance_kwargs)

Spectral clustering over time series using a kernel affinity matrix.

Builds a graph Laplacian from pairwise distances converted via a Gaussian kernel, then clusters the leading eigenvectors with k-means (K-Spectral Centroid approach).

Parameters

df DataFrame with columns id_col and target_col. k Number of clusters. method Distance metric name (e.g. "sbd", "dtw"). sigma Bandwidth parameter for the Gaussian kernel: affinity[i,j] = exp(-dist[i,j]^2 / (2 * sigma^2)). id_col Column identifying each time series. target_col Column with the time series values. seed Random seed for k-means initialisation. **distance_kwargs Extra keyword arguments forwarded to the distance function.

Returns

pl.DataFrame DataFrame with columns [id_col, "cluster"].