Quick Reference · hierarchical density-based clustering

hdbscan cheat sheet

HDBSCAN finds clusters of varying density and leaves the rest as noise — no need to guess the number of clusters or a single distance threshold. It reshapes space by density, builds a cluster hierarchy, then keeps the most stable clusters. Two dials do most of the work: min_cluster_size (how big a group must be) and min_samples (how conservative to be about noise).

data & setup density · min_samples, metric hierarchy · min_cluster_size, selection fit / run labels & prediction pitfall ★ most common

Distilled & cross-checked across: hdbscan.readthedocs.io (docs · API · parameter selection · how it works) · Campello, Moulavi & Sander, 2013 · McInnes, Healy & Astels — JOSS 2017 · Malzer & Baum, 2019 (ε) · scikit-learn

How a clustering is built — & the two dials that steer it

01Install & Importonce per env

pip install hdbscan★
The standalone library (needs a C compiler).
conda install -c conda-forge hdbscan
Prebuilt — no compiler needed.
import hdbscan★
Then hdbscan.HDBSCAN(...).
from sklearn.cluster import HDBSCAN
In sklearn ≥ 1.3 — fewer extras than standalone. To match results, sklearn's min_samples must be 1 greater than this package's.

0260-Second Startcluster & read

c = hdbscan.HDBSCAN(min_cluster_size=15)★
Create the clusterer.
c.fit(X)★
Run the clustering.
labels = c.labels_★
One label per point; −1 = noise.
labels = c.fit_predict(X)★
Fit + return labels in one call.
n = labels.max() + 1
Number of clusters found (noise excluded).
plt.scatter(*X.T, c=labels, s=5)
Color points by cluster.

03Core parameterswhat to tune

min_cluster_size=5★
Smallest group that counts as a cluster.
min_samples=None★
How conservative; defaults to min_cluster_size.
cluster_selection_method="eom"
"eom" few big · "leaf" many small.
metric="euclidean"
Distance in the input space.
cluster_selection_epsilon=0.0
Merge clusters closer than this (DBSCAN-ish floor).

04min_cluster_size · granularitytune this first

min_cluster_size=5★
Default; small groups still count.
min_cluster_size=50..100
Fewer, larger, core clusters.
# set to the smallest group you care about
Its meaning is intuitive — pick by domain.
# too small ⇒ micro-clusters
Larger values are more robust to noise.

05min_samples · conservativenessthe noise dial

min_samples=None★
Defaults to min_cluster_size.
min_samples=1
Little noise; clusters reach further out.
min_samples=25
Dense cores; more points called noise.
# set it apart from min_cluster_size
Decouple to tune granularity & noise separately.

06Cluster selectionreading the tree

cluster_selection_method="eom"★
Excess of Mass — a few most-persistent clusters.
cluster_selection_method="leaf"
Many small, homogeneous, fine clusters.
allow_single_cluster=True
Permit one big cluster (off by default).
cluster_selection_epsilon=0.5
Stop splitting below a distance — merges micro-clusters.
max_cluster_size=0
Cap eom cluster size (0 = no limit).

07Metrics & inputmeasuring distance

metric="euclidean"★
Default; general numeric data.
metric="manhattan"
Other tree-supported metrics.
metric="minkowski", p=3
Pass extra args as kwargs.
metric="haversine"
Lat/lon in radians.
metric="precomputed"
X is a square distance matrix.
# cosine not in the fast trees
Normalize rows + euclidean, or precompute.

08Reading the resultfitted attributes

c.labels_★
Cluster id per point; −1 is noise.
c.probabilities_★
Membership strength 0–1 (0 for noise).
c.cluster_persistence_
Stability score per cluster (1 = rock-solid).
c.outlier_scores_
GLOSH outlier score per point.
c.exemplars_
Representative points (needs prediction_data).

09Predict new pointsassign unseen data

hdbscan.HDBSCAN(prediction_data=True)★
Cache what's needed to predict later.
c.generate_prediction_data()
Or enable it after fitting.
labels, probs = hdbscan.approximate_predict(c, X_new)★
Assign new points to existing clusters.
hdbscan.approximate_predict_scores(c, X_new)
Outlier score for new points.
# not a full re-clustering
Re-fit if the data shifts a lot.

10Soft clusteringfuzzy membership

hdbscan.all_points_membership_vectors(c)★
(n × k) — each point's membership to every cluster.
hdbscan.membership_vector(c, X_new)
Soft-assign new points across clusters.
vecs.argmax(axis=1)
Hard label = strongest membership.
# requires prediction_data=True
Same cached data as approximate_predict.

11Visualize the hierarchythe signature plots

c.condensed_tree_.plot(select_clusters=True)★
Icicle plot — see which clusters were chosen.
c.single_linkage_tree_.plot()
Full dendrogram of the merge hierarchy.
c.condensed_tree_.to_pandas()
parent · child · lambda_val · child_size.
c.minimum_spanning_tree_.plot()
Needs gen_min_span_tree=True at init.

12Outliers & validityscore the result

c.outlier_scores_★
Higher = more outlier-like (GLOSH).
np.quantile(c.outlier_scores_, 0.9)
Threshold to flag the top outliers.
c.relative_validity_
Fast DBCV — compare across hyper-params.
hdbscan.validity.validity_index(X, labels)
Full DBCV score (−1 … 1, higher better).

13DBSCAN* & speedextras & scale

c.dbscan_clustering(cut_distance=0.3)
Extract a DBSCAN* clustering for free.
core_dist_n_jobs=-1★
Parallelize core-distance computation.
algorithm="best"
Auto-pick; or boruvka_kdtree for big data.
gen_min_span_tree=True
Enable the MST plot & relative_validity_.
memory="./cache"
Cache the hard computation across re-runs.

★Recommended recipesensible starting point

min_cluster_size = smallest meaningful group
Pick by domain, then adjust.
min_samples=None → lower it
Drop it to reduce noise if too much is −1.
cluster_selection_method="eom"
"leaf" when you want many fine clusters.
PCA / UMAP → HDBSCAN
Reduce high-dim first, cluster the result.
condensed_tree_.plot(select_clusters=True)
Always eyeball the chosen clusters.
prediction_data=True
If you'll assign new points later.

!Watch out forcommon gotchas

noise is a feature (−1)by design
HDBSCAN won't force outliers into clusters.
min_samples = min_cluster_sizedefault
Set it explicitly to control noise.
raw high-dim ⇒ poor clusterscare
Reduce dimensions first.
all-noise result?care
Lower min_cluster_size / try allow_single_cluster.
probabilities_ ≠ confidencecare
It's persistence-based membership strength.

How the pieces shape the clustering

Four ideas that decide what HDBSCAN returns — based on the “How HDBSCAN Works” and parameter-selection guides.

the condensed tree

As the density threshold rises, points “fall out” of clusters and bars narrow. HDBSCAN keeps the most persistent branches (Excess of Mass) — circled here.

min_cluster_size: fine ↔ coarse

Small values keep many little clusters; large values merge them and prune the small ones as noise.

min_samples: less ↔ more noise

Low values let clusters absorb sparse fringes; high values pull clusters into dense cores and declare the fringes noise.

why not k-means / DBSCAN

With clusters of different density, k-means splits by distance alone and DBSCAN's single ε can't fit all. HDBSCAN varies the threshold per region.

Worth memorizing

min_cluster_size = granularitysmallest group that's a cluster — the dial you tune first

min_samples = conservativenesshigher ⇒ more noise & denser cores; defaults to min_cluster_size

noise is label −1HDBSCAN refuses to force outliers into clusters

eom vs leafeom = a few big clusters · leaf = many small homogeneous ones

probabilities_membership strength (persistence), not classifier confidence

no n_clusters neededdensity finds the count for you (unlike k-means)

varying densityhandled natively — plain DBSCAN's single ε can't

reduce first on high-DPCA / UMAP → HDBSCAN beats raw high-dim

prediction_data=Trueenables approximate_predict for new points

the one plotcondensed_tree_.plot(select_clusters=True)

hdbscan cheat sheet · synthesized from the official documentation (hdbscan.readthedocs.io — basic usage, parameter selection, “How HDBSCAN Works” & API), Campello, Moulavi & Sander, “Density-Based Clustering Based on Hierarchical Density Estimates” (2013), McInnes, Healy & Astels, “hdbscan: Hierarchical density based clustering” (JOSS, 2017), Malzer & Baum (ε selection, 2019), and scikit-learn.
API shown for hdbscan 0.8.41 (current, re-verified 2026-08-28; sklearn ships cluster.HDBSCAN natively since 1.3) · defaults: min_cluster_size=5, min_samples=None (→ = min_cluster_size), metric="euclidean", cluster_selection_method="eom", allow_single_cluster=False.