trajectory-inference

用途

该技能沿分化或激活路径对细胞排序，并估计每个细胞的走向。它在单细胞转录组和空间转录组数据上工作，输出伪时间、速率流、终末状态与命运概率；在空间数据上还可把这些结果映射到组织切片，并检验排序是否与空间位置一致。

主要能力

流程分三层，每层都可以在前一层的基础上选择是否使用：

PAGA + DPT：需要聚类、邻接图和指定的根簇，输出簇间连接图和伪时间。
scVelo：需要 layers["spliced"] 与 layers["unspliced"]，输出每个细胞的变化方向（RNA 速率）。
CellRank 2：需要转移核（速率核或伪时间核），输出终末状态、命运概率和驱动基因。

spliced/unspliced 计数可由 velocyto、STARsolo（--soloFeatures Gene Velocyto）或 kallisto|bustools 从 reads 生成；Visium 与 Slide-seq 可在 Space Ranger 或流水线 BAM 上生成。Xenium、MERFISH、CosMx 等成像平台只计数探针、不计数内含子，因此无法计算速率。

适用场景

从选定的起点出发，沿分化或激活路径给细胞排序
依据 spliced/unspliced 计数估计细胞走向（RNA 速率）
寻找终末状态、命运概率及驱动各命运走向的基因
检查发育或激活排序是否在组织空间中体现出来
寻找沿推断路径变化的基因

若只需在标准 scRNA-seq 流程中得到一次快速的 PAGA 图，应改用 scanpy-scrna-seq；若关注的是组织区域而非细胞状态路径，应使用 spatial-domain-detection。

前提条件

输入：原始计数，以及一个聚类或细胞类型列；计算速率时还需上述两个层
空间数据：第 6 步需要 obsm["spatial"] 中的坐标
Python 包：scvelo、cellrank（CellRank 2.x 要求 Python >= 3.12；CPU 即可）

安装命令：

# Install only what `import` reports missing. `--pypi` keeps the env's scanpy/numba
# stack; a conda add can swap it and bare pip can shadow it.
pixi add --pypi scvelo cellrank scanpy

使用方式

工作流程共六步：

加载数据并检查层：读取 h5ad，确认是否存在 spliced、unspliced 层及空间坐标。
预处理与建立邻接图：有速率层时按 scVelo 顺序过滤基因、按细胞归一化，再对所有层取 log；无速率层时仅做 scanpy 归一化。随后计算高变基因、PCA、邻接图和 UMAP。
PAGA 与扩散伪时间：根簇是生物学选择（祖细胞、naive 状态等），不明显时应询问用户。根细胞取根簇中扩散成分 1 的极值细胞，而非簇内第一个细胞（后者会整体平移伪时间）。若各簇中位伪时间不符合预期顺序，说明根或聚类有误；DPT 本身不是对顺序的检验。
RNA 速率（scVelo）：MODE 可选 "stochastic" 或更慢但能给出 latent time 的 "dynamical"。簇内 velocity_confidence 低于约 0.5 说明其箭头是噪声，应如实说明而不是强行解读；速率基因少于约 100 个通常意味着 unspliced reads 过少。
终末状态与命运概率（CellRank 2）：有速率层时融合速率核与连接核（默认 0.8/0.2，连接项用于抑制速率噪声），否则使用伪时间核。通过 GPCCA 寻找宏观状态、预测终末状态、计算命运概率和谱系驱动基因。终末状态应是用户认可的终点；若漏掉已知终点，可调整 N_STATES 或按名称手工设定。
在组织上映射伪时间与命运：用 6 近邻图计算 Moran's I，接近 0 表示排序未在空间中体现。将 obsm["spatial"] 复制到 obsm["X_spatial"] 后可在组织坐标上绘制速率流；这只是把转录方向画在空间上，并非物理细胞迁移。

关键参数

ROOT_GROUP：伪时间起点，选错会翻转整个排序
n_neighbors（第 2 步，默认 30）：PAGA、DPT、moments 与 CellRank 共用的图
min_shared_counts（默认 20）：spliced+unspliced 计数的基因过滤
MODE（默认 "stochastic"）："dynamical" 逐基因拟合动力学、额外给出 latent time，约慢 10 倍
核权重：0.8 速率 / 0.2 连接；连接权重越高越平滑、方向性越弱
N_STATES（默认 8）：搜索终末状态所用的宏观状态数
PAGA 阈值（默认 0.05）：低于该连接度的边在图中隐藏

常用配方

沿伪时间变化的基因：用 Spearman 相关对基因排序，取正负各前 15 个，按伪时间顺序画热图
单一空间域内的轨迹：全局图可能连接无关区域，先限定到一个域（来自 spatial-domain-detection）再重算
伪时间是否随到某标志点的距离变化：对带空间轴的组织，将伪时间与到最近标志点细胞的距离做 Spearman 相关；细胞数达数千时 p 值总是极小，应看 r 值和空间图

预期输出

paga_adjacency.csv（簇间 PAGA 连接度）、fate_probabilities.csv（每个细胞到达各终末状态的概率）、lineage_drivers.csv（与各命运相关的基因）、trajectory_result.h5ad（伪时间、速率层、term_states_fwd、lineages_fwd）、figures/（PAGA 图、伪时间 UMAP、速率流）、trajectory_spatial.png（组织上的伪时间与命运图）、pseudotime_genes.csv（与伪时间最相关的基因）。

限制与排错

缺少 spliced 层：需在 BAM 上运行 velocyto / STARsolo Velocyto，或改用伪时间核走第 3、5 步
箭头从成熟细胞指向祖细胞：可能违反稳态假设、unspliced reads 过少或存在批次效应，可尝试 MODE="dynamical"、检查 velocity_confidence、分批分析
部分细胞 dpt_pseudotime 为 inf：图不连通，应取连通谱系的子集或增大 n_neighbors
predict_terminal_states 返回为空或过多：调整 N_STATES 或手工设定状态
成像平台无法计算速率；空间速率流绘制失败时需确认 X_spatial 已复制

参考：PAGA（Wolf 等，2019）、扩散伪时间（Haghverdi 等，2016）、scVelo（Bergen 等，2020）、CellRank 2（Weiler 等，2024）。