细胞类型注释：给 29 个 cluster 贴上可复核的标签
1. 这一步在做什么
上一页已经完成预处理：保留 141,871 个细胞和 19,888 个基因，并在 leiden 列中得到 29 个 cluster。
细胞类型注释就是根据每个 cluster 的 marker，把编号换成 B、Myeloid、Epi 等生物学名称。
cluster + marker + 物种 / 组织 / 疾病背景
→ 候选细胞类型 → 证据复核 → 写入注释
omicOS 可以整理 marker、查询候选证据、标出冲突并写入新标签。标签是否符合真实样本和实验设计，仍要由分析者确认。
2. 开始前：激活正确的智能体
智能体是负责某一类任务的专业助手。任务已经明确时，直接激活注释智能体最省事。
打开“智能体”页面，选择一个单细胞注释智能体并点击“激活”。点击可查看原图。
| 智能体 | 适合什么情况 |
|---|---|
| Single-cell Annotator Free | 根据 cluster marker 快速生成初步注释 |
| Single-cell Annotator Pro | 提供候选标签、marker 证据和文献依据 |
| Single-cell Annotator Pro V2 | 先看 marker，再结合候选证据处理冲突和不确定性；本案例使用它 |
| Vertical Agent Selector | 不确定选谁时，让它自动导航；它本身不执行注释 |
本次回放最初激活了预处理智能体。它识别出任务属于注释，并自动转交给 Single-cell Annotator Pro V2。自动导航可以兜底，但任务明确时仍建议手动激活对应智能体。
本教程直接使用预处理教程生成的 leiden 聚类结果。本步骤只给现有 cluster 做细胞类型注释，不会重复预处理，也不会重新聚类。
3. 直接看一个真实案例
这个案例直接使用上一页的预处理结果。
| 项目 | 本案例 |
|---|---|
| 输入规模 | 141,871 个细胞 × 19,888 个基因 |
| 数据背景 | 人类健康泛组织、多组织单细胞数据 |
| cluster 列 | leiden，共 29 个 cluster |
| 注释粒度 | 细胞大类 |
| 目标大类 | Myeloid、TILC、Stromal、Epi、End、B、Plasma、Mast |
可以直接复制下面的提示词：
<预处理后 h5ad 路径>
这是人类健康泛组织数据。
请使用现有 leiden 聚类进行细胞大类注释，不要重新聚类。
主要注释为：Myeloid、TILC、Stromal、Epi、End、B、Plasma、Mast。
本次提示词没有重新指定 resolution。leiden 是上一页使用 resolution 0.8 得到的结果，这一步只是使用现有分群。
案例得到的核心结果
真实结果汇总。29 个 cluster 被映射到 8 个目标大类；点击可查看原图。
| 大类 | Leiden cluster | 细胞数 |
|---|---|---|
| Epi | 9、10、11、12、13、15、16、25、27、28 | 52,547 |
| TILC | 1、3、22、24 | 25,483 |
| Stromal | 14、17、18、20、26 | 22,322 |
| Plasma | 0、2 | 20,486 |
| End | 19、21、23 | 10,357 |
| Myeloid | 4、6、8 | 7,800 |
| B | 5 | 1,685 |
| Mast | 7 | 1,191 |
八类细胞数相加正好是 141,871。主要结果写入 cell_type_pro_primary；回放也确认生成了 cell_type_pro_major。
注释前的 29 个 Leiden cluster。编号只表示分群，不代表细胞身份。
同一批细胞按八个大类着色。TILC 是本项目使用的宽泛淋巴细胞标签；Epi 也不等于已经证明是恶性肿瘤细胞。
到这里，八大类注释已经生成。下面的内容是给需要进一步把关的人看的。
4. omicOS 实际做了什么
| 阶段 | 本案例的处理 |
|---|---|
| 核对输入 | 确认 Human、健康泛组织、major 粒度，并使用现有 leiden；没有重新聚类 |
| 整理 marker | 每个 cluster 最多整理 50 个正 marker、25 个负 marker |
| 生成候选 | 根据 marker 和泛组织背景查询候选细胞类型 |
| 独立判断 | 先只看 marker 判断，再与候选证据比较 |
| 处理冲突 | 标出候选分歧、弱证据和需要人工决定的 cluster |
| 邻接复核 | 检查 6 对高连接或可疑邻接 cluster，全部保留原分群判断 |
| 写回结果 | 生成注释后的 h5ad、UMAP、marker 图、汇总表和复核指南 |
邻接复核不是“两个群在 UMAP 上靠得近，就把它们改成同一种细胞”。本案例的 6 对邻接 cluster 最终都选择 keep_both。
5. 结果应该怎样看
5.1 先看 marker，不要只看 UMAP
八个大类的 marker dotplot。点越大，表达该基因的细胞比例越高；颜色越深，组内平均表达越高。图较宽时可点击查看原图。
本案例中可以重点核对这些 marker 组合：
| 大类 | 代表 marker |
|---|---|
| Plasma | JCHAIN、IGHA1、MZB1、TNFRSF17 |
| TILC | CD3D、CD3E、TRBC2、CCL5 / NKG7 |
| B | MS4A1、CD79A、CD79B、CD19 |
| Myeloid | TYROBP、FCER1G、C1QA / FCN1 |
| Mast | TPSAB1、TPSB2、CPA3、KIT |
| Epi | KRT8、KRT18、KRT19，以及组织特异的上皮 marker |
| Stromal | DCN、LUM、ACTA1 / ACTA2 |
| End | PECAM1、VWF、CLDN5、PLVAP |
不要用一个 marker 拍板。NKG7 可出现在 T 和 NK 相关细胞中；HLA-II 也不是髓系专属。要看成组的正 marker，也要看不该出现的负 marker。
5.2 “全部分完了”不等于“全部确定了”
本次运行状态是：
| 状态 | 结果 |
|---|---|
| 分析状态 | completed_with_warnings |
| 交付状态 | complete |
| 可复现状态 | verified |
| 证据状态 | partial |
| 是否可进入用户复核 | true |
所有 29 个 cluster 都被标记为 HIGH priority review。这里的 HIGH 是复核优先级，不是“高置信度正确”。
最需要关注的群包括：
| Cluster | 汇总大类 | 为什么要复核 |
|---|---|---|
| 16，38 个细胞 | Epi | 肾上皮 marker 与巨噬细胞候选发生冲突；群很小 |
| 22，86 个细胞 | TILC | 同时出现淋巴和髓系信号，候选中包含 neutrophil |
| 26，80 个细胞 | Stromal | CCL19/CXCL12 成纤维信号与 KRT14 上皮信号并存 |
| 8，4,544 个细胞 | Myeloid | monocyte 与 neutrophil 有分歧，但大类都属于 Myeloid |
| 11，191 个细胞 | Epi | 集合管上皮 marker 很强，但数据库支持较依赖单一 marker |
回放中的总览和详细候选表对 16、22、26 的解释并不完全一致。因此这三群不能写成“已经确定”，应回看原始 marker、样本来源和双细胞风险。
6. 已有标签只能作为参考
本案例中，ann1 与新注释在八大类层面的一致率为 90.90%，说明两套标签总体方向接近。
左侧为 ann1，右侧为新注释。并排查看可以快速找到标签分布不同的区域，但不能据此判断哪一套更准确；图较宽时可点击查看原图。
但这个比较并不完全公平。从标签粒度和数据背景看，ann1 更像是各样本分别精细注释后再合并的结果；新注释则是在整合后的泛组织数据中，按整个 Leiden cluster 统一赋予大类标签。两者使用的信息和注释粒度不同。
因此，不要用这个数字判断哪一列“整体更准确”。发现差异时，只把它当作复核线索，再回看 marker、样本来源和 cluster 内部是否混合。
7. 谁负责什么，结果怎样检查
| 分析者负责 | 可以交给 omicOS |
|---|---|
| 确认物种、组织、疾病背景和目标注释粒度 | 读取已聚类的数据并核对 cluster 列 |
| 判断八个目标大类是否适合研究问题 | 整理正、负 marker 和候选证据 |
| 复核小群、混合群和跨组织异质性 | 标出冲突、弱证据和复核优先级 |
| 决定是否拆分 cluster 或重新聚类 | 保留原字段，并写入新的注释列 |
| 判断 Epi 是否为恶性细胞 | 生成 UMAP、dotplot、汇总表和复核指南 |
| 决定旧标签与新标签冲突时怎样处理 | 汇总两套标签的差异，标出需要复核的位置 |
交付前至少检查：
- 实际使用的 cluster 列是否为
leiden，并且没有重新聚类； - 29 个 cluster 是否都有结果，八类细胞数之和是否为 141,871；
- 每一类是否有多条相互支持的 marker；
- 16、22、26 等冲突群是否单独列出；
- 小 cluster 是否可能来自双细胞、低质量细胞或不稳定聚类；
- 每个大类是否被单一样本、组织或癌种主导；
- 原有
ann1是否保留，新注释是否写入新字段； - 报告中的 warning 和
evidence_status=partial是否被记录。
本案例主要交付：
| 文件 | 用途 |
|---|---|
annotated.h5ad |
写入新注释的数据文件，本案例约 28 GB |
REPORT.html / REPORT.md |
注释报告 |
tables/final_annotation_summary.csv |
29 个 cluster 的注释汇总 |
tables/user_decision_guide.csv |
需要人工复核的决定清单 |
| 标签对照报告和交叉表 | 可选地汇总 ann1 与新注释的差异 |
8. 下一步
大类注释确认后，可以进入常规画图与简单差异表达，用现有标签展示 UMAP、统计细胞组成或进行样本级表达比较。
如果某个 cluster 明显混合，先回到预处理检查聚类颗粒度，或只取该群重新分群。若要判断恶性上皮细胞，还需要 CNV 等额外证据；本案例没有执行这一步。
想回看完整路线，可以返回单细胞分析导读。
9. 案例实际回放
9.1 在同一项目中新建对话
在“我的项目A”下新建对话，命名为“3-细胞类型注释”。
项目可以整理多轮分析，但新对话不会自动继承上一轮的全部信息。需要再次提供输入文件，并写清数据背景和 cluster 列。
9.2 激活注释智能体
打开“智能体”页面，手动激活 Single-cell Annotator Pro V2。按当前账号可用权限选择 Free 或 Pro；不确定时可激活 Vertical Agent Selector。
9.3 发送提示词
发送第 3 节中的提示词。路径替换为上一页输出的 adata.h5ad。
9.4 先核对输入
看到第一份检查结果时，先确认：
| 要核对什么 | 本案例应看到什么 |
|---|---|
| 输入规模 | 141,871 个细胞 × 19,888 个基因 |
| 数据背景 | Human / healthy pan-tissue / mixed tissue |
| cluster 列 | leiden，29 个 cluster |
| 注释粒度 | major，细胞大类 |
| 是否重新聚类 | 否 |
数字或列名不一致时，先停下来核对文件，不要继续注释。
9.5 打开结果，不只看完成提示
依次打开：
- 29 群 UMAP；
- 八大类 UMAP；
- marker dotplot；
- cluster 注释汇总；
- 用户复核指南。
确认 cluster 数、细胞数和注释字段一致，并检查图中是否真的有数据、图例和标签。
9.6 用已有标签辅助复核
如果数据中有旧注释，可以继续问：
请把 ann1 作为参考，与 cell_type_pro_primary 做大类层面的差异汇总。
两者的注释粒度和生成方式可能不同，不要判断哪一列整体更准确。
请只标出需要回看 marker、样本来源或混合群的位置。
本案例的八大类一致率为 90.90%。它只说明总体方向接近，不代表两套标签适合直接进行准确率比赛。
9.7 记录最终决定
在项目笔记中记录：
- 使用的 cluster 列和注释粒度；
- 八大类的细胞数；
- 代表 marker；
- 冲突和混合 cluster；
ann1对照结果；- 哪些标签已经确认，哪些仍需复核；
- 后续是否需要拆群、细分或做 CNV。
不要只记录“注释完成”。