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
scaled_data = StandardScaler().fit_transform(data) embedding = umap.UMAP().fit_transform(scaled_data)
也可分步执行以复用已训练模型：
reducer = umap.UMAP(random_state=42) reducer.fit(scaled_data) embedding = reducer.embedding_
预处理要求：预处理方式需与所选度量匹配。对于数值型欧氏类度量，应在拟合前对特征进行缩放，避免高方差列主导结果；对于余弦、二值、预计算距离或混合特征工作流，应选择与度量匹配的预处理方式，而非盲目标准化所有列。
主要参数
n_neighbors（默认 15）：平衡嵌入中的局部与全局结构。低值（2-5）强调局部细节但可能使数据碎片化；中值（15-20）兼顾局部与全局，推荐作为起点；高值（50-200）优先保留整体拓扑结构。
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 维用于聚类预处理，10-50 维用于下游机器学习特征工程。
metric（默认 'euclidean'）：输入数据点间距离的计算方式。支持 Minkowski 变体（euclidean、manhattan、chebyshev）、空间度量（canberra、braycurtis、haversine）、相关性度量（cosine、correlation，适合文本/文档嵌入）、二值数据度量（hamming、jaccard、dice 等）以及通过 Numba 定义的自定义度量。数值数据用 euclidean，文本/文档向量用 cosine，二值数据用 hamming。
监督与半监督降维
UMAP 支持通过 y 参数传入标签信息来引导嵌入过程，实现类别分离并保留类内结构：
embedding = umap.UMAP().fit_transform(data, y=labels)
半监督场景下，按 scikit-learn 约定将未标注点标记为 -1：
semi_labels = labels.copy() semi_labels[unlabeled_indices] = -1 embedding = umap.UMAP().fit_transform(data, y=semi_labels)
适用于标注成本高或数据量多于标签量的情况。
用于聚类
UMAP 可作为 HDBSCAN 等基于密度的聚类算法的有效预处理，克服维度灾难。聚类时应采用与可视化不同的参数：n_neighbors 增至约 30，min_dist 设为 0.0，n_components 使用 5-10 维。需单独安装 HDBSCAN：
uv pip install hdbscan
聚类工作流示例：
import umap import hdbscan from sklearn.preprocessing import StandardScaler
scaled_data = StandardScaler().fit_transform(data) reducer = umap.UMAP(n_neighbors=30, min_dist=0.0, n_components=10, metric='euclidean', random_state=42) embedding = reducer.fit_transform(scaled_data) clusterer = hdbscan.HDBSCAN(min_cluster_size=15, min_samples=5, metric='euclidean') labels = clusterer.fit_predict(embedding)
注意：UMAP 并不完全保留密度，可能产生人为的簇划分，应始终验证并探索所得聚类。
变换新数据
UMAP 通过 transform() 方法将新数据投影到已学习的嵌入空间：
trans = umap.UMAP(n_neighbors=15, random_state=42).fit(X_train) test_embedding = trans.transform(X_test)
可与机器学习管道集成：
from sklearn.pipeline import Pipeline from sklearn.svm import SVC
pipeline = Pipeline([ ('scaler', StandardScaler()), ('umap', umap.UMAP(n_components=10)), ('classifier', SVC()) ]) pipeline.fit(X_train, y_train) predictions = pipeline.predict(X_test)
注意事项：transform 假设训练与测试数据在高维空间中的整体分布一致，若该假设不成立，可考虑 Parametric UMAP。变换操作通常高效（一般小于 1 秒），首次调用可能因 Numba JIT 编译而较慢。0.5.x 版本改进了特征名支持及与当前 scikit-learn 验证 API 的兼容性。
可复现性
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。
- 导入解析到本地文件而非真实包：不要在 notebook 或脚本旁保留名为 umap.py、sklearn.py、hdbscan.py 或 tensorflow.py 的项目文件，这些名称会遮蔽已安装包。
资源与参考
官方文档、UMAP 用户指南、发布说明、PyPI 包（当前稳定版 0.5.12）、GitHub 仓库。references/ 目录包含详细 API 文档：api_reference.md 提供完整的 UMAP 类参数与方法。
代理操作流程
- 检查环境：确认 Python 环境与库版本，检查数据形状、类型与缺失值。
- 确定输入：从数据或用户处确认格式、标识符与参数，对影响结果的取值应询问而非猜测。
- 先运行小版本：在样本或单折上运行，检查运行时间与内存。
- 执行完整任务。
- 验证结果：使用留出数据、固定随机种子与适当指标，检查泄漏，报告不确定性。
- 报告：说明运行内容（版本、命令、参数）、已检查项与仍不确定项。
完整性规则：不得捏造结果、参数、标识符、引用或统计量；不得报告本次会话未计算的指标；版本相关细节可能过时，应以已安装版本的官方文档为准；涉及费用、共享 GPU/云配额、个人或患者数据以及不可撤销操作前应先询问。
相关技能：scanpy（单细胞 RNA-seq 分析流程）、tensorboard（记录与查看 ML 训练数据）、sentence-transformers（本地生成句子、文本与图像嵌入）。