spatial-transcriptomics-deconvolution-cell2location

概述

每个 Visium spot（55 微米）包含若干细胞，因此细胞类型需以每个 spot 的丰度表示，而非每个 spot 单一标签。cell2location 从 scRNA-seq 参考中学习每种细胞类型的表达特征，再将每个 spot 的计数解释为这些特征的混合。输出包括每个 spot 与细胞类型的估计细胞数和比例、组织切片上的分布图，以及针对每张图的标记基因检查。

适用场景

被要求在 Visium、Slide-seq 或 ST 数据上“注释细胞类型”或“定位细胞类型位置”。
将已发表的 scRNA-seq 图谱映射到基于 spot 的切片。
比较组织区域或切片之间的细胞类型组成。
为下游生态位或细胞通讯分析生成每个 spot 的组成。
获得带后验不确定性（5% 分位数）的丰度估计。

当每个观测对应一个细胞时（Xenium、MERFISH、CosMx），应改用 spatial-transcriptomics-cell-type-annotation；当需要将单细胞放置到组织学图像分割的细胞核上（约束式去卷积路线）时，应改用 spatial-mapping-tangram。

前置条件

输入：Space Ranger 输出（filtered_feature_bc_matrix.h5 和 spatial/ 目录），包含原始计数。
参考：包含原始计数和 obs["cell_type"] 的 scRNA-seq 数据（步骤2会获取一份）。
计算：强烈建议使用 GPU。在 CPU 上，空间模型（步骤4）需要的训练轮数少于默认值，由该处的计时探针决定；参考模型（步骤3）需要数分钟。
Python 包：cell2location（会引入 torch、scvi-tools、pyro，体积较大）、scanpy。

安装命令：pixi add --pypi scanpy cell2location

前置询问

运行前需确认：组织及状态（健康或何种肿瘤/疾病）；是否有同组织同状态的 scRNA/snRNA-seq 参考（h5ad，含原始计数和细胞类型列），或需检索公开数据（CELLxGENE）；参考中哪一列存放细胞类型及层级（主要谱系或精细亚型）；计算路线（无 GPU 时可减少训练轮数运行 cell2location，或改用 Tangram 快速获得每 spot 比例）；每个 spot 大约包含多少细胞核（默认30）；若有多个切片，是合并为一个模型（共享细胞类型特征、每切片敏感度）还是各自单独拟合；RNA 检测是否在切片上强烈变化（默认 DETECTION_ALPHA=20，检测均匀时为200）；参考是否汇集多个供体或研究并需按该列校正特征。

工作流程

步骤1：加载 Visium 输出。使用 scanpy 读取 h5，处理组织位置文件（兼容 Space Ranger 2.0 前后的格式），将空间坐标写入 obsm，剔除线粒体基因，并打印每个 spot 的 UMI 中位数。

步骤2：获取参考。使用用户提供的参考，或按组织与状态从 CELLxGENE 检索下载子采样参考（复用 cell-type-annotation 技能的步骤3-4，GENES=None、MAX_PER_TYPE=300）。细胞数少于约20的类型无法产生稳定特征，步骤3会将其丢弃。

步骤3：拟合参考特征。过滤基因，设置 RegressionModel，训练250轮，导出后验，得到基因×细胞类型的特征矩阵。多供体参考可加 batch_key="donor_id"。

步骤4：拟合空间模型。取空间数据与特征矩阵的共享基因，设置 N_CELLS_PER_SPOT（默认30）和 DETECTION_ALPHA（默认20，检测均匀时可试200）。在 CPU 上先用一次性模型计时50轮，推算每轮耗时，再在预算内选择 MAX_EPOCHS；GPU 可用时用默认30000。低于约3000轮的地图过于粗糙，不宜报告，应改用 Tangram 路线。然后训练正式模型。报告中需注明 MAX_EPOCHS，低于30000视为探索性结果。

步骤5：导出并检查丰度。导出后验，生成每个 spot 与细胞类型的丰度表（q05）及比例表，保存 h5ad 和丰度最高的若干类型组织分布图。用用户生物学预期的标记基因检验每张图：丰度与标记表达应在 spot 间相关；若某类型分布与其自身标记不相关，则该结果不支持。

关键参数

参考状态：来自用户，健康与疾病特征差异是最重要的选择。
N_CELLS_PER_SPOT：默认30，作为 spot 密度的先验，缩放绝对丰度，应根据组织学设定。
DETECTION_ALPHA：默认20，正则化每 spot 敏感度；检测均匀时为200。
MAX_EPOCHS（空间）：默认30000，控制收敛；轮数越少地图越粗糙。
每类型最少细胞数：20，低于此值的类型从参考中丢弃。

常用配方

多切片单模型：读取各切片并合并（label="sample"），共享特征、按切片估计敏感度，然后按步骤4训练。
在 H&E 图像上绘图：用 squidpy 读取 Space Ranger 目录，将丰度写入 obs，绘制空间散点图。
主导类型与区域组成：计算每个 spot 的主导类型及其占比；若有区域注释列，可按区域汇总平均组成。spot 的主导类型只是摘要而非标签，报告时需同时给出占比。

预期输出

cell2location_abundance.csv：每个 spot 与细胞类型的估计细胞数（5% 后验分位数）。
cell2location_proportions.csv：每个 spot 的比例。
cell2location_spatial.h5ad：obsm 中的完整后验。
cell2location_top_types.png：丰度最高类型的分布图。

常见问题

共享基因太少：可能是基因符号与 Ensembl ID 不一致，两侧统一使用符号。
训练很慢：CPU 上30000轮过慢，降低 MAX_EPOCHS 并在报告中说明，或使用 GPU。
某一类型主导所有 spot：参考缺少该组织主要类型，应选择更匹配的参考。
KeyError: means_per_cluster_mu_fg_...：未在参考上运行 export_posterior，需在步骤4前运行。
导出时内存不足：降低 sample_kwargs 中的 batch_size。
总丰度不跟随细胞核密度：DETECTION_ALPHA 过强，比较20与200，保留更符合组织学的值。

技能介绍