Spatial Visium Hd

Visium HD Branch — Cell Segmentation & Bin-to-Cell

Goal

Reconstruct single-cell-level expression from Visium HD 2 μm bins. The 2 μm bin is a transcript-capture unit, NOT a biological unit (a cell spans ~25 bins). The default 8 μm bin output is also NOT the analysis unit — segment, not bin.

Prerequisites

• Visium HD Space Ranger output:
  • binned_outputs/square_002um/filtered_feature_bc_matrix.h5 (bins × genes)
  • binned_outputs/square_002um/spatial/tissue_positions.parquet (bin coordinates)
  • spatial/cytassist_image.tiff (full-resolution HE image)
• Python: scanpy, stardist, scipy, geopandas (optional for soft assignment)

GPU 加速（自动检测，无需手动配置）

• segment_cells 会自动探测 GPU：可用则用 GPU 加速，不可用自动回退 CPU。
• 有 NVIDIA GPU 时建议安装 GPU 版 TensorFlow：

  bashCopy code
  pip install "tensorflow[and-cuda]"
  

  无 GPU 或只想用 CPU：pip install tensorflow 即可，代码自动回退，不影响功能。
• 强制 CPU：设置环境变量 STARDIST_DEVICE=cpu。
• 注意：TF 首次在 GPU 上编译卷积会花 30-60 秒（XLA 编译），之后推理很快；大图分割 GPU 比 CPU 快约 6-10 倍。

参数决策约定（LLM 必须遵守）

设计原则（2026-08-26）：skill 不替 LLM 做"需要判断"的决策。参数分两类：

A. 能直接计算的参数（代码自动算，LLM 不干预）

• n_cells（downsample 上限，每类型 1000）— 纯计算
• n_neighbors（表达图 KNN k）— 按数据规模 min(15, max(5, n//1000))
• n_comps（PCA 维数）— min(30, n_cells-1, n_genes-1)
• HVG flavor（counts vs log）— 数据自动检测（整数+非负=counts）
• n_top_genes — min(2000, n_vars)

B. 需要 LLM 判断的参数（skill 输出诊断，LLM 决策后显式传参）

工作流：

1. skill 先跑可计算参数（A 类）
2. 需要判断处（B 类）→ skill 输出 DIAGNOSTIC 信息（域数量、数据规模等）
3. LLM 看到诊断后，根据组织学知识/用户需求决策，显式传参重跑（如 resolution=1.2）
4. 禁止 skill 内部用参数搜索"自动找正确答案"——那是不可判定的

Steps

流程按 stage 编号执行（S1→S6），S4 分两个分支：

1. S1 Load 2 μm bins

   • sc.read_10x_h5(square_002um/filtered_feature_bc_matrix.h5) — millions of bins, keep sparse.
   • Attach coordinates from tissue_positions.parquet into obsm['spatial'].

2. S2 Destripe (recommended)

   • Correct the known Visium HD striping artifact (per-row/column quantile scaling of UMI counts at 2 μm).
   • Optional but improves segmentation downstream.

3. S3 Segment nuclei (StarDist)

   • Model: 2D_versatile_he (H&E) on the full-res HE image.
   • Tiled inference (predict_instances_big, block_size ~4096, overlap ~128).
   • Save labels as sparse NPZ. Inspect a crop (03_nuclei_crop.png) to confirm segmentation quality before proceeding.

4. S4 Cell reconstruction（两分支二选一或都跑）

   • S4A StarDist + bin2cell（默认）: 核多边形 buffer 扩展（expand_px 默认 29px ≈ 8µm，对齐 10x Space Ranger --nucleus-expansion-distance-micron 默认值；0 = 严格核内）→ bin-to-cell 聚合（重叠 bins 按最近核分配）→ 04_bin2cell.h5ad。
   • S4B Proseg: run Proseg Bayesian segmentation (voxel_size auto, samples auto, 2 μm bins + StarDist masks) → proseg_out.zarr/ + 04_proseg_cells.h5ad。
   • 两分支共用 S3 的核分割结果；输出后各生成一张全图高清几何 overlay（04_cells_overlay.png）。
   • 分割完成后得到的是"空间单细胞"数据，直接按 scRNA-seq 处理（注释 → domains → neighborhood → CellChat），不需要反卷积（依据：Bin2cell/ENACT/10x 官方指南，见知识库 concepts/visium-hd-segmentation-vs-deconvolution.md）。
   • 细胞类型鉴定用注释（annotation / label transfer）：CellTypist、CellAssign、或 scRNA 参考（如 Haber 2017 小鼠小肠）做 label transfer，不用 deconvolve。
   • 反卷积（deconvolve）不是 10x 官方流程的一部分（无论分割与否）：官方做法是聚类 + marker 注释。反卷积只是社区工具（Cell2location/SpatialDWLS/SpaceXR）的可选增强，且需要外部 scRNA 参考——默认不做，用户明确要求时才走经典 visium.py 的 deconvolve_spatial_*。

5. S5 QC & sanity check

   • Report: number of cells, median genes/cell, median counts/cell, median bins/cell, novelty score, fraction of tissue bins assigned.
   • Flag: suspiciously low cell count, high empty fraction, low bins/cell (median < 5 → 提示 bin_to_cell 缺核扩展), or segmentation failures.
   • 输出 segmentation_summary.json + qc_metrics.json + QC 可视化面板（05_qc.png：基因数/UMI 数/mito% violin + novelty score/bin_count 直方图 + 空间低质量细胞标记，参照 SIB-Swiss 空间转录组培训与 bcbio spatial-reports 标准）+ 全图 overlay；提示用户可用 ROI 工具框选局部检查（见下方"HD 可视化 & 交互式 ROI 选择"）。

Outputs

统一输出到 results/07b_segmentation/，每个方法一个子目录：

Copy code
results/07b_segmentation/
├── <sample>_stardist/            # StarDist 分支
│   ├── 01_load_bins.h5ad
│   ├── 02_destripe.h5ad          # (如启用 destripe)
│   ├── 03_nuclei_labels.npz      # 核分割 labels
│   ├── 03_nuclei_polys.pckl      # StarDist 多边形 (供几何绘图)
│   ├── 03_nuclei_crop.png        # 核分割检查图
│   ├── 04_bin2cell.h5ad          # 细胞级 AnnData (cells × genes)
│   ├── 04_cells_overlay.png      # 全图高清几何 overlay (蓝色轮廓)
│   ├── 05_qc.png                 # QC 可视化面板 (基因/UMI/bin 分布 + 空间)
│   ├── segmentation_summary.json # 细胞数/QC/参数
│   ├── qc_metrics.json           # QC 数字指标 (n_cells/median genes/counts)
│   └── params.json               # 实际运行参数
├── <sample>_proseg/              # Proseg 分支
│   ├── 01_load_bins.h5ad
│   ├── 03_nuclei_labels.npz / 03_nuclei_polys.pckl
│   ├── 03_nuclei_crop.png
│   ├── proseg_out.zarr/          # Proseg 几何输出 (cell_boundaries)
│   ├── 04_proseg_cells.h5ad      # 细胞级 AnnData
│   ├── 04_cells_overlay.png      # 全图高清几何 overlay (红色轮廓)
│   ├── segmentation_summary.json
│   └── params.json
└── crops/                        # 用户 ROI 选择产出的 crop 图
    ├── roi_<sample>_<method>.json  # ROI 坐标 (pick_roi.py 输出)
    └── crop_<sample>_<method>_<x0>_<y0>_<x1>_<y1>.png

统一命名规则：

• 中间产物：NN_<阶段>.<ext>（01_load / 02_destripe / 03_nuclei / 04_cells）
• 图：04_cells_overlay.png（全图高清几何）、03_nuclei_crop.png（核分割检查）
• 分支标识：目录名 <sample>_stardist / <sample>_proseg
• 所有用户 ROI 产出集中在 crops/ 子目录

下游验证（S4 之后、交用户审查前）

细胞级 h5ad 产出后，先跑下游验证确认结果可进入共享下游流程，再交用户审查：

bashCopy code
# 服务器 (用 S4 输出的细胞级 h5ad)
python validate_downstream.py \
    --input <sample>_stardist/04_bin2cell.h5ad \
    --out-dir downstream_test \
    --n-cells 10000 --n-top-genes 2000 --n-pcs 30 --resolution 1.0

输出（默认 downstream_test/ 目录）：

• sub10000.h5ad — 验证子集（原始计数）
• sub10000_normalized.h5ad + sub10000_hvg.png — normalize + 高变基因图
• sub10000_clustered.h5ad + sub10000_umap.png — PCA + Leiden 聚类 + UMAP 图

全部输出存在才算通过；任一项缺失脚本报错退出。验证通过后，再向用户展示全图 overlay 并提示可用 ROI 工具做局部检查。

HD 可视化 & 交互式 ROI 选择

绘图统一走 visium_new_platforms.py 中的 _plot_cells_overlay / plot_cells_crop，输出 HE 全分辨率 + 真实细胞几何（多边形边界） 的高清图，不再是低清质心散点。

挂载点：S4 分析结束后

S4 输出结果和大图后，提示用户：可以用 ROI 工具选择区域做局部检查。

textCopy code
[Visium HD] S4 完成:
  StarDist: N cells -> <sample>_stardist/04_cells_overlay.png (全图蓝色轮廓)
  Proseg:   M cells -> <sample>_proseg/04_cells_overlay.png   (全图红色轮廓)
  如对某区域细胞边界与 HE 组织对齐存疑，可用 ROI 工具框选局部放大检查:
    python pick_roi.py --image tissue_image.png --out crops/roi_<sample>_<method>.json
    python make_crop.py --method stardist|proseg --roi-json crops/roi_<sample>_<method>.json

全图高清几何 overlay

• StarDist 分支：蓝色轮廓（edge_color="tab:blue"，linewidth 0.12），输出 <sample>_stardist/04_cells_overlay.png
• Proseg 分支：红色轮廓（edge_color="tab:red"，linewidth 0.12），输出 <sample>_proseg/04_cells_overlay.png
• 默认：HE 全分辨率（downsample=1）、全部细胞（max_points=None）、dpi=150

交互式 ROI 选择（用户手动框选区域）

本地工具 pick_roi.py（弹窗 + 鼠标框选），输出到 results/07b_segmentation/crops/：

bashCopy code
# 本地 (需 Python + matplotlib + pillow)
python pick_roi.py --image tissue_image.png --out roi_<sample>_<method>.json
# 鼠标左键拖拽框选 ROI; Enter 确认, r 重选, q 退出
# 输出全分辨率像素坐标到 roi_<sample>_<method>.json

服务器配套 make_crop.py（用 ROI 坐标生成高清 crop，输出到 results/07b_segmentation/crops/）：

bashCopy code
# 服务器 (crop 图统一存 crops/ 子目录)
python make_crop.py --method stardist --roi x0,y0,x1,y1 [--out crops/crop_<sample>_stardist_x0_y0_x1_y1.png]
python make_crop.py --method proseg  --roi-json crops/roi_<sample>_proseg.json

plot_cells_crop 函数本身支持三种 ROI 指定方式：

• roi=None：自动选细胞最密集区
• roi=(x0, y0, x1, y1)：手动矩形区域
• roi=(cx, cy) + roi_size：中心点 + 边长

空间域命名规范（LLM 必须遵守）

背景（2026-08-26）：空间转录组领域没有统一的 domain 命名标准（不像细胞类型有 Cell Ontology / CellTypist 参考库）。命名按以下 5 步流程执行，禁止 LLM 自由发挥。

LLM 命名流程（5 步）

1. 读 annotation CSV：identify_spatial_domains 产出的 *_domains_annotation.csv，含每 domain 的 top marker 基因（logFC）+ 细胞类型组成（占比）
2. 判定组织类型：从样本元数据/组织来源推断（肠/肺/心/肝/癌等）。不同组织的解剖结构差异大，命名词汇必须匹配组织
3. 对照组织类型参考表选候选名：优先解剖结构，其次组织学特征。参考表（持续积累，遇到新组织补充）：
   • 小肠：绒毛吸收上皮 / 隐窝-绒毛过渡 / 隐窝底部(潘氏细胞) / 黏膜下间质 / 平滑肌 / 淋巴组织(HEV+) / B细胞区 / 浆细胞富集区
   • 脑：皮层 L1-L6 / 白质 / 海马区 / 脑室周围（参照 DLPFC spatialLIBD 标准）
   • 肺：肺泡区 / 支气管上皮 / 血管周围间质 / 平滑肌 / 淋巴滤泡 / 肿瘤实性区 / 坏死区
   • 心脏：心肌层 / 心外膜 / 心内膜 / 血管壁 / 纤维化区 / 脂肪浸润区
   • 肝脏：肝小叶中央 / 门静脉周围 / 胆管区 / 纤维化区 / 肿瘤结节
   • 癌症（通用）：肿瘤实性区 / 肿瘤浸润前沿 / 肿瘤间质 / 免疫浸润区 / 坏死区 / 淋巴聚集区 / 血管区 / 纤维包膜
4. 用 marker 基因验证：候选名必须有 marker 支持。例："隐窝底部"需 Lgr5/Defa 等潘氏/干细胞 marker；"心肌层"需 TNNT2/ACTA2 等；"肿瘤浸润前沿"需 EMT/增殖 marker
5. 输出统一格式：D{n} {结构名}({特征})。证据不足 → D{n} 未命名(待定) 并说明缺什么证据（如"无明确 marker 支持，需 H&E 图像辅助判断"）

命名约束

• domain 是组织切片上的空间结构域，不是细胞类型——命名必须回答"这个区域在组织里是什么"（解剖结构/组织学特征），细胞类型组成只作为佐证
• 命名对齐 Uberon 解剖学术语（跨物种解剖学本体），不自己造词
• 命名后向用户展示：annotation CSV 摘要 + 拟定命名 + 依据（marker/细胞类型），用户确认后才画图
• 用户指出命名错误 → 记录到 knowledge/lessons/，并补充组织类型参考表

Biological Interpretation

• Report total cells and QC stats.
• Verify reconstructed cells overlap tissue regions in the HE overlay; flag low-density regions.
• Cross-check: do cell-level patterns respect tissue architecture (e.g., epithelial sheets, immune infiltrates)?

Stop for Review

Present interpretation using the template from the parent spatial-transcriptomics skill. Wait for 通过 / 调整 / 跳过 before proceeding to shared downstream.

Notes

• Memory: 2 μm matrices are huge (millions of bins) — prefer sparse/chunked operations.
• Deconvolution is NOT needed for Visium HD — cells are already resolved after bin-to-cell.
• Reference implementations: bin2cell (Teichmann lab), ENACT (Sanofi) — in knowledge/references/projects/spatial-transcriptomics-seg/.