scvi-tools

scvi-tools

概要

scvi-tools は、シングルセルゲノミクスにおける確率モデルのための包括的な Python フレームワークです。PyTorch および PyTorch Lightning 上に構築されており、多様なシングルセルデータモダリティを解析するために、変分推論を用いた深層生成モデルを提供します。

このスキルを使用するタイミング

次のような場合にこのスキルを使用してください:

• シングルセル RNA-seq データの解析（次元削減、バッチ補正、インテグレーション）
• シングルセル ATAC-seq またはクロマチンアクセシビリティデータの扱い
• マルチモーダルデータのインテグレーション（CITE-seq、マルチオーム、ペア/非ペアのデータセット）
• 空間トランスクリプトミクスデータの解析（デコンボリューション、空間マッピング）
• シングルセルデータに対する差次的発現解析の実施
• 細胞種アノテーションまたは転移学習タスクの実施
• 特殊なシングルセルモダリティ（メチル化、サイトメトリー、RNA velocity）の扱い
• シングルセル解析のためのカスタム確率モデルの構築

中核機能

scvi-tools は、データモダリティごとに整理されたモデルを提供します:

1. シングルセル RNA-seq 解析

発現解析、バッチ補正、インテグレーションのための中核モデルです。以下については references/models-scrna-seq.md を参照してください:

• scVI: 教師なし次元削減とバッチ補正
• scANVI: 半教師あり細胞種アノテーションとインテグレーション
• AUTOZI: ゼロ過剰の検出とモデル化
• VeloVI: RNA velocity 解析
• contrastiveVI: 摂動効果の分離

2. クロマチンアクセシビリティ（ATAC-seq）

シングルセルクロマチンデータを解析するためのモデルです。以下については references/models-atac-seq.md を参照してください:

• PeakVI: ピークベースの ATAC-seq 解析とインテグレーション
• PoissonVI: 定量的なフラグメントカウントのモデル化
• scBasset: モチーフ解析を伴う深層学習アプローチ

3. マルチモーダル・マルチオミクスのインテグレーション

複数のデータタイプの統合解析です。以下については references/models-multimodal.md を参照してください:

• totalVI: CITE-seq におけるタンパク質と RNA の同時モデル化
• MultiVI: ペアおよび非ペアのマルチオミクスインテグレーション
• MrVI: 多解像度のサンプル横断解析

4. 空間トランスクリプトミクス

空間的に解像されたトランスクリプトミクスの解析です。以下については references/models-spatial.md を参照してください:

• DestVI: 多解像度の空間デコンボリューション
• Stereoscope: 細胞種デコンボリューション
• Tangram: 空間マッピングとインテグレーション
• scVIVA: 細胞と周辺環境の関係解析

5. 特殊なモダリティ

追加の特殊な解析ツールです。以下については references/models-specialized.md を参照してください:

• MethylVI/MethylANVI: シングルセルのメチル化解析
• CytoVI: フロー/マスサイトメトリーのバッチ補正
• Solo: ダブレット検出
• CellAssign: マーカーベースの細胞種アノテーション

典型的なワークフロー

すべての scvi-tools モデルは、一貫した API パターンに従います:

# 1. Load and preprocess data (AnnData format)
import scvi
import scanpy as sc

adata = scvi.data.heart_cell_atlas_subsampled()
sc.pp.filter_genes(adata, min_counts=3)
sc.pp.highly_variable_genes(adata, n_top_genes=1200)

# 2. Register data with model (specify layers, covariates)
scvi.model.SCVI.setup_anndata(
    adata,
    layer="counts",  # Use raw counts, not log-normalized
    batch_key="batch",
    categorical_covariate_keys=["donor"],
    continuous_covariate_keys=["percent_mito"]
)

# 3. Create and train model
model = scvi.model.SCVI(adata)
model.train()

# 4. Extract latent representations and normalized values
latent = model.get_latent_representation()
normalized = model.get_normalized_expression(library_size=1e4)

# 5. Store in AnnData for downstream analysis
adata.obsm["X_scVI"] = latent
adata.layers["scvi_normalized"] = normalized

# 6. Downstream analysis with scanpy
sc.pp.neighbors(adata, use_rep="X_scVI")
sc.tl.umap(adata)
sc.tl.leiden(adata)

主要な設計原則:

• 生カウントが必須: モデルは最適な性能を得るために、正規化されていないカウントデータを想定しています
• 統一された API: すべてのモデルで一貫したインターフェース（セットアップ → 学習 → 抽出）
• AnnData 中心: scanpy エコシステムとのシームレスな統合
• GPU アクセラレーション: 利用可能な GPU の自動利用
• バッチ補正: 共変量の登録を通じて技術的変動に対処

よくある解析タスク

差次的発現解析

学習済みの生成モデルを用いた確率的な DE 解析です:

de_results = model.differential_expression(
    groupby="cell_type",
    group1="TypeA",
    group2="TypeB",
    mode="change",  # Use composite hypothesis testing
    delta=0.25      # Minimum effect size threshold
)

詳細な方法論と解釈については references/differential-expression.md を参照してください。

モデルの永続化

学習済みモデルの保存と読み込みです:

# Save model
model.save("./model_directory", overwrite=True)

# Load model
model = scvi.model.SCVI.load("./model_directory", adata=adata)

バッチ補正とインテグレーション

複数のバッチや研究をまたいでデータセットを統合します:

# Register batch information
scvi.model.SCVI.setup_anndata(adata, batch_key="study")

# Model automatically learns batch-corrected representations
model = scvi.model.SCVI(adata)
model.train()
latent = model.get_latent_representation()  # Batch-corrected

理論的基礎

scvi-tools は次の要素に基づいて構築されています。

• 変分推論: スケーラブルなベイズ推論のための近似事後分布
• 深層生成モデル: 複雑なデータ分布を学習する VAE アーキテクチャ
• 償却推論: 細胞間で効率的に学習するための共有ニューラルネットワーク
• 確率モデリング: 原理に基づく不確実性の定量化と統計的検定

数学的枠組みの詳細な背景については、references/theoretical-foundations.md を参照してください。

追加リソース

• ワークフロー: references/workflows.md には、一般的なワークフロー、ベストプラクティス、ハイパーパラメータのチューニング、GPU の最適化が含まれています
• モデルリファレンス: references/ ディレクトリには、モデルカテゴリごとの詳細なドキュメントがあります
• 公式ドキュメント: https://docs.scvi-tools.org/en/stable/
• チュートリアル: https://docs.scvi-tools.org/en/stable/tutorials/index.html
• API リファレンス: https://docs.scvi-tools.org/en/stable/api/index.html

インストール

uv pip install scvi-tools
# For GPU support
uv pip install scvi-tools[cuda]

ベストプラクティス

1. 生のカウントデータを使用する: モデルには必ず正規化されていないカウントデータを渡してください
2. 遺伝子をフィルタリングする: 解析の前に、低カウントの遺伝子を除去してください（例: min_counts=3）
3. 共変量を登録する: 既知の技術的因子（バッチ、ドナーなど）を setup_anndata に含めてください
4. 特徴量の選択: 性能向上のために高変動遺伝子を使用してください
5. モデルの保存: 再学習を避けるため、学習済みモデルは必ず保存してください
6. GPU の利用: 大規模データセットでは GPU アクセラレーションを有効にしてください（accelerator="gpu"）
7. Scanpy との連携: 後続の解析のため、出力は AnnData オブジェクトに格納してください