| --- |
| license: other |
| license_name: non-commercial-research |
| license_link: LICENSE.md |
| library_name: pytorch |
| pipeline_tag: feature-extraction |
| tags: |
| - pathology |
| - multimodal |
| - imagebind |
| - spatial-transcriptomics |
| - multiplex-immunofluorescence |
| - contrastive-learning |
| --- |
| |
| # 四模态病理嵌入模型（H&E · mIF · RNA · 文本） |
|
|
| 这个模型把四种模态嵌入到同一个 1536 维空间里： |
| - **H&E** 图像； |
| - **mIF**：多重免疫荧光，即蛋白； |
| - **RNA**：空间转录组 spot 表达； |
| - **病理文本**。 |
|
|
| 做法和 ImageBind 一样。冻结的 UNI2-h 图像空间是锚点，其余每种模态只和 H&E 配对训练。mIF↔RNA、mIF↔文本、文本↔RNA 之间的对齐是"涌现"出来的，没有直接训练过。 |
|
|
| - **训练数据：** 只用真实的配对数据。 |
| - **评估数据：** 虚拟数据和合成数据只用于评估，从不参与训练。 |
|
|
| | 内容 | 位置 | |
| |---|---| |
| | 发布版模型 | `models/ej_ad_mv/` | |
| | fold-0 模型（带留出测试集） | `models/ej_ad_mv_fold0/` | |
| | 推理接口 | `embed.py` | |
| | 训练 | `52_final_model.py` | |
| | 训练用的编码器特征和数据划分 | 私有数据集仓库 [`Pathstudy/fourmodal-pathology-features`](https://huggingface.co/datasets/Pathstudy/fourmodal-pathology-features) | |
| | 图文报告 | `report/fourmodal_report.html` | |
| | 全部实验记录 | `RESULTS.md` | |
|
|
| ## 1. 数据 |
|
|
| 没有任何数据集同时测量了全部四种模态，所以每种模态各用一个和 H&E 配对的真实数据集。 |
|
|
| | 数据集 | 配对 | 规模 | 用途 | |
| |---|---|---|---| |
| | ORION CRC（1% 图块子集） | H&E – mIF（17 通道，使用 16 个标记） | 3,187 个 333×333 图块，约 40 名病人 | 训练 + 测试 | |
| | HEST-1k Visium | H&E – RNA（14,802 基因） | 9,484 spots，57 项研究，16 个器官 | 训练 + 测试 | |
| | TCGA / PathGen-1.6M | H&E – 文本 | 6,144 张图像，6,115 条清洗后的描述 | 训练 + 测试 | |
| | STPath 虚拟 RNA / MIPHEI 虚拟 mIF / GPT 合成描述 | 给没有真实配对的模态对构建测试集 | ORION、TCGA 测试图块 | **只用于测试** | |
| | DLPFC（spatialLIBD，脑） | H&E – RNA | 482 spots，3 名供体 | 外部测试 | |
|
|
| - **划分：** 按病人划分 train/val/test。HEST 按研究划分，病人分组见 `splits/`。做 5 折交叉验证。 |
| - **验证集：** val 只用于早停，所有报告的数字都是 test 上的。 |
| - **虚拟模态的校准：** 每种虚拟模态先在同一批有真实数据的样本上校准，即用虚拟数据替换真实数据，看配对结果能否接近。 |
|
|
| | 虚拟模态 | 校准结果（真实 → 虚拟） | 结论 | |
| |---|---|---| |
| | STPath 虚拟 RNA | 0.148 → 0.126 | 可用 | |
| | GPT 合成描述 | 0.219 → 0.162 | 可用，偏保守 | |
| | MIPHEI 虚拟 mIF | 配对准确率 0.92 → 0.55 | 可用 | |
| | GigaTIME 虚拟 mIF | 0.644 → 0.038 | 不可用，已弃用 | |
|
|
| ## 2. 最佳架构：EJ-ad+MV（两阶段，3 种子适配器平均） |
|
|
| ``` |
| H&E ──► UNI2-h (frozen, 1536) ───────────────┬──────────────► (+) ──► z_HE |
| └► MedVTok (frozen, 1152) ─► Adapter×3 ◄┘ (zero-init, mean of 3 seeds) ┐ |
| mIF ──► VirTues (16 markers, 512) ─► MLP head ─────────────────────► z_mIF │ 1536-d |
| RNA ──► hvg · Tahoe-x1 · SE-600M · AIDO.Cell ─► 4 linear heads ─► fuse ─► z_RNA │ shared |
| text ──► KEEP · BiomedCLIP · Qwen3-Emb-0.6B ─► 3 linear heads ─► fuse ─► z_text ┘ space |
| ``` |
|
|
| **第一阶段：每个编码器一个映射头。** |
| - 每个映射头用 InfoNCE 对齐到冻结的 UNI2 CLS 特征。 |
| - 文本用多正样本 InfoNCE：同一张图像的多条文本都算正样本。 |
| - RNA 和文本是后期融合：`z = normalise(Σ_e normalise(head_e(x_e)))`。 |
|
|
| **第二阶段：只训练 H&E 一侧。** |
| - 冻结所有映射头，只训练一个零初始化的残差适配器：`H&E = UNI2 + mean_s A_s([UNI2, c·MedVTok])`。 |
| - 损失：三种配对的 InfoNCE 之和，加上对 UNI2 相似度结构的蒸馏（λ=1）。 |
| - 优化：AdamW，学习率 1e-4，1000 步，OneCycle 学习率调度。 |
| - 选择规则：每个种子按验证集上三种 R@1 的几何平均早停，再把 3 个种子的适配器残差取平均。 |
|
|
| **为什么这样设计：** mIF、RNA、文本的嵌入和第一阶段完全一样，所以涌现配对不受第二阶段影响，只有 H&E 这一侧变好。以下结论都来自 5 折配对检验，详见 `RESULTS.md`： |
|
|
| | 设计选择 | 依据 | |
| |---|---| |
| | UNI2-h 做锚点 | 在任何训练配对上都没有被显著超过。GigaPath 在 RNA 上低 0.035；CONCH 在 H&E↔mIF 上低 0.155；MedVTok 当锚点在 H&E↔RNA 上只有 0.131（UNI2 是 0.192）。 | |
| | 多编码器后期融合 | 最大的单项提升：H&E↔RNA +0.037，H&E↔文本 +0.062，4 个涌现配对全部提升（5/5 折）。拼接（早期融合）和单编码器多种子平均都达不到这个效果。 | |
| | 只动 H&E 侧的联合训练 | 共享 H&E 头会让涌现配对损失 26–74%；只训练残差适配器时，H&E↔mIF 提升 0.10，涌现配对完全不变。 | |
| | MedVTok 作为额外输入 | H&E↔mIF +0.015，H&E↔文本 +0.016。换成同尺寸的 UNI2 随机投影没有提升。 | |
| | 3 种子平均 | 单次早停的步数在 100–900 步之间波动，同一设置重跑 H&E↔mIF 可以差 0.05。3 个种子平均后，H&E↔文本再提高 0.015（5/5 折，p=0.02）。 | |
| | RNA 和文本用线性头 | 训练配对持平，涌现配对 +5%。mIF 保留 MLP 头。 | |
| | 编码器挑选 | RNA：4 个编码器融合（+0.037）接近 10 个融合（+0.044）。文本：3 个融合（0.299）接近 5 个融合（0.303）。mIF：VirTues 的跨模态迁移比从头训练的 CNN 好得多。 | |
|
|
| ## 3. 结果（5 折测试集均值，100 个样本的检索库，随机水平 R@1 = 0.01） |
|
|
| | 配对 | 类型 | R@1 | R@10 | 配对准确率 | |
| |---|---|---|---|---| |
| | H&E ↔ mIF（ORION） | 训练 | **0.801** ± 0.043 | 0.991 | 0.942 | |
| | H&E ↔ RNA（HEST） | 训练 | **0.203** ± 0.033 | 0.625 | 0.258 | |
| | H&E ↔ 文本（TCGA） | 训练 | **0.323** ± 0.007 | 0.813 | 0.347 | |
| | mIF ↔ RNA（虚拟） | 涌现 | 0.141 ± 0.007 | 0.657 | 0.194 | |
| | mIF ↔ 文本（合成） | 涌现 | 0.089 ± 0.008 | 0.491 | 0.104 | |
| | 文本 ↔ RNA（虚拟） | 涌现 | 0.095 ± 0.006 | 0.436 | 0.100 | |
| | 文本 ↔ mIF（MIPHEI 虚拟） | 涌现 | 0.046 ± 0.005 | 0.271 | 0.051 | |
| | H&E ↔ RNA（DLPFC 脑，外部） | 外部 | 0.012 | 0.112 | 0.012 | |
|
|
| 各阶段的提升见下表（训练配对 R@1，5 折均值）。逐折结果在 `results/final_cv_long.csv`，各阶段的完整比较在 `results/medvtok_*.csv`、`results/joint_ens_*.csv`。 |
|
|
| | 阶段 | H&E↔mIF | H&E↔RNA | H&E↔文本 | |
| |---|---|---|---| |
| | 单编码器（S4） | 0.675 | 0.155 | 0.236 | |
| | 多编码器融合（E，第一阶段） | 0.675 | 0.192 | 0.299 | |
| | + H&E 适配器 | 0.776 | 0.201 | 0.299 | |
| | + MedVTok | 0.792 | 0.200 | 0.315 | |
| | **最终（3 种子平均）** | **0.801** | **0.203** | **0.323** | |
|
|
| ## 4. 使用方法 |
|
|
| 环境：Python 3.11 和一块 CUDA GPU。依赖见 `requirements.txt`。所有脚本都用 `python -I` 运行。 |
|
|
| ```bash |
| pip install -r requirements.txt |
| ``` |
|
|
| **用预先算好的编码器特征**（不需要任何冻结编码器）： |
|
|
| ```python |
| from embed import Embedder |
| E = Embedder("models/ej_ad_mv") |
| z_he = E.he_from_feats(uni2_feats, medvtok_feats) # (N,1536) / (N,1152) |
| z_mif = E.mif_from_feats(virtues_feats) # (N,512) |
| z_rna = E.rna_from_feats({"hvg": X, "tahoex1": X, "se600m": X, "aidocell": X}) |
| z_text = E.text_from_feats({"keep": X, "biomedclip": X, "qwen3-0.6b": X}) |
| sim = z_he @ z_mif.T # 输出都是 L2 归一化的 (N, 1536) CPU tensor |
| ``` |
|
|
| **用原始输入**。需要先运行 `bash setup_encoders.sh` 下载第三方代码和权重。UNI2-h 是受限仓库，需要账号有访问权限，或者设置 `UNI2_PATH`。 |
|
|
| ```python |
| z = E.he(images) # PIL 图像列表或 (N,H,W,3) uint8；约 0.5 µm/px，视野 112–166 µm |
| z = E.text(["Tumor cells with ...", ...]) |
| z = E.rna(counts, genes) # 原始计数（spots × genes），HGNC 基因名 |
| z = E.mif(tiles, slide) # (N,16,H,W) 8 位强度，通道顺序为 embed.MIF_MARKERS，每个图块附 slide id |
| ``` |
|
|
| 注意： |
| - **mIF 标准化：** 统计量是在一次调用给定的全部图块上计算的，所以请一次传入整张切片或整个数据集。 |
| - **新平台的 RNA 数据：** 建议用 `zscore="self"`，并且一次至少传入几百个 spots。 |
|
|
| ## 5. 复现（已验证：从 HF 下载到全新目录 + 全新虚拟环境） |
|
|
| ```bash |
| PYTHON=python bash reproduce.sh # 约 20 分钟（单卡 RTX A5000） |
| RAW=1 PYTHON=python bash reproduce.sh # 再加上原始输入检查（需要先运行 setup_encoders.sh） |
| ``` |
|
|
| `reproduce.sh` 依次执行： |
| 1. 下载特征仓库，得到 `cache/` 和 `splits/`，共约 1.1 GB。 |
| 2. `evaluate_saved.py`：用已发布的 fold-0 模型在留出测试集上重算结果，必须和 `models/ej_ad_mv_fold0/test.csv` 完全一致。 |
| 3. 从特征重新训练 fold 0 和 5 折交叉验证，然后用 `compare_reproduction.py` 和已发布的数字对比。 |
| - 在相同硬件和相同依赖版本下，结果逐位一致。2026-10-28 在 RTX A5000 上用全新的 `requirements.txt` 环境验证：fold 0 和 5 折的全部配对差值都是 0。 |
| - 换 GPU 或库版本时，第二阶段（H&E 适配器）可能在种子波动范围内变化，约 ±0.01；`compare_reproduction.py` 的容差就是按这个设的。 |
| 4. 重新训练发布版模型，输出到 `models/repro_release/`。 |
| 5. 加 `RAW=1` 时运行 `example_check.py`：把 `examples/`（每个数据集 64 个 fold-0 测试样本）的原始输入送进 `embed.py`，检查编码器特征和缓存特征是否一致，再检查检索结果。 |
|
|
| 已发布的结果不会被覆盖：复现的输出写到 `repro_*` 名下。 |
|
|
| ## 6. 局限 |
|
|
| - **外部泛化差：** 脑组织 DLPFC 上处于随机水平。训练用的 HEST 里脑组织也只有 R@1 0.021。所以模型只适用于训练数据覆盖过的组织类型。 |
| - **H&E↔文本的 MedVTok 增益可能偏高：** MedVTok 预训练时见过 PathGen 的图像，包括我们 TCGA 测试集的图像（只有图像，没有文本）。ORION 上的 mIF 增益不受影响。 |
| - **涌现配对的数值偏保守：** 涌现配对的一侧是虚拟或合成数据，所以这些数值是保守估计。 |
| - **实例级涌现对齐仍然弱：** mIF↔RNA 只有 0.141。概念级的对齐（AUROC 0.6–0.7）更可靠。 |
|
|
| ## 7. 许可证 |
|
|
| **只能用于非商业研究。** 本仓库的权重是在以下冻结编码器的特征上训练的，使用时需要分别遵守它们的许可： |
|
|
| | 编码器 | 许可 | |
| |---|---| |
| | UNI2-h | CC-BY-NC-ND，受限访问 | |
| | MedVTok | MIT；它对齐的 CONCH v1.5 是 CC-BY-NC-ND | |
| | SE-600M、AIDO.Cell | 非商业 | |
| | Tahoe-x1 | Apache-2.0 | |
| | VirTues、KEEP、BiomedCLIP | MIT | |
| | Qwen3-Embedding | Apache-2.0 | |
|
|
| 数据本身也有各自的条款，见各数据集的原始发布：ORION、HEST-1k（CC-BY-NC-SA）、TCGA、PathGen-1.6M、spatialLIBD。 |
|
|
| ## 8. 文件 |
|
|
| ``` |
| embed.py 推理接口 (Bind4 模型 + Embedder) |
| 52_final_model.py 训练 (cv / fold0 / release) |
| evaluate_saved.py 特征级评估 (fold-0 测试, 与 test.csv 完全一致) |
| example_check.py 原始输入端到端检查 (examples/) |
| reproduce.sh, compare_reproduction.py, setup_encoders.sh, requirements.txt |
| 14_ 43_ 45_ 45b_ 50_ *.py, biomedclip_text.py, common.py, rna_sets.py 冻结编码器的特征提取 (embed.py 调用) |
| 53_embed_check.py, 54_make_examples.py 在完整原始数据上做的检查 / 生成 examples/ (需要原始数据集) |
| models/ ej_ad_mv (发布版), ej_ad_mv_fold0 (+ test.csv, test_items.npz) |
| results/ 所有实验的 csv 结果 |
| experiments/ 01_–51_ 全部实验脚本 (记录用; 依赖原始数据, 不在本仓库) |
| RESULTS.md 完整实验记录; report/fourmodal_report.html 图文报告 |
| ``` |
|
|
