scvi-tools

scvi-tools

概要

scvi-tools は、シングルセルゲノミクスの確率モデル向けの包括的な Python フレームワークです。PyTorch と PyTorch Lightning を基盤とし、変分推論を用いた深層生成モデルにより、多様なシングルセルデータモダリティを解析できます。現在の安定版リリース：scvi-tools 1.4.3（2026年5月）。

モデルの名前空間は重要です： コアモデル（scVI、scANVI、totalVI、MultiVI、PeakVI、AUTOZI、CondSCVI、DestVI、LinearSCVI、AmortizedLDA、JaxSCVI）は scvi.model にあります。その他のほとんどのモデル（VeloVI、contrastiveVI、CellAssign、PoissonVI、scBasset、MrVI、MethylVI/MethylANVI、CytoVI、SysVI、Decipher、gimVI、scVIVA、ResolVI、Stereoscope、Solo、totalANVI、DIAGVI）は scvi.external にあります。各モデルの名前空間は、参照ファイルで指定されています。

このスキルを使う場面

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

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

主な機能

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 の同時モデリング
• totalANVI：半教師ありの CITE-seq（細胞型ラベル付きの totalVI）
• MultiVI：対応あり・対応なしのマルチオミクス統合（MuData ベース）
• MrVI：複数の解像度でのサンプル間解析
• DIAGVI：対応なしのシングルセルデータセットの対角統合（1.4.3 で追加）

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

インストール

Python **3.12+**が必要です（scvi-tools 1.4では古いバージョンのサポートが終了しました）。

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

再現可能な環境を構築するには、バージョンを固定してください：uv pip install scvi-tools==1.4.3。

**計算バックエンド：**学習では、デフォルトでPyTorch（CPU/GPU/TPU）が使用されます。 JAXバックエンド（scvi.model.JaxSCVI）と、Appleシリコン向けの実験的なMLXバックエンド （scvi.model.mlxSCVI）も、一部のモデルで利用できます。

ベストプラクティス

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

エージェントの作業手順

1. 環境を確認します。 ツールのバージョン、参照ゲノム／アノテーションのビルド、入力形式（FASTQ、BAM、VCF、h5ad）を確認します。
2. 入力を明確にします。 データまたはユーザーに確認し、形式、識別子、パラメーターを確定します。結果を左右する値は推測せず、確認してください。
3. まず小規模なバージョンを実行します。 最初に、小さなサブセット（1サンプル、1染色体、数千個の細胞）でパイプラインを実行します。
4. 上記の手順と参照情報を使用して、タスク全体を実行します。
5. 結果を検証します。 結果を解釈する前に、QC 指標、サンプルの同一性、ゲノムビルドの整合性、バッチ効果を確認します。
6. 報告します。 実行した内容（バージョン、コマンド、パラメーター）、確認した内容、未確定の点を明記します。

こうした場合	対応
入力間でゲノムビルドまたは識別子が一致しない	続行する前に停止し、調整します（liftover、ID マッピング）。
これらの手順に記載された関数、フラグ、またはエンドポイントが、インストール済みのバージョンに存在しない	インストール済みバージョンのドキュメント（help()、--help、公式ドキュメント）を確認し、対応してユーザーに伝えます。API を捏造してはいけません。
必須の入力、識別子、またはパラメーターが曖昧	ユーザーに確認するか、実行前に仮定を明示します。

インテグリティに関するルール

• 結果、パラメーター、識別子、引用、統計値を決して捏造しないでください。実行または検証できないことがあれば、明確に伝えてください。
• 統計的根拠を超えて生物学的意義を解釈しないでください。多重検定補正について報告してください。
• ここに記載されているバージョン固有の詳細は古くなっている可能性があるものとして扱い、インストール済みバージョンの公式ドキュメントと照合してください。
• 費用が発生する、共有 GPU またはクラウドのクォータを消費する、個人データまたは患者データに触れる、または取り消せない操作を行う前に、確認してください。

関連スキル

• scanpy：標準的なシングルセル RNA-seq 解析パイプラインです。
• anndata：シングルセル解析で使用されるアノテーション付き行列のデータ構造です。
• cellxgene-census：バージョン管理された公開シングルセルおよび空間トランスクリプトミクスデータを、プログラムから CZ CELLxGENE Census にクエリします。