.. -- mode: rst --

.. image:: doc/logo_large.png :width: 600 :alt: UMAP 标志 :align: center

|pypi_version|_ |pypi_downloads|_

|conda_version|_ |conda_downloads|_

|License|_ |build_status|_ |Coverage|_

|Docs|_ |joss_paper|_

.. |pypi_version| image:: https://img.shields.io/pypi/v/umap-learn.svg .. _pypi_version: https://pypi.python.org/pypi/umap-learn/

.. |pypi_downloads| image:: https://pepy.tech/badge/umap-learn/month .. _pypi_downloads: https://pepy.tech/project/umap-learn

.. |conda_version| image:: https://anaconda.org/conda-forge/umap-learn/badges/version.svg .. _conda_version: https://anaconda.org/conda-forge/umap-learn

.. |conda_downloads| image:: https://anaconda.org/conda-forge/umap-learn/badges/downloads.svg .. _conda_downloads: https://anaconda.org/conda-forge/umap-learn

.. |License| image:: https://img.shields.io/pypi/l/umap-learn.svg .. _License: https://github.com/lmcinnes/umap/blob/master/LICENSE.txt

.. |build_status| image:: https://dev.azure.com/TutteInstitute/build-pipelines/_apis/build/status/lmcinnes.umap?branchName=master .. _build_status: https://dev.azure.com/TutteInstitute/build-pipelines/_build/latest?definitionId=2&branchName=master

.. |Coverage| image:: https://coveralls.io/repos/github/lmcinnes/umap/badge.svg .. _Coverage: https://coveralls.io/github/lmcinnes/umap

.. |Docs| image:: https://readthedocs.org/projects/umap-learn/badge/?version=latest .. _Docs: https://umap-learn.readthedocs.io/en/latest/?badge=latest

.. |joss_paper| image:: http://joss.theoj.org/papers/10.21105/joss.00861/status.svg .. _joss_paper: https://doi.org/10.21105/joss.00861

==== UMAP

Uniform Manifold Approximation and Projection（UMAP，均匀流形近似与投影）是一种降维技术，可以像 t-SNE 一样用于可视化，同时也可以用于一般的非线性降维。该算法基于以下三个关于数据的假设：

1. 数据在黎曼流形上是均匀分布的；
2. 黎曼度量是局部恒定的（或者可以近似为如此）；
3. 流形是局部连通的。

基于这些假设，可以用模糊拓扑结构对流形进行建模。嵌入通过寻找数据的低维投影来实现，该投影具有尽可能接近等价的模糊拓扑结构。

底层数学的详细信息可以在我们的 ArXiv 论文 <https://arxiv.org/abs/1802.03426>_ 中找到：

McInnes, L, Healy, J, UMAP: Uniform Manifold Approximation and Projection for Dimension Reduction, ArXiv e-prints 1802.03426, 2018

一篇面向科学界更广泛的 UMAP 介绍可以在我们发表于 Nature Review Methods Primers 的论文 <https://doi.org/10.1038/s43586-024-00363-x>_ 中找到：

Healy, J., McInnes, L. Uniform manifold approximation and projection. Nat Rev Methods Primers 4, 82 (2024).

这篇论文的只读版本可以通过 链接 <https://rdcu.be/d0YZT>_ 访问。

重要的是，你不需要担心这些——你可以像使用 scikit-learn 的 t-SNE 一样轻松地将 UMAP 用作降维和可视化的替代工具。

文档可通过 Read the Docs 查看 <https://umap-learn.readthedocs.io/>_。

新功能：此包现在还支持 densMAP。 densMAP 算法扩展了 UMAP，除了保留数据的拓扑结构外，还可以保留局部密度信息。 此方法的详细信息描述在以下 论文 <https://doi.org/10.1038/s41587-020-00801-7>_ 中：

Narayan, A, Berger, B, Cho, H, Assessing Single-Cell Transcriptomic Variability through Density-Preserving Data Visualization, Nature Biotechnology, 2021

---

安装

UMAP 依赖于 scikit-learn，因此也依赖于 scikit-learn 的依赖项（如 numpy 和 scipy）。为了性能原因，UMAP 还增加了对 numba 的要求。原始版本使用了 Cython，但 Numba 提供了更好的代码清晰度、简洁性和性能，因此进行了必要的转换。

需求：

• Python 3.6 或更高版本
• numpy
• scipy
• scikit-learn
• numba
• tqdm
• pynndescent <https://github.com/lmcinnes/pynndescent>_

推荐的包：

• 用于绘图
  • matplotlib
  • datashader
  • holoviews
• 用于参数化 UMAP
  • tensorflow > 2.0.0

安装选项

通过 conda-forge 团队的出色工作，使用 Conda 安装：

.. code:: bash

conda install -c conda-forge umap-learn

conda-forge 包适用于 Linux、OS X 和 Windows 64 位。

PyPI 安装，假设你已经安装了 numba 和 sklearn 及其所有依赖项（numpy 和 scipy）：

.. code:: bash

pip install umap-learn

如果你想使用绘图功能，可以使用

.. code:: bash

pip install umap-learn[plot]

来安装所有绘图依赖项。

如果你想使用 Parametric UMAP，则需要安装 Tensorflow，可以通过 https://www.tensorflow.org/install 的说明进行安装（推荐），或者使用

.. code:: bash

pip install umap-learn[parametric_umap]

安装仅支持 CPU 的 Tensorflow 版本。

如果你使用的是 x86 处理器，还可以选择安装 tbb，它将提供额外的 CPU 优化：

.. code:: bash

pip install umap-learn[tbb]

如果 pip 在拉取依赖项时遇到困难，我们建议先使用 anaconda 手动安装依赖项，然后再通过 pip 拉取 umap：

.. code:: bash

conda install numpy scipy
conda install scikit-learn
conda install numba
pip install umap-learn

对于手动安装，请获取此包：

.. code:: bash

wget https://github.com/lmcinnes/umap/archive/master.zip
unzip master.zip
rm master.zip
cd umap-master

可选地，通过 Conda 安装依赖项：

.. code:: bash

conda install scikit-learn numba

然后安装包：

.. code:: bash

python -m pip install -e .

---

如何使用 UMAP

umap 包继承自 sklearn 类，因此可以无缝地与其他 sklearn 转换器一起使用，并且具有相同的调用 API。

.. code:: python

import umap
from sklearn.datasets import load_digits

digits = load_digits()

embedding = umap.UMAP().fit_transform(digits.data)

UMAP 类有许多可以设置的参数；主要参数如下：

• n_neighbors：这决定了用于局部流形结构近似的邻近点的数量。较大的值将导致更多全局结构被保留，但会损失详细的局部结构。通常，该参数的范围应在 5 到 50 之间，默认值选择 10 到 15 是合理的。

• min_dist: 这个参数控制嵌入（embedding）过程中允许将点压缩到一起的紧密程度。较大的值确保嵌入点分布更加均匀，而较小的值允许算法更准确地优化局部结构。合理的取值范围为 0.001 到 0.5，0.1 是一个合理的默认值。

• metric: 这个参数决定了用于测量输入空间中距离的度量方法。目前已经有多种度量方法被实现，并且只要用户定义的函数经过 numba 的 JIT 编译，也可以传入自定义函数。

以下是如何使用这些选项的一个示例：

.. code:: python

import umap
from sklearn.datasets import load_digits

digits = load_digits()

embedding = umap.UMAP(n_neighbors=5,
                      min_dist=0.3,
                      metric='correlation').fit_transform(digits.data)

UMAP 还支持对稀疏矩阵数据进行拟合。更多详细信息，请参阅 UMAP 文档 <https://umap-learn.readthedocs.io/>_

---

UMAP 的优势

当前版本的 UMAP 拥有几项显著的优势。

首先，UMAP 速度很快。它可以轻松处理大型数据集和高维数据，其扩展性超越了大多数 t-SNE 包的能力。这包括非常高维的稀疏数据集。UMAP 已成功直接应用于超过一百万维的数据。

其次，UMAP 在嵌入维度上表现良好——它不仅仅适用于可视化！您可以将 UMAP 作为一种通用的降维技术，作为其他机器学习任务的初步步骤。稍加注意，它可以很好地与 hdbscan <https://github.com/scikit-learn-contrib/hdbscan>_ 聚类库配合使用（更多详情请参见 使用 UMAP 进行聚类 <https://umap-learn.readthedocs.io/en/latest/clustering.html>_）。

第三，UMAP 在保留数据某些全局结构方面通常比大多数 t-SNE 实现表现得更好。这意味着它可以提供更好的“全局视角”，同时保留局部邻近关系。

第四，UMAP 支持多种距离函数，包括非度量距离函数，例如 余弦距离 和 相关距离。您终于可以使用余弦距离正确地嵌入词向量了！

第五，UMAP 支持通过标准的 sklearn transform 方法将新点添加到现有嵌入中。这意味着 UMAP 可以用作 sklearn 管道中的预处理转换器。

第六，UMAP 支持监督和半监督降维。这意味着如果您有希望用作额外降维信息的标签信息（即使是部分标签），也可以通过简单地将其作为 y 参数传递给 fit 方法来实现。

第七，UMAP 支持多种附加实验功能，包括：一种“逆变换”功能，可以近似生成映射到嵌入空间中特定位置的高维样本；能够嵌入到非欧几里得空间，包括双曲嵌入和带有不确定性的嵌入；还存在非常初步的支持嵌入数据框的功能。

最后，UMAP 在流形学习方面具有坚实的理论基础（参见 我们的 ArXiv 论文 <https://arxiv.org/abs/1802.03426>_）。这不仅证明了该方法的合理性，还为进一步扩展提供了可能，这些扩展将很快被添加到库中。

---

性能与示例

UMAP 在嵌入大型高维数据集时非常高效。特别是它在输入维度和嵌入维度上的扩展性都很好。为了获得最佳性能，我们建议安装最近邻计算库 pynndescent <https://github.com/lmcinnes/pynndescent>_。即使不安装，UMAP 也能正常工作，但如果安装了，运行速度会更快，尤其是在多核机器上。

对于像 MNIST 手写数字数据集这样的问题（784 维，70000 个样本），UMAP 可以在一分钟内完成嵌入（相比之下，scikit-learn 的 t-SNE 实现需要大约 45 分钟）。尽管运行效率很高，UMAP 仍然能生成高质量的嵌入。

经典的 MNIST 手写数字数据集，在安装了 pynndescent 并经过 numba jit 预热后，使用 3.1 GHz Intel Core i7 处理器仅需 42 秒即可完成嵌入（n_neighbors=10, min_dist=0.001）：

.. image:: images/umap_example_mnist1.png :alt: UMAP 嵌入 MNIST 手写数字数据集

然而，MNIST 数据集相对简单。更好的测试是较新的“Fashion MNIST”数据集，其中包含 70000 张时尚物品图像（同样为 784 维）。UMAP 在 49 秒内生成了此嵌入（n_neighbors=5, min_dist=0.1）：

.. image:: images/umap_example_fashion_mnist1.png :alt: UMAP 嵌入 Fashion MNIST 数据集

UCI Shuttle 数据集（43500 个样本，8 维）在 相关距离 下嵌入效果良好，耗时 44 秒（请注意，相关距离计算需要更长的时间）：

.. image:: images/umap_example_shuttle.png :alt: UMAP 嵌入 UCI Shuttle 数据集

以下是基于上述相同参数（n_neighbors=10, min_dist=0.001）的 MNIST 数据集的 densMAP 可视化结果。densMAP 揭示了对应数字 1 的簇明显更密集，表明数字 1 的图像相比其他数字自由度更少。

.. image:: images/densmap_example_mnist.png :alt: densMAP 嵌入 MNIST 数据集

---

绘图

UMAP 包含一个子包 umap.plot，用于绘制 UMAP 嵌入的结果。这个包需要单独导入，因为它有一些额外的依赖（matplotlib、datashader 和 holoviews）。它能够快速简单地绘制图形，并尝试做出明智的决策以避免过度绘制和其他问题。以下是一个使用示例：

.. code:: python

import umap
import umap.plot
from sklearn.datasets import load_digits

digits = load_digits()

mapper = umap.UMAP().fit(digits.data)
umap.plot.points(mapper, labels=digits.target)

绘图包提供了基本图表以及带有悬停工具和各种诊断绘图选项的交互式图表。更多详细信息请参阅文档。

---

参数化 UMAP

Parametric UMAP 提供了训练神经网络以学习基于 UMAP 的数据转换的支持。这可以用于支持对新未见数据的更快推断、更稳健的逆变换、UMAP 的自编码器版本以及半监督分类（特别是对于通过 UMAP 能够很好分离且标记数据非常有限的情况）。更多内容请参阅 Parametric UMAP 文档 <https://umap-learn.readthedocs.io/en/0.5dev/parametric_umap.html>_ 或 示例笔记本 <https://github.com/lmcinnes/umap/tree/master/notebooks/Parametric_UMAP>_。

---

densMAP

densMAP 算法增强了 UMAP，除了捕捉 UMAP 所捕获的拓扑结构外，还额外保留了局部密度信息。可以通过设置 densmap 输入标志轻松使用 umap 包运行 densMAP：

.. code:: python

embedding = umap.UMAP(densmap=True).fit_transform(data)

此功能基于 densMAP 开发者提供的 densMAP 实现 <https://github.com/hhcho/densvis>_ 构建，这些开发者也为将 densMAP 集成到 umap 包中做出了贡献。

densMAP 继承了 UMAP 的所有参数。以下是可为 densMAP 设置的附加参数列表：

• dens_frac：确定在优化目标中包含密度保留项的 epoch 比例（值介于 0 和 1 之间）。默认值为 0.3。请注意，densMAP 在初始使用 UMAP 优化嵌入后才会开启密度优化。

• dens_lambda：确定密度保留目标的权重。较高的值优先考虑密度保留，较低的值（接近零）优先考虑 UMAP 目标。将此参数设置为零会将算法简化为 UMAP。默认值为 2.0。

• dens_var_shift：为了数值稳定性，添加到嵌入中局部密度方差的正则化项。我们建议将此参数设置为 0.1，在许多情况下表现一致良好。

• output_dens：当此标志为 True 时，调用 fit_transform 不仅返回嵌入，还会返回原始数据集和嵌入的局部半径（在 densMAP 论文 <https://doi.org/10.1101/2020.05.12.077776>_ 中定义的局部密度的反向度量）。输出是一个元组 (embedding, radii_original, radii_embedding)。请注意，半径经过对数变换。如果为 False，则只返回嵌入。此标志也可以与 UMAP 一起使用，以探索 UMAP 嵌入的局部密度。默认情况下，此标志为 False。

对于 densMAP，我们建议使用较大的 n_neighbors 值（例如 30），以便可靠地估计局部密度。

以下是如何使用这些选项的示例（基于 mnist_784 数据集的子样本）：

.. code:: python

import umap
from sklearn.datasets import fetch_openml
from sklearn.utils import resample

digits = fetch_openml(name='mnist_784')
subsample, subsample_labels = resample(digits.data, digits.target, n_samples=7000,
                                       stratify=digits.target, random_state=1)

embedding, r_orig, r_emb = umap.UMAP(densmap=True, dens_lambda=2.0, n_neighbors=30,
                                     output_dens=True).fit_transform(subsample)

更多详细信息，请参阅 文档 <https://umap-learn.readthedocs.io/en/0.5dev/densmap_demo.html>_。

---

使用 torchdr 实现 GPU 加速的 UMAP

对于 GPU 加速的 UMAP 计算，torchdr <https://github.com/TorchDR/TorchDR>_ 提供了一个基于 PyTorch 的实现，显著加快了算法速度。 torchdr 在 GPU 上加速了降维管道的每个步骤：kNN 计算、亲和力构建和嵌入优化。

使用 torchdr 和 UMAP 很简单：

.. code:: python

from torchdr import UMAP as torchdrUMAP

umap_gpu = torchdrUMAP(
    n_neighbors=15,
    min_dist=0.1,
    n_components=2,
    device='cuda'
)
embedding = umap_gpu.fit_transform(data-maps)

更多信息和高级用法，请参阅 torchdr 文档 <https://torchdr.github.io/index.html>_。

---

帮助和支持

文档位于 Read the Docs <https://umap-learn.readthedocs.io/>。 文档 包含常见问题解答 <https://umap-learn.readthedocs.io/en/latest/faq.html>， 可能会回答您的问题。如果您仍有疑问，请 提交问题 <https://github.com/lmcinnes/umap/issues/new>_， 我将尽力提供任何可能的帮助和指导。

---

引用

如果您在工作中使用了本软件，我们将不胜感激您引用以下来自《开源软件期刊》的论文：

.. code:: bibtex

@article{mcinnes2018umap-software,
  title={UMAP: Uniform Manifold Approximation and Projection},
  author={McInnes, Leland and Healy, John and Saul, Nathaniel and Grossberger, Lukas},
  journal={The Journal of Open Source Software},
  volume={3},
  number={29},
  pages={861},
  year={2018}
}

如果您希望在您的工作中引用该算法，当前的参考文献是 ArXiv 论文：

.. code:: bibtex

@article{2018arXivUMAP, author = {{McInnes}, L. and {Healy}, J. and {Melville}, J.}, title = "{UMAP: Uniform Manifold Approximation and Projection for Dimension Reduction}", journal = {ArXiv e-prints}, archivePrefix = "arXiv", eprint = {1802.03426}, primaryClass = "stat.ML", keywords = {Statistics - Machine Learning, Computer Science - Computational Geometry, Computer Science - Learning}, year = 2018, month = feb, }

如果您发现 Nature Primer 的介绍有用，请引用以下参考文献：

.. code:: bibtex

@article{Healy2024,
  author={Healy, John
  and McInnes, Leland},
  title={Uniform manifold approximation and projection},
  journal={Nature Reviews Methods Primers},
  year={2024},
  month={Nov},
  day={21},
  volume={4},
  number={1},
  pages={82},
  abstract={Uniform manifold approximation and projection is a nonlinear dimension reduction method often used for visualizing data and as pre-processing for further machine-learning tasks such as clustering. In this Primer, we provide an introduction to the uniform manifold approximation and projection algorithm, the intuitions behind how it works, how best to apply it on data and how to interpret and understand results.},
  issn={2662-8449},
  doi={10.1038/s43586-024-00363-x},
  url={https://doi.org/10.1038/s43586-024-00363-x}
}

此外，如果您在工作中使用了 densMAP 算法，请引用以下参考文献：

.. code:: bibtex

@article {NBC2020, author = {Narayan, Ashwin 和 Berger, Bonnie 以及 Cho, Hyunghoon}, title = {通过密度保持的数据可视化评估单细胞转录组变异性}, journal = {自然生物技术（Nature Biotechnology）}, year = {2021}, doi = {10.1038/s41587-020-00801-7}, publisher = {Springer Nature}, URL = {https://doi.org/10.1038/s41587-020-00801-7}, eprint = {https://www.biorxiv.org/content/early/2020/05/14/2020.05.12.077776.full.pdf}, }

如果您在工作中使用了 Parametric UMAP 算法，请引用以下参考文献：

.. code:: bibtex

@article {SMG2020,
    author = {Sainburg, Tim and McInnes, Leland and Gentner, Timothy Q.},
    title = {Parametric UMAP: learning embeddings with deep neural networks for representation and semi-supervised learning},
    journal = {ArXiv e-prints},
    archivePrefix = "arXiv",
    eprint = {2009.12981},
    primaryClass = "stat.ML",
    keywords = {Statistics - Machine Learning,
                Computer Science - Computational Geometry,
                Computer Science - Learning},
    year = 2020,
    }

---

许可证

umap 包采用 3 条款 BSD 许可证。

我们想指出，umap 包大量使用了 NumFOCUS 赞助的项目，没有这些项目的 支持，umap 就不可能实现，因此请考虑为 NumFOCUS 做出贡献 <https://www.numfocus.org/membership>_。

---

贡献指南

非常欢迎您的贡献！有许多潜在的项目机会，所以如果您愿意帮忙， 请随时联系我们。无论是代码、笔记本、示例还是文档，所有贡献都是同等重要的， 请不要觉得自己无法贡献。要贡献代码，请先 派生项目 <https://github.com/lmcinnes/umap/issues#fork-destination-box>_， 进行修改后提交拉取请求。我们将尽力与您一起解决任何问题，并将您的代码合并到主分支中。

UMAP 快速上手指南

UMAP（Uniform Manifold Approximation and Projection）是一种高效的降维工具，适用于数据可视化和非线性降维任务。以下是如何快速开始使用 UMAP 的简明指南。

---

环境准备

系统要求

• Python 3.6 或更高版本
• 支持的操作系统：Linux、macOS、Windows（64 位）

前置依赖

UMAP 依赖以下 Python 库：

• numpy
• scipy
• scikit-learn
• numba
• tqdm
• pynndescent

推荐安装的可选库：

• 绘图功能：matplotlib、datashader、holoviews
• Parametric UMAP：tensorflow > 2.0.0

---

安装步骤

使用 Conda 安装（推荐）

Conda 是一个跨平台的包管理工具，适合科学计算环境。推荐使用国内镜像源加速安装：

conda install -c conda-forge umap-learn

使用 Pip 安装

如果更倾向于使用 pip，请确保已安装前置依赖（如 numpy 和 scipy），然后运行以下命令：

pip install umap-learn

可选功能安装

• 如果需要绘图功能：

  pip install umap-learn[plot]
  

• 如果需要 Parametric UMAP（仅 CPU 版本）：

  pip install umap-learn[parametric_umap]
  

• 如果需要额外的 CPU 优化（x86 处理器）：

  pip install umap-learn[tbb]
  

国内加速方案

建议使用国内镜像源加速 pip 安装，例如阿里云或清华大学开源镜像站：

pip install umap-learn -i https://pypi.tuna.tsinghua.edu.cn/simple

---

基本使用

以下是一个简单的 UMAP 使用示例，展示如何对高维数据进行降维并生成二维嵌入。

示例代码

import umap
from sklearn.datasets import load_digits

# 加载示例数据集（MNIST 手写数字）
digits = load_digits()

# 使用 UMAP 进行降维
embedding = umap.UMAP().fit_transform(digits.data)

# 输出嵌入结果的形状
print(embedding.shape)  # 输出: (n_samples, 2)

参数说明

UMAP 提供了多个可调参数，以下是一些常用选项：

• n_neighbors: 控制邻近点的数量，影响局部与全局结构的平衡。默认值为 15。
• min_dist: 控制嵌入点之间的最小距离，影响嵌入的紧凑程度。默认值为 0.1。
• metric: 距离度量方法，默认为 'euclidean'，支持多种距离函数（如 'correlation' 和 'cosine'）。

自定义参数示例

embedding = umap.UMAP(
    n_neighbors=5,
    min_dist=0.3,
    metric='correlation'
).fit_transform(digits.data)

---

以上是 UMAP 的快速上手指南，更多高级功能和详细文档请参考 官方文档。