single-trajectory-analysis

单轨迹分析技能

概述

本技能介绍如何在 omicverse 中复现和扩展单轨迹分析工作流，结合基于图的轨迹推断、RNA velocity 耦合和下游命运评分笔记本。

轨迹设置

• PAGA（基于分区的图抽象）
  • 在预处理后的 AnnData 对象上构建邻域图（pp.neighbors）。
  • 使用 tl.paga 计算簇间连通性，并使用 tl.draw_graph 或 tl.umap（设置 init_pos='paga'）进行嵌入。
  • 解读边权重，以优先确定分支解析和种子路径。
• Palantir
  • 在扩散成分上运行 Palantir，并使用手动选择的起始细胞（例如初始 T 细胞）作为种子。
  • 提取伪时间、分支概率和分化潜能，以便后续叠加分析。
• VIA
  • 在 kNN 图上执行 via.VIA，通过自动选择根节点或用户指定根节点来识别谱系进程。
  • 导出终末状态和伪时间，与 PAGA 和 Palantir 结果进行交叉验证。

Velocity 耦合（VIA + scVelo）

• 使用 scv.pp.filter_and_normalize、scv.pp.moments 和 scv.tl.velocity 生成 velocity 层。
• 将 adata.layers['velocity'] 提供给 VIA，以优化谱系方向性（via.VIA(..., velocity_weight=...)）。
• 将 VIA 伪时间与 scVelo 潜在时间（scv.tl.latent_time）进行比较，以验证方向性和根节点选择。

高级 RNA Velocity 后端（ov.single.Velo）

OmicVerse 提供统一的 Velo 类，封装了 4 种 velocity 后端。需要超越基础 scVelo 功能时可使用：

后端选择指南

后端	最适用场景	GPU？	前提条件
scvelo	标准 velocity 分析	否	spliced/unspliced 层
dynamo	动力学建模、向量场	否	spliced/unspliced 层
latentvelo	基于 VAE、批次校正、复杂动力学	是（torchdiffeq）	celltype_key，batch_key 可选
graphvelo	在任意后端之上进行精修	否	基础 velocity + connectivities

统一的 Velo 流程

import omicverse as ov

velo = ov.single.Velo(adata)

# 1. Filter (scvelo backend) or preprocess (dynamo backend)
velo.filter_genes(min_shared_counts=20)     # For scvelo
# velo.preprocess(recipe='monocle', n_neighbors=30, n_pcs=30)  # For dynamo

# 2. Compute moments
velo.moments(backend='scvelo', n_pcs=30, n_neighbors=30)
# backend: 'scvelo' or 'dynamo'

# 3. Fit kinetic parameters
velo.dynamics(backend='scvelo')

# 4. Calculate velocity
velo.cal_velocity(method='scvelo')
# method: 'scvelo', 'dynamo', 'latentvelo', 'graphvelo'

# 5. Build velocity graph and project to embedding
velo.velocity_graph(basis='umap')
velo.velocity_embedding(basis='umap')

latentvelo 详情（深度学习 velocity）

latentvelo 使用 VAE + 神经 ODE 学习潜在动力学。与传统 scVelo 相比，它能更好地处理批次效应和复杂轨迹：

velo.cal_velocity(
    method='latentvelo',
    celltype_key='cell_type',    # Optional: AnnotVAE uses cell type info
    batch_key='batch',           # Optional: batch correction
    velocity_key='velocity_S',
    n_top_genes=2000,
    latentvelo_VAE_kwargs={},    # Pass custom VAE hyperparameters
)
# Requires: pip install torchdiffeq
# Uses GPU if available, falls back to CPU

graphvelo 详情（精修层）

GraphVelo 利用细胞图结构，优化任意基础方法得出的 velocity 估计值。在 scvelo 或 dynamo 之后运行：

# First: compute base velocity with scvelo or dynamo
velo.cal_velocity(method='scvelo')

# Then: refine with graphvelo
velo.graphvelo(
    xkey='Ms',                          # Spliced moments key
    vkey='velocity_S',                  # Base velocity key to refine
    basis_keys=['X_umap', 'X_pca'],    # Project to multiple embeddings
    gene_subset=None,                   # Optional: restrict to gene subset
)

下游命运评分笔记本

• CellFateGenie：要发现与伪时间相关的基因，请使用 search_skills('CellFateGenie fate genes') 加载专用的 CellFateGenie 技能。
• t_metacells.ipynb：汇总元细胞轨迹，用于稳健性检查和元状态差异表达分析。

所需的预处理

1. 质量控制：移除低质量细胞/基因，并进行双细胞过滤。
2. 归一化和对数转换（sc.pp.normalize_total、sc.pp.log1p）。
3. 针对免疫数据集选择高变基因（sc.pp.highly_variable_genes）。
4. 必要时进行批次校正（例如 scvi-tools、bbknn）。
5. 计算所有轨迹方法共用的 PCA、邻域图和嵌入（UMAP/FA）。
6. 对于 velocity，在运行 VIA 耦合前，基于同一邻域图计算矩。

参数调优

• 应在 PAGA、VIA 和 Palantir 之间统一邻域图参数 n_neighbors 和 n_pcs，以保持一致性。
• 对于 VIA，可针对采样不均的数据集调整 knn、too_big_factor 和 root_user。
• Palantir 需要谨慎选择起始细胞；请使用标记基因和 velocity 箭头进行确认。
• 对于 PAGA，调整 threshold 以控制边的稀疏度；确保连通分量反映生物学分支。
• Velocity 估计：比较 scVelo 中的 mode='stochastic' 和 mode='dynamical'；如果终末状态与 VIA 不一致，则重新校准。

可视化与导出

1. 在 UMAP 上叠加 PAGA 边（scv.pl.paga），并标注分支标签。
2. 在嵌入图上绘制 Palantir 拟时序和分支概率。
3. 使用 via.plot_fates 和 via.plot_scatter 可视化 VIA 轨迹。
4. 将拟时序表和命运概率导出为 CSV，供下游 Notebook 使用。
5. 保存高分辨率图（PNG/SVG）和 Notebook 产物，以便复现。
6. 分享前，使用一致的配色方案和元数据列更新 Notebook。

防御性验证模式

# Before PAGA: verify neighbor graph exists
assert 'neighbors' in adata.uns, "Neighbor graph required. Run sc.pp.neighbors(adata) first."

# Before VIA velocity coupling: verify velocity layers exist
if 'velocity' not in adata.layers:
    print("WARNING: velocity layer missing. Run scv.tl.velocity(adata) first for VIA coupling.")
assert 'spliced' in adata.layers and 'unspliced' in adata.layers, \
    "Missing spliced/unspliced layers. Check loom/H5AD import preserved velocity layers."

# Before Palantir: verify PCA/diffusion components
assert 'X_pca' in adata.obsm, "PCA required. Run ov.pp.pca(adata) first."

故障排除提示

• 缺少速度层：重新运行 scv.pp.moments 和 scv.tl.velocity，确保存在 adata.layers['spliced']/['unspliced']；验证 loom/H5AD 导入时保留了这些层。
• PAGA 图不连通：检查邻居图或调整 n_neighbors；确认批次校正没有将流形分割开。
• Palantir 收敛问题：减少扩散分量，或重新初始化起始细胞；确保数据矩阵中没有 NaN 值。
• VIA 终末状态不稳定：增加迭代次数（cluster_graph_pruning_iter），或根据标记物表达提供手动终末状态提示。
• Notebook 内核内存错误：对细胞进行下采样，或在重新运行前预计算汇总数据（metacells）。
• latentvelo ImportError: torchdiffeq：使用 pip install torchdiffeq 安装。神经 ODE 后端需要此依赖。
• graphvelo 返回 NaN 速度：确保已先计算基础速度（scvelo/dynamo）。graphvelo 用于细化速度，不会从头开始计算。
• dynamo preprocess 失败：dynamo 需要 spliced/unspliced 层。使用 'spliced' in adata.layers 验证。