scvelo

scVelo RNA Velocity

何时使用

用于对已比对的 spliced/unspliced RNA 计数进行动力学分析、方向性轨迹假设、基因水平相图以及动力学潜在时间。有关假设、转移概率以及可选的 CellRank 交接，请参阅模型参考。

RNA velocity 在某个模型下估计表达导数。平滑的箭头并不是观测到的细胞移动、谱系追踪、因果驱动因素，或对未来命运的证明。动力学估计器并不自动比稳态估计器在任何数据集上都更准确。

测试环境与兼容性

所维护的工作流面向 Python 3.13 上的 scVelo 0.3.4、Scanpy 1.12.4、AnnData 0.13.4、NumPy 2.5.3、pandas 2.3.3、SciPy 1.18.1、Matplotlib 3.11.2 和 loompy 3.0.8。请使用隔离环境：

uv venv --python 3.13 .venv-velocity
uv pip install --python .venv-velocity/bin/python \
  scvelo==0.3.4 scanpy==1.12.4 anndata==0.13.4 numpy==2.5.3 \
  pandas==2.3.3 scipy==1.18.1 matplotlib==3.11.2 loompy==3.0.8

上述包从缓存解析，并在隔离的 uv 环境中进行了测试；上述 shell 路径使用 POSIX 语法。除非包已缓存，否则安装需要网络访问。不需要 API key。

• 确定性模型与动力学模型： 原生合成拟合、图、相对时间、绘图以及 H5AD 往返在此技术栈上经过测试。
• 随机模型： scVelo 0.3.4 的默认 GLS 标量分配在 NumPy 2 下失败。Scanpy 1.12 需要 NumPy 2，因此在当前 Scanpy 旁边安装 numpy<2 并不是解决方案。需要单独验证过的旧版 Scanpy/NumPy 环境；该旧版技术栈未在本次评审中执行。辅助程序会在修改数据之前拒绝此组合，且不会更改模型。
• pandas 3: scVelo 0.3.4 的动力学拟合和部分绘图使用了 pandas 3 不再支持的操作。请保留显式的 pandas 版本固定。
• 上游稳定教程仍包含已移除的 scv.read 和较旧的前处理调用。当教程与已安装的 API 不一致时，请查看 0.3.4 源码。

输入约定

1. 从支持 velocity 的定量工具获取 spliced 和 unspliced 计数。保留定量工具/版本、参考注释、计数模式、样本 ID 和细胞 barcode 映射。上游定量不在捆绑脚本的范围内。
2. 在 adata.layers['spliced'] 和 adata.layers['unspliced'] 中提供 细胞 × 基因 矩阵，并确保细胞/基因顺序完全一致且 ID 唯一。计数必须是有限且非负的；允许分数计数估计值。切勿将取对数、缩放、残差化或批次校正后的值用作计数。仅靠数值检查无法确定数据是否为原始数据。
3. 在拟合之前，检查每个文库/簇的覆盖率、双细胞、环境 RNA、零计数细胞以及注释兼容性。保留原始的全基因计数文件。保留基因的备份不会保留被过滤掉的基因。
4. 在合并文件时，显式解决 barcode 前缀和基因标识符问题。不要静默剥离文库 ID、通过取交集去除大部分细胞，或在未理解重复原因的情况下将重复的生物学 ID 变为唯一。

通过 AnnData 读取 H5AD。scVelo 0.3.4 没有 scv.read 或 scv.DataFrame：

import anndata as ad
adata = ad.read_h5ad("velocity_counts.h5ad")

对于旧版 loom 输入，请使用 ad.io.read_loom('counts.loom', X_name='spliced', sparse=True)。AnnData 0.13 弃用 loom；请转换为 H5AD 以便进一步处理。其 layers[None] 是 X 的别名：不要删除它，也不要像每个键都是字符串那样遍历所有层。辅助程序仅访问命名的 velocity 层。原生 loom 读取以及精确、重排序的元数据对齐已由测试覆盖；AnnData 0.13 的 write_loom 未使用。

运行维护好的工作流

随附脚本 接受本地文件，启动时绝不会下载演示数据集：

MPLBACKEND=Agg .venv-velocity/bin/python scripts/rna_velocity_workflow.py \
  velocity_counts.h5ad --mode dynamical --groupby clusters \
  --n-top-genes 2000 --n-neighbors 30 --n-jobs 1 --output-dir velocity_results

# Import a loom and align its raw counts to an existing annotation file:
MPLBACKEND=Agg .venv-velocity/bin/python scripts/rna_velocity_workflow.py \
  counts.loom --processed-h5ad annotated.h5ad --groupby clusters \
  --mode deterministic --output-dir velocity_check

请从 skill 目录运行这些命令。输入文件名和生物学注释仅为示例；相同的命令行和函数已在小型生成的动力学测试数据上验证。当注释不可用时，省略 --groupby。使用 --no-plots 可在不计算 UMAP 的情况下进行分析。

该辅助脚本执行以下步骤：

1. 校验层、ID、模型兼容性和分组；拒绝先前已生成的 moments/velocity，以免预处理在不知不觉中运行两次。
2. 将保留的原始层备份为 spliced_counts 和 unspliced_counts，并从原始 spliced counts 重建 X。过滤基因，并在线性尺度上对 X 和两个 count 层进行归一化。
3. 仅对 X 应用 sc.pp.log1p，用 Scanpy 选择高变基因，并在取子集后重建 PCA 和 neighbors。复用来自无关特征集的陈旧 PCA/neighbors 可能会在不知不觉中改变 velocity 模型。
4. 使用 scv.pp.moments(adata, n_neighbors=None) 从显式 Scanpy 图计算 Ms 和 Mu。Moments 是稠密的：要为多个 cells-by-genes 数组预留内存，而不只是稀疏输入。
5. 对于 dynamical 模式，在 velocity(mode='dynamical') 之前对所选基因调用 recover_dynamics(var_names='all')；否则拟合所选模型。要求有可用的基因和非空的 velocity 图。
6. 计算 velocity coherence 和 velocity pseudotime；仅对 dynamical 拟合添加 latent time。仅在至少有 2 个分组且每组至少有 2 个细胞时，才对 velocity 相关基因进行排序。在 uns['velocity_workflow']['diagnostics'] 中记录/警告非有限或恒定的 time/coherence 输出；恒定的 pseudotime 不支持轨迹排序。排序结果是探索性的。
7. 对于绘图，从重建的图重新计算 UMAP，投影 velocity，将 PNG 直接保存到请求的目录，然后保存带包版本和所选参数的 H5AD。现有标签仍然是注释，而非经过验证的细胞身份。

Python 函数会原地修改其参数；传入 adata.copy() 以保留原始对象。命令行会写入 output_dir/adata_velocity.h5ad。版本 2 有意改变了先前辅助脚本的行为：原始层几何被重建，缺失所请求的标签会报错，绘图/并行可以显式控制。运行时间取决于细胞数、基因数和拟合难度；不存在通用的 10–30 分钟预期。

在解释之前先检查证据

在 dynamical 运行之后（数据集特定的基因选择仅为示例）：

import pandas as pd
import scvelo as scv

# Candidate kinetic genes, not experimentally established drivers.
candidates = adata.var['fit_likelihood'].dropna().nlargest(6).index.tolist()
scv.pl.velocity(adata, var_names=candidates, basis='umap', show=False)

# This ranks group-associated velocities, not causal influence or condition DE.
scv.tl.rank_velocity_genes(adata, groupby='clusters', min_corr=0.3)
ranked = pd.DataFrame(adata.uns['rank_velocity_genes']['names'])

scv.tl.velocity_confidence(adata)
scv.pl.scatter(adata, color=['velocity_length', 'velocity_confidence'], show=False)

检查 spliced 与 unspliced 的相图、诱导和抑制过程中的覆盖度、拟合参数、失败/NaN 拟合，以及分支特异性动力学。检查对基因集、neighbors、子采样和模型假设的敏感性。在有条件时，使用时间序列标签、扰动、谱系追踪或标记实验作为独立的方向性证据。仅凭一个看似合理的 UMAP 无法验证拟合，而不断调参直到箭头与期望的故事相符也不是验证策略。

并不存在通用的 2,000 个细胞下限、通用的 unspliced 比例，或根细胞必须具有最高 unspliced/spliced 比值的规则。关键动力学状态的覆盖度和测量质量才是重要的。负 velocity 可能代表抑制或模型设定错误；它本身并不是层被交换的证据。

输出解读

字段	解读
layers['velocity']	处理后的基因表达空间中模型估计的导数
var['velocity_genes']	为速度图选择的基因；区别于所有 HVG
layers['Ms']、layers['Mu']	邻域平均的线性尺度已剪接/未剪接表达
layers['fit_t']	基因特异性拟合时间坐标，仅限动力学模型
var['fit_alpha/beta/gamma']	在模型推断尺度上拟合的速率；并非校准的物理速率
var['fit_likelihood']	相对模型拟合诊断指标；并非生物学真相的后验概率
uns['velocity_graph']	候选转换的稀疏正余弦相关性；并非行随机
obsm['velocity_umap']	投影向量，仅在嵌入计算/绘图之后
obs['velocity_pseudotime']	基于图的相对排序
obs['latent_time']	耦合动力学排序；通常缩放至 0–1，并非经过的小时数
obs['velocity_length']	处理后空间中的向量模长；并非物理细胞速度
obs['velocity_confidence']	邻域速度一致性，并非校准的不确定性

对于命运概率，请使用显式归一化的转移核和经过验证的终态定义；参见参考中的可选 CellRank 示例。PAGA 需要可选的 igraph 和兼容的 Scanpy 内部实现；它不属于经过测试的核心工作流，也不能替代命运推断。

故障排除

问题	操作
层缺失或不匹配	重新检查定量和显式 ID 对齐；X 不能替代未剪接计数
速度基因极少	在更改阈值之前检查深度、状态覆盖和相位图
箭头平滑但不合理	检查模型假设、批次几何结构和单个基因；比较独立证据
拟合非有限或图为空	停止解读并调查退化特征/覆盖
内存或拟合时间过多	使用有依据的基因集和 n_jobs=1；考虑稠密矩和拟合数组
NumPy 2 上的随机失败	使用单独验证过的兼容旧版技术栈，或明确重新考虑模型
拟合/绘图中的 pandas unique 错误	使用经过测试的 pandas 2.3.3 固定版本

来源与验证范围

2026-10-01 对照已发布源码、API、动力学模型注意事项和 AnnData loom 读取器进行了审核。主要论文为 Bergen et al., 2020。合成执行测试验证软件契约和文件/图形生成；它们并不确立生物学准确性、可识别性或数据集特定的参数恢复。可选的 CellRank/PAGA 分析仍为经来源审核的示例性扩展。未使用经过身份验证的远程服务。