alterlab-scvi-tools

scvi-tools

概要

scvi-tools は、単一細胞ゲノミクスの確率モデルに対応する包括的な Python フレームワークです。PyTorch と PyTorch Lightning を基盤としており、変分推論を用いた深層生成モデルにより、多様な単一細胞データモダリティを解析できます。

このスキルを使用する場面

次の場合にこのスキルを使用します。

• 単一細胞 RNA-seq データを解析する場合（次元削減、バッチ補正、統合）
• 単一細胞 ATAC-seq またはクロマチンアクセシビリティデータを扱う場合
• マルチモーダルデータを統合する場合（CITE-seq、multiome、ペア／非ペアのデータセット）
• 空間トランスクリプトミクスデータを解析する場合（デコンボリューション、空間マッピング）
• 単一細胞データの差次的発現解析を行う場合
• 細胞型アノテーションまたは転移学習タスクを実施する場合
• 特殊な単一細胞モダリティを扱う場合（メチル化、サイトメトリー、RNA 速度）
• 単一細胞解析用のカスタム確率モデルを構築する場合

対象外

シナリオ	代わりに使用
標準的な QC → 正規化 → HVG → PCA → UMAP → Leiden → マーカー DE	alterlab-scanpy
.h5ad オブジェクト自体の読み込み、整形、または連結	alterlab-anndata
事前学習済み基盤モデルによるゼロショットアノテーションまたは埋め込み	alterlab-scgpt
スプライス済み／未スプライスカウントからの RNA 速度（scVelo の EM／動的モデル）	alterlab-scvelo
Visium／Xenium スライド上の空間近傍統計、Moran's I、リガンド・受容体解析	alterlab-squidpy-spatial
バルク RNA-seq の差次的発現解析	alterlab-pydeseq2

主な機能

scvi-tools は、データモダリティ別にモデルを提供しています。

1. 単一細胞 RNA-seq 解析

発現解析、バッチ補正、統合のための主要モデルです。以下については references/models-scrna-seq.md を参照してください。

• scVI：教師なし次元削減とバッチ補正
• scANVI：半教師ありの細胞型アノテーションと統合
• AUTOZI：ゼロ過剰の検出とモデリング
• VeloVI：RNA 速度解析
• 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_results = model.differential_expression(
    groupby="cell_type",
    group1="TypeA",
    group2="TypeB",
    mode="change",  # composite hypothesis testing with an effect-size threshold
    delta=0.25,     # minimum |LFC| to count as a real change
)

# Significance lives in proba_de (posterior prob. of DE), NOT a p-value.
# In "change" mode this is the posterior prob. that |LFC| > delta.
sig = de_results[de_results["proba_de"] > 0.95]

出力スキーマ全体と解釈については 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
uv pip install "scvi-tools[cuda]"      # CUDA 12; use [cuda13] for CUDA 13
uv pip install "scvi-tools[metal]"     # Apple silicon (MPS)
uv pip install "scvi-tools[autotune]"  # hyperparameter search (Ray Tune)

バージョンに関する注記（2026-09）：scvi-tools 1.5 では JAX バックエンドが完全に廃止されたため、scvi.model.JaxSCVI および Jax で始まるその他のモデルは利用できなくなりました。すべて PyTorch/Lightning で実行されます（Apple シリコン向けの mlxSCVI バリアントもあります）。Tangram も 1.5.0 で PyTorch バックエンドに移行したため、 JAX 時代の実行結果とはわずかに異なる場合があります。1 つの比較で古い結果と新しい結果を混在させず、 再実行してください。

ベストプラクティス

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