用途
本技能用于为基于成像的单细胞分辨率空间转录组数据（Xenium、MERFISH、CosMx、SeqFISH）注释细胞类型和组织生态位。此类数据中每个观测对应一个分割后的细胞。技能会从 CELLxGENE 拉取与组织及状态匹配的 scRNA-seq 参考，用 Harmony 迁移标签，再依据聚类标志基因表为每个聚类命名。输出为包含每细胞标签、置信度和生态位的 AnnData，以及支撑每个命名的证据表。
使用前需先核对平台：单细胞分辨率的靶向面板或全转录组数据使用本技能；Visium、Visium HD bins、Slide-seq、ST 等斑点数据因每个斑点混合多个细胞，应改用反卷积技能 spatial-transcriptomics-deconvolution-cell2location。无空间坐标的解离 scRNA-seq 应使用 cell-type-annotation。
主要能力
- 读取 Xenium 输出目录（cell_feature_matrix.h5、cells.csv.gz）或含原始计数与 obsm["spatial"] 的 .h5ad。
- 针对小面板进行宽松的逐细胞质控，检查负对照探针比例、细胞核面积比等指标，并通过互斥谱系标志基因双阳性率评估分割泄漏。
- 预处理与聚类：保留计数层、过滤基因、归一化、log1p、PCA（靶向面板不做高变基因选择）、邻居图、UMAP、Leiden 聚类。
- 检索 CELLxGENE 公开元数据，按物种、组织、疾病状态、assay 筛选候选参考数据集，优先整体组织多细胞类型数据集。
- 通过 CELLxGENE Census 仅拉取面板基因并按类型限制细胞数，或从数据集的 h5ad 分块抽样读取，生成精简参考文件。
- 在共享基因上做联合 PCA，用 Harmony 去除平台效应，再以参考细胞训练分类器迁移标签。
- 以面板自身标志基因核对迁移标签，为每个聚类命名。
- 基于邻域组成识别组织生态位（如肿瘤核心、免疫富集基质）。
- 为空间细胞间通讯分析准备标签。
使用方式
前置条件：输入为 Xenium 输出目录或含原始计数与空间坐标的 .h5ad；需可访问 CELLxGENE Discover API 与 Census（公开、无需密钥）；Python 包需 scanpy、cellxgene-census、harmonypy、scikit-learn，生态位步骤另需 squidpy。仅安装 import 时缺失的包：
pixi add --pypi harmonypy cellxgene-census
pixi add --pypi squidpy
运行前需确认三项决策：组织及状态（健康或具体肿瘤/疾病）；是否有匹配的 scRNA/snRNA-seq 参考，或需检索 CELLxGENE 公共数据；注释路线（参考标签迁移为推荐但较慢；CellTypist 快速但不推荐，因其模型基于全转录组训练，靶向面板上仅重叠基因可用，准确性较低；仅用标志基因命名则无需参考）。可选设定每个细胞最少转录本数，默认 10。
工作流依次为：加载 Xenium 输出并保留 Gene Expression 特征、构建空间坐标；质控与聚类；检索匹配参考；下载抽样的参考数据；用 Harmony 迁移标签；结合标志基因命名；按需计算生态位。参考检索与迁移不保证即时完成，公共参考可能不在 Census 中或耗尽内存；在约 15.4 万细胞上，UMAP 约需 45 秒、Leiden 约 2 分钟，之后才开始 Harmony 与训练。若迁移工具的安装或导入失败，应停止并告知用户错误，再回退到 CellTypist 并说明其局限。
适用场景
- 为 Xenium、MERFISH、CosMx 或 SeqFISH 切片中的细胞类型命名。
- 将已发表 scRNA-seq 图谱标签迁移到靶向基因面板。
- 核验迁移标签是否得到面板自身标志基因支持。
- 依据邻域组成发现肿瘤核心、免疫富集基质等组织生态位。
- 为空间细胞间通讯分析准备细胞标签。
限制
- 不适用于斑点级平台，此类数据应使用反卷积技能。
- 共享基因过少（低于约 100）时标签迁移不可靠。
- 参考必须与组织和状态匹配，否则仍会给每个细胞高置信度错误标签；放宽条件时应先放宽状态再放宽组织，物种不可放宽。
- 公共参考的可用性与下载时间无保证，可能缺失或导致内存不足。
- CellTypist 在靶向面板上准确性较低，其结果需用标志基因核对。
- 分割泄漏会表现为混合聚类与混合迁移标签，此时应报告为分割问题，并考虑仅用细胞核计数或重新分割后再命名亚型。