.. image:: https://img.shields.io/pypi/v/hdbscan.svg :target: https://pypi.python.org/pypi/hdbscan/ :alt: PyPI 版本 .. image:: https://anaconda.org/conda-forge/hdbscan/badges/version.svg :target: https://anaconda.org/conda-forge/hdbscan :alt: Conda-forge 版本 .. image:: https://anaconda.org/conda-forge/hdbscan/badges/downloads.svg :target: https://anaconda.org/conda-forge/hdbscan :alt: Conda-forge 下载量 .. image:: https://img.shields.io/pypi/l/hdbscan.svg :target: https://github.com/scikit-learn-contrib/hdbscan/blob/master/LICENSE :alt: 许可证 .. image:: https://travis-ci.org/scikit-learn-contrib/hdbscan.svg :target: https://travis-ci.org/scikit-learn-contrib/hdbscan :alt: Travis 构建状态 .. image:: https://codecov.io/gh/scikit-learn-contrib/hdbscan/branch/master/graph/badge.svg :target: https://codecov.io/gh/scikit-learn-contrib/hdbscan :alt: 测试覆盖率 .. image:: https://readthedocs.org/projects/hdbscan/badge/?version=latest :target: https://hdbscan.readthedocs.org :alt: 文档 .. image:: http://joss.theoj.org/papers/10.21105/joss.00205/status.svg :target: http://joss.theoj.org/papers/10.21105/joss.00205 :alt: JOSS 文章 .. image:: https://mybinder.org/badge.svg :target: https://mybinder.org/v2/gh/scikit-learn-contrib/hdbscan :alt: 在 Binder 中启动示例笔记本

======= HDBSCAN

HDBSCAN - 噪声鲁棒的层次化密度聚类算法。该算法在不同的 ε 值上执行 DBSCAN，并整合结果以找到在不同 ε 值下具有最佳稳定性的聚类。这使得 HDBSCAN 能够发现不同密度的簇（与 DBSCAN 不同），并且对参数选择更加鲁棒。

在实践中，这意味着 HDBSCAN 可以在几乎无需调整参数的情况下直接给出良好的聚类结果——而其主要参数“最小簇大小”直观易懂，易于选择。

HDBSCAN 非常适合探索性数据分析；它是一种快速且鲁棒的算法，能够可靠地返回有意义的聚类（如果数据中确实存在聚类的话）。

基于以下论文：

McInnes L, Healy J. *加速的层次化密度聚类* 
在：2017 IEEE 国际数据挖掘研讨会 (ICDMW), IEEE, pp 33-42.
2017 `[pdf] <http://ieeexplore.ieee.org/stamp/stamp.jsp?tp=&arnumber=8215642>`_

R. Campello, D. Moulavi, 和 J. Sander, *基于层次化密度估计的密度聚类*
在：知识发现与数据挖掘进展, Springer, pp 160-172.
2013

文档，包括教程，可在 ReadTheDocs 上找到：http://hdbscan.readthedocs.io/en/latest/ 。

比较 HDBSCAN 与其他聚类算法的笔记本 <http://nbviewer.jupyter.org/github/scikit-learn-contrib/hdbscan/blob/master/notebooks/Comparing%20Clustering%20Algorithms.ipynb>、解释 HDBSCAN 工作原理的笔记本 <http://nbviewer.jupyter.org/github/scikit-learn-contrib/hdbscan/blob/master/notebooks/How%20HDBSCAN%20Works.ipynb> 以及 比较与其他 Python 聚类实现性能的笔记本 <http://nbviewer.jupyter.org/github/scikit-learn-contrib/hdbscan/blob/master/notebooks/Benchmarking%20scalability%20of%20clustering%20implementations-v0.7.ipynb>_ 均可获取。

---

如何使用 HDBSCAN

hdbscan 包继承自 sklearn 的类，因此可以无缝地与其他 sklearn 聚类器一起使用，调用接口完全一致。同样，它支持多种输入格式：形状为 (num_samples x num_features) 的数组（或 pandas 数据框、稀疏矩阵）；或者提供样本间距离矩阵的数组（或稀疏矩阵）。

.. code:: python

import hdbscan
from sklearn.datasets import make_blobs

data, _ = make_blobs(1000)

clusterer = hdbscan.HDBSCAN(min_cluster_size=10)
cluster_labels = clusterer.fit_predict(data)

---

性能

为了使 hdbscan 实现尽可能高效，开发团队付出了巨大努力。与 Java 中的参考实现相比，它的速度要快 几个数量级 <http://nbviewer.jupyter.org/github/scikit-learn-contrib/hdbscan/blob/master/notebooks/Python%20vs%20Java.ipynb>_ ，并且目前比 C 和 C++ 中高度优化的单链接实现还要快。版本 0.7 的性能可以在这个笔记本中查看 <http://nbviewer.jupyter.org/github/scikit-learn-contrib/hdbscan/blob/master/notebooks/Benchmarking%20scalability%20of%20clustering%20implementations-v0.7.ipynb>_ 。 特别是，在低维数据上的性能优于 sklearn 的 DBSCAN http://nbviewer.jupyter.org/github/scikit-learn-contrib/hdbscan/blob/master/notebooks/Benchmarking%20scalability%20of%20clustering%20implementations%202D%20v0.7.ipynb`_ ，并且通过 joblib 的缓存支持，使用不同参数重新聚类几乎是免费的。

---

附加功能

hdbscan 包附带了可视化工具，可以帮助您理解聚类结果。拟合数据后，聚类器对象具有以下属性：

• 紧凑的聚类层次结构
• 鲁棒的单链接聚类层次结构
• 可达性距离最小生成树

所有这些都配备了绘图方法，并且可以转换为 Pandas 或 NetworkX 格式以便进一步分析。有关示例和详细信息，请参阅关于 HDBSCAN 工作原理的笔记本 <http://nbviewer.jupyter.org/github/scikit-learn-contrib/hdbscan/blob/master/notebooks/How%20HDBSCAN%20Works.ipynb>_ 。

聚类器对象还包含一个提供簇成员隶属度的属性，从而实现可选的软聚类（且无需额外计算成本）。最后，每个簇还会获得一个持久性分数，用于衡量该簇在数据中存在的不同距离尺度范围内的稳定性。这为簇的相对强度提供了一个度量标准。

---

异常值检测

HDBSCAN 聚类器对象还支持 GLOSH 异常值检测算法。在将聚类器拟合到数据后，可以通过 outlier_scores_ 属性访问异常值得分。结果是一个得分向量，其中每个数据点对应一个得分值。得分越高，表示该点越可能是异常值。通常，通过选取高分位数来筛选异常值是一个不错的方法。

基于以下论文： R.J.G.B. Campello, D. Moulavi, A. Zimek 和 J. Sander 用于数据聚类、可视化和异常值检测的层次化密度估计, ACM 数据知识发现汇刊, 第 10 卷, 第 1 期 (2015 年 7 月), 1-51.

---

鲁棒单链接

hdbscan 包还支持 Chaudhuri 和 Dasgupta 提出的 鲁棒单链接 聚类算法。与 HDBSCAN 的实现类似，这也是该算法的一个高性能版本，性能优于 scipy 标准的单链接实现。鲁棒单链接层次结构作为鲁棒单链接聚类器的一个属性提供，同样具备绘制或导出层次结构、以及在给定切割水平和 gamma 值下提取扁平聚类的功能。

示例用法：

.. code:: python

import hdbscan
from sklearn.datasets import make_blobs

data, _ = make_blobs(1000)

clusterer = hdbscan.RobustSingleLinkage(cut=0.125, k=7)
cluster_labels = clusterer.fit_predict(data)
hierarchy = clusterer.cluster_hierarchy_
alt_labels = hierarchy.get_clusters(0.100, 5)
hierarchy.plot()

基于论文： K. Chaudhuri 和 S. Dasgupta. "聚类树的收敛速度。" 神经信息处理系统进展, 2010年.

---

分支检测

hdbscan 包支持由 Bot 等人提出的分支检测后处理步骤 https://peerj.com/articles/cs-2792/_。聚类形状，例如分支结构，可以揭示密度基聚类层次结构中无法表达的有趣模式。BranchDetector 类模仿了 HDBSCAN 的 API，可用于检测聚类中的分支层次结构。它提供压缩后的分支层次结构、分支持久性以及分支成员关系，并支持 joblib 的缓存功能。一个演示 BranchDetector 的笔记本 可在此处找到 http://nbviewer.jupyter.org/github/scikit-learn-contrib/hdbscan/blob/master/notebooks/How%20to%20detect%20branches.ipynb`_。

示例用法：

.. code:: python

import hdbscan
from sklearn.datasets import make_blobs

data, _ = make_blobs(1000)

clusterer = hdbscan.HDBSCAN(branch_detection_data=True).fit(data)
branch_detector = hdbscan.BranchDetector().fit(clusterer)
branch_detector.cluster_approximation_graph_.plot(edge_width=0.1)

基于论文： D.M. Bot, J. Peeters, J. Liesenborgs 和 J. Aerts FLASC：一种对“flare”敏感的聚类算法。 PeerJ 计算机科学，第11卷，2025年4月，e2792。 https://doi.org/10.7717/peerj-cs.2792。

---

安装

最简单的安装方式，如果你有 Anaconda（感谢 conda-forge 这个超棒的平台！）：

.. code:: bash

conda install -c conda-forge hdbscan

通过 PyPI 安装，假设你已经更新了 pip：

.. code:: bash

pip install hdbscan

得益于 Ryan Helinski rlhelinski@gmail.com 的工作，多个平台的二进制 wheel 文件现已可用。

如果 pip 在拉取依赖项时遇到困难，我们建议先将 pip 升级到至少 10 版本，然后再试一次：

.. code:: bash

pip install --upgrade pip
pip install hdbscan

否则，可以先使用 anaconda 手动安装依赖项，再从 pip 拉取 hdbscan：

.. code:: bash

conda install cython
conda install numpy scipy
conda install scikit-learn
pip install hdbscan

若要直接从 GitHub 手动安装最新代码：

.. code:: bash

pip install --upgrade git+https://github.com/scikit-learn-contrib/hdbscan.git#egg=hdbscan

或者，下载包、安装所需依赖项，然后手动运行安装程序：

.. code:: bash

wget https://github.com/scikit-learn-contrib/hdbscan/archive/master.zip
unzip master.zip
rm master.zip
cd hdbscan-master

pip install -r requirements.txt

python setup.py install

---

运行测试

安装完成后，可以使用以下命令运行包的测试：

.. code:: bash

nosetests -s hdbscan

或者，如果已安装 nose 但 nosetests 并未添加到你的 PATH 变量中：

.. code:: bash

python -m nose -s hdbscan

如果有一个或多个测试失败，请在 https://github.com/scikit-learn-contrib/hdbscan/issues/new 上提交 bug 报告。

---

Python 版本

hdbscan 库同时支持 Python 2 和 Python 3。不过，如果条件允许，我们推荐使用 Python 3，因为它是一个更好的选择。

---

帮助与支持

对于简单问题，你可以查阅文档中的 常见问题解答 <https://hdbscan.readthedocs.io/en/latest/faq.html>。如果在那里未能解决问题，请查看 github 上的 问题页面 <https://github.com/scikit-learn-contrib/hdbscan/issues>。最后，如果那里也没有解决方案，欢迎 提交一个问题 <https://github.com/scikit-learn-contrib/hdbscan/issues/new>_；作者会尽量及时回复。

---

贡献

我们欢迎任何形式的贡献！尤其欢迎协助扩展教程等文档工作。如需贡献，请 fork 该项目 <https://github.com/scikit-learn-contrib/hdbscan/issues#fork-destination-box>_，做出修改并提交 pull request。我们会尽力与你一起解决任何问题，并将你的代码合并到主分支。

---

引用

如果你在科学出版物中使用过此代码库并希望引用它，请使用 开源软件期刊的文章 <http://joss.theoj.org/papers/10.21105/joss.00205>_。

L. McInnes, J. Healy, S. Astels, *hdbscan：基于密度的层次聚类*
收录于：开源软件期刊，开放期刊，第2卷，第11期。
2017年

.. code:: bibtex

@article{mcinnes2017hdbscan,
  title={hdbscan: Hierarchical density based clustering},
  author={McInnes, Leland and Healy, John and Astels, Steve},
  journal={The Journal of Open Source Software},
  volume={2},
  number={11},
  pages={205},
  year={2017}
}

若要引用本库中开发的高性能算法，请参考我们在 ICDMW 2017 会议论文集中的论文。

McInnes L, Healy J. *加速的基于密度的层次聚类* 
收录于：2017 IEEE 国际数据挖掘研讨会 (ICDMW), IEEE, 第33–42页。
2017年

.. code:: bibtex

@inproceedings{mcinnes2017accelerated,
  title={Accelerated Hierarchical Density Based Clustering},
  author={McInnes, Leland and Healy, John},
  booktitle={Data Mining Workshops (ICDMW), 2017 IEEE International Conference on},
  pages={33--42},
  year={2017},
  organization={IEEE}
}

如果你使用了本库中的分支检测功能，请引用我们的 PeerJ 论文 <https://peerj.com/articles/cs-2792/>_：

Bot DM, Peeters J, Liesenborgs J, Aerts J. 
*FLASC：一种对“flare”敏感的聚类算法。*
收录于：PeerJ 计算机科学，第11卷，e2792，2025年。
https://doi.org/10.7717/peerj-cs.2792 

.. code:: bibtex

@article{bot2025flasc, title = {{FLASC：一种对耀斑敏感的聚类算法}}, author = {博特，丹尼尔·M. 和 彼特斯，扬内斯 和 利森博格斯，约里 和 阿尔茨，扬}, year = {2025}, month = {4月}, journal = {PeerJ 计算科学}, volume = {11}, pages = {e2792}, issn = {2376-5992}, doi = {10.7717/peerj-cs.2792}, url = {https://peerj.com/articles/cs-2792}, }

---

许可协议

hdbscan 软件包采用三条款 BSD 许可证。请尽情使用吧。

HDBSCAN 快速上手指南

HDBSCAN（Hierarchical Density-Based Spatial Clustering of Applications with Noise）是一种基于密度的层次聚类算法。相比传统的 DBSCAN，它能自动处理不同密度的簇，对参数选择更鲁棒，且无需预先指定簇的数量，非常适合探索性数据分析。

环境准备

• 操作系统：支持 Windows、macOS 和 Linux。
• Python 版本：支持 Python 2.7 及 Python 3.x（推荐使用 Python 3）。
• 核心依赖：
  • numpy
  • scipy
  • scikit-learn
  • cython (编译时需要)

提示：由于该库包含 C/C++ 扩展，直接通过 pip 安装可能需要编译环境（如 Windows 下的 Visual C++ Build Tools 或 Linux 下的 build-essential）。使用 Conda 可避免大部分编译问题。

安装步骤

方案一：使用 Conda 安装（推荐）

如果你已安装 Anaconda 或 Miniconda，这是最稳定且无需编译的安装方式。国内用户可使用清华或中科大镜像加速。

# 配置清华镜像源（可选，提升下载速度）
conda config --add channels https://mirrors.tuna.tsinghua.edu.cn/anaconda/cloud/conda-forge/
conda config --set show_channel_urls yes

# 安装 hdbscan
conda install -c conda-forge hdbscan

方案二：使用 Pip 安装

确保你的 pip 版本较新（建议 >= 10），以便自动获取预编译的二进制轮子（wheels），避免本地编译失败。

# 升级 pip
pip install --upgrade pip

# 安装 hdbscan
pip install hdbscan

如果 pip 安装因缺少依赖报错，请先手动安装依赖：

pip install cython numpy scipy scikit-learn
pip install hdbscan

方案三：从 GitHub 源码安装（最新开发版）

pip install --upgrade git+https://github.com/scikit-learn-contrib/hdbscan.git#egg=hdbscan

基本使用

HDBSCAN 的 API 设计与 scikit-learn 完全兼容，可以无缝替换其他聚类器。

最简单的使用示例

以下示例演示如何生成模拟数据并进行聚类：

import hdbscan
from sklearn.datasets import make_blobs

# 1. 准备数据 (生成 1000 个样本的模拟数据)
data, _ = make_blobs(1000)

# 2. 初始化模型
# min_cluster_size: 最小簇大小，是主要调节参数，默认为 5
clusterer = hdbscan.HDBSCAN(min_cluster_size=10)

# 3. 拟合并预测
# cluster_labels: 聚类结果标签，噪声点标记为 -1
cluster_labels = clusterer.fit_predict(data)

# 4. 查看结果概览
print(f"找到的簇数量: {len(set(cluster_labels)) - (1 if -1 in cluster_labels else 0)}")
print(f"噪声点数量: {list(cluster_labels).count(-1)}")

进阶功能简述

• 软聚类（成员概率）：通过 clusterer.probabilities_ 获取每个样本属于其簇的概率。
• 异常值检测：拟合后通过 clusterer.outlier_scores_ 获取每个点的异常得分，分数越高越可能是异常值。
• 可视化支持：内置方法可将聚类层级树转换为 Pandas DataFrame 或 NetworkX 图对象进行进一步分析。