预处理：从 counts 得到可注释的细胞分群
1. 这一步在做什么
上一页已经把数据整理好了：这是人类单细胞数据，表达值是 raw counts，并且 obs 中有可用的样本信息。
预处理会继续完成质量控制、归一化、降维、批次校正和聚类。最后得到细胞分群及每群的 marker，供下一步细胞类型注释使用。
raw counts → QC → 归一化 → 高变基因 → PCA
→ 批次校正 → UMAP / 聚类 → marker
这一步还不给细胞正式命名。目标是得到一份可以检查、可以注释的数据。
2. 开始前：激活正确的智能体
智能体是负责某一类任务的专业助手。激活单细胞预处理智能体后，可以把当前对话明确交给对应流程。
打开“智能体”页面，找到单细胞预处理智能体并点击“激活”。图中红色箭头标出了入口和按钮；点击可查看原图。
| 智能体 | 适合什么情况 |
|---|---|
| Single-cell Preprocessor（Plus） | 完成常规 QC、归一化、降维、批次校正、聚类和 marker 计算 |
| Single-cell Preprocessor Pro | 完成同样的核心流程，并提供更完整的参数记录、结果校验和可追溯交付；本案例使用它 |
| Vertical Agent Selector | 不确定选谁时，让它自动导航到合适的智能体；它本身不执行预处理 |
任务明确时，建议直接激活可用的预处理智能体。没有 Pro 权限时，Plus 也可以完成核心流程。
3. 直接看一个真实案例
这个案例直接使用上一页输出的数据。它是从人类健康泛组织图谱中筛选出的 6 个 dataset 子集，不是泛癌数据。
| 项目 | 本案例 |
|---|---|
| 输入规模 | 142,540 个细胞 × 21,812 个基因 |
| 表达数据 | raw counts |
| 批次字段 | sampleID，共 65 类 |
| 批次校正 | Harmony，按 sampleID 执行 |
| 聚类参数 | Leiden resolution = 0.8 |
| 高变基因 | 2,000 个 HVG |
真实提问很短：
可以直接复制下面的提示词：
<第一步输出的 h5ad 路径>
对该数据进行预处理
对 sampleID 进行去批次
res 选为 0.8
HVGs 设为 2000
sampleID 是本案例由用户指定的 batch key。换成自己的数据时，要根据实验设计选择字段，不能默认照抄。
HVG 是“高变基因”，也就是不同细胞之间变化较明显、用于后续降维和聚类的一组基因。本案例由用户指定 2,000 个。
案例得到的核心结果
真实结果表。它汇总了 QC、归一化、Harmony、聚类和 marker；点击可查看原图。
| 检查项 | 结果 |
|---|---|
| QC 前后细胞数 | 142,540 → 141,871，移除 669 个细胞 |
| 基因数 | 21,812 → 19,888 |
| 高变基因 | 2,000 个 |
| 批次处理 | Harmony 按 65 个 sampleID 执行 |
| 聚类 | resolution 0.8，得到 29 个 cluster |
| marker | 每群计算 Wilcoxon 和 COSG top 50 marker |
Harmony 后按 sampleID 着色的 UMAP。颜色混合可以帮助发现明显的样本分离，但不能单独证明批次校正正确。图例较密时，可点击图片查看原图。
resolution 0.8 得到 29 个 cluster。编号只是分群标签，还不是细胞类型。
到这里，数据已经具备进入细胞类型注释的技术条件。下面的内容是给需要进一步把关的人看的。
4. omicOS 实际做了什么
| 阶段 | 本案例的处理 |
|---|---|
| QC | min_genes=200、min_counts=1000、min_cells=3、max_genes_by_counts=6000、max_mito=25% |
| 归一化 | 每个细胞总 counts 缩放到 10,000，再做 log1p |
| 高变基因 | Seurat v3，按用户要求选择 2,000 个 HVG |
| 缩放与降维 | scale(max_value=10)，下游采用 25 个 PC |
| 批次校正 | Harmony 按 sampleID 生成校正后的 PCA 表示 |
| UMAP 和聚类 | 在 Harmony 空间建邻居图，计算 UMAP 和 Leiden 0.8 |
| marker | 每个 cluster 计算 Wilcoxon 和 COSG top 50 marker |
正式运算前，第一次参数配置没有通过完整性检查。omicOS 补齐配置后重新启动，错误配置没有继续进入主流程。
主流程中还发生了一次真实 fallback：按 sampleID 分批挑选高变基因时，部分 batch 的拟合不稳定，因此改为不按 batch 挑选 HVG。Harmony 仍按 sampleID 成功执行。
65 个 sampleID 的细胞数从 42 到 8,543 不等，中位数为 1,521，其中一个样本少于 50 个细胞。样本规模不均可能增加分批拟合难度，但本回放不能证明它就是 fallback 的唯一原因。
这不代表流程失败，但必须记录。后面如果发现某些 cluster 被少数样本主导，要把这条 fallback 一起考虑。
交付阶段还发现一个中间检查点损坏。omicOS 删除损坏文件，从上一个有效检查点继续生成最终交付；最终主文件可以读取，最终运行清单没有失败阶段。这类恢复过程也应写进记录，不能只留下“成功”两个字。
5. QC 怎么看
QC 是质量控制。它主要检查每个细胞的总 counts、检测到的基因数和线粒体比例。
这是一个容错示例。发现图片为空时，直接告诉 omicOS“提琴图没有画出来，请检查并重新生成”即可。
修复后的 QC violin，包含 141,871 个细胞。五个面板依次是总 counts、检测基因数、线粒体比例、核糖体比例和血红蛋白比例。窄屏下可点击图片查看原图。
先看三件事：
total_counts和检测基因数是否有明显的低值或高值长尾；- 线粒体比例是否集中在合理范围，并与组织类型相符；
- QC 前后细胞数能否对上，移除比例是否符合预期。
本案例移除了 669 个细胞，约占 0.47%。这不自动等于“数据质量很好”，也可能是输入此前已经筛选过，或本次阈值较宽。
本次没有启用 MAD 自适应过滤，也没有重新执行双细胞过滤或环境 RNA 去除。因此不能写成“已经排除所有双细胞和环境 RNA”。
如果结果中没有出图，或者打开后是空白，不需要自己排查绘图代码。直接指出哪张图有问题，让 omicOS 检查并重新生成；新图出来后，再确认分布、坐标和标签是否完整。
6. 批次、resolution 和 marker 怎么看
6.1 批次校正不能只看一张 UMAP
本案例按用户指定的 sampleID 做 Harmony。是否选对 batch key，仍要结合实验设计判断。
判断校正是否合理，至少一起看：
- 同类细胞是否不再只按样本分开；
- 已知组织、疾病状态和 marker 差异是否仍然保留；
- 每个 cluster 是否由多个样本共同支持，而不是被单一样本占满；
- 校正前后的结果是否一致改善，而不是把所有细胞硬混在一起。
画 PC1、PC2、PC3 并按 batch、组织和已知细胞类型着色，有助于找主要变异来源，但它也只是辅助证据。需要更严格比较时，可以再计算 iLISI、kBET、graph connectivity 等批次混合指标，同时用 cLISI 或 silhouette 检查生物学结构有没有被抹掉；这些指标本案例没有计算。
6.2 resolution 决定分群颗粒度
resolution 越高，通常会得到更多、更细的 cluster。
本案例只运行 resolution=0.8，得到 29 个 cluster。它是本次指定的分析尺度，不是所有数据都适用的标准答案。
如果 cluster 太碎、marker 不稳定，或一个群几乎只来自单一样本，就要考虑调整 resolution 或回查上游。
6.3 marker 用来检查 cluster 是否合理
点越大，表达该基因的细胞比例越高；颜色越深，群内平均表达越高。图片信息较密，建议点击查看原图。
不要只找一个“最响”的基因。要看一组 marker 是否共同支持同一类细胞，同时检查是否出现互相冲突的信号。
7. 谁负责什么，结果怎样检查
| 分析者负责 | 可以交给 omicOS |
|---|---|
| 确认正确的 batch key | 读取字段并执行指定的批次校正 |
| 判断 QC 阈值是否适合组织和实验 | 应用规则并生成 QC 图 |
| 决定是否需要双细胞、环境 RNA 等额外处理 | 本案例未启用；需要时先确认，再另行执行 |
| 判断批次校正不足或过度 | 生成 batch UMAP、组成图和运行记录 |
| 选择适合研究问题的 resolution | 按指定 resolution 完成聚类 |
| 复核 cluster 和 marker 的一致性 | 计算 marker 表和 dotplot |
交付前至少检查：
- 细胞数 142,540 → 141,871、基因数 21,812 → 19,888 是否能对上；
sampleID是否真的是需要校正的技术来源；- 65 个样本在 UMAP 和各 cluster 中的组成是否合理；
- 29 个 cluster 是否过碎，是否存在样本独占群；
- QC 图是否真的有分布、坐标和标签，而不是只有一个文件名；
- marker 是否成组支持各 cluster；
- fallback、警告和未启用模块是否写进报告。
本案例最终交付：
| 文件 | 用途 |
|---|---|
adata.h5ad |
处理后的数据，含 counts layer、Harmony、UMAP 和 Leiden 结果；本案例约 28 GB |
adata_counts.h5ad |
配套 counts 数据文件；本案例约 2.8 GB |
marker_table.csv |
汇总 marker 表 |
tables/ |
聚类计数等结果表，其中包括 cluster_counts.csv |
REPORT.html / REPORT.md |
完整分析报告 |
analysis.ipynb / analysis.py |
可复现分析文件 |
run_manifest.json / validation.json |
运行与文件级验证记录 |
运行清单显示流程成功、没有失败阶段，文件级验证也通过。但它没有发现最初的空白 QC 图。这里的“通过”只表示主要文件和技术步骤存在，不代表图片一定正确，也不代表 batch key、QC 阈值或 29 个 cluster 已得到生物学证明。
另有一条不影响核心结果的文件整理警告：最终保留 54 个文件，高于紧凑输出上限 45。流程状态仍为成功，主要交付文件完整。
8. 下一步
确认 QC、批次校正、resolution 和 marker 都合理后，再进入细胞类型注释。
实际操作时，应把本页生成的 adata.h5ad 作为输入。本案例 resolution 0.8 对应的 cluster 列是 leiden；进入注释前仍应再次核对。下一页沿用这份预处理结果。
9. 案例实际回放
下面接着上一页的“我的项目A”继续操作。
9.1 在同一项目中新建对话
在“我的项目A”下新建一个对话，命名为“2-预处理”。
点击项目右侧的 + 新建会话。
数据整理、预处理和注释分别使用独立对话，后面更容易回看。新对话不会自动继承上一段对话的全部内容，因此要准备好输入文件和 batch key。
9.2 激活预处理智能体
打开“智能体”页面，手动激活 Single-cell Preprocessor Pro。没有 Pro 权限时可使用 Plus；不确定时也可以激活 Vertical Agent Selector 自动导航。
9.3 发送提示词
回到“2-预处理”对话，发送：
<第一步输出的 h5ad 路径>
对该数据进行预处理
对 sampleID 进行去批次
res 选为 0.8
HVGs 设为 2000
9.4 先核对运行设置
运行开始后，先确认 omicOS 识别的信息与预期一致：
| 要核对什么 | 本案例应看到什么 |
|---|---|
| 输入规模 | 142,540 个细胞 × 21,812 个基因 |
| 表达数据 | raw counts |
| batch key | sampleID，65 类 |
| resolution | 0.8 |
| HVG | 2,000 |
如果规模或 batch key 不对，先停下来核对文件和 obs，不要带着错误设置继续运行。
9.5 运行后追问结果
核心文件生成后，可以继续问：
请用简表总结这次预处理：
1. QC 前后的细胞数；
2. HVG 数；
3. 批次校正方法和 batch key；
4. resolution 和 cluster 数；
5. fallback、警告和未启用的模块；
6. 主要输出文件。
请把“已经执行”和“建议后续执行”分开写。
本案例应得到这些关键信息：141,871 个细胞被保留；使用 2,000 个 HVG；Harmony 按 65 个 sampleID 完成；resolution 0.8 得到 29 个 cluster；cluster 列为 leiden；batch-aware HVG 发生 fallback；Notebook 和分析脚本已经交付。
9.6 实际打开结果
至少打开 QC violin、batch UMAP、cluster UMAP 和 marker dotplot。检查：
- 图中是否真的有数据；
- 坐标、图例和标签是否完整；
- cluster 数是否与报告一致；
- 图片是否清晰到可以读。
本案例正是在这里发现 QC violin 是空图。用户指出问题后，omicOS 重新读取绘图数据并生成了完整图片。不要只看到“验证通过”就结束检查。
9.7 记录结论
在项目笔记中记下输入文件、batch key、QC 前后细胞数、resolution、cluster 数、fallback 和输出文件。不要只记录“运行成功”。