用途
UMAP-Learn 实现了 UMAP（Uniform Manifold Approximation and Projection），一种用于可视化与通用非线性降维的降维技术。它可应用于需要快速、可扩展嵌入的场景，能够保留数据的局部与全局结构，并支持监督学习与聚类预处理。
主要能力
- 作为 t-SNE 或 PCA 的替代方案，遵循 scikit-learn 约定。
- 支持通过 n_neighbors、min_dist、n_components、metric 等参数控制嵌入行为。
- 支持监督降维（通过 y 参数传入标签）与半监督降维（未标注点标记为 -1）。
- 支持度量学习：在标注数据上训练嵌入，再应用到新的未标注数据。
- 作为 HDBSCAN 等基于密度的聚类算法的预处理步骤。
- 提供 transform 方法，将新数据投影到已学习的嵌入空间，并可与 scikit-learn 管道集成。
- 提供参数化 UMAP（Parametric UMAP），使用 TensorFlow/Keras 训练编码器网络，支持自定义架构与逆变换。
- 提供逆变换（inverse_transform），从低维嵌入重构高维数据。
- 提供 AlignedUMAP，用于分析时间序列或相关数据集。
使用方式
安装命令：
uv pip install umap-learn
基本用法：UMAP 遵循 scikit-learn 约定。使用前始终对特征进行标准化，以确保各维度获得相同权重。
单步使用（拟合与转换）：
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_
典型工作流：预处理数据、创建并拟合 UMAP、可视化。
参数调节指南：
- n_neighbors（默认 15）：平衡局部与全局结构。低值（2-5）强调局部细节但可能使数据碎片化；中值（15-20）平衡；高值（50-200）优先考虑整体拓扑结构。
- min_dist（默认 0.1）：控制低维空间中点的聚集紧密程度。低值（0.0-0.1）产生聚集嵌入，适用于聚类；高值（0.5-0.99）防止紧密堆积。
- n_components（默认 2）：输出嵌入空间的维度。2-3 维用于可视化；5-10 维用于聚类预处理；10-50 维用于下游机器学习模型的特征工程。
- metric（默认 'euclidean'）：输入数据点之间的距离计算方式。支持 Minkowski 变体、空间度量、相关性度量（如 cosine、correlation）、二元数据度量（如 hamming、jaccard）以及通过 Numba 定义的自定义度量。
监督与半监督降维：
- 监督 UMAP：拟合时通过 y 参数传入目标标签。
- 半监督 UMAP：对部分标签数据，未标注点标记为 -1。
- 度量学习：在标注数据上训练嵌入，再应用到新的未标注数据。
用于聚类：UMAP 可作为 HDBSCAN 等基于密度的聚类算法的预处理。聚类时推荐参数：n_neighbors 增至约 30，min_dist 设为 0.0，n_components 使用 5-10 维。注意 UMAP 并不完全保留密度，可能产生人为的簇划分，应验证并探索结果簇。
转换新数据：通过 transform() 方法将新数据投影到已学习的嵌入空间。transform 操作通常高效（一般小于 1 秒），首次调用可能因 Numba JIT 编译而较慢。当训练与测试数据分布不一致时，可考虑使用参数化 UMAP。
高级功能：
- 参数化 UMAP：用学习到的神经网络映射函数替代直接嵌入优化，使用 TensorFlow/Keras 训练编码器网络，支持重构（逆变换）与自定义架构（如用于图像的 CNN、用于序列的 RNN）。安装：
uv pip install umap-learn[parametric_umap]，需要 TensorFlow 2.x。 - 逆变换：从低维嵌入重构高维数据，计算开销大，在嵌入凸包之外效果较差，簇间空隙区域精度下降。
- AlignedUMAP：用于分析时间或相关数据集（如时间序列实验、批次数据），保持一致的坐标系。
可复现性：UMAP 使用随机优化，应始终设置 random_state 参数以确保结果可复现。
适用场景
- 2D/3D 数据可视化。
- 聚类预处理（与 HDBSCAN 配合）。
- 监督与半监督降维。
- 面向下游机器学习模型的特征工程。
- 从低维嵌入重构高维数据。
- 跨相关数据集的对齐嵌入分析。
- 使用自定义神经网络架构的参数化嵌入。
限制
- 应用前必须对特征进行标准化，以确保各维度权重一致。
- UMAP 不完全保留密度，可能创建人为的簇划分，需验证结果。
- transform 方法假设训练与测试数据在高维空间的整体分布一致，当该假设不成立时需改用参数化 UMAP。
- 逆变换计算开销大，且在嵌入凸包之外效果差。
- 不设置 random_state 时结果会因随机优化而略有差异。
- 参数化 UMAP 需要 TensorFlow 2.x。
- 大数据集上性能可能较慢，可设置 low_memory=True（默认）或先用 PCA 降维。
常见问题与解决
- 出现不连通组件或碎片化簇：增大 n_neighbors。
- 簇过于分散或分离不佳：减小 min_dist。
- 聚类效果差：使用聚类专用参数（n_neighbors=30, min_dist=0.0, n_components=5-10）。
- transform 结果与训练差异大：确保测试数据分布匹配训练，或使用参数化 UMAP。
- 大数据集性能慢：设置 low_memory=True（默认），或先用 PCA 降维。
- 所有点塌缩为单一簇：检查数据预处理（确保正确缩放），增大 min_dist。