tooluniverse-spatial-transcriptomics

空间转录组分析

全面分析空间分辨转录组数据，以了解组织结构背景下的基因表达模式。结合表达谱与空间坐标，揭示组织结构、细胞间相互作用和空间变异基因。

不要猜测，要查证

对任何科学事实不确定时，请先搜索数据库，而不是凭记忆推理。经数据库验证的答案总是比猜测更可靠。

何时使用此技能

触发条件：

• 用户拥有空间转录组数据（Visium、MERFISH、seqFISH 等）
• 用户只有 H&E 组织学图像，完全没有空间检测数据——DeepSpotM_predict_gene_expression（本地模型，无需 API/密钥）可直接根据 224x224 的 H&E 图块预测空间基因表达；当尚无真实空间数据时，它可提供虚拟读数。应将其输出视为模型预测，用于指导后续工作（例如确定实际检测哪个区域），而不是在目标为获取真实空间数据时替代上述平台。
• 关于组织结构或空间组织的问题
• 空间基因表达模式分析
• 细胞间邻近关系或邻域分析需求
• 肿瘤微环境空间结构相关问题
• 空间数据与单细胞数据整合
• 空间域识别
• 组织形态与表达的相关性

示例问题：

1. “分析这个 10x Visium 数据集，识别空间域”
2. “哪些基因在该组织中呈现空间变异表达？”
3. “绘制肿瘤微环境的空间组织图”
4. “找出在组织边界富集的基因”
5. “根据空间邻近关系识别细胞间相互作用”
6. “将空间转录组与 scRNA-seq 注释整合”

---

核心能力

• 数据导入：10x Visium、MERFISH、seqFISH、Slide-seq、STARmap、Xenium 格式
• 质量控制：点位/细胞 QC、空间对齐验证、组织覆盖范围
• 归一化：采用考虑组织异质性的空间感知归一化方法
• 空间聚类：识别表达谱相似的空间域
• 空间变异基因：查找具有非随机空间模式的基因
• 邻域分析：细胞间邻近关系、空间邻域、生态位识别
• 整合：与 scRNA-seq 合并以进行细胞类型映射（Cell2location、Tangram、SPOTlight）
• 配体-受体空间分析：通过 OmniPath 映射组织背景下的细胞通信

支持的平台

• 10x Visium：55um 点位（每个点位约 50 个细胞），全基因组，包含 H&E 图像——最常见
• MERFISH/seqFISH：单细胞分辨率，100-10,000 个目标基因，基于成像
• Slide-seq/V2：10um 微珠，全基因组——分辨率高于 Visium
• Xenium：单细胞/亚细胞分辨率，300+ 个目标基因（10x 平台）

---

工作流概览

Input: Spatial Transcriptomics Data + Tissue Image
    |
    v
Phase 1: Data Import & QC
    |-- Load spatial coordinates + expression matrix
    |-- Load tissue histology image
    |-- Quality control per spot/cell (min 200 genes, 500 UMI, <20% MT)
    |-- Align spatial coordinates to tissue
    |
    v
Phase 2: Preprocessing
    |-- Normalization (spatial-aware methods)
    |-- Highly variable gene selection (top 2000)
    |-- Dimensionality reduction (PCA)
    |-- Spatial lag smoothing (optional)
    |
    v
Phase 3: Spatial Clustering
    |-- Build spatial neighbor graph (squidpy)
    |-- Graph-based clustering with spatial constraints (Leiden)
    |-- Annotate domains with marker genes (Wilcoxon)
    |-- Visualize domains on tissue
    |
    v
Phase 4: Spatial Variable Genes
    |-- Test spatial autocorrelation (Moran's I, Geary's C)
    |-- Filter significant spatial genes (FDR < 0.05)
    |-- Classify pattern types (gradient, hotspot, boundary, periodic)
    |
    v
Phase 5: Neighborhood Analysis
    |-- Define spatial neighborhoods (k-NN, radius)
    |-- Calculate neighborhood composition (squidpy nhood_enrichment)
    |-- Identify interaction zones between domains
    |
    v
Phase 6: Integration with scRNA-seq
    |-- Cell type deconvolution (Cell2location, Tangram, SPOTlight)
    |-- Map cell types to spatial locations
    |-- Validate with marker genes
    |
    v
Phase 7: Spatial Cell Communication
    |-- Identify proximal cell type pairs
    |-- Query ligand-receptor database (OmniPath)
    |-- Score spatial interactions (squidpy ligrec)
    |-- Map communication hotspots
    |
    v
Phase 8: Generate Spatial Report
    |-- Tissue overview with domains
    |-- Spatially variable genes
    |-- Cell type spatial maps
    |-- Interaction networks in tissue context

---

各阶段摘要

阶段 1：数据导入与 QC

加载平台特定的数据（Visium 使用 scanpy read_visium）。应用 QC 过滤条件：每个点位至少 200 个基因、至少 500 个 UMI、线粒体基因占比最高 20%。通过组织图像叠加层验证空间对齐。

阶段 2：预处理

归一化至总计数中位数，进行对数转换，选取排名前 2000 的 HVG。可选：通过邻居平均进行空间平滑（适用于噪声较大的数据，但会模糊边界）。

阶段 3：空间聚类

进行 PCA（50 个成分），随后构建空间邻居图（squidpy）。结合空间约束进行 Leiden 聚类，得到空间域。使用 Wilcoxon 秩和检验查找域标记基因。

阶段 4：空间变异基因

Moran's I 统计量用于检验空间自相关：I > 0 = 聚集，I ~ 0 = 随机，I < 0 = 棋盘格模式。按 FDR < 0.05 进行过滤。将模式分类为梯度、热点、边界或周期性。

阶段 5：邻域分析

邻域富集分析（squidpy）用于检验细胞类型／域是否比随机预期更倾向于共定位。使用 k-NN 空间图识别域边界处的相互作用区域。

阶段 6：scRNA-seq 整合

细胞类型去卷积将单细胞注释映射到空间点位。方法：Cell2location（推荐用于 Visium）、Tangram、SPOTlight。生成每个点位的细胞类型比例估计。

阶段 7：空间细胞通信

将空间邻近性与配体-受体数据库相结合。关键 ToolUniverse 工具：

• OmniPath_get_ligand_receptor_interactions — 来自 CellPhoneDB、CellChatDB 等数据库的 14,000 多对配体-受体组合。使用 partners 参数指定特定基因。
• OmniPath_get_intercell_roles — 将蛋白质分类为配体／受体／ECM。使用 proteins 参数。
• OmniPath_get_cell_communication_annotations — CellPhoneDB／CellChatDB 通路注释。使用 proteins 参数。
• OmniPath_get_signaling_interactions — 受体下游的细胞内信号相互作用。

根据邻近细胞中配体-受体组合的共表达情况对相互作用进行评分。绘制相互作用评分达到峰值的热点区域。

阶段 7.5：数据发现与基因背景（ToolUniverse API 工具）

用于数据集发现和基因注释（基于 API，无需本地计算）：

• geo_search_datasets / OmicsDI_search_datasets / NCBI_SRA_search_runs — 查找空间 TX 数据集
• UniProt_get_function_by_accession — 获取基质／免疫标记物的蛋白质功能
• STRING_get_network — 获取关键标记物的蛋白质相互作用网络
• kegg_search_pathway / kegg_get_pathway_info — 查找相关代谢／信号通路
• DGIdb_get_drug_gene_interactions — 查找空间背景下可成药的靶点
• PubMed_search_articles — 查找空间生物学背景相关文献

API 工具与本地计算：阶段 1-2（数据导入、QC）和阶段 3-6（聚类、SVG、邻域分析、去卷积）需要使用带有 squidpy／scanpy 的本地 Python。阶段 7 的配体-受体数据库和阶段 7.5 的基因背景使用 ToolUniverse API 工具。

阶段 8：报告生成

完整输出示例请参见 report_template.md。

---

与 ToolUniverse 技能集成

• tooluniverse-single-cell：用于去卷积（阶段 6）的 scRNA-seq 参考数据和用于配体-受体数据库（阶段 7）的数据
• tooluniverse-gene-enrichment：空间域标记基因的通路富集分析（阶段 3）
• tooluniverse-multi-omics-integration：与其他组学层整合（阶段 8）

ToolUniverse 数据检索工具

HuBMAP 空间图谱工具

使用 HuBMAP 工具发现已发表的空间生物学数据集，以供参考、验证或跨研究比较。

可用性说明：HuBMAP_search_datasets、HuBMAP_list_organs 和 HuBMAP_get_dataset 可能未在你的 ToolUniverse 实例中注册。使用前请通过 tu.list_tools() 验证。如果不可用，可使用 OmicsDI（OmicsDI_search_datasets(query="spatial transcriptomics kidney")）或 CELLxGENE（CELLxGENE_get_cell_metadata）作为可靠的空间数据集发现替代方案。

• HuBMAP_search_datasets：按 organ（代码，例如 "LK"=左肾，"BR"=脑）、dataset_type、query、limit 搜索已发表的数据集
• HuBMAP_list_organs：列出所有器官及其代码和 UBERON ID（无需必填参数）
• HuBMAP_get_dataset：获取指定 hubmap_id 的详细元数据（例如 "HBM626.FHJD.938"）

器官代码：LK/RK=肾脏，LI=大肠，SI=小肠，HT=心脏，LV=肝脏，LU=肺，SP=脾脏，BR=脑，PA=胰腺，SK=皮肤。

HuBMAP 生物样本 + 空间配准层（样本与供体）

在数据集层级之下，HuBMAP 对实体组织样本（解剖组织块／切片／器官／悬液）和人类供体进行索引。使用这些工具可检查 CCF/RUI 空间配准和供体人口统计信息——这些上下文信息无法通过数据集工具获取。

• HuBMAP_search_samples：按 organ（2 字母代码）、sample_category（"block"/"section"/"organ"/"suspension"）、registered_only（仅限已进行 CCF/RUI 配准的样本）和 limit 查找组织样本。每条结果都会标明 spatially_registered，并链接到其父供体。
• HuBMAP_get_sample：获取一个样本 hubmap_id（例如 "HBM658.BXNB.873"）的完整记录，包括解析后的 rui_location——CCF placement_target 参考器官、x/y/z dimension 及单位，以及 ccf_annotations（样本块所覆盖的 UBERON/FMA 结构）。
• HuBMAP_search_donors：按 group_name（例如 "Stanford"）或自由文本 query 查找供体，并提供标准化的 demographics（年龄、性别、种族、body_mass_index、死亡原因），这些信息从 UMLS/SNOMED 编码元数据中提取。可用于构建人口统计特征匹配的组织队列。

# Spatially-registered kidney blocks (carry CCF coordinates)
blocks = tu.tools.HuBMAP_search_samples(organ="LK", sample_category="block", registered_only=True, limit=5)

# Inspect the CCF spatial registration of one block
s = tu.tools.HuBMAP_get_sample(hubmap_id="HBM658.BXNB.873")
# s["data"]["rui_location"] -> {placement_target: ...VHMLung..., x/y/z_dimension, dimension_units, ccf_annotations:[UBERON...]}

# Demographically-matched donor cohort
donors = tu.tools.HuBMAP_search_donors(group_name="Stanford", limit=10)
# donors["data"]["donors"][i]["demographics"] -> {age, sex, race, body_mass_index, ...}

适用场景：

• 查找特定器官／组织的空间参考数据集
• 确认某种组织可用的空间检测类型（Visium、CODEX、MERFISH）
• 交叉参考空间数据集的供体元数据（年龄、性别）
• 获取已发表空间图谱数据集的 DOI 链接

HuBMAP 工具不可用时的备用方案：

# Use OmicsDI for spatial dataset discovery
result = tu.tools.OmicsDI_search_datasets(query="spatial transcriptomics kidney Visium")

# Use CELLxGENE for cell-level expression context
# obs_value_filter is required (unfiltered Census queries time out)
result = tu.tools.CELLxGENE_get_cell_metadata(
    obs_value_filter='tissue_general == "kidney"',
    column_names=["cell_type", "tissue", "disease"],
)

# Example: Find spatial datasets for kidney (if HuBMAP tools available)
result = tu.tools.HuBMAP_search_datasets(organ="LK", limit=5)
# Returns: {data: {total, returned, datasets: [{hubmap_id, title, dataset_type, organ, doi_url, ...}]}}

# Example: Get all available organs
organs = tu.tools.HuBMAP_list_organs()
# Returns: {data: {total, organs: [{code, term, organ_uberon, rui_supported}]}}

---

示例用例

用例 1：肿瘤微环境图谱绘制

问题："绘制肿瘤、免疫细胞和基质细胞的空间组织结构" 工作流：加载 Visium -> 质量控制 -> 空间聚类 -> 去卷积 -> 相互作用区域 -> 配体-受体分析 -> 报告

用例 2：发育梯度分析

问题："识别发育组织中的空间基因表达梯度" 工作流：加载空间数据 -> SVG 分析 -> 对梯度模式分类 -> 绘制形态发生素分布 -> 与细胞命运相关联 -> 报告

用例 3：脑区识别

问题："自动将脑组织分割为解剖区域" 工作流：加载脑部 Visium 数据 -> 高分辨率聚类 -> 匹配已知脑区 -> 使用 Allen Brain Atlas 验证 -> 报告

---

量化最低要求

• 质量控制后至少有 500 个空间位置
• 过滤低质量位点（至少 200 个基因、至少 500 UMI、线粒体基因比例 <20%），并验证比对结果
• 至少使用一种空间聚类方法（采用空间约束的基于图的方法）
• 使用 Moran's I 或等效方法检验空间可变基因（FDR < 0.05）
• 在组织图像上绘制所有主要发现的空间图
• 报告涵盖：空间域、空间基因、细胞类型图谱、关键相互作用

---

推理框架

起点：空间问题是什么？

空间数据为表达信息增加了位置维度。关键问题是：空间模式由细胞类型组成驱动（平凡），还是由同一细胞类型内受空间调控的基因表达驱动（值得关注）？去卷积有助于区分这两种情况。

解读任何空间可变基因（SVG）之前，请先询问：

1. 这个基因是否只是标记了一种空间分布受限的细胞类型？（例如，T 细胞标记基因在免疫浸润区域富集——这是预期现象，信息量不大）
2. 还是说，这个基因在同一细胞类型内会随空间位置不同而差异表达？（例如，肿瘤-基质交界处的成纤维细胞基因上调——这属于空间调控，具有生物学意义）

区分方法：(a) 运行去卷积（Cell2location、Tangram），获得每个位点的细胞类型比例；(b) 对 SVG 表达量与细胞类型比例进行回归；(c) 若控制细胞类型组成后空间模式仍然存在，则反映了真实的空间调控。解读之前务必查阅该基因的已知生物学信息——查看 UniProt 功能和 STRING 相互作用，不要凭空猜测。

证据分级

• T1：通过正交方法验证（IHC、smFISH、已知解剖结构）——例如，空间区域与组织学确认的肿瘤边缘相吻合
• T2：具有统计学显著性，且符合生物学规律——预期组织区域中的 SVG，其 Moran's I > 0.3 且 FDR < 0.01
• T3：通过计算识别，尚待验证——通过聚类发现的新型空间区域，没有组织学对应特征
• T4：探索性或容易受伪影影响——低 UMI 边缘点位、受批次效应驱动的区域

解读指南

空间区域：空间区域表示基因表达一致的区域，通常对应组织结构（肿瘤核心、基质、免疫细胞浸润、坏死）。当其标记基因与已知细胞类型特征相符时，该区域在生物学上具有意义。组织边界处的区域（例如肿瘤-基质界面）对微环境研究尤其有价值。

细胞间邻近显著性：邻域富集 z 分数 > 2 表示细胞类型的共定位程度高于随机预期。负 z 分数表示空间回避。应结合生物学背景解读：免疫细胞在肿瘤细胞附近富集，可能表示免疫反应活跃，也可能表示免疫抑制性生态位，具体取决于涉及的细胞类型（例如 CD8+ T 细胞与 Treg）。

空间变异基因（SVG）：Moran's I > 0.3 且 FDR < 0.05 表示存在强烈的空间模式。根据模式对 SVG 分类：梯度（形态发生信号，例如沿隐窝-绒毛轴分布的 WNT）、热点（免疫细胞聚集区域中的局部表达）、边界基因（在区域交界处富集，例如上皮-间质转化标记）。具有已知空间生物学作用的 SVG（例如组织极性基因）比新候选基因可信度更高。

综合分析问题

完整的空间转录组报告应回答：

1. 识别出了哪些空间区域？它们是否对应已知的组织结构？
2. 哪些基因具有显著的空间变异？它们呈现什么模式？
3. 哪些特定细胞类型组合在空间邻近关系中富集或减少？
4. 哪些配体-受体相互作用在区域边界或细胞间界面处活跃？
5. 空间分析结果与同一组织类型的 bulk 或单细胞数据相比如何？

---

程序化访问（工具之外）

当 ToolUniverse 工具返回元数据，但你需要实际的表达矩阵时：

import scanpy as sc, pandas as pd, requests, io

# Load h5ad (most common format for spatial/single-cell)
adata = sc.read_h5ad("spatial_data.h5ad")

# Load 10X Visium output directory
adata = sc.read_visium("path/to/spaceranger_output/")

# Download from GEO supplementary files
geo_id = "GSE123456"
# Check for h5ad or MTX in supplementary files
url = f"https://www.ncbi.nlm.nih.gov/geo/query/acc.cgi?acc={geo_id}&targ=gsm&view=data"

# Load 10X MTX format (matrix + barcodes + features)
adata = sc.read_10x_mtx("filtered_feature_bc_matrix/", var_names="gene_symbols")

# HuBMAP data portal
# Search at https://portal.hubmapconsortium.org/search then download via globus or direct link
# Human Cell Atlas: https://data.humancellatlas.org/ — download h5ad/loom files

有关格式指南和批量下载模式，请参阅 tooluniverse-data-wrangling 技能。

---

局限性

• 分辨率：Visium 点位包含多个细胞（并非单细胞）
• 基因覆盖范围：成像方法的基因面板有限
• 3D 结构：大多数平台使用 2D 切片
• 组织质量：成像需要保存完好的组织
• 计算资源：大型数据集需要大量内存
• 参考依赖：去卷积质量取决于 scRNA-seq 参考数据

---

参考文献

方法：

• Squidpy：https://doi.org/10.1038/s41592-021-01358-2
• Cell2location：https://doi.org/10.1038/s41587-021-01139-4
• SpatialDE：https://doi.org/10.1038/nmeth.4636

平台：

• 10x Visium：https://www.10xgenomics.com/products/spatial-gene-expression
• MERFISH：https://doi.org/10.1126/science.aaa6090
• Slide-seq：https://doi.org/10.1126/science.aaw1219

---

参考文件

• code_examples.md - 各阶段的 Python 代码（scanpy、squidpy、cell2location）
• report_template.md - 完整报告示例（乳腺癌 TME）