Skip to content
v0.1.3latest release121 skills4 categories6 sub-categories247 tested scripts397 reference docsContact us
Vector Agentic Skills
Submit a skill

clustering-algorithm-selector

Choose the right clustering algorithm and check that clustering makes sense at all: cluster tendency (Hopkins statistic with a correlated-features caveat, nearest-neighbour isolation), then k-means / MiniBatchKMeans, Gaussian mixtures with BIC, agglomerative (Ward, average, complete, single) with dendrograms, DBSCAN, HDBSCAN, OPTICS, spectral clustering, BIRCH, mean shift, k-prototypes and k-modes for mixed or categorical data, and Gower distance, matched to data size, expected shapes, noise, varying density, known k, soft memberships, hierarchy and streaming. Covers preprocessing (scaling, encoding, dimensionality, distance metrics), validation (internal indices, bootstrap stability, external labels, business profiling) and assigning new points. Use when someone wants to segment customers, group products or documents, find natural groups, asks which clustering algorithm to use, k-means vs DBSCAN vs HDBSCAN, or whether their clusters are real.

AI & Machine Learning / Classical Machine Learningv1.0.0Updated OCT 25 20264 references2 scripts

Clustering always returns clusters, so the first question is whether the data has structure worth finding, and the second is what kind: convex segments a business can act on (k-means, GMM, Ward), or arbitrary dense groups with noise left out (HDBSCAN, DBSCAN). The features and their scaling decide more than the algorithm. scripts/cluster_tendency.py measures cluster tendency (Hopkins statistic, isolation of points, correlated-feature caveat); scripts/select_clustering.py ranks algorithms for the data and the goal, with starting parameters and cautions.

Trigger Conditions

Activate this skill when the user:

  • Wants to segment customers, users, products, stores, documents or embeddings
  • Asks which clustering algorithm to use, or k-means vs DBSCAN vs HDBSCAN vs hierarchical vs GMM
  • Has mixed numeric and categorical data to cluster
  • Got clusters and wants to know whether they are real, stable or useful
  • Needs to assign new records to existing segments

Choosing k for k-means: kmeans-cluster-count-finder; DBSCAN parameters: dbscan-parameter-tuner; reducing dimensions first: pca-dimensionality-reducer and umap-tsne-embedding-visualizer; scaling: feature-scaling-advisor.

Workflow

text
1. GOAL       -> what decision do the segments drive? fixed k? must every row be assigned?
2. FEATURES   -> behaviour features, no IDs/labels; transform skew; scale; handle categoricals
3. TENDENCY   -> python scripts/cluster_tendency.py data.csv --drop id   (H > 0.75 clustered, ~0.5 random)
4. SELECT     -> python scripts/select_clustering.py --csv data.csv --drop id [--k-known 5 --noise ...]
5. FIT 2-3    -> top candidates; choose k / density parameters with the dedicated skills
6. VALIDATE   -> internal index matching the algorithm, bootstrap stability (ARI), profiles, outcome differences
7. OPERATE    -> naming, assignment of new rows (predict or a classifier), refresh cadence, drift of segment sizes

Is There Anything to Cluster?

text
Hopkins H = 0.856 (blobs fixture: 3 groups + noise)   -> clustered
Hopkins H = 0.535 (uniform fixture)                   -> no clear structure (close to random)
Hopkins H = 0.728 + 13 pairs with |r| > 0.7 (wide)    -> correlated features, not necessarily clusters
  • H measures departure from uniform randomness. Strongly correlated features (points on a low-dimensional manifold) raise H without forming groups; the script warns when many column pairs have |r| > 0.7. Re-check on a few principal components.
  • A high share of isolated points (> 3x the median nearest-neighbour distance) favours density methods that can label noise.

Selection Table

SituationFirst choiceAlternatives
k fixed by the business, numeric, convex segmentsk-means (MiniBatchKMeans if large)GMM, Ward
Overlapping groups, need probabilitiesGaussian mixture (BIC for k)HDBSCAN soft clustering
Arbitrary shapes, noise, unknown kHDBSCANDBSCAN (single density), OPTICS
Varying densitiesHDBSCANOPTICS
Need a hierarchy / drill-downAgglomerative + dendrogramHDBSCAN condensed tree
Non-convex, small data, k knownSpectral clusteringHDBSCAN
Streaming / huge dataMiniBatchKMeans, BIRCHHDBSCAN on a sample + classifier
Mixed numeric + categoricalk-prototypesGower + agglomerative / HDBSCAN
Categorical onlyk-modesGower / Jaccard + agglomerative
Embeddings / textUMAP -> HDBSCANk-means on normalised embeddings
Geographic pointsHDBSCAN / DBSCAN with haversinegrid aggregation

Assumptions, scaling limits and typical pipelines: algorithm-guide.md.

Preprocessing Decides the Result

  1. Choose features that describe the differences you want segments to capture.
  2. log1p skewed amounts and counts; standardise (or robust-scale) everything.
  3. Categoricals: a dedicated method (k-prototypes, Gower) or carefully down-weighted one-hot.
  4. Remove redundant copies of the same signal (they double its weight).
  5. Reduce dimensions above ~20-50 features (PCA for centroid methods, UMAP for density methods); never cluster on a 2-D t-SNE map.

Details and metric choice per data type: preprocessing-for-clustering.md.

Validating Clusters

CheckHowGood sign
Internal indexsilhouette / CH / DB for centroid methods; DBCV for density methodsclear optimum, not just "higher with k"
Stabilityrefit on 80% subsamples / new seeds; adjusted Rand indexARI > 0.8
Profilesfeature means per cluster relative to the populationnameable, distinct segments
Outcomeschurn / spend / response by clusterreal differences
Actionabilityone action per segmentyes
Sizeshare per clusterno trivial (< 1-2%) segments unless they are the point

Code: validating-clusters.md. Verified recipes for every algorithm (k-means, GMM/BIC, HDBSCAN, DBSCAN, agglomerative + dendrogram, spectral, k-prototypes, Gower, k-modes) and how to assign new points: clustering-recipes.md. Note from the fixture: with 5% uniform noise, GMM's BIC keeps adding components (minimum at k = 8 vs k = 3 without noise); handle noise first.

Output Format

When recommending a clustering approach, deliver:

  1. Goal and constraints - decision, k fixed or free, noise allowed, soft or hard, hierarchy.
  2. Tendency - Hopkins H, isolated share, correlation caveat (cluster_tendency.py).
  3. Preprocessing - features, transforms, scaling, categorical handling, dimensionality reduction.
  4. Ranked algorithms - top 2-3 with starting parameters (select_clustering.py).
  5. Validation plan - index, stability, profiling, outcome comparison.
  6. Operational plan - assigning new rows, refresh cadence, monitoring segment sizes.

Scripts

bash
python scripts/cluster_tendency.py data.csv --drop customer_id
python scripts/cluster_tendency.py data.csv --columns x1 x2 x3 --sample 300 --repeats 10 --json
python scripts/cluster_tendency.py data.csv --power d          # dimension-adjusted Hopkins variant

Standardises numeric columns, averages the Hopkins statistic over repeats (uniform points in the bounding box vs sampled data points), reports the nearest-neighbour distance CV and isolated-point share, and lists column pairs with |r| > 0.7. Exit codes: 0 clustered (H > 0.7), 1 no clear structure, 2 usage or read error.

bash
python scripts/select_clustering.py --csv customers.csv --drop customer_id
python scripts/select_clustering.py --rows 2000000 --dims 12 --k-known 5 --streaming
python scripts/select_clustering.py --rows 5000 --dims 3 --shapes arbitrary --noise --varying-density --json

Scores 11-13 algorithms (k-means, GMM, HDBSCAN, DBSCAN, Ward, spectral, BIRCH, OPTICS, mean shift, plus k-prototypes / Gower for mixed data and k-modes for categorical data) from rows, dimensions, categorical count and the goal flags, and prints why, a starting configuration and cautions for each. Exit codes: 0 printed, 2 usage or read error.

Additional Resources

FileContent
algorithm-guide.mdAssumptions, k, noise, shapes, scale and soft assignment per algorithm; decision questions; typical pipelines; limits of clustering
preprocessing-for-clustering.mdFeature choice, scaling, categorical handling, dimensionality reduction, distance metrics, outliers
validating-clusters.mdInternal indices and their biases, bootstrap stability, external labels, profiling, business validation
clustering-recipes.mdVerified code for each algorithm, mixed-type options, assigning new points
More in Classical Machine Learning

anomaly-detection-model-builder

Build and evaluate anomaly detection for tabular, sensor and transaction data with few or no labels: define the anomaly type (point, contextual, collective), choose detectors (robust z-score/MAD and IQR rules, Mahalanobis with robust covariance, k-NN distance, LOF, Isolation Forest, one-class SVM, PCA reconstruction / autoencoders, forecasting residuals for time series), combine them by rank, explain each alert by its deviating features, set thresholds from an alert budget or the score distribution, and evaluate with precision@k, PR-AUC and recall on known incidents, or detector agreement when no labels exist. Includes pure-Python detectors (robust z, Mahalanobis, kNN, Isolation Forest, ensemble) and an evaluation script.

catboost-model-builder

Build CatBoost models that use its strengths correctly: raw categorical columns as cat_features (ordered target statistics, no manual encoding), text_features, Pool construction with NaN-safe categories, ordered boosting and has_time for temporal data, symmetric (oblivious) trees, overfitting detector with eval_set and use_best_model, losses for classification, regression (Quantile, Poisson, Tweedie) and ranking (YetiRank), class weights, monotone constraints, feature importance (PredictionValuesChange, LossFunctionChange) and SHAP values, GPU training and model export. Plans cat/text/numeric columns from a CSV and generates a runnable training script, and checks parameter sets for the conflicts CatBoost rejects (iterations vs n_estimators, Bayesian bootstrap with subsample, multiple class-weight options, depth > 16, use_best_model without eval_set).

categorical-encoding-selector

Choose and implement the right encoding for every categorical column given the model family and the data: one-hot (with infrequent-level grouping and handle_unknown), ordinal with an explicit order, cross-fitted target encoding (scikit-learn TargetEncoder, CatBoost ordered statistics, category_encoders inside CV), frequency/count encoding, feature hashing, native categorical support in LightGBM, HistGradientBoosting, XGBoost and CatBoost, prefix levels for codes (zip3, NAICS-2), and embeddings. Measures cardinality, rare-level share, unseen-level rate on a time-ordered holdout and target signal per column, emits the ColumnTransformer, and quantifies target-encoding leakage (in-sample vs out-of-fold vs holdout AUC).

classification-model-selector

Choose the right classification algorithm for tabular, text or mixed data and prove the choice with a fair bake-off: logistic regression (L2, L1, elastic net), linear SVM, naive Bayes, k-NN, RBF SVM, decision trees, random forest, extra trees, HistGradientBoosting, LightGBM, XGBoost, CatBoost, explainable boosting machines (EBM/GAM), points scorecards and MLPs, matched to data size, width, categorical and high-cardinality share, missingness, class imbalance, text, and constraints such as interpretability, monotonic constraints, calibrated probabilities, latency budgets and tiny deployable models. Ranks candidates with starting hyperparameters and cautions, then generates a bake-off script running every candidate on identical CV folds with per-fold metrics, fit time and prediction latency.

collaborative-filtering-implementer

Implement collaborative filtering recommenders that beat popularity: item-based kNN with cosine, Jaccard or asymmetric similarity, shrinkage, neighbourhood size, positive-only or mean-centred rating signals and 'because you liked X' explanations; implicit ALS with confidence weighting, BPR pairwise ranking and the closed-form EASE model in plain NumPy, tuned on a temporal validation split by recall@k and NDCG@k and refit on all data; plus user-kNN, explicit matrix factorisation, the implicit/LightFM libraries, hyperparameter ranges, cold-start fallbacks, scaling with sparse matrices and approximate nearest neighbours. Produces top-k lists in the format of the recommendation evaluator.

counterfactual-explanation-generator

Generate counterfactual explanations and algorithmic recourse: the smallest realistic change to a row's features that changes the model's decision. Solves exact minimal-cost recourse for linear and logistic models (MAD-scaled L1 cost, immutable features, increase/decrease directions, bounds, integer and binary features, diverse alternatives, features every counterfactual must change, and a no-recourse finding when immutable features decide), generates DiCE counterfactuals for any scikit-learn model with constraints turned into permitted ranges and every result re-predicted, and validates counterfactuals from any method for constraint violations, implausible values, off-manifold rows, broken derived-feature relations and failure to flip the prediction.