如何看懂scFM-dataselection:微软Nature Methods单细胞基础模型预训练实验的完整入门指南
如何看懂scFM-dataselection:微软Nature Methods单细胞基础模型预训练实验的完整入门指南
scFM-dataselection 是微软为 Nature Methods 论文《Evaluating the role of pretraining dataset size and diversity on single-cell foundation model performance》公开的单细胞基础模型预训练检查点合集,共包含 455 个模型资产:125 个 Geneformer、125 个 scVI、125 个 SSL/MLP 神经网络检查点,以及 80 个 PCA 主成分矩阵。对做单细胞组学(single-cell foundation model)研究的新手来说,这份仓库最大的价值在于:它把"预训练数据量与多样性到底影响多大"这一问题的全部实验结果,以可下载、可加载的形式完整公开了,你不需要重跑任何训练,就能直接对比不同数据采样策略下的模型行为。
🧭 一分钟看懂这个项目在做什么
单细胞基础模型的"基础"来自海量预训练数据。微软团队系统性地回答了三个问题:
- 数据量:用 1%、10%、25%、50%、75%、100% 的预训练语料,模型能力如何变化?
- 数据多样性:随机抽样(random)、按细胞类型重加权(celltype_reweighted)、几何草图(geometric_sketching)三种采样策略各有什么影响?
- 干扰实验:在语料中掺入 10% / 50% 扰动 spike-in(spikein_10 / spikein_50),模型还能保持稳健吗?
每个条件都跑了 5 个随机种子(seed),保证结论不是偶然。完整背景可先读 README.md 前 45 行,论文引用信息在 CITATION.cff。
📦 455 个模型资产全景图
资产数量与规模一览(完整清单见 model-index.csv):
| 模型家族 | 数量 | 检查点格式 | 说明 |
|---|---|---|---|
| Geneformer | 125 | model.safetensors + config.json |
BERT 架构,输入按表达量排序的基因序列 |
| scVI | 125 | model.safetensors + config.json |
深度生成模型,输入 AnnData |
| SSL/MLP | 125 | model.safetensors + config.json |
自编码式无监督表示学习 |
| PCA components | 80 | components.npy + config.json |
经典降维基线 |
完整下载约 22.4 GB,仓库按 Python 3.10 + CPU 环境验证过所有加载示例,依赖版本锁死在 requirements.txt 中。
🗂️ 目录结构:按"模型家族 → 采样策略 → 数据量_种子"组织
所有权重统一放在 portable-checkpoints/ 下,目录命名规则非常规整:
portable-checkpoints/
├── geneformer/ # Geneformer 检查点(5 种采样策略)
├── scvi/ # scVI 检查点
├── ssl/ # SSL/MLP 检查点
└── pca/ # PCA 主成分矩阵(3 种采样策略)
└── <采样策略>/
└── idx_<数据比例>pct_seed<种子号>/
├── config.json
└── model.safetensors # 或 components.npy(PCA)
如何解读一个目录名——以 idx_10pct_seed5 为例:
| 片段 | 含义 |
|---|---|
10pct |
使用了 10% 规模的预训练语料 |
seed5 |
第 5 号随机种子 |
而它上一级的目录名代表采样策略:
random/:纯随机抽样(唯一包含idx_100pct_seed25~seed29完整数据组的策略,作为全量基线)celltype_reweighted/:按细胞类型重新加权,缓解类型不均衡geometric_sketching/:几何草图采样,在降维空间保留数据几何结构spikein_10/、spikein_50/:掺入 10% / 50% 扰动数据的稳健性实验
👉 想对比"同数据量、不同采样策略",只需横向对比同一 idx_* 下的四个目录;想对比"同策略、不同数据量",纵向看 1pct → 75pct 即可。
📋 model-index.csv:所有检查点的"总目录"
每个模型文件夹在 model-index.csv 中都有一行登记,字段含义如下(表头位于 model-index.csv):
family:模型家族(Geneformer / scVI / SSL / PCA)sampling:采样策略(如celltype_reweighted、random)percentage/seed:数据比例与随机种子experiment_type:main为主实验,spike_in为扰动实验portable_directory:该检查点的确切目录路径
下载单个模型时,可以直接用这份索引配合 allow_patterns 只拉取需要的文件夹,避免 22.4 GB 全量下载。
🚀 最小示例:加载你的第一个检查点
加载逻辑全部封装在 tools/portable_models.py 的 load_model() 函数中(tools/portable_models.py),它会根据 config.json 自动识别家族类型。核心用法:
sys.path.insert(0, "tools")
from portable_models import load_model
geneformer = load_model(
"portable-checkpoints/geneformer/random/idx_100pct_seed25"
)
不同家族的输入要求(详见 README.md 的 "Load a checkpoint" 一节):
| 家族 | 输入 | 备注 |
|---|---|---|
| Geneformer | 排序后的基因 ID 张量 | 需配合 public-resources/geneformer/ 下的 tokenizer 字典做归一化 |
| SSL / PCA | 19,331 基因矩阵(scTab 基因顺序) | 基因顺序见 public-resources/sctab/adata_var.csv |
| scVI | AnnData 对象(raw counts 在 X 中) |
基因顺序必须与 config.json 的 gene_names 完全一致,否则直接报错 |
几个值得注意的工程细节:
- SSL 模型通过 tools/_native_ssl.py 从 public-resources/ssl-source/ 的原始源码动态构建模型类,保证了与论文训练代码一致;
- 所有加载都是严格校验模式——权重缺漏、基因顺序不符、PCA 矩阵形状不一致都会主动抛错,防止你拿着"错配"的权重得出错误结论。
⚠️ 新手常见坑位清单
- Python 版本:示例基于 Python 3.10 在 CPU 上测试通过,其他版本未验证;
- 只下需要的:全量 22.4 GB,按需使用
allow_patterns下载单个idx_*目录,并记得带上model-index.csv、tools/、public-resources/和requirements.txt; - scVI 的基因顺序陷阱:
var_names顺序与config.json不一致会直接抛ValueError,这是保护性设计而非 bug; - Geneformer ≠ 官方 Geneformer:这里的权重是本研究从零训练的模型,tokenizer 字典(Apache-2.0)来自上游 Geneformer 项目,但权重并非上游预训练权重(见 THIRD_PARTY_NOTICES.md);
- 许可:模型权重与加载代码为 MIT 许可,商用前建议通读 LICENSE 与 THIRD_PARTY_NOTICES.md。
📌 使用与引用
使用这批检查点时,请按 CITATION.cff 的要求引用原论文:
DenAdel, A., Hughes, M., Thoutam, A., et al. Evaluating the role of pretraining dataset size and diversity on single-cell foundation model performance. Nature Methods 23, 1447-1457 (2026).
如果你要克隆本仓库,仓库地址为 https://gitcode.com/hf_mirrors/microsoft/scFM-dataselection ;模型本体则推荐通过 Hugging Face 的 snapshot_download(repo_id="microsoft/scFM-dataselection")获取,具体命令见 README.md 的 "Download" 章节。
✅ 小结
scFM-dataselection 用统一的目录规范和一张 model-index.csv,把"预训练数据量 × 采样多样性 × 3 类基础模型 + PCA 基线"的 455 个实验结果整理成了一个可检索、可加载的资产库。新手只需记住三件事:按目录名读懂实验条件、用 model-index.csv 定位模型、用 load_model() 一键加载,就可以开始复现或对比 Nature Methods 论文中的任何结论了。