Stage 2 模型把每个细胞的 64 邻居图、4 象限 H&E patch 与 Stage 1.5 嵌入融合，输出 e_niche 与 e_combined。
本指南演示一份完整的 Visium HD 样本从原始 spaceranger 输出到 niche cluster 图的全过程。
直接对接 10x Space Ranger ≥ 3.0 的输出目录；最少需要 binned matrix、空间坐标与一张高分辨率 H&E 图像。 数据预处理流水线把它们打包成单一 HDF5，再喂入 Stage 2。
| spaceranger out/ | binned_outputs/square_002um/filtered_feature_bc_matrix.h52 μm bins · 推荐 50–100 μm cell-aggregation 后送入模型 |
|---|---|
| 空间坐标 | spatial/tissue_positions.csv · μm 坐标脚本会从 scale_factors.json 自动换算 |
| H&E 图像 | tissue_hires_image.png 或自带 .tif≥ 2000 px short side；冻结 ViT-L 抽取 4 象限 patch (4 × 1024d) |
| QC 阈值 | min 50 UMI · min 20 genes · per-cell binning(51) prepare_stage2_data.py 第 0–1 步默认应用 |
| 邻居图 | KDTree · K_comp = 64 · R = 50 μm composition 目标用全部 64 邻居；attention 仅用最近 K_attn = 20 |
| teacher 嵌入 | Stage 1.5 离线推理产物 (512d, fp16) 第 4 步 prepare 阶段缓存 |
下面是 prepare_stage2_data.py 中真实执行的九步处理；每一步对应 HDF5 中产生的字段，因此你可以随时打断后续再续。
下面这四个样本来自 0429 训练集 registry（共 11 个）。点击运行将模拟 prepare → Stage 2 forward → niche clustering 的整链路。
每个样本来自一个真实组织切片；编号与仓库 dataset_registry.json 中一致。
下面把九步预处理 + Stage 2 前向折叠为 6 个进度条；终端显示对应仓库脚本的实际日志格式。
左侧是按 niche 上色的组织图（叠在 H&E 之上）；右侧是模型对每个 niche 的邻居组成预测——可与 ground-truth 病理标注对比。
| cell type | fraction | % |
|---|
e_combined 做病理区分类（identity + niche）e_niche 做跨样本 niche 对齐| --k_attn | 20 (默认) · 参与 spatial attention 的最近邻数；增大稍提精度但显存翻倍 |
|---|---|
| --leiden_res | 0.8 (默认) · 控制 niche cluster 数量；上调 → 更多更细的 niche |
| --use_he | true (默认) · 关闭后忽略 H&E 分支，仅靠基因 + 空间 |
| --panel_dropout | 0 (推理) · 训练时为 10%，推理勿开 |
| --neighbor_dropout | 0 (推理) · 训练时 15–20%，推理勿开 |
| --niche_aggregator | attn-pool (默认) · 备选 mean/weightedv5_final 仅支持 attn-pool |
可以。--use_he false 时 image token 会被 zero-mask，对应 dropout 模式。NMI 通常下降 2–4 个点。
在我们的 11 个样本上 K=20 与 K=40 的 NMI 几乎重合；K=40 的显存翻倍且训练并未在该设定下收敛，不推荐推理。
Visium 标准版可以通过同流水线，把 bin 设为 55 μm 即可；Xenium 因为是 single-cell-resolution，需要先汇总成 ~50 μm cell-agg 后送入。我们正在准备 Xenium 兼容器，预计 0530 发布。