3CA 元程序分析：从逐样本 h5ad 找到跨样本复现的肿瘤细胞程序

1. 任务说明

同一种肿瘤细胞里，仍然可能同时存在增殖、应激、上皮分化等不同转录状态。只做细胞亚类注释，往往看不到这些可以跨细胞、跨样本重复出现的表达程序。

3CA（Curated Cancer Cell Atlas）分析的核心思路是：先在每个样本内部寻找共同变化的一组基因，再比较这些程序能否在多个样本中复现。 跨样本重复出现、彼此相似的程序会进一步组成元程序（meta-program，简称 MP）。3CA 研究曾用这种框架在大规模肿瘤单细胞数据中整理肿瘤内转录异质性；本页演示怎样把同一思路用于自己的小队列。

MP 不是新的细胞类型。一个细胞可以同时带有多个程序，只是强弱不同。把细胞分配给某个 MP，主要是为了画图和汇总，不能替代细胞注释。

本案例的完整过程如下：

前端在每个样本内独立运行 NMF，避免先把不同样本混成一个“大样本”；后端再寻找跨样本复现的稳健程序并组成 MP。图中的两个“确认”是实际交互边界，不是额外分析步骤。

2. 智能体选择：C3CA Phase Runner 属于 Lab 订阅

打开“智能体”页面，在 Single Cell Analysis 中找到 C3CA Phase Runner。

卡片右上角标有“实验室”，底部显示“订阅实验室解锁”。这表示该智能体由 omicOS 设为 Lab 订阅能力；需要先具备相应订阅权限，才能激活并运行。它不是普通免费或 Pro 卡片。

订阅等级只决定能否使用这套工作流，不代表生成的生物学结论自动更可靠。结果仍然需要按本页后面的图、表和样本支持进行复核。

3. 真实案例：5 个头颈癌样本的肿瘤细胞

本案例使用 Puram 2017 HNSCC 数据中的 5 个样本。输入已经按样本拆成 5 个 h5ad，每个文件只包含同一谱系的肿瘤上皮细胞。

项目	本案例内容
输入形式	一个文件夹，内含 5 个逐样本 h5ad
分析单位	sample；每个 h5ad 对应一个样本
细胞总数	938
每个样本的细胞数	263、13、229、284、149
每个样本进入 NMF 的基因数	7,000
NMF 的 K 范围	4–9
最终主要结果分支	`spectra_score`

这里不能把 938 个细胞当作 938 个生物学重复。3CA 判断一个程序是否可复现时，关键是它获得了多少样本支持。

样本 Puram_2017_HNSCC_scRNAseq_24 只有 13 个细胞，明显少于其他样本。工作流虽然完成，但这个样本内的程序稳定性需要谨慎看待；不能因为程序在热图上出现，就忽略样本规模差异。

4. 实际执行：发送一句初学者会写的提示词

参考提示词（可直接复制）：把尖括号中的内容替换成自己的文件夹路径。

<存放同一谱系逐样本 h5ad 的文件夹完整路径>

请用 3CA 分析这些肿瘤细胞的转录程序。

不需要在第一句话里写 K 值、过滤阈值或所有输出格式。C3CA Phase Runner 会先检查文件结构和输入矩阵，再向用户确认两个真正需要授权的计算边界：

启动 NMF 前确认一次：确认样本数、细胞数和基因集合后，开始样本内 rust-NMF；
启动 3CA 下游前确认一次：前端交接矩阵验证成功后，开始稳健程序筛选、MP 聚类、质控、评分、出图和报告。

同一阶段内部不会要求用户每完成一个 phase 就回复“继续”。本次运行内部保留了 12 个可审计 phase，但用户看到的是连续的两段流程。

4.1 前端做了什么

前端依次完成：

逐样本输入检查
→ 每个样本选择 7,000 个基因
→ 每个样本独立运行 K=4–9 的 rust-NMF
→ 收集每个 K 下的程序
→ 输出并回读验证 Genes_nmf_w_basis 程序矩阵

5 个样本各产生 39 个程序，共得到 195 个样本内程序。这里的“程序”是 NMF 找到的一组共同变化基因，还不是最终 MP。

4.2 后端做了什么

后端依次完成：

验证前端矩阵
→ 选择跨 K、跨样本复现的稳健程序
→ 将相似稳健程序聚为候选 MP
→ MP 质控和生物学注释
→ 回到细胞计算 MP 分数
→ usage 与敏感性分支复核
→ 最终图和报告

本次结果从 195 个样本内程序中保留 26 个稳健程序，形成 4 个候选 MP；质控后保留 3 个 MP，另有 1 个低质量候选被明确记录为排除，而不是静默消失。

5. 结果解读：从程序是否复现开始看

5.1 稳健程序相似性：先看 MP 是怎样组成的

横纵轴都是稳健 NMF 程序；颜色越亮，top genes 的 Jaccard 相似度越高。红色虚线方框标出最终 MP 中彼此相似的程序块。应检查亮色是否主要集中在方框内部，而不是所有程序都同样相似。

这张最终 companion 图展示的是进入所示最终 MP 块的 17 个程序，不是“稳健程序总数”。报告中的 26 个稳健程序还包括没有进入这些最终保留块的程序，两个数字处在不同筛选阶段，不能互相替代。

5.2 跨样本总热图：检查程序能否在多个样本中看到

每列是一个真实细胞，每行是 MP 基因。顶部第一条颜色带表示样本，第二条表示细胞被汇总到哪个 MP；白色为 Unassigned。检查每个红色表达块是否由多个样本共同贡献，以及 MP 基因块与对应细胞块是否形成较清楚的阶梯状结构。

热图包含全部 938 个细胞，没有为了让图更平滑而把多个细胞平均成一列。红色表示该基因在相应细胞中的相对表达较高，不能跨行直接比较绝对表达量。

本次细胞级汇总为：

细胞汇总标签	细胞数	占全部细胞
`MP_3`	204	21.7%
`MP_1`	190	20.3%
`MP_2`	152	16.2%
`Unassigned`	392	41.8%

Unassigned 不等于低质量细胞，也不等于“没有生物学状态”。它只表示在当前 MP 集合和当前分配规则下，没有足够明确地归入某一个 MP。工作流从默认规则开始搜索，最终选择能把未分配比例降到 50% 以下、同时保留 3 个活跃 MP 的设置；这项调整已写入运行记录。

5.3 逐样本热图：不要只看合并图

样本 18 含 263 个细胞。顶部给出每个 MP 和 Unassigned 的比例；主图检查对应 MP 的基因块是否在相应细胞块内升高。每个最终 MP 都应再去其他 4 张逐样本图中检查，不能用一张“最好看”的图代表整个队列。

final_figures 中一共保存 5 张逐样本热图。小样本 24 只有 13 个细胞，其百分比很容易被少数细胞改变，解读时应优先报告绝对细胞数并保留这一限制。

5.4 GO/KEGG：给 MP 一个可复核的生物学线索

每个面板对应一个最终 MP，横轴是富集显著性。结果提示 MP_1 与凋亡执行调控、MP_2 与表皮发育、MP_3 与有丝分裂相关微管组织有关。查看时要同时看基因组成和其他证据，不能只复制最显著的通路名称。

这些名称是根据富集结果生成的建议标签，不是已验证的机制：

MP	本次建议标签	样本支持	成员程序数
`MP_1`	Regulation of execution phase of apoptosis	4	8
`MP_2`	Epidermis development	5	5
`MP_3`	Microtubule cytoskeleton organization involved in mitosis	4	4

5.5 marker 重叠：用独立线索复核，不替代通路结果

点大小表示重叠基因数，颜色表示 Jaccard 相似度。MP_3 与 G2M marker 的重叠支持有丝分裂解释；MP_2 与角化/上皮相关 marker 的多处小重叠支持表皮分化方向。单个小点只能作为提示。

这张图适合回答“富集标签有没有另一组基因证据支持”，不适合把 MP 直接命名成细胞亚型。

5.6 两种基因排序分支：检查结果是否只依赖一种表示

对角线上的三个亮块表示两种排序方式都找到了相对应的 3 个 MP。对应 MP 的 Jaccard 相似度分别约为 81.8%、78.6% 和 72.4%；非对应位置接近 0，说明配对较明确。

工作流将原始 NMF basis 排序的 spectra_score 保留为主要分支，把 spectra_tpm 作为敏感性分析。两者一致会增强“结果不只依赖一种排序”的信心，但仍不能证明这些程序具有因果作用。

5.7 没有采用的图也要说明原因

本次 final_figures 还生成了 scRNA-seq 与 snRNA-seq 样本贡献散点图。但本案例 5 个样本全部是 scRNA-seq，没有 snRNA-seq 对照，纵轴没有可比较变化，因此不作为本教程的生物学主结果展示。文件生成成功不等于图就适合回答当前问题。

6. 核心输出文件

文件或文件夹	用途
`final_figures/`	11 张最终 PNG、图件索引和 manifest
`final_figures/figure_index.tsv`	图件类别、展示顺序和深层来源路径
`results/c3ca_my_study/genes_nmf_w_basis/`	前端交给后端的逐样本程序矩阵
`results/c3ca_my_study/branches/spectra_score/programs/`	稳健程序和 top genes
`results/c3ca_my_study/branches/spectra_score/mps/`	候选/最终 MP、质控和注释表
`results/c3ca_my_study/branches/spectra_score/scoring/`	细胞 MP 分数、分配和阈值搜索记录
`results/c3ca_my_study/branches/spectra_score/usage_validation/`	NMF usage 与 MP signature 的复核
`results/c3ca_my_study/reports/c3ca_methods_results_report.html`	最终方法与结果报告
`results/c3ca_my_study/workflow/`	12 个 phase 的 manifest、报告和检查点

final_figures 是最容易找到的展示入口；深层目录中的表格和 manifest 才是复核数字、排查 warning 和续跑的依据。

7. 人机职责

分析者负责	可以交给 omicOS
决定哪些样本属于同一谱系、可以放在同一次分析中	检查逐样本 h5ad、基因集合和矩阵结构
判断样本数和每个样本的细胞数是否足以支持问题	在每个样本内运行 NMF 并保留可续跑检查点
根据基因、通路、marker 和研究背景命名 MP	筛选稳健程序、聚类候选 MP、生成证据表和图
决定 `Unassigned` 是否需要进一步研究	搜索并记录分配规则，输出逐样本分布
决定哪些结论需要外部队列或实验验证	比较敏感性分支并生成完整报告

omicOS 可以自动完成长流程和文件审计，但不能决定“这个 MP 就是治疗靶点”或“这个程序导致肿瘤进展”。

8. 验收清单

输入按样本拆分，每个 h5ad 只包含本次研究的同一细胞谱系；
报告列出的样本数、细胞数与自己的输入一致；
前端交接矩阵已完整回读验证，不只有“任务提交成功”；
稳健程序总数、候选 MP 数和最终 MP 数能在报告中对应；
被排除的低质量 MP 有原因记录，没有静默删除；
合并热图和全部逐样本热图都能打开，程序不是只由一个样本支撑；
MP 标签同时查看了基因、GO/KEGG、marker 和样本支持；
Unassigned 比例和自动选择规则已记录，没有把未分配细胞写成“无状态细胞”；
敏感性分支的相似性结果与主要 MP 大体对应；
结论使用“转录程序”“相关”或“提示”，没有写成细胞类型、实测功能或因果机制。

如果只得到程序表、没有看到最终图，可以继续发送：

补充参考提示词（可直接复制）

请继续完成 3CA 下游，并把最终图和报告放到容易找到的文件夹。

9. 下一步

完成 MP 发现后，可以比较每个样本或实验条件中的 MP 分布，也可以在独立队列中验证 MP 基因集。条件比较必须回到 sample 或 donor 层面；不能把同一样本中的每个细胞当成独立重复。

如果要研究 MP 与临床结局、治疗反应或空间位置的关系，需要另外准备对应的样本级元数据，并设计独立统计分析。本页的 5 个样本主要用于演示流程，不足以支持宽泛的临床推断。

10. 操作回放

整理输入：把同一谱系细胞按样本保存为多个 h5ad，放进同一个文件夹。
确认权限：在智能体页面找到带“实验室”标识的 C3CA Phase Runner；如界面显示“订阅实验室解锁”，先完成 Lab 订阅授权。
发送第 4 节提示词：只写输入文件夹路径和“请用 3CA 分析”。
第一次确认：阅读输入检查摘要，确认样本数、细胞数无误后启动 NMF。
第二次确认：确认 Genes_nmf_w_basis 交接成功后启动 3CA 下游。
按证据顺序看结果：稳健程序相似性 → 合并热图 → 逐样本热图 → GO/KEGG → marker 重叠 → 敏感性分支。
记录限制：样本数、每个样本的细胞数、排除 MP、Unassigned 比例、自动调整和缺失的比较维度。

7. 3CA 元程序分析