feat: Add HDBSCAN clustering method

[ChenChihYuan]

Add HDBSCAN Clustering Method

Summary

This PR adds Cluster.HDBSCAN() — a pure numpy/scipy implementation of the Hierarchical Density-Based Spatial Clustering of Applications with Noise algorithm to topologicpy's Cluster class. It also adds demonstration and comparison cells to the Unsupervised_Learning.ipynb notebook.

Motivation

DBSCAN requires users to specify an epsilon (neighborhood radius) parameter, which can be difficult to tune — especially for datasets with clusters of varying density. HDBSCAN eliminates this requirement by building a hierarchical density-based clustering and automatically extracting the most stable clusters. This makes it a more robust, general-purpose density-based clustering method.

Implementation Details

Algorithm (Cluster.HDBSCAN()):

1. Core distances — For each point, compute the distance to its minSamples-th nearest neighbor
2. Mutual reachability matrix — Build a distance matrix where d_mreach(a,b) = max(core(a), core(b), d(a,b))
3. Minimum spanning tree — Construct via Prim's algorithm on the mutual reachability graph
4. Condensed cluster tree — Walk the single-linkage dendrogram top-down, splitting only when both children have ≥ minClusterSize points
5. Cluster extraction — Select the most stable clusters using either Excess of Mass (eom) or leaf method

API (follows existing Cluster.DBSCAN() conventions):

Cluster.HDBSCAN(
    topologies,                    # List of topologicpy Topology objects
    selectors=None,                # Optional selector points
    keys=["x", "y", "z"],          # Dictionary keys for feature extraction
    minClusterSize=5,              # Minimum cluster size
    minSamples=None,               # Core distance neighbor count (defaults to minClusterSize)
    clusterSelectionMethod="eom"   # "eom" or "leaf"
)
# Returns: (list_of_clusters, noise_cluster_or_None)

Dependencies: Uses only numpy and scipy (both already imported in Cluster.py). No new dependencies.

Notebook additions (12 cells in Unsupervised_Learning.ipynb):

• HDBSCAN on spiral data with visualization
• HDBSCAN on gallery floor plan with visualization
• DBSCAN vs HDBSCAN comparison table

Testing

• All 14 existing pytest tests pass
• Verified on synthetic Gaussian clusters (correctly identifies 3 clusters)
• Verified on elongated and varying-density clusters
• Verified on spiral and gallery floor plan datasets in the notebook

[wassimj]

Hi @ChenChihYuan. Can you please re-send this with just the changed to Cluster.py without the jupyter notebook? Thanks!

[ChenChihYuan]

Yes I will do that. Sorry for bothering! DBSCAN for AEC usage looks pretty great so I thought about using HDBSCAN.