Scanpy 中 ingest 函数使用 PCA 时的注意事项

问题背景

在使用 Scanpy 进行单细胞数据分析时，ingest 函数是一个常用的工具，用于将参考数据集（reference dataset）的标注信息转移到新的数据集（query dataset）上。然而，在实际使用过程中，用户可能会遇到一个关于 PCA 的错误提示，这往往是由于对数据预处理流程理解不足导致的。

错误现象

当用户尝试按照官方文档示例运行 ingest 函数时，可能会遇到以下错误：

AttributeError: 'Ingest' object has no attribute '_pca_use_hvg'

这个错误提示表明，在尝试执行 PCA 分析时，程序无法找到与高变基因（HVG）相关的属性。

原因分析

这个错误的核心原因在于数据预处理步骤不完整。ingest 函数内部依赖于 PCA 降维结果来进行数据对齐和标注转移，但用户没有在参考数据集上预先执行 PCA 分析。

具体来说：

1. ingest 函数期望参考数据集 adata_ref 已经包含 PCA 分析结果
2. 如果没有执行 PCA，函数会尝试自动执行，但缺少必要的参数（如是否使用高变基因）
3. 这导致了上述属性错误

解决方案

正确的使用流程应该包含以下关键步骤：

1. 数据预处理：确保参考数据集和新数据集使用相同的基因集
2. PCA 分析：在参考数据集上显式执行 PCA
3. 邻居图构建：基于 PCA 结果构建邻居图
4. UMAP 可视化（可选）：用于可视化验证
5. 执行 ingest：最后进行标注转移

修正后的代码示例如下：

import scanpy as sc

# 加载示例数据集
adata_ref = sc.datasets.pbmc3k_processed()
adata = sc.datasets.pbmc68k_reduced()

# 确保使用相同的基因集
var_names = adata_ref.var_names.intersection(adata.var_names)
adata_ref = adata_ref[:, var_names]
adata = adata[:, var_names]

# 清除可能存在的旧结果
del adata.obs["louvain"]
adata.uns = {}
adata_ref.uns = {}

# 关键步骤：在参考数据集上执行PCA
sc.pp.pca(adata_ref)

# 后续分析流程
sc.pp.neighbors(adata_ref)
sc.tl.umap(adata_ref)
sc.tl.ingest(adata, adata_ref, obs="louvain")

技术细节

1. PCA 在单细胞分析中的作用：

   • 降维：将高维基因表达数据降至可管理的维度
   • 去噪：保留数据的主要变异来源
   • 加速计算：减少后续计算复杂度

2. 高变基因（HVG）的重要性：

   • 单细胞数据通常包含大量基因，但只有部分基因具有生物学意义
   • 使用 HVG 可以提高分析的效率和准确性
   • 在 PCA 前通常需要先识别 HVG

3. ingest 函数的工作原理：

   • 基于参考数据集的 PCA 空间
   • 将新数据投影到同一空间
   • 使用最近邻算法进行标注转移

最佳实践建议

1. 完整的预处理流程：

   • 质量控制 → 归一化 → HVG 选择 → PCA
   • 确保参考数据集和新数据集使用相同的预处理步骤

2. 参数检查：

   • 在执行 ingest 前，检查参考数据集是否包含必要的分析结果
   • 确认 .obsm 中是否有 'X_pca' 等关键结果

3. 错误排查：

   • 遇到类似错误时，首先检查预处理步骤是否完整
   • 确认数据结构和属性是否符合函数要求

总结

Scanpy 的 ingest 函数是一个强大的标注转移工具，但其正确使用依赖于完整的数据预处理流程。特别是 PCA 分析步骤，必须在参考数据集上显式执行，否则会导致函数内部逻辑出错。理解这一机制不仅可以帮助用户避免常见错误，还能提高单细胞数据分析的质量和效率。

对于初学者来说，建议在使用任何高级分析函数前，先完整了解其依赖的前置步骤，这样可以减少调试时间，提高工作效率。