技能介绍

单细胞测序的聚类结果只是数学上的分组，研究者真正关心的是每个簇对应什么生物学身份。手工查看标志基因耗时且主观，批次间结论难以复现，这正是细胞注释工具存在的理由。singlecell-cell-annotation 把主流注释方法收拢到一套调用流程里，让分类器或参考图谱替你给出可记录的细胞类型标签。

核心能力

该技能覆盖四类自动化注释路线，可按语言生态和参考资源选择：

CellTypist（Python）：加载预训练模型或自训练模型，在簇级别通过多数投票得到一致性预测，结果写入 AnnData。支持在领域特异性参考数据上训练逻辑回归分类器，含特征筛选步骤。
SingleR（R）：将每个细胞的表达谱与参考转录组做相关性比较，并对低置信度标注做剪枝处理。
Azimuth（R/Seurat）：将查询细胞映射到预构建的参考图谱，同时迁移细胞类型标签与置信度分数。
scPred（R）：从带标签的参考数据提取信息性 PCA 特征，训练 SVM/RF 分类器后应用于查询数据。

关键步骤

统一标签词汇表：这是最容易踩坑的一步。SingleR 输出 CD4 T，Azimuth 输出 CD4+_T_cells，CellTypist 输出 CD4+ T cells。若不先映射到共同命名空间，多数投票几乎必然返回 Ambiguous。
多工具共识整合：汇总各方法预测结果，通过多数投票确定最终标签，并显式标记方法间存在分歧的细胞。
注释方法比较：计算标签集之间的调整兰德指数（ARI）与归一化互信息（NMI），构建混淆矩阵，用于定量评估方法间一致性。
标志基因验证：用已知 marker 反向核验注释结果，确认生物学合理性。

适用边界

不同方法对输入数据的预处理要求严格，混用会导致静默错误：

CellTypist 要求 .X 为 target_sum=1e4 的 log1p 归一化数据。若数据已执行过 sc.pp.scale()，必须从原始 counts 重新归一化，否则会报 ImportError、AttributeError 或 TypeError。
Azimuth 需要 RNA assay 的 counts slot 含原始计数，不接受 log 转换后的值。
SingleR 在 as.SingleCellExperiment() 默认使用 Seurat RNA@data（log-normalized），符合其输入要求。
scPred 的 getFeatureSpace() 要求参考数据已完成 PCA。

技能参考示例基于 pandas 2.2+、scanpy 1.10+、scikit-learn 1.4+ 编写。版本不匹配时，先用 pip show 或 packageVersion() 确认实际 API 签名，再调整代码，不要盲目重试。

细胞注释的质量取决于参考图谱的覆盖度和数据质量。图谱与查询数据物种、组织或实验条件差异过大时，置信度分数会明显下降，此时应考虑自训练模型或改用标志基因手工注释。