umap-learn

UMAP-Learn

概述

UMAP（Uniform Manifold Approximation and Projection，统一流形近似与投影）是一种用于可视化和一般非线性降维的技术。适用于需要快速、可扩展嵌入，同时保留局部和全局结构、进行监督学习以及聚类预处理的场景。

快速入门

安装

当前稳定版本：umap-learn 0.5.12（于 2026 年 4 月发布）。需要 Python 3.9+，并依赖 scikit-learn>=1.6、numba、pynndescent、numpy 和 scipy。请固定到经过验证的版本：

uv pip install umap-learn==0.5.12

基本用法

UMAP 遵循 scikit-learn 的惯例，可直接替代 t-SNE 或 PCA。

import umap
from sklearn.preprocessing import StandardScaler

# Prepare data (standardization is essential)
scaled_data = StandardScaler().fit_transform(data)

# Method 1: Single step (fit and transform)
embedding = umap.UMAP().fit_transform(scaled_data)

# Method 2: Separate steps (for reusing trained model)
reducer = umap.UMAP(random_state=42)
reducer.fit(scaled_data)
embedding = reducer.embedding_  # Access the trained embedding

**预处理要求：**根据距离度量选择对应的预处理方式。对于数值型欧几里得类度量，应在拟合前缩放特征，避免高方差列占据主导地位。对于余弦、二值、预计算距离或混合特征工作流，应选择与度量相匹配的预处理方式，而不是不加区分地对每一列进行标准化。

典型工作流

import umap
import matplotlib.pyplot as plt
from sklearn.preprocessing import StandardScaler

# 1. Preprocess data
scaler = StandardScaler()
scaled_data = scaler.fit_transform(raw_data)

# 2. Create and fit UMAP
reducer = umap.UMAP(
    n_neighbors=15,
    min_dist=0.1,
    n_components=2,
    metric='euclidean',
    random_state=42
)
embedding = reducer.fit_transform(scaled_data)

# 3. Visualize
plt.scatter(embedding[:, 0], embedding[:, 1], c=labels, cmap='Spectral', s=5)
plt.colorbar()
plt.title('UMAP Embedding')
plt.show()

参数调优指南

UMAP 有四个主要参数会影响嵌入效果。理解这些参数对于有效使用至关重要。

n_neighbors（默认值：15）

**用途：**平衡嵌入中的局部结构与全局结构。

**工作原理：**控制 UMAP 在学习流形结构时考察的局部邻域大小。

不同取值的影响：

• **较低取值（2-5）：**强调精细的局部细节，但可能将数据分割为互不连通的组件
• **中等取值（15-20）：**兼顾局部结构和全局关系（建议从此范围开始）
• **较高取值（50-200）：**优先保留整体拓扑结构，但会牺牲精细细节

**建议：**从 15 开始，并根据结果调整。要保留更多全局结构，可增大取值；要呈现更多局部细节，可减小取值。

min_dist（默认值：0.1）

**用途：**控制点在低维空间中的聚集紧密程度。

**工作原理：**设置输出表示中各点之间允许的最小距离。

不同取值的影响：

• **较低取值（0.0-0.1）：**生成紧密聚集的嵌入，适用于聚类；有助于展现精细的拓扑细节
• **较高取值（0.5-0.99）：**避免点过于紧密地聚集；相比局部结构，更强调整体拓扑结构的保留

**建议：**聚类任务使用 0.0，可视化使用 0.1-0.3，宽松结构使用 0.5+。

n_components（默认值：2）

**用途：**确定嵌入输出空间的维数。

**主要特点：**与 t-SNE 不同，UMAP 能够良好地扩展到更高的嵌入维数，因此不局限于可视化。

常见用途：

• **2-3 维：**可视化
• **5-10 维：**聚类预处理（相比 2D，能更好地保留密度）
• **10-50 维：**为下游 ML 模型构造特征

**建议：**可视化使用 2 维，聚类使用 5-10 维，ML 工作流则使用更高维数。

metric（默认值：'euclidean'）

**用途：**指定如何计算输入数据点之间的距离。

支持的度量：

• **Minkowski 变体：**euclidean、manhattan、chebyshev
• **空间度量：**canberra、braycurtis、haversine
• **相关性度量：**cosine、correlation（适用于文本/文档嵌入）
• **二值数据度量：**hamming、jaccard、dice、russellrao、kulsinski、rogerstanimoto、sokalmichener、sokalsneath、yule
• **自定义度量：**通过 Numba 定义距离函数

**建议：**数值数据使用 euclidean，文本/文档向量使用 cosine，二值数据使用 hamming。

参数调优示例

# For visualization with emphasis on local structure
umap.UMAP(n_neighbors=15, min_dist=0.1, n_components=2, metric='euclidean')

# For clustering preprocessing
umap.UMAP(n_neighbors=30, min_dist=0.0, n_components=10, metric='euclidean')

# For document embeddings
umap.UMAP(n_neighbors=15, min_dist=0.1, n_components=2, metric='cosine')

# For preserving global structure
umap.UMAP(n_neighbors=100, min_dist=0.5, n_components=2, metric='euclidean')

监督式和半监督式降维

UMAP 支持纳入标签信息来引导嵌入过程，从而在保留内部结构的同时实现类别分离。

监督式 UMAP

拟合时通过 y 参数传入目标标签：

# Supervised dimension reduction
embedding = umap.UMAP().fit_transform(data, y=labels)

主要优势：

• 实现清晰的类别分离
• 保留各类别内部结构
• 维持类别之间的全局关系

半监督式 UMAP

对于部分标注的数据，按照 scikit-learn 惯例，将未标注点标记为 -1：

# Create semi-supervised labels
semi_labels = labels.copy()
semi_labels[unlabeled_indices] = -1

# Fit with partial labels
embedding = umap.UMAP().fit_transform(data, y=semi_labels)

适用场景： 标注成本高昂，或数据量大于可用标签数量时。

用于聚类的 UMAP

UMAP 可作为基于密度的聚类算法（如 HDBSCAN）的有效预处理方法，克服维度灾难。

聚类最佳实践

主要原则： 与用于可视化相比，用于聚类时应采用不同的 UMAP 配置。

推荐参数：

• n_neighbors： 增大至约 30（默认值 15 的局部性过强，可能产生人为的细粒度聚类）
• min_dist： 设为 0.0（将簇内点密集排列，使边界更清晰）
• n_components： 使用 5-10 个维度（在保持性能的同时，相较于 2D 提高密度保留效果）

聚类工作流

单独安装 HDBSCAN 以进行基于密度的聚类：

uv pip install hdbscan

import umap
import hdbscan
from sklearn.preprocessing import StandardScaler

# 1. Preprocess data
scaled_data = StandardScaler().fit_transform(data)

# 2. UMAP with clustering-optimized parameters
reducer = umap.UMAP(
    n_neighbors=30,
    min_dist=0.0,
    n_components=10,  # Higher than 2 for better density preservation
    metric='euclidean',
    random_state=42
)
embedding = reducer.fit_transform(scaled_data)

# 3. Apply HDBSCAN clustering
clusterer = hdbscan.HDBSCAN(
    min_cluster_size=15,
    min_samples=5,
    metric='euclidean'
)
labels = clusterer.fit_predict(embedding)

# 4. Evaluate
from sklearn.metrics import adjusted_rand_score
score = adjusted_rand_score(true_labels, labels)
print(f"Adjusted Rand Score: {score:.3f}")
print(f"Number of clusters: {len(set(labels)) - (1 if -1 in labels else 0)}")
print(f"Noise points: {sum(labels == -1)}")

聚类后的可视化

# Create 2D embedding for visualization (separate from clustering)
vis_reducer = umap.UMAP(n_neighbors=15, min_dist=0.1, n_components=2, random_state=42)
vis_embedding = vis_reducer.fit_transform(scaled_data)

# Plot with cluster labels
import matplotlib.pyplot as plt
plt.scatter(vis_embedding[:, 0], vis_embedding[:, 1], c=labels, cmap='Spectral', s=5)
plt.colorbar()
plt.title('UMAP Visualization with HDBSCAN Clusters')
plt.show()

重要注意事项： UMAP 无法完全保留密度，并且可能产生人为的簇划分。请务必验证并探索生成的簇。

转换新数据

UMAP 可通过其 transform() 方法对新数据进行预处理，让训练好的模型将未见过的数据投影到学得的嵌入空间中。

transform 基本用法

# Train on training data
trans = umap.UMAP(n_neighbors=15, random_state=42).fit(X_train)

# Transform test data
test_embedding = trans.transform(X_test)

与机器学习流水线集成

from sklearn.svm import SVC
from sklearn.model_selection import train_test_split
from sklearn.preprocessing import StandardScaler
import umap

# Split data
X_train, X_test, y_train, y_test = train_test_split(data, labels, test_size=0.2)

# Preprocess
scaler = StandardScaler()
X_train_scaled = scaler.fit_transform(X_train)
X_test_scaled = scaler.transform(X_test)

# Train UMAP
reducer = umap.UMAP(n_components=10, random_state=42)
X_train_embedded = reducer.fit_transform(X_train_scaled)
X_test_embedded = reducer.transform(X_test_scaled)

# Train classifier on embeddings
clf = SVC()
clf.fit(X_train_embedded, y_train)
accuracy = clf.score(X_test_embedded, y_test)
print(f"Test accuracy: {accuracy:.3f}")

重要注意事项

数据一致性： transform 方法假定训练数据与测试数据在高维空间中的总体分布一致。如果这一假设不成立，可以考虑使用 Parametric UMAP。

性能： transform 操作效率很高（通常 <1 秒），不过首次调用可能因 Numba JIT 编译而较慢。

Scikit-learn 兼容性： UMAP 遵循标准 sklearn 惯例，可用于流水线。近期的 0.5.x 版本还改进了对特征名称的支持，以及与当前 scikit-learn 验证 API 的兼容性：

from sklearn.pipeline import Pipeline

pipeline = Pipeline([
    ('scaler', StandardScaler()),
    ('umap', umap.UMAP(n_components=10)),
    ('classifier', SVC())
])

pipeline.fit(X_train, y_train)
predictions = pipeline.predict(X_test)
feature_names = pipeline.named_steps['umap'].get_feature_names_out()

高级功能

详情、代码示例和参数表： references/advanced-features.md。适用时请阅读。

可复现性

为确保结果可复现，请始终设置 random_state 参数：

reducer = umap.UMAP(random_state=42)

UMAP 使用随机优化，因此在未固定随机状态时，每次运行的结果都会略有不同。

设置 random_state 可优先保证输出的确定性。当吞吐量比精确的可重复性更重要时，请不要设置该参数，因为 UMAP 在未固定种子的情况下可以利用更多并行能力。

常见问题与解决方案

问题： 组件不连通或簇碎片化

• 解决方案： 增大 n_neighbors，以强调更多全局结构

问题： 簇过于分散或分离不明显

• 解决方案： 减小 min_dist，使点更紧密地排列

问题： 聚类结果不理想

• 解决方案： 使用针对聚类的参数（n_neighbors=30, min_dist=0.0, n_components=5-10）

问题： 转换结果与训练结果差异显著

• 解决方案： 确保测试数据的分布与训练数据一致，或使用 Parametric UMAP

问题： 大型数据集上的性能较慢

• 解决方案： 设置 low_memory=True（默认值），或考虑先使用 PCA 降维

问题： 输入数据中含有 NaN 或 inf 值

• 解决方案： 拟合前插补或删除无效行。当前 UMAP 会在 fit() 和 update() 中使用 scikit-learn 风格的有限值检查（ensure_all_finite），因此默认情况下，最稳妥的做法是使用干净的数值输入

问题： 所有点都坍缩到单个簇中

• 解决方案： 检查数据预处理（确保正确缩放），增大 min_dist

问题： 导入解析到本地文件，而非实际的软件包

• 解决方案： 不要在笔记本或脚本旁放置名为 umap.py、sklearn.py、hdbscan.py 或 tensorflow.py 的项目文件。这些名称可能会遮蔽已安装的软件包，导致示例出错或受到干扰。

资源

官方文档

• UMAP 用户指南
• 发行说明
• PyPI 软件包（当前稳定版本：0.5.12）
• GitHub 仓库

references/

包含详细的 API 文档：

• api_reference.md：完整的 UMAP 类参数和方法

需要详细的参数信息或高级方法用法时，请加载这些参考资料。

Agent 操作流程

1. 检查环境。 确认 Python 环境和库版本（python -c "import pkg; print(pkg.__version__)"），并检查数据的形状、类型和缺失值。
2. 明确输入。 根据数据或用户确认格式、标识符和参数。任何会改变结果的值都应询问确认，不要猜测。
3. 先运行小规模版本。 先在样本或单个折上运行，并检查运行时间和内存。
4. 使用以上说明和参考资料执行完整任务。
5. 验证结果。 使用留出数据、固定随机种子和适当的指标；检查是否存在泄漏；报告不确定性（置信区间、不同随机种子的标准差）。
6. 报告结果。 说明运行了什么（版本、命令、参数）、检查了什么，以及仍有哪些不确定之处。

如果出现这种情况	请这样做
内存不足或执行速度很慢	进行子采样，使用分块或惰性计算，或缩小模型规模，并告知用户做了哪些更改。
已安装版本中缺少这些说明里的函数、标志或端点	查阅已安装版本自身的文档（help()、--help、官方文档），调整方案并告知用户。切勿虚构 API。
必需的输入、标识符或参数不明确	询问用户，或在运行前明确说明假设。

诚信规则

• 切勿编造结果、参数、标识符、引用或统计数据。如果无法运行或验证某项内容，请如实说明。
• 切勿报告本次会话中未计算的指标；为每个数字展示其生成所经过的代码路径。
• 此处与特定版本相关的细节可能已经过时：请根据已安装版本的官方文档进行确认。
• 对于会产生费用、占用共享 GPU 或云配额、涉及个人或患者数据，或无法撤销的操作，执行前必须征得同意。

相关技能

• scanpy：标准的单细胞 RNA-seq 分析流程。
• tensorboard：使用 PyTorch SummaryWriter 和 TensorFlow/Keras 回调，在 TensorBoard 中记录和查看 ML 训练数据：标量、图像、文本、直方图……
• sentence-transformers：使用 Python sentence-transformers（SBERT）库和预训练的 Hugging Fac…，在本地生成句子、文本和图像嵌入。