虚拟细胞扰动预测评测
本案例面向已经拥有扰动预测模型和计算环境的研究者。SciForge 负责组织数据、代码、运行记录、结果、证据和人工审查；预测能力来自用户接入的外部模型。
离线 fixture、模型 adapter 和完整连续截图尚未在当前版本完成最终验证。本页公开的是可实施的评测契约与操作边界，不会把它写成“开箱即用的内置虚拟细胞模型”。
评测任务
2026 Virtual Cell Challenge 的任务是零样本跨细胞背景预测：模型接收未扰动基线细胞和 CRISPRi knockdown 靶基因，预测此前未见细胞背景中的扰动后表达谱。官方说明见 Arc Institute 的任务介绍。
这个教程关注四类常见风险：
- 模型在预测前看到了密封真值，造成数据泄漏
- 数据、权重或环境漂移，导致结果无法复跑
- 输出形状合法但基因顺序、数值类型或标签错误
- 只报告总分，隐藏特定背景或扰动上的稳定失败
先选择一条路径
| 路径 | 用途 | 真值与评分 | 外部影响 |
|---|---|---|---|
| A. 离线复现演示 | 准备离线数据后，走通预测、密封、本地评分和复跑 | 需预先准备独立密封的验证数据；本站尚未提供已验证的 fixture，不是官方保留真值 | 默认不上传，可用本地 CPU 小切片 |
| B. VCC 2026 线上路径 | 组织官方输入并执行提交前检查 | 本地运行官方 CLI 预检；最终评分在官方服务端完成 | 下载、登录、上传和提交都需单独确认 |
两条路径可以共用预测产物契约，但不能混用真值和评分声明。无法判定路径时应停止。
SciForge 中的工作区边界
首先在 SciForge 文件面板中检查协议、数据、模型与已有运行，不要直接启动完整预测。
图 1：文件面板用于核对当前工作区与关键输入；这张功能截图不是一次已完成的 benchmark 运行。
建议目录：
virtual-cell-benchmark/
├── protocol/
│ ├── evaluation-plan.md
│ ├── data-contract.yaml
│ └── split-manifest.json
├── data/
│ ├── inputs/
│ └── sealed-reference/ # 仅路径 A
├── models/
│ ├── baseline/
│ └── external-adapter/
├── scripts/
│ ├── validate_inputs.py
│ ├── run_prediction.py
│ ├── validate_prediction.py
│ ├── evaluate_offline.py # 仅路径 A
│ └── analyze_failures.py
└── runs/<run-id>/
├── run-manifest.json
├── environment-lock.*
├── logs/
├── predictions/
├── validation/
├── metrics/
├── figures/
└── dossier/
run-manifest.json 是核心索引，至少记录路径类型、输入 hash、代码 commit、模型与权重 hash、环境、设备、随机种子、预测 hash、命令、返回码和时间戳。
官方输出契约快照
截至 2026-09-04，官方 VCC CLI 文档给出的完整提交契约包括：
| 契约项 | 官方要求 | 本地检查 |
|---|---|---|
| 扰动 × 每条件细胞 × 背景 | 300 × 400 × 3 | 逐背景、逐扰动精确计数 |
| 总预测细胞 | 360,000 | 检查 obs 行数与重复键 |
| 基因维度 | 18,533 | 基因集合、顺序和唯一性 |
| 数值 | 原始、非负整数 counts | 拒绝 log-normalized、scaled 或负值 |
| 对照细胞 | 不应包含 | 扫描 non-targeting control 标签 |
| 本地预检 | vcc prep --dry-run | 保存 CLI 版本、命令、返回码和完整输出 |
以运行时下载的官方 bundle 和 VCC CLI 文档 为最终依据；若 CLI 与本文不一致，应停止并更新协议。
完整任务提示词
请在当前工作区组织一次可复现的虚拟细胞扰动预测评测。
目标：使用未扰动基线细胞和给定 knockdown 靶基因生成扰动后表达预测，
并将数据、模型、环境、运行和结果固定为可审查的证据链。
首先根据工作区判断路径：
- 路径 A：离线复现 fixture，可在预测密封后做本地评分。
- 路径 B：官方 VCC 2026，本地只做契约检查和 vcc prep --dry-run。
- 无法判定时停止，不要猜测或混用两条路径。
执行要求：
1. 只读检查 Git、数据、模型代码、权重、环境和评测脚本。
2. 生成输入清单和 hash manifest，区分模型可见与不可见内容。
3. 首次预测前固定指标、聚合规则和失败条件。
4. 先运行小样本 dry run，检查 shape、gene order、标签、数值类型、设备和随机种子。
5. 通过后生成预测，记录命令、参数、环境、资源、返回码和预测 hash。
6. 路径 A 只有在预测密封后才能读取 sealed fixture。
7. 路径 B 仅执行 vcc prep --dry-run；下载、登录、上传或提交前停下确认。
8. 按背景、靶基因、表达区间和指标组件拆分误差，不只报告总分。
9. 将协议、输入、运行、预测、验证、指标、失败和限制加入 Evidence DAG。
10. 从干净环境复跑并生成 Research Dossier。
未经我确认，不要下载权重、安装依赖、登录外部服务、提交计算任务或上传数据。
如果输入契约、基因空间、评分路径或评估脚本无法核对，立即停止。
执行阶段
1. 预注册协议
在第一次预测前创建 evaluation-plan.md，冻结数据切分、主指标、辅助指标、聚合规则、模型可见内容和停止条件。文件时间和 Git 记录必须早于预测输出。
2. 固定模型与环境
记录代码 commit、权重 hash、许可证、环境锁文件、设备和随机种子。不得静默下载新权重、替换模型或切换数据预处理。
需要外部 GPU 或实验室集群时，可以通过终端把任务提交到你自己的远程环境；远端仍使用相同输出契约。
3. 小样本 dry run
在最小切片上检查：
- 输入和输出 shape
- gene ID 集合与顺序
- 扰动和背景标签
- 每条件细胞数
- 非负整数 counts
- 稀疏存储与内存峰值
- 设备、随机种子和返回码
任一硬性契约失败时，不得进入完整预测。
4. 运行并密封预测
完整预测完成后立刻计算 hash，写入 run manifest，并把日志、返回码和资源信息放进同一个 run-id。原运行不得被后续重跑覆盖。
5A. 离线评分
只有预测密封后才能打开 sealed fixture，并用冻结的评估脚本评分。若 reference 在密封前被模型或分析脚本读取，应将该 run 标记为无效并从新工作区重新开始。
5B. 官方预检
使用当期官方 CLI 运行 vcc prep --dry-run。预检通过不等于已经提交。任何登录、打包上传和正式提交都属于外部操作，必须展示目标、文件、大小与用途，并由用户确认。
分层分析与证据审查
结果至少分成四层：
- 契约层：文件、shape、gene order、count type 和标签是否正确。
- 指标层：报告所有组件、总分和聚合规则。
- 分层层：按背景、扰动、表达强度和基因丰度检查表现。
- 生物学层：将通路或细胞状态解释标为假设，不把分数直接写成机制结论。
推荐图表包括组件指标、按背景分层的点图、扰动级误差排名、观测与预测的差异表达对比，以及至少一个失败条件的深入剖面。
最终在 SciForge 中把协议、输入、运行、预测、指标、失败案例与限制组织进科研档案。
图 3：Research Dossier 用于聚合研究叙述、版本、可信度和限制；案例正式发布前仍需补采同一 benchmark 会话的连续截图。
必须停止的情况
| 问题 | 风险 | 处理 |
|---|---|---|
| 背景标签未知或对换 | 在错误背景上产生合法外观的预测 | 使用固定映射检查，立即停止 |
| 基因集合相同但顺序不同 | 指标失真 | 预测和评分前同时检查集合与顺序 |
| 输出是归一化或缩放值 | 违反原始 count 契约 | 验证非负、整数性和来源，失败即停止 |
| 每扰动细胞数错误 | 条件权重改变 | 逐背景、逐扰动精确核对 |
| 环境或权重漂移 | 复跑不可比 | 新建 run-id 并生成差异报告 |
| 路径 B 准备上传 | 数据离开本机 | 显示目标和文件，等待用户确认 |
完成标志
这些项目是后续集成运行的验收标准；当前页面未提供一次已完成预测、评分和复跑的证明。
- 路径 A/B 清楚且没有混用
- 协议时间早于首次预测
- 输入、代码、权重、环境和预测 hash 齐全
- dry run 的硬性契约全部通过
- 总分和分层失败同时报告
- 复跑差异有记录和解释
- 外部上传或提交没有在未确认时发生
下一步：远程资源与协作。