Examples

The library provides runnable examples covering basic clustering workflows, custom distance metrics, cluster geometries, and scikit-learn pipeline integration.

For rendered output with generated plots and downloadable Jupyter notebooks (.ipynb), visit the Example Gallery.

Overview of examples

Cluster geometries:

• CLARANS 2D Clustering on Synthetic Blobs: Medoid identification on isotropic Gaussian clusters.

• CLARANS Clustering on Interleaving Moons: Behavior on non-convex interleaving moons.

• CLARANS on Anisotropically Distributed Clusters: Performance on elongated, anisotropic cluster shapes.

Distance metrics and representations:

• Distance Metrics and Metric Parameters in CLARANS Clustering: Evaluate clustering results using Euclidean, Manhattan, and Cosine metrics.

• Clustering Sparse CSR Matrices with CLARANS: Cluster CSR sparse feature matrices directly.

• Clustering with Precomputed Distance Matrices: Cluster datasets using precomputed pairwise distance matrices.

• Graph Clustering with Precomputed Shortest-Path Distances: Cluster network nodes with shortest-path distances.

• Clustering Incomplete Data with Missing Values (NaN): Cluster incomplete data with missing values (NaN) using nan_euclidean.

• Custom Callable Distance Metric: Geospatial Haversine Clustering: Cluster geographic coordinates using a custom Haversine distance callable.

• Clustering on Asymmetric Precomputed Distance Matrices (D != D^T): Cluster directed networks on asymmetric precomputed distance matrices.

• Clustering Non-Vector Data: Text Sequences with Edit Distance: Cluster non-vector text sequences using Levenshtein edit distance.

• Clustering Time Series with Dynamic Time Warping (DTW): Cluster temporal signals with Dynamic Time Warping (DTW) distance matrices.

• Clustering Mixed-Type Tabular Data with Gower’s Dissimilarity: Cluster mixed continuous, binary, and categorical data using Gower’s dissimilarity.

Seeding and validation:

• Comparison of Initial Medoid Seeding Strategies in scikit-clarans: Compare k-medoids++, random, build, and heuristic seeding.

• User-Provided Initial Candidate Centers for CLARANS: Provide user-specified candidate coordinates for domain-guided seeding.

• Cluster Quality vs. Number of Clusters (Silhouette Analysis): Select optimal cluster count \(k\) using silhouette scores.

Inference and pipelines:

• Predicting Cluster Labels on Unseen Query Data: Assign unseen samples to existing cluster centers.

• Feature Transformation via Cluster-Distance Space: Transform observations into distance-to-medoid representations.

• Fast Precomputed Inference: Compact (n_test, k) vs. Full (n_test, n_train): Accelerate precomputed inference using compact (n_test, k) distance submatrices.

• Hyperparameter Tuning with GridSearchCV and Pipelines: Integrate estimators into scikit-learn GridSearchCV pipelines.

Robustness and anomaly detection:

• Outlier Robustness: CLARANS (k-Medoids) vs. K-Means: Compare medoid resistance against centroids in the presence of extreme values.

• Unsupervised Anomaly Detection via Medoid Distance Scoring: Unsupervised outlier and anomaly detection via distance-to-medoid scoring.

Benchmarks and convergence:

• Benchmarking CLARANS vs. FastCLARANS Convergence Speed: Compare runtime, swap counts, and memory between CLARANS and FastCLARANS.

• Comparing Cost Evaluation Strategies: Delta vs. Brute-Force: Compare runtime and solution equivalence between delta caching and brute-force evaluation.

• Monitoring Search Progress and Restart Convergence Trajectories: Monitor search progress across restarts and track candidate evaluations and swaps.

• Side-by-Side Comparison: CLARANS, FastCLARANS, and K-Means: Direct visual comparison between CLARANS, FastCLARANS, and K-Means.

• Runtime Scaling vs. Dataset Size (num_local=2): Measure execution time scaling across sample sizes.

• Parameter Sensitivity: num_local vs. max_neighbors: Analyze trade-offs across num_local and max_neighbors.

Interactive execution

All scripts are available in the examples directory on GitHub.

An interactive notebook is available on Google Colab: