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：

  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/，每个方法一个子目录：

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/ 子目录