正在加载中...

展开本页目录
算法教程HDBSCAN-HDBSCAN

HDBSCAN-HDBSCAN

No.118 · 在线教程

HDBSCAN（Hierarchical Density-Based Spatial Clustering of Applications with Noise）可以看作 DBSCAN 的层次化扩展。它不再依赖单一固定密度阈值，而是通过互可达距离构造层次聚类结构，再从层次树中选…

返回教程目录 算法详情 下载方式 购买授权

HDBSCAN-HDBSCAN

1. 方法概述

HDBSCAN（Hierarchical Density-Based Spatial Clustering of Applications with Noise）可以看作 DBSCAN 的层次化扩展。它不再依赖单一固定密度阈值，而是通过互可达距离构造层次聚类结构，再从层次树中选择稳定簇，因此更适合处理不同密度水平并存的数据，同时保留对噪声点的识别能力。

本项目中的 HDBSCAN-HDBSCAN 模块不是自写密度树算法，而是对 hdbscan.HDBSCAN 的工程化封装。程序支持：

  1. min_cluster_size、min_samples、alpha、cluster_selection_method、cluster_selection_epsilon 等 HDBSCAN 关键参数；
  2. euclidean、manhattan、cosine 三种距离度量；
  3. none、minmax、zscore 三种预处理方式；
  4. 输出样本标签、成员概率、簇稳定性、噪声比例、概率分布图与复现脚本。

设共有 \(n\) 个样本、\(p\) 个参与聚类的数值特征。对选定特征列构成原始特征矩阵

$$ X=(x_{ij})_{n\times p},\quad i=1,2,\ldots,n,\ j=1,2,\ldots,p \tag{1} $$

若用户指定 label_col，该列仅用于样本标识回填，不参与距离计算；若未指定，则程序自动生成 样本1, 样本2, \ldots, 样本n 作为样本名称。

2. 问题定义与数据预处理

记第 \(i\) 个样本的特征向量为 \(x_i\in\mathbb{R}^p\)。项目支持 none、minmax、zscore 三种预处理模式。

2.1 Min-Max 归一化

当 normalize="minmax" 时，第 \(j\) 个特征按

$$ z_{ij}=\frac{x_{ij}-x_j^{\min}}{x_j^{\max}-x_j^{\min}} \tag{2} $$

映射到 \([0,1]\) 区间。若某列极差为 0，代码会把缩放因子置为 1 以避免除零。

2.2 Z-score 标准化

当 normalize="zscore" 时，第 \(j\) 个特征按

$$ z_{ij}=\frac{x_{ij}-\bar x_j}{s_j} \tag{3} $$

进行标准化，其中 \(\bar x_j\) 为均值，\(s_j\) 为总体标准差。

若 normalize="none"，则直接令 \(z_{ij}=x_{ij}\)。经预处理后得到用于 HDBSCAN 的输入矩阵

$$ Z=(z_{ij})_{n\times p} \tag{4} $$

2.3 符号说明

符号 含义
\(n\) 样本数量
\(p\) 特征维数
\(z_i\) 第 \(i\) 个样本的预处理后特征向量
\(m\) 邻域规模参数，底层实际使用的 min_samples
\(d(\cdot,\cdot)\) 选定的距离度量
\(\alpha\) robust single linkage 距离缩放参数
\(d_{\text{core}}(z_i)\) 样本 \(z_i\) 的核距离
\(d_{\text{mreach}}(z_i,z_j)\) 样本 \(z_i,z_j\) 的互可达距离
\(y_i\) 第 \(i\) 个样本的聚类标签，\(-1\) 表示噪声
\(p_i\) 第 \(i\) 个样本的成员概率 probabilities_
\(s_k\) 第 \(k\) 个簇的稳定性 cluster_persistence_

3. 核心数学模型

3.1 邻域规模与距离缩放

当前界面中，min_samples 输入框允许用户填 0，其工程含义是“自动”。项目在进入底层库前会把 0 转为 None；根据随包参考源码，底层 hdbscan.HDBSCAN 在 min_samples=None 时会令实际邻域规模等于 min_cluster_size。因此，算法真正使用的邻域规模 \(m\) 可写为

$$ m= \begin{cases} \texttt{min\_samples}, & \texttt{min\_samples}\neq \texttt{None}\\[4pt] \texttt{min\_cluster\_size}, & \texttt{min\_samples}=\texttt{None} \end{cases} \tag{5} $$

此外，底层实现会先对样本间距离做 distance_matrix /= alpha 处理，因此可将缩放后的距离写为

$$ \tilde d(z_i,z_j)=\frac{d(z_i,z_j)}{\alpha} \tag{6} $$

其中 \(\alpha>0\) 为 alpha 参数。当前界面允许范围为 0.1 到 5.0，默认值为 1.0。

3.2 核距离与互可达距离

设 \(z_{i,(m)}\) 表示样本 \(z_i\) 在缩放距离 \(\tilde d\) 下的第 \(m\) 近邻，则核距离定义为

$$ d_{\text{core}}(z_i)=\tilde d\!\left(z_i,z_{i,(m)}\right) \tag{7} $$

进一步，HDBSCAN 构造互可达距离

$$ d_{\text{mreach}}(z_i,z_j)= \max\left\{ d_{\text{core}}(z_i),\ d_{\text{core}}(z_j),\ \tilde d(z_i,z_j) \right\} \tag{8} $$

与 DBSCAN 仅在单一半径 \(\varepsilon\) 下做密度扩张不同，HDBSCAN 正是基于式(8) 在不同密度尺度上建立层次结构。

3.3 最小生成树与层次簇选择

底层实现会基于互可达距离图构造最小生成树（Minimum Spanning Tree, MST），并进一步转为单链接层次树。记互可达图为 \(G=(V,E)\)，则最小生成树可记为

$$ T=\operatorname{MST}\!\left(G,\ d_{\text{mreach}}\right) \tag{9} $$

随后，HDBSCAN 从该层次结构中提取稳定簇。当前项目暴露两种簇选择方法：

  1. eom：Excess of Mass，倾向于选择更稳定、更持续的簇；
  2. leaf：选择层次树叶节点，通常得到更细粒度的簇划分。

同时，cluster_selection_epsilon 作为距离阈值，用于控制过近簇的合并。

3.4 项目输出中的标签、概率与稳定性

拟合完成后，底层库返回每个样本的原始标签 labels_。在当前项目中，非噪声簇会保留底层整数编号，噪声统一记为

$$ y_i=-1 \tag{10} $$

项目同时输出样本成员概率 probabilities_，记为

$$ p_i\in[0,1] \tag{11} $$

该值越大，表示样本越稳定地属于当前分配的簇；根据随包参考源码和属性说明，噪声样本的概率为 0。

程序统计的噪声比例为

$$ \rho_{\text{noise}}=\frac{1}{n}\sum_{i=1}^{n}\mathbf{1}(y_i=-1) \tag{12} $$

非噪声簇数量为

$$ K=\left|\{y_i\mid y_i\neq -1\}\right| \tag{13} $$

对某个具体簇 \(k\)，项目在 ClusterSummary 中输出其平均概率

$$ \bar p_k=\frac{1}{n_k}\sum_{i:y_i=k}p_i \tag{14} $$

并在 Persistence 表中输出对应簇稳定性 \(s_k\)。这里的 \(s_k\) 直接来自底层 cluster_persistence_ 属性，数值越大通常表示该簇在层次结构中越稳定。

4. 算法流程

结合当前项目实现，HDBSCAN-HDBSCAN 的实际计算流程如下：

  1. 读取 .xlsx、.xls 或 .csv 文件；CSV 会依次尝试 utf-8-sig、utf-8、gbk 编码。
  2. 上传阶段检查数据中是否至少存在一个完整可转为数值的列。
  3. 在“特征设置”页选择可选样本名称列 label_col，并勾选参与聚类的数值特征列。
  4. 程序检查所选特征列是否存在空值、非数值项或常数列。
  5. 按 normalize 设置对特征矩阵进行预处理，得到 \(Z\)。
  6. 将界面参数组装为 HDBSCANParams，并把 min_samples<=0 的情形转换为 None。
  7. 调用 hdbscan.HDBSCAN(...).fit(Z) 执行聚类，其中当前封装固定 gen_min_span_tree=True、core_dist_n_jobs=1。
  8. 提取底层 labels_、probabilities_、cluster_persistence_ 等结果，生成标签表、簇汇总表和指标表。
  9. 绘制聚类散点图 cluster_scatter.png 与概率直方图 probability_hist.png。
  10. 导出 Excel 文件 hdbscan_results.xlsx，并自动生成复现脚本 repro_hdbscan_hdbscan.py。

5. 关键参数说明

5.1 min_cluster_size

最小簇大小，界面允许范围为 2 到 200，默认值为 5。它决定一个样本组至少要包含多少个点，才能在簇选择阶段被保留为有效簇。

5.2 min_samples

邻域规模参数，界面允许范围为 0 到 200，默认值为 0。其中：

  1. 输入 0 表示自动，程序会传入 None；
  2. 底层库在 None 时会将其替换为 min_cluster_size；
  3. 该值越大，算法通常越保守，更容易把低密度区域识别为噪声。

5.3 metric

距离度量，当前界面支持：

  1. euclidean
  2. manhattan
  3. cosine

该参数直接传入 hdbscan.HDBSCAN。不同距离度量会改变核距离与互可达距离，从而显著影响簇结构。

5.4 alpha

距离缩放参数，界面允许范围为 0.1 到 5.0，默认值为 1.0。根据当前项目所依赖实现，其作用体现在距离矩阵先除以 \(\alpha\) 后再进入互可达距离计算。

5.5 cluster_selection_method

簇选择方法，可选：

  1. eom
  2. leaf

默认值为 eom。eom 倾向于给出更稳定的主簇，leaf 往往给出更细粒度的叶节点簇。

5.6 cluster_selection_epsilon

簇选择阈值，界面允许范围为 0.0 到 5.0，默认值为 0.0。该值越大，越倾向于合并距离上彼此较近的簇。

5.7 allow_single_cluster

是否允许单簇结果，界面取值为“否/是”，默认值为“否”。当数据整体结构接近一个单簇时，启用该选项可允许底层算法返回单一簇，而不是强制拆分或主要识别为噪声。

5.8 normalize

预处理方式与界面映射关系如下：

  • 无 → none
  • Min-Max → minmax
  • Z-Score → zscore

当特征量纲差异较大时，通常建议优先尝试 minmax 或 zscore。

6. 评价指标与输出结果解释

程序导出的 Excel 文件固定命名为 hdbscan_results.xlsx。在当前开发环境下，结果目录通常形如：

results/HDBSCAN-HDBSCAN分析结果_<时间戳>/

若软件被打包运行，则结果目录会写入用户目录下的 ~/.HDBSCAN-HDBSCAN系统/results/。当前实现会输出以下工作表：

  1. Parameters：参数配置、特征列、样本数与输出文件路径。
  2. RawData：原始数据表。
  3. ProcessedData：预处理后的建模数据，包含样本名称列与特征列。
  4. Labels：样本名称、底层簇标签、项目映射后的簇名称与成员概率。
  5. ClusterSummary：各簇样本数与平均概率；若存在噪声，也会单独统计“噪声”一行。
  6. Persistence：各非噪声簇的稳定性。
  7. Metrics：簇数量、噪声比例、平均概率、最大概率、最小概率。
  8. Charts：图表路径索引。

同时，结果目录下还会生成：

  1. plots/cluster_scatter.png
  2. plots/probability_hist.png
  3. repro_hdbscan_hdbscan.py
  4. repro_inputs/ 下的复现输入文件

从结果解释角度看：

  1. 簇标签 是底层 HDBSCAN 返回的原始整数标签，噪声为 -1。
  2. 簇名称 是项目为便于展示而生成的别名，如 C1、C2；它是对非噪声簇按标签排序后重新命名的结果。
  3. 概率 越高，说明样本越稳定地属于当前簇；噪声点的概率通常为 0。
  4. Persistence 越高，通常表示该簇在层次结构中的稳定性越强。
  5. Metrics 中的“簇数量”不包含噪声簇。
  6. cluster_scatter.png 仅使用处理后数据的前两维绘图；当仅有一个特征时，程序会绘制单轴散点图。
  7. probability_hist.png 用于观察样本成员概率的整体分布，高概率样本占比越大，通常说明聚类结构越清晰。
  8. 结果页界面中的标签表只预览前 50 行，完整结果应以导出的 Excel 为准。

7. 论文写作模板

7.1 方法描述模板

可将当前项目实现表述为：

“本文采用 HDBSCAN 方法对样本进行密度聚类分析。首先选取研究对象的数值型指标，并根据需要进行归一化或标准化处理。随后基于样本间距离构造核距离与互可达距离，通过最小生成树建立单链接层次结构，并从层次簇树中选取稳定簇。与 DBSCAN 依赖单一密度阈值不同，HDBSCAN 能够在不同密度水平下识别簇结构，同时将无法稳定归属的样本识别为噪声。本文输出样本簇标签、成员概率、簇稳定性以及噪声比例等结果，用于刻画样本的层次密度结构与聚类可靠性。”

若需要更贴近本项目工程实现，还可补充说明：本文实现直接调用 hdbscan.HDBSCAN，支持 eom 与 leaf 两种簇选择策略，并输出 probabilities_ 与 cluster_persistence_ 作为样本归属强度和簇稳定性的解释依据。

7.2 结果解释模板

结果部分可写为：HDBSCAN 在不同密度层级下识别出若干稳定簇，并将稳定性不足的样本保留为噪声。样本成员概率越高，表示其越稳定地归属于某一簇；簇稳定性越高，则说明该簇在层次密度结构中更具可靠性。

7.3 表格标题模板

表题可写为：HDBSCAN 聚类标签、成员概率与簇稳定性结果表。

7.4 图表题注模板

图注可写为：HDBSCAN 密度聚类结果及噪声样本分布图。

7.5 表格示例

建议列名：样本编号、聚类标签、成员概率、簇稳定性、噪声标记、参数设置。

8. 实现说明与注意事项

  1. HDBSCAN 适合处理簇密度不一致、簇形状不规则且噪声点较多的数据场景。
  2. 当前实现要求所选特征列全部为数值型，且不能包含空值、非数值项或常数列。
  3. 若 min_cluster_size 或底层实际使用的 min_samples 大于样本数，底层库会直接报错，因此小样本场景下应避免设置过大的邻域规模。
  4. 当前封装依赖外部 hdbscan 包；若环境中未安装该依赖，程序会报错并提示先执行 pip install hdbscan。
  5. 虽然参数类中保留了 random_state 字段，但当前界面未暴露该参数，且拟合时也未把它传入 hdbscan.HDBSCAN，因此结果复现主要依赖输入数据、参数组合与库版本，而不是随机种子控制。
  6. 当前 Excel 输出并不导出最小生成树、单链接树或 condensed tree 本身，而是仅保留标签、概率、稳定性与汇总统计，因此若论文需要展示层次树结构，需要额外补充底层对象可视化。
  7. 簇名称 是项目层面的展示映射，真正参与计算和底层输出的是 簇标签；论文中若只需要结果解释，用 C1、C2 更直观，若需要严格对应原始库输出，则应保留整数标签。
  8. Metrics 中当前没有输出轮廓系数、Davies-Bouldin 或 Calinski-Harabasz 等传统无监督指标，因此本模块更强调“概率 + 稳定性 + 噪声比例”的解释口径。
  9. 当前散点图仅基于前两维处理后特征，不能完整代表高维空间中的真实层次密度结构。

9. 论文写作建议

论文中建议突出 HDBSCAN 的三个核心输出：

  1. 聚类标签；
  2. 样本概率或稳定性；
  3. 噪声比例。

如果需要和 DBSCAN 对比，正文里应强调 HDBSCAN 能处理不同密度簇，而不只是“自动找簇数”。结果表建议同时包含各簇样本数、稳定性摘要和噪声点比例。

10. 单篇终审补充

10.1 图题与表题对齐建议

当前 HDBSCAN 模块的真实工作簿包含：

  • Parameters
  • RawData
  • ProcessedData
  • Labels
  • ClusterSummary
  • Persistence
  • Metrics
  • Charts

其中 Persistence 是最能体现 HDBSCAN 特征的结果页，适合作为“簇稳定性结果表”在论文中单列引用；ClusterSummary 则适合做簇规模与噪声比例汇总。不要把这套输出写得和 DBSCAN 完全一样，因为当前实现比 DBSCAN 多了稳定性这一层。

图文件位于结果目录 plots/ 子目录，当前实现输出：

  • cluster_scatter.png
  • probability_hist.png

因此图题建议写成“HDBSCAN 聚类散点图”“HDBSCAN 样本概率分布直方图”。不要写成 condensed tree 或层次树图，因为当前程序并未导出这类图。

10.2 终审说明

这篇文档最需要避免的误写，是把 HDBSCAN 简化成“更高级的 DBSCAN”。从真实输出看，Persistence 和 probability_hist.png 才是与 DBSCAN 拉开差异的关键证据，它们对应簇稳定性和样本归属概率，而不是单纯的标签结果。

另外，当前 repro 脚本已经稳定采用 repro_inputs/... 相对路径，结果目录中可见 window1_hdbscan_input.csv 或 hdbscan_sample.xlsx 的副本引用。因此这一篇在“可复现性”表述上可以直接按新框架标准写。

10.3 全量强化补充

本篇终审补充绑定的真实算法目录为 具体的算法3/聚类与降维/HDBSCAN-HDBSCAN，本次采用的代表性结果目录为 具体的算法3/聚类与降维/HDBSCAN-HDBSCAN/results/HDBSCAN-HDBSCAN分析结果_20260329_171250。这一轮结果目录里主工作簿、两张主图、复现脚本和 repro_inputs 同轮共存，证据链比较完整。

主结果工作簿为 具体的算法3/聚类与降维/HDBSCAN-HDBSCAN/results/HDBSCAN-HDBSCAN分析结果_20260329_171250/hdbscan_results.xlsx，实测工作表如下：

  • Parameters
  • RawData
  • ProcessedData
  • Labels
  • ClusterSummary
  • Persistence
  • Metrics
  • Charts

这里最关键的是 Persistence 页真实存在，因此论文正文不应只把 HDBSCAN 写成“自动找簇数的密度聚类”，而应明确说明当前软件还导出了簇稳定性结果。若只引用 Labels 与 ClusterSummary，会把 HDBSCAN 与 DBSCAN 的核心差异写丢。

本轮真实图文件为：

  • 具体的算法3/聚类与降维/HDBSCAN-HDBSCAN/results/HDBSCAN-HDBSCAN分析结果_20260329_171250/plots/cluster_scatter.png
  • 具体的算法3/聚类与降维/HDBSCAN-HDBSCAN/results/HDBSCAN-HDBSCAN分析结果_20260329_171250/plots/probability_hist.png

因此该轮结果只能被表述为“散点图 + 概率直方图”的组合，不应额外声称已经导出了 condensed tree、single linkage tree 或层次树图。

复现实物方面，该目录实际包含：

  • 具体的算法3/聚类与降维/HDBSCAN-HDBSCAN/results/HDBSCAN-HDBSCAN分析结果_20260329_171250/repro_hdbscan_hdbscan.py
  • 具体的算法3/聚类与降维/HDBSCAN-HDBSCAN/results/HDBSCAN-HDBSCAN分析结果_20260329_171250/repro_inputs/window1_hdbscan_input.csv

脚本中已明确写成 INPUT_FILE = 'repro_inputs/window1_hdbscan_input.csv'。因此这一轮应如实描述为“主结果工作簿已落地，复现实验依赖结果目录中的相对路径输入副本”；当前目录并没有额外预置第二份 repro 输出工作簿，不能把脚本入口和再生产物混成一回事。

10. 软件实现核查补充（2026-07）

  • 当前主结果目录应写作 具体的算法3/聚类与降维/HDBSCAN-HDBSCAN/results/HDBSCAN-HDBSCAN分析结果_20260329_171250。
  • 正文应围绕 Labels、Probabilities、Persistence、ClusterSummary、Parameters、Charts 来写。
  • 图证应对应 cluster_scatter.png 与 probability_hist.png，并把稳定性概率与噪声点解释清楚。
  • 复现脚本应按 repro_hdbscan_hdbscan.py + repro_inputs/window1_hdbscan_input.csv 的口径说明。