single-trajectory-analysis

単一軌跡解析スキル

概要

このスキルでは、グラフベースの軌跡推定、RNA velocity の連携、下流の運命スコアリング用ノートブックを組み合わせて、omicverse で単一軌跡解析のワークフローを再現し、拡張する方法を説明します。

軌跡の設定

• PAGA（Partition-based graph abstraction）
  • 前処理済みの AnnData オブジェクトで近傍グラフ（pp.neighbors）を構築します。
  • tl.paga を使ってクラスター間の接続性を計算し、埋め込みには init_pos='paga' を指定して tl.draw_graph または tl.umap を使用します。
  • エッジの重みを解釈して、分岐の解像度調整と開始経路の優先順位を決めます。
• Palantir
  • 手動で選択した開始細胞（例：ナイーブ T 細胞）をシードとして、拡散成分に対して Palantir を実行します。
  • その後のオーバーレイに使用するため、擬似時間、分岐確率、分化ポテンシャルを抽出します。
• 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 には、4 つの velocity バックエンドをラップする統合 Velo クラスが用意されています。基本的な 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 にエクスポートします。
5. 再現性を確保するため、高解像度の図（PNG/SVG）とノートブックの成果物を保存します。
6. 共有前に、一貫した配色とメタデータ列を使うようノートブックを更新します。

防御的な検証パターン

# 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."

トラブルシューティングのヒント

• velocity レイヤーが見つからない：adata.layers['spliced']／['unspliced'] が存在することを確認し、scv.pp.moments と scv.tl.velocity を再実行します。loom/H5AD のインポート時にレイヤーが保持されたことを確認してください。
• PAGA グラフが分断されている：近傍グラフを調べるか、n_neighbors を調整します。バッチ補正によって多様体が断片化されていないことを確認してください。
• Palantir の収束に関する問題：拡散成分を減らすか、開始細胞を再初期化します。データ行列に NaN 値がないことを確認してください。
• VIA の終端状態が安定しない：反復回数（cluster_graph_pruning_iter）を増やすか、マーカー発現に基づく終端状態の手動ヒントを指定します。
• ノートブックのカーネルでメモリエラーが発生する：細胞をダウンサンプリングするか、再実行前に要約（メタセル）を事前計算します。
• latentvelo の ImportError: torchdiffeq：pip install torchdiffeq でインストールします。ニューラル ODE バックエンドに必要です。
• graphvelo が NaN の速度を返す：ベースとなる速度（scvelo/dynamo）が先に計算されていることを確認してください。graphvelo は速度を改良するものであり、ゼロから計算するものではありません。
• dynamo の preprocess が失敗する：dynamo には spliced/unspliced レイヤーが必要です。'spliced' in adata.layers で確認してください。