SuperAPI AI 工具集
合作ENAI 行业资讯收藏
Skill 广场spatial-domain-detection

spatial-domain-detection

数据与分析

查看项目

更新于 10-28 09:26

技能介绍

用途

该技能用于空间转录组学数据的空间域检测，即根据基因表达和空间位置将组织切片分割为空间上连贯的区域（如皮层分层、肿瘤核心与间质、生发中心）。每个方法为每个 spot 或细胞分配一个域标签。输出包括一个或多个方法的域标签、方法间的一致性、域标记基因和域图。

主要能力

提供三种方法：

  • SpaGCN：适用于 Visium / ST spots，可选结合 H&E 图像，利用表达、空间图和直方图颜色，CPU 运行，需数分钟。
  • GraphST：适用于 spots 或细胞（最多约 30k 观测），使用对比图嵌入，推荐 GPU（torch）。
  • UTAG：适用于单细胞分辨率（Xenium、MERFISH、CosMx、IMC），在半径内平均表达，CPU 运行，可扩展至 10^5-10^6 细胞。
  • 组成生态位（Composition niches）：适用于已注释的单细胞，基于邻域细胞类型混合，CPU 运行，为 spatial-transcriptomics-cell-type-annotation 的第 7 步。

使用方式

  1. 加载数据：支持 Visium 数据（如 10x 小鼠脑矢状面前部切片）或用户自己的 Space Ranger 输出。数据需包含原始计数矩阵和空间坐标。
  2. 预处理：计算质控指标、过滤细胞和基因、标准化、对数转换。
  3. 运行 SpaGCN（Visium 带 H&E）：构建结合 spot 距离和组织学颜色的图，平滑表达，然后用图卷积网络聚类。可进行细化（根据邻域多数标签重新标记）。
  4. 运行 GraphST：学习空间平滑嵌入，然后聚类（默认 Leiden，作者推荐 mclust）。
  5. 运行 UTAG（单细胞分辨率）：在 max_dist 内平均每个细胞的表达，然后聚类（Leiden），合并小簇。
  6. 比较方法和表征域：计算调整兰德指数（ARI）比较方法一致性，绘制域图，用 Wilcoxon 检验找域标记基因，分析域组成（若有细胞类型标签或 cell2location 丰度）。

适用场景

  • 将 Visium 或 ST 切片划分为组织区域（如分层、肿瘤核心和间质）。
  • 结合 H&E 图像和表达绘制区域边界（SpaGCN）。
  • 在 Xenium、MERFISH、CosMx 或 IMC 数据中无标签寻找细胞生态位（UTAG）。
  • 获取区域标签以汇总反卷积组成或细胞类型。
  • 检查两种独立方法是否在主要边界上一致。

限制

  • 域是聚类结果，并非 ground truth：建议运行两种方法并报告一致之处。
  • SpaGCN 的 Louvain 初始化需要 louvain 包，但该包无 Python 3.13 conda 构建或 wheel，且无法在此编译；若无，可使用 k-means 初始化。
  • GraphST 的密集 spot-by-spot 图限制其约 30k 观测；CUDA GPU 可使训练快约 10 倍。
  • UTAG 不在 PyPI 上，需从 GitHub 安装。
  • 当细胞已注释且生态位应由细胞类型混合定义时，应使用 spatial-transcriptomics-cell-type-annotation 的第 7 步。
  • 对于邻域富集或空间可变基因，应使用 spatial-transcriptomics-analysis-squidpy。

安装命令

# 仅安装 `import` 报告缺失的包。`--pypi` 保持环境的 scanpy/numba 栈；conda 添加可能替换它，裸 pip 可能遮蔽它。
pixi add --pypi scanpy SpaGCN GraphST
pixi add --pypi "utag @ git+https://github.com/ElementoLab/utag.git@main"

关键参数

  • N_DOMAINS：目标域数量（默认 7），可尝试 5-15 并比较。
  • SpaGCN p（search_l）：从邻居获取的表达比例（默认 0.5），越高域越平滑。
  • SpaGCN alpha：图中组织学颜色的权重（默认 1）。
  • SpaGCN shape：细化时使用的邻居环（"hexagon" 用于 Visium，"square" 用于 ST）。
  • GraphST datatype："10X" 用于 spot 网格和成像细胞；"Slide" 或 "Stereo" 用于 Slide-seq / Stereo-seq（KNN 图）。
  • GraphST radius：当 refinement=True 时使用的邻居数（默认 50）。
  • UTAG max_dist：平均半径（坐标单位），自动（约 3 个邻居），越大生态位越粗。
  • UTAG resolutions：Leiden 分辨率（0.05-0.5）。
  • MIN_CLUSTER_SIZE：小于此值的 UTAG 簇合并到最近的大簇（默认 100）。

预期输出

  • spatial_domains.csv：每个 spot 的 spagcn、spagcn_refined、graphst 标签。
  • spatial_domains.h5ad：带域标签和 obsm["graphst_emb"] 的数据。
  • domain_markers.csv：每个域的 Wilcoxon 标记基因。
  • domains_spatial.png：组织坐标上的域图。
  • domain_composition.csv：每个域的细胞类型混合（配方）。

故障排除

  • SpaGCN UnboundLocalError: y_pred：初始化不是 "louvain" 或 "kmeans"；使用 init="louvain"（需要 louvain）或 init="kmeans" 并指定 n_clusters。
  • SpaGCN AttributeError: ... has no attribute 'A'：scipy >= 1.14 下的稀疏 X；在 SpaGCN 前稠密化 X（步骤 3 已处理）。
  • SpaGCN 域忽略组织图像：坐标交换或全分辨率尺度用于 hires 图像；传递按 tissue_hires_scalef 缩放的 pxl_row/pxl_col，行在前。
  • GraphST Assert...：资料未提供完整信息。