single-cell-annotation-skills-with-omicverse

使用 omicverse 进行单细胞注释

概述

使用此技能，复现并调整 omicverse 教程中记录的单细胞注释操作指南：SCSA t_cellanno.ipynb、MetaTiME t_metatime.ipynb、CellVote t_cellvote.md 和 t_cellvote_pbmc3k.ipynb、CellMatch t_cellmatch.ipynb、GPTAnno t_gptanno.ipynb，以及标签转移 t_anno_trans.ipynb。以下各节重点介绍所需输入、训练／推理步骤，以及如何解读输出。

说明

1. SCSA 自动聚类注释

   • 数据要求：需要来自 10x Genomics 的 PBMC3k 原始计数（pbmc3k_filtered_gene_bc_matrices.tar.gz），或处理后的 sample/rna.h5ad。下载说明见笔记本；请解压到 data/filtered_gene_bc_matrices/hg19/。确保有可用的 SCSA SQLite 数据库（例如教程中 Figshare／Drive 链接提供的 pySCSA_2024_v1_plus.db），并将 model_path 指向其位置。
   • 预处理与模型拟合：使用 ov.io.read_10x_mtx 加载数据，运行 QC（ov.pp.qc）、归一化和 HVG 选择（ov.pp.preprocess）、缩放（ov.pp.scale）、PCA（ov.pp.pca）、邻居计算、Leiden 聚类，并计算排序标记基因（sc.tl.rank_genes_groups）。实例化 scsa = ov.single.pySCSA(...)，选择 target='cellmarker' 或 'panglaodb'、组织范围和阈值（foldchange、pvalue）。
   • 推理与解读：调用 scsa.cell_anno(clustertype='leiden', result_key='scsa_celltype_cellmarker') 或 scsa.cell_auto_anno，将预测结果添加到 adata.obs。通过 ov.pl.embedding 或 sc.pl.dotplot 与基于手动标记基因的标签进行比较，检查标记基因字典（ov.single.get_celltype_marker），并使用 scsa.get_model_tissue() 查询支持的组织。使用 ROI／ROE 辅助函数（ov.utils.roe、ov.utils.plot_cellproportion）验证丰度趋势。

2. MetaTiME 肿瘤微环境状态

   • 数据要求：需要带有 scVI 潜在嵌入的批次 TME AnnData。教程使用 Figshare 上的 TiME_adata_scvi.h5ad（https://figshare.com/ndownloader/files/41440050）。如果从计数数据开始，请先运行 scVI（scvi.model.SCVI），以填充 adata.obsm['X_scVI']。
   • 预处理与模型拟合：可选地通过 adata.obs['isTME'] 筛选出非恶性细胞。在潜在表示上重新构建邻居图（sc.pp.neighbors(adata, use_rep="X_scVI")），并使用 umap 生成嵌入（adata.obsm['X_umap'] = ov.pp.umap(...)）。初始化 TiME_object = ov.single.MetaTiME(adata, mode='table')；如需更细粒度的结果，可进行过度聚类：TiME_object.overcluster(resolution=8, clustercol='overcluster')。
   • 推理与解读：运行 TiME_object.predictTiME(save_obs_name='MetaTiME')，以分配次要状态和 Major_MetaTiME。使用 TiME_object.plot 或 sc.pl.embedding 进行可视化。通过比较聚类层级的分布，并确认 MetaTiME 和 Major_MetaTiME 列与预期的生态位相符，来解读输出。

3. CellVote 共识标注

   • 数据要求：聚类后的 AnnData（例如，将 PBMC3k 保存为 CELLVOTE_PBMC3K 环境变量，或保存为 data/pbmc3k.h5ad），以及至少两列预先计算好的注释（教程中模拟为 scsa_annotation、gpt_celltype、gbi_celltype）。通过 sc.tl.rank_genes_groups 为每个簇准备标记基因。
   • 预处理与模型拟合：完成标准预处理（归一化、log1p、HVG、PCA、邻居、Leiden）后，构建标记基因字典 marker_dict = top_markers_from_rgg(adata, 'leiden', topn=10)，或通过 ov.single.get_celltype_marker 构建。实例化 cv = ov.single.CellVote(adata)。
   • 推理与解读：调用 cv.vote(clusters_key='leiden', cluster_markers=marker_dict, celltype_keys=[...], species='human', organization='PBMC', provider='openai', model='gpt-4o-mini')。离线示例会通过打补丁的方式替换仲裁逻辑，以避免调用 API；在线投票需要有效的凭据。最终共识标签保存在 adata.obs['CellVote_celltype'] 中。将每个簇的多数票与输入来源（adata.obs[['leiden', 'scsa_annotation', ...]]）进行比较，以说明判断依据。

4. CellMatch 本体映射

   • 数据要求：带注释的 AnnData，例如 pertpy.dt.haber_2017_regions()，其中包含 adata.obs['cell_label']。通过 ov.single.download_cl(...) 下载 Cell Ontology JSON（cl.json），或使用手动链接；还可选择下载 Cell Taxonomy 资源（Cell_Taxonomy_resource.txt）。确保能够访问 SentenceTransformer 模型（sentence-transformers/all-MiniLM-L6-v2、BAAI/bge-base-en-v1.5 等）；如果处于离线环境，请将模型下载到 local_model_dir。
   • 预处理与模型拟合：使用 ov.single.CellOntologyMapper(cl_obo_file='new_ontology/cl.json', model_name='sentence-transformers/all-MiniLM-L6-v2', local_model_dir='./my_models') 创建映射器。运行 mapper.map_adata(...) 以分配本体派生的标签/ID；也可在调用 load_cell_taxonomy_resource 后启用分类匹配（use_taxonomy=True）。
   • 推理与解读：查看映射摘要（mapper.print_mapping_summary_taxonomy），并检查以 cell_ontology、cell_ontology_cl_id 或 enhanced_cell_ontology 着色的嵌入图。使用 mapper.find_similar_cells('T helper cell')、mapper.get_cell_info(...) 等辅助查询，并浏览类别，以验证本体覆盖范围。

5. GPTAnno 大模型驱动的注释

   • 数据要求：相同的 PBMC3k 数据集（原始矩阵或 .h5ad）和簇分配结果。需要能够访问大模型端点——对于兼容 OpenAI 的提供方（provider='openai'、'qwen'、'kimi' 等），请配置 AGI_API_KEY；或者为 ov.single.gptcelltype_local 提供本地模型路径。
   • 预处理与模型拟合：按照上文所述的 SCSA 工作流步骤执行质控、归一化、HVG、缩放、PCA、邻居、Leiden 和标记基因发现（可复用 SCSA 工作流的输出）。使用 ov.single.get_celltype_marker(adata, clustertype='leiden', rank=True, key='rank_genes_groups', foldchange=2, topgenenumber=5) 自动构建标记基因字典。
   • 推理与解读：调用 ov.single.gptcelltype(...) 并指定组织/物种背景以及所需的提供方/模型。对响应进行后处理，以保留整洁的标签（result[key].split(': ')[-1]...），并将其写入 adata.obs['gpt_celltype']。比较嵌入图（ov.pl.embedding(..., color=['leiden','gpt_celltype'])），以验证簇的身份。如果在离线环境下运行，请调用 ov.single.gptcelltype_local 并使用已下载的指令微调检查点。

6. 加权 KNN 注释迁移

   • 数据要求：具有对齐嵌入的跨模态 GLUE 输出，例如 data/analysis_lymph/rna-emb.h5ad（已注释 RNA）和 data/analysis_lymph/atac-emb.h5ad（查询 ATAC），二者均包含 obsm['X_glue']。
   • 预处理与模型拟合：加载两种模态，可选择合并以绘制 QC 图，并使用 ov.utils.mde 计算共享的低维嵌入。使用 ov.utils.weighted_knn_trainer(train_adata=rna, train_adata_emb='X_glue', n_neighbors=15) 训练邻居模型。
   • 推理与解读：通过 labels, uncert = ov.utils.weighted_knn_transfer(query_adata=atac, query_adata_emb='X_glue', label_keys='major_celltype', knn_model=knn_transformer, ref_adata_obs=rna.obs) 迁移标签。将预测结果存入 atac.obs['transf_celltype']，将不确定性存入 atac.obs['transf_celltype_unc']；如果希望命名保持一致，可复制到 major_celltype。使用 ov.pl.embedding 可视化，并检查不确定性以标记存在歧义的细胞。

防御式验证模式

# Before SCSA: verify rank_genes_groups has been computed
assert 'rank_genes_groups' in adata.uns, \
    "Marker genes required. Run sc.tl.rank_genes_groups(adata, groupby='leiden') first."

# Before any annotation: verify clustering exists
assert 'leiden' in adata.obs.columns or 'louvain' in adata.obs.columns, \
    "Clustering required. Run ov.pp.leiden(adata) or sc.tl.leiden(adata) first."

# Before CellVote: verify multiple annotation columns exist
annotation_keys = ['scsa_annotation', 'gpt_celltype']  # adjust to actual keys
for key in annotation_keys:
    assert key in adata.obs.columns, f"Annotation column '{key}' not found — run annotators first"

关键 API 参考——准确的函数签名

pySCSA——重要：参数是 clustertype，不是 cluster

正确用法：

# Step 1: Initialize pySCSA
scsa = ov.single.pySCSA(
    adata,
    foldchange=1.5,
    pvalue=0.01,
    species='Human',
    tissue='All',
    target='cellmarker'  # or 'panglaodb'
)

# Step 2: Run annotation - NOTE: use clustertype='leiden', NOT cluster='leiden'!
anno_result = scsa.cell_anno(clustertype='leiden', cluster='all')

# Step 3: Add cell type labels to adata.obs
scsa.cell_auto_anno(adata, clustertype='leiden', key='scsa_celltype')
# Results are stored in adata.obs['scsa_celltype']

错误用法——请勿使用：

# WRONG! 'cluster' is NOT a valid parameter for cell_auto_anno!
# scsa.cell_auto_anno(adata, cluster='leiden')  # ERROR!

COSG 标记基因——结果存储在 adata.uns 中，而不是 adata.obs

正确用法：

# Step 1: Run COSG marker gene identification
ov.single.cosg(adata, groupby='leiden', n_genes_user=50)

# Step 2: Access results from adata.uns (NOT adata.obs!)
marker_names = adata.uns['rank_genes_groups']['names']  # DataFrame with cluster columns
marker_scores = adata.uns['rank_genes_groups']['scores']

# Step 3: Get top markers for specific cluster
cluster_0_markers = adata.uns['rank_genes_groups']['names']['0'][:10].tolist()

# Step 4: To create celltype column, manually map clusters to cell types
cluster_to_celltype = {
    '0': 'T cells',
    '1': 'B cells',
    '2': 'Monocytes',
}
adata.obs['cosg_celltype'] = adata.obs['leiden'].map(cluster_to_celltype)

错误用法——请勿使用：

# WRONG! COSG does NOT create adata.obs columns directly!
# adata.obs['cosg_celltype']  # This key does NOT exist after running COSG!
# adata.uns['cosg_celltype']  # This key also does NOT exist!

需要避免的常见问题

1. pySCSA 参数混淆：

   • clustertype = 哪一列 obs 包含聚类标签（例如，'leiden'）
   • cluster = 要注释的具体聚类（'all' 或特定聚类 ID）
   • 这是两个不同的参数！

2. COSG 结果访问：

   • COSG 是标记基因查找工具，不是细胞类型注释工具
   • 结果是按聚类排列的基因排名，存储在 adata.uns['rank_genes_groups'] 中
   • 若要指定细胞类型，必须根据标记基因手动将聚类映射到细胞类型

3. OmicVerse 中的结果存储模式：

   • 细胞类型注释 → adata.obs['<key>']
   • 标记基因结果 → adata.uns['<key>']（包括 'names'、'scores'、'logfoldchanges'）
   • 差异表达 → adata.uns['rank_genes_groups']

示例

• “在 PBMC3k 上使用 CellMarker 和 PanglaoDB 两种参考运行 SCSA，然后与手动标记基因分配结果进行基准测试，再将结果输入 CellVote。”
• “在 MetaTiME Figshare 数据集中注释肿瘤微环境状态，突出显示 Major_MetaTiME 类别，并导出每位患者的标签分布。”
• “下载 Cell Ontology 资源，将 haber_2017_regions 聚类映射到本体术语，并利用 Cell Taxonomy 提示丰富存在歧义的聚类。”
• “将 RNA 衍生的 major_celltype 标签迁移到 GLUE 整合的 ATAC 细胞，并报告标签迁移不确定性较高的聚类。”

参考资料

• 教程和笔记本：t_cellanno.ipynb、t_metatime.ipynb、t_cellvote.md、t_cellvote_pbmc3k.ipynb、t_cellmatch.ipynb、t_gptanno.ipynb、t_anno_trans.ipynb。
• 示例数据和资源：来自 10x Genomics 的 PBMC3k 矩阵、MetaTiME TiME_adata_scvi.h5ad（Figshare）、SCSA 数据库下载内容、data/analysis_lymph/ 下的 GLUE 嵌入、Cell Ontology cl.json 以及 Cell Taxonomy 资源。
• 快速复制命令：reference.md。