scvelo

scVelo RNA Velocity

使用するタイミング

スプライシング済み/未スプライシングの 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 環境でテストされました。上記のシェルパスは POSIX 構文を使用しています。パッケージがキャッシュされていない限り、インストールにはネットワーク アクセスが必要です。API キーは不要です。

• 決定論的モデルと動学的モデル: ネイティブの合成フィッティング、グラフ、 相対時間、プロット、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 対応の定量化ツールからスプライシング済みおよび未スプライシングのカウントを取得します。 定量化ツール/バージョン、参照アノテーション、カウントモード、サンプル ID、およびセル バーコードのマッピングを保持してください。上流の定量化は同梱のスクリプトの対象外です。
2. adata.layers['spliced'] と adata.layers['unspliced'] に細胞×遺伝子の行列を提供し、細胞/遺伝子の順序を同一にし、ID を一意にしてください。 カウントは有限かつ非負でなければなりません。小数のカウント推定値は許容されます。 対数変換、スケーリング、残差化、またはバッチ補正された値をカウントとして決して使用しないでください。 数値的な検査だけでは、データが生カウントであることを立証できません。
3. フィッティングの前に、ライブラリ/クラスターごとのカバレッジ、ダブレット、アンビエント RNA、カウントがゼロの細胞、 およびアノテーションの互換性を検査してください。元の全遺伝子 カウントファイルを保存してください。保持された遺伝子のバックアップは、フィルタリングで除外された遺伝子を保存しません。
4. ファイルを結合する際は、バーコードプレフィックスと遺伝子識別子を明示的に 解決してください。ライブラリ ID を暗黙的に削除したり、ほとんどの細胞を交差で除外したり、 重複した生物学的 ID がなぜ繰り返されるのかを理解せずに一意にしたりしないでください。

H5AD は AnnData を通じて読み取ります。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

これらはスキルディレクトリから実行してください。入力ファイル名と生物学的アノテーションは 例示用です。同じ CLI と関数は、小さな生成された反応速度論的フィクスチャでテストされています。 アノテーションが利用できない場合は --groupby を省略してください。UMAP を計算せずに 解析するには --no-plots を使用します。

このヘルパーは次の手順を実行します：

1. レイヤー、ID、モデルの互換性、グループ化を検証します。以前に生成された モーメント／ベロシティを拒否し、前処理が暗黙に二重実行されないようにします。
2. 保持された生レイヤーを spliced_counts と unspliced_counts としてバックアップし、 生の spliced カウントから X を再構築します。遺伝子をフィルタリングし、X と 2 つのカウントレイヤーを線形スケールで正規化します。
3. sc.pp.log1p を X にのみ適用し、Scanpy で高変動遺伝子を選択し、 サブセット化後に PCA と近傍を再構築します。無関係な特徴量セットから古い PCA／近傍を 再利用すると、ベロシティモデルが暗黙に変わり得ます。
4. 明示的な Scanpy グラフから scv.pp.moments(adata, n_neighbors=None) で Ms と Mu を計算します。モーメントは密なので、スパースな入力だけでなく 複数の細胞×遺伝子配列のためにメモリを見積もってください。
5. 動的モードでは、velocity(mode='dynamical') の前に選択した遺伝子に対して recover_dynamics(var_names='all') を呼び出します。それ以外の場合は選択したモデルを フィッティングします。使用可能な遺伝子と空でないベロシティグラフを必須とします。
6. ベロシティコヒーレンスとベロシティ疑似時間を計算します。潜在時間は動的フィッティングの 場合にのみ追加します。ベロシティ関連遺伝子のランキングは、少なくとも 2 つのグループと グループごとに少なくとも 2 つの細胞がある場合にのみ行います。非有限または一定の 時間／コヒーレンス出力は uns['velocity_workflow']['diagnostics'] に記録／警告します。 一定の疑似時間はトラジェクトリの順序付けを支持しません。ランキングは探索的です。
7. プロットについては、再構築されたグラフから UMAP を再計算し、ベロシティを投影し、 PNG を要求されたディレクトリに直接保存し、次にパッケージバージョンと選択した パラメータとともに H5AD を保存します。既存のラベルはアノテーションのままであり、 検証済みの細胞アイデンティティではありません。

Python 関数は引数をインプレースで変更します。元のオブジェクトを保持するには adata.copy() を渡してください。CLI は output_dir/adata_velocity.h5ad に書き込みます。 バージョン 2 は以前のヘルパーの動作を意図的に変更しています：生レイヤーのジオメトリが 再構築され、要求されたラベルが欠落している場合はエラーとなり、プロット／並列処理を 明示的に制御できます。実行時間は細胞数、遺伝子数、フィッティングの難易度に依存します。 普遍的な 10〜30 分という想定はありません。

解釈の前にエビデンスを調べる

動的実行の後（データセット固有の遺伝子選択は例示用です）：

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 のフィット、分岐固有の反応速度論を調べます。遺伝子セット、 近傍、サブサンプリング、モデルの仮定に対する感度を確認します。利用可能な場合は、 タイムコースラベル、摂動、系統追跡、または標識実験を独立した方向性のエビデンスとして 使用します。もっともらしい UMAP だけではフィットを検証できず、矢印が望むストーリーに 一致するまでチューニングすることは検証戦略ではありません。

一般的な最小 2,000 細胞、普遍的な unspliced 比率、またはルート細胞が最高の unspliced/spliced 比を持たなければならないという規則はありません。関連する反応速度論的 状態のカバレッジと測定品質が重要です。負のベロシティは抑制またはモデルの誤指定を 表す可能性があり、それ自体がレイヤーが入れ替わった証拠ではありません。

出力の解釈

フィールド	解釈
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 分析はソースレビューのみの、例示的な拡張です。認証済みのリモートサービスは使用していません。