alterlab-squidpy-spatial

Squidpy：空间转录组学

Squidpy 是 scverse 面向空间分辨组学的工具包，构建于 AnnData 和 SpatialData 之上。它能回答非空间 scRNA-seq 流程无法回答的问题：哪些细胞类型彼此相邻（邻域富集）、不同细胞类型对在不同距离上如何共同出现（共现）、哪些基因在组织空间中呈现变异（Moran's I / 空间变异基因），以及哪些配体-受体信号传导具有合理性（ligrec）。此技能负责空间分析；非空间 QC/聚类交由 alterlab-scanpy 处理，spot 去卷积交由 alterlab-scvi-tools 处理。

何时使用此技能

在请求涉及以下内容时使用：

• 对 Visium、Visium HD、Xenium、 MERFISH/MERSCOPE 或 CosMx 数据进行空间转录组学 / 空间分辨组学分析。
• 构建空间邻居图并运行邻域富集、 共现、交互矩阵、Ripley 统计量或 中心性评分。
• 通过 Moran's I (spatial_autocorr) 或 Sepal 查找空间变异基因。
• 在空间背景下进行配体-受体分析 (ligrec)。
• 识别空间生态位 / 组织域 (calculate_niche_*：邻域 特征、UTAG、CellCharter、SpatialLeiden)。
• 将平台输出读入 AnnData/SpatialData，并为平台选择合适的 coord_type。

不适用的情形

请求	转交给
非空间 scRNA-seq QC、归一化、PCA/UMAP、Leiden 聚类、标记基因	alterlab-scanpy
spot 去卷积 / 将细胞类型映射到 Visium spots（destVI、Tangram）、概率批次校正/整合	alterlab-scvi-tools（参见其 references/models-spatial.md）
构建/切片/拼接 .h5ad AnnData 对象、整理 layer 和 obsm（不涉及空间分析）	alterlab-anndata
RNA velocity / 轨迹动态	alterlab-scvelo
从计数矩阵进行 Bulk RNA-seq 差异表达分析	alterlab-pydeseq2
原始 FASTQ → 表达矩阵（reads 比对/定量）	alterlab-rnaseq-quant
对特征表进行多样性 / 生态学统计	alterlab-scikit-bio

如果用户需要完整流程（“聚类我的 Xenium 数据，然后找出哪些细胞类型彼此相邻”），先通过 alterlab-scanpy 运行 scanpy 聚类步骤，再返回此处构建空间图并进行富集分析。

最重要的决策：平台 → coord_type

Squidpy 的空间图取决于测量几何结构。coord_type 设置错误会悄无声息地生成毫无意义的图。（以下参数行为均来自 squidpy 1.8 的 sq.gr.spatial_neighbors API。）

平台	分辨率	构建器	配合使用
Visium	spot（多细胞，六边形网格）	coord_type="grid"、n_neighs=6、n_rings=1..2	去卷积 → alterlab-scvi-tools
Visium HD	2/8/16 µm 分箱（方形网格）	coord_type="grid"（方形格点）	预先选择分箱方式
Xenium / MERFISH / CosMx	单细胞	coord_type="generic"、delaunay=True（或 n_neighs=k）	直接进行细胞类型分析

• 仅当 spatial 位于 adata.uns 中且 n_neighs=6（Visium 特征）时，coord_type=None 才会自动选择 "grid"；否则会回退到 "generic"。请显式设置 coord_type，不要依赖自动检测。
• 只有当 coord_type="generic" 时才会使用 delaunay=True；它通过 Delaunay 三角剖分构建图，而非使用 k 近邻 spots。只有当 coord_type="grid" 时才会使用 n_rings。
• Squidpy 1.8 也直接提供了各类构建器：sq.gr.spatial_neighbors_grid、 _knn、_radius、_delaunay，每个构建器仅包含适用于自身的参数。已知几何结构时优先使用这些构建器：sq.gr.spatial_neighbors(..., delaunay=True) 会悄悄忽略 n_neighs，这是常见的“我的 k 没有起作用”问题来源。

加载数据（根据平台选择读取器）

import squidpy as sq
import scanpy as sc

# Visium (legacy spot data) — squidpy's own reader, returns AnnData
adata = sq.read.visium("path/to/visium_outs/")

# Vizgen MERSCOPE / Nanostring CosMx via squidpy readers
adata = sq.read.vizgen("path/to/merscope/", counts_file="cell_by_gene.csv",
                       meta_file="cell_metadata.csv")
adata = sq.read.nanostring("path/to/cosmx/", counts_file="exprMat_file.csv",
                           meta_file="metadata_file.csv", fov_file="fov_positions.csv")

对于 Xenium 和 Visium HD，请使用 spatialdata-io 读取器（squidpy 没有 sq.read.xenium），并对 SpatialData 对象进行操作：

from spatialdata_io import xenium, visium_hd, merscope
sdata = xenium("path/to/xenium_outs/")        # 10x Xenium
sdata = visium_hd("path/to/visium_hd_outs/")  # 10x Visium HD
sdata = merscope("path/to/merscope/")         # Vizgen MERSCOPE

spatialdata-io 读取器名称已根据 spatialdata-io 稳定版 API 验证。 Squidpy 1.8 可直接接受 SpatialData 对象；关于 SpatialData ↔ AnnData（表格）的流程，请参阅 references/spatialdata_io.md。

标准空间分析工作流

QC、归一化、高变基因（HVG）、PCA、邻居、Leiden 和 sc.tl.umap 都是 scanpy 步骤——请通过 alterlab-scanpy 运行。获得聚类 / 细胞类型标签后， 再在此处进行空间分析。

import squidpy as sq

# 1. Build the spatial neighbor graph (choose coord_type per the table above)
sq.gr.spatial_neighbors(adata, coord_type="generic", delaunay=True)   # Xenium/MERFISH
# sq.gr.spatial_neighbors(adata, coord_type="grid", n_neighs=6)       # Visium

# 2. Neighborhood enrichment: which cluster pairs are spatially adjacent?
sq.gr.nhood_enrichment(adata, cluster_key="leiden")
sq.pl.nhood_enrichment(adata, cluster_key="leiden")

# 3. Co-occurrence across distance
sq.gr.co_occurrence(adata, cluster_key="leiden")
sq.pl.co_occurrence(adata, cluster_key="leiden", clusters="0")

# 4. Spatially variable genes via Moran's I
sq.gr.spatial_autocorr(adata, mode="moran")
svgs = adata.uns["moranI"].head(20)   # ranked by Moran's I

# 5. Ligand-receptor interaction (Omnipath-backed)
sq.gr.ligrec(adata, cluster_key="leiden")

# 6. Spatial niches / tissue domains — cluster cells by their neighborhood, not
#    just their own expression. Requires a spatial graph (step 1) already built.
sq.gr.calculate_niche_neighborhood(adata, groups="leiden", resolutions=[0.5, 1.0])
# other flavors: calculate_niche_utag, calculate_niche_cellcharter,
#                calculate_niche_spatialleiden

通用的 sq.gr.calculate_niche(..., flavor=...) 分派器仍可使用，但已弃用，并计划在 squidpy 1.9 中移除——请调用对应的特定风味函数，其签名仅包含该风味实际使用的参数。生态位分析回答的问题与 nhood_enrichment 不同：富集分析关注哪些带标签的细胞类型平均而言会聚集在一起，而生态位分析则为每个细胞分配一个反复出现的组织微环境。

其他图统计方法：sq.gr.interaction_matrix、sq.gr.centrality_scores、 sq.gr.ripley（相对于 CSR 的聚类 / 离散程度）和 sq.gr.sepal（另一种空间变异基因检验）。使用 sq.pl.spatial_scatter （点位）或 sq.pl.spatial_segment（已分割细胞）可视化组织； sq.pl.nhood_enrichment_dotplot 和 sq.pl.var_by_distance（以到锚点的距离为函数的表达量）也是值得了解的另外两种绘图方法。对于 H&E/IF 图像特征，sq.im 模块（process、segment、calculate_image_features）作用于 ImageContainer。

辅助脚本——通过一次调用构建图并运行核心统计分析：

uv run python skills/bioinformatics/alterlab-squidpy-spatial/scripts/spatial_neighborhood.py \
    clustered.h5ad --platform xenium --cluster-key leiden --out spatial_report.json

参阅 scripts/spatial_neighborhood.py --help。该脚本根据 --platform 选择 coord_type，运行 spatial_neighbors、nhood_enrichment、co_occurrence 和 spatial_autocorr，并写入 JSON 摘要（排名靠前的空间变异基因 + 富集 z 分数矩阵）以及更新后的 .h5ad。

深入参考资料

• references/platform_routing.md — 完整的平台→coord_type 决策表、n_neighs/n_rings/delaunay 参数含义，以及各平台的注意事项。
• references/analysis_recipes.md — 每个 sq.gr / sq.pl 函数的可复制粘贴示例，包含重要参数及输出解读方式。
• references/spatialdata_io.md — 将 Xenium / Visium HD / MERSCOPE 读入 SpatialData，以及获取 squidpy 操作的 AnnData table。

报告前自检

• 是否设置了与平台匹配的 coord_type（Visium 使用 grid，单细胞使用 generic）？错误的图会使所有下游统计分析失效。
• 聚类 / QC 是否通过 alterlab-scanpy 运行（本技能假定标签已存在）？
• 对于 Visium 点位数据，是否说明在做细胞类型层面的推断前需要进行去卷积（alterlab-scvi-tools）——一个点位包含多个细胞？
• 报告 nhood_enrichment z 分数时，是否同时说明了置换分析背景，而非将其当作原始计数？

AlterLab Academic Skills 套件的一部分。