Skip to content

Contrastive

polars_ts.clustering.contrastive

Contrastive learning for time series clustering.

Trains a 1D CNN encoder via instance-level contrastive learning (NT-Xent) on augmented views, then clusters the learned embeddings with k-means.

References

  • Cross-Domain Contrastive Learning for TS Clustering (AAAI 2024)
  • Unsupervised Contrastive Learning for TS Clustering (Electronics, 2025)

ContrastiveClusterer

Contrastive learning time series clusterer.

Learns representations via instance-level contrastive learning, then applies k-means on the embeddings.

Parameters

n_clusters Number of clusters. embedding_dim Dimension of learned embeddings. projection_dim Projection head dimension (used during training only). n_filters Base CNN filter count. max_epochs Training epochs for contrastive learning. lr Learning rate. batch_size Training batch size. temperature NT-Xent temperature parameter. jitter_sigma Jitter augmentation noise level. scale_sigma Scaling augmentation noise level. seed Random seed. id_col, target_col Column names.

fit(df)

Train encoder via contrastive learning and cluster embeddings.

_kmeans(X, k, seed, max_iter=100) staticmethod

Run k-means on embedding vectors.

contrastive_cluster(df, k, max_epochs=50, embedding_dim=64, n_filters=32, seed=42, id_col='unique_id', target_col='y', **kwargs)

Contrastive clustering convenience function.

Returns

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