scvi-tools

scvi-tools ディープラーニングスキル

このスキルでは、単一細胞ゲノミクスにおける確率モデルの主要なフレームワークである scvi-tools を使用した、ディープラーニングベースの単一細胞解析について説明します。

このスキルの使い方

1. 以下のモデル／ワークフローの表から適切なワークフローを特定します
2. 対応するリファレンスファイルを読み、詳細な手順とコードを確認します
3. よく使うコードを書き直さずに済むよう、scripts/ のスクリプトを使用します
4. インストールや GPU の問題については、references/environment_setup.md を参照します
5. デバッグについては、references/troubleshooting.md を参照します

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

• scvi-tools、scVI、scANVI、または関連モデルが言及されている場合
• ディープラーニングベースのバッチ補正や統合が必要な場合
• マルチモーダルデータ（CITE-seq、multiome）を扱う場合
• リファレンスマッピングやラベル転送が必要な場合
• ATAC-seq または空間トランスクリプトミクスデータを解析する場合
• 単一細胞データの潜在表現を学習する場合

モデル選択ガイド

データ型	モデル	主な用途
scRNA-seq	scVI	教師なし統合、DE、補完
scRNA-seq + ラベル	scANVI	ラベル転送、半教師あり統合
CITE-seq（RNA+protein）	totalVI	マルチモーダル統合、タンパク質のノイズ除去
scATAC-seq	PeakVI	クロマチンアクセシビリティ解析
Multiome（RNA+ATAC）	MultiVI	モダリティの統合解析
Spatial + scRNA reference	DestVI	細胞型のデコンボリューション
RNA velocity	veloVI	転写ダイナミクス
Cross-technology	sysVI	システムレベルのバッチ補正

ワークフローのリファレンスファイル

ワークフロー	リファレンスファイル	説明
環境設定	references/environment_setup.md	インストール、GPU、バージョン情報
データの準備	references/data_preparation.md	各モデルで使用するデータの形式設定
scRNA の統合	references/scrna_integration.md	scVI/scANVI によるバッチ補正
ATAC-seq 解析	references/atac_peakvi.md	アクセシビリティ解析のための PeakVI
CITE-seq 解析	references/citeseq_totalvi.md	タンパク質+RNA のための totalVI
Multiome 解析	references/multiome_multivi.md	RNA+ATAC のための MultiVI
空間デコンボリューション	references/spatial_deconvolution.md	DestVI による空間解析
ラベル転送	references/label_transfer.md	scANVI によるリファレンスマッピング
scArches マッピング	references/scarches_mapping.md	クエリからリファレンスへのマッピング
バッチ補正	references/batch_correction_sysvi.md	高度なバッチ補正手法
RNA velocity	references/rna_velocity_velovi.md	veloVI によるダイナミクス解析
トラブルシューティング	references/troubleshooting.md	よくある問題と解決方法

CLI スクリプト

よく使うワークフロー向けのモジュール式スクリプトです。必要に応じて連結したり、変更したりできます。

パイプラインスクリプト

スクリプト	目的	使用方法
prepare_data.py	QC、フィルタリング、HVG 選択	python scripts/prepare_data.py raw.h5ad prepared.h5ad --batch-key batch
train_model.py	任意の scvi-tools モデルを学習	python scripts/train_model.py prepared.h5ad results/ --model scvi
cluster_embed.py	近傍探索、UMAP、Leiden	python scripts/cluster_embed.py adata.h5ad results/
differential_expression.py	DE 解析	python scripts/differential_expression.py model/ adata.h5ad de.csv --groupby leiden
transfer_labels.py	scANVI によるラベル転送	python scripts/transfer_labels.py ref_model/ query.h5ad results/
integrate_datasets.py	複数データセットの統合	python scripts/integrate_datasets.py results/ data1.h5ad data2.h5ad
validate_adata.py	データの互換性を確認	python scripts/validate_adata.py data.h5ad --batch-key batch

ワークフローの例

# 1. Validate input data
python scripts/validate_adata.py raw.h5ad --batch-key batch --suggest

# 2. Prepare data (QC, HVG selection)
python scripts/prepare_data.py raw.h5ad prepared.h5ad --batch-key batch --n-hvgs 2000

# 3. Train model
python scripts/train_model.py prepared.h5ad results/ --model scvi --batch-key batch

# 4. Cluster and visualize
python scripts/cluster_embed.py results/adata_trained.h5ad results/ --resolution 0.8

# 5. Differential expression
python scripts/differential_expression.py results/model results/adata_clustered.h5ad results/de.csv --groupby leiden

Python ユーティリティ

scripts/model_utils.py には、カスタムワークフローでインポートして使用できる関数が用意されています。

関数	用途
prepare_adata()	データの準備（QC、HVG、レイヤーの設定）
train_scvi()	scVI または scANVI のトレーニング
evaluate_integration()	統合メトリクスの算出
get_marker_genes()	DE マーカーの抽出
save_results()	モデル、データ、プロットの保存
auto_select_model()	最適なモデルの提案
quick_clustering()	近傍グラフ + UMAP + Leiden

重要な要件

1. 生カウントデータが必要です：scvi-tools のモデルには整数のカウントデータが必要です。

   adata.layers["counts"] = adata.X.copy()  # Before normalization
   scvi.model.SCVI.setup_anndata(adata, layer="counts")
   

2. HVG の選択：高度に変動する遺伝子を 2000～4000 個使用します。

   sc.pp.highly_variable_genes(adata, n_top_genes=2000, batch_key="batch", layer="counts", flavor="seurat_v3")
   adata = adata[:, adata.var['highly_variable']].copy()
   

3. バッチ情報：統合には batch_key を指定します。

   scvi.model.SCVI.setup_anndata(adata, layer="counts", batch_key="batch")
   

クイック判断ツリー

Need to integrate scRNA-seq data?
├── Have cell type labels? → scANVI (references/label_transfer.md)
└── No labels? → scVI (references/scrna_integration.md)

Have multi-modal data?
├── CITE-seq (RNA + protein)? → totalVI (references/citeseq_totalvi.md)
├── Multiome (RNA + ATAC)? → MultiVI (references/multiome_multivi.md)
└── scATAC-seq only? → PeakVI (references/atac_peakvi.md)

Have spatial data?
└── Need cell type deconvolution? → DestVI (references/spatial_deconvolution.md)

Have pre-trained reference model?
└── Map query to reference? → scArches (references/scarches_mapping.md)

Need RNA velocity?
└── veloVI (references/rna_velocity_velovi.md)

Strong cross-technology batch effects?
└── sysVI (references/batch_correction_sysvi.md)

主なリソース

• scvi-tools のドキュメント
• scvi-tools のチュートリアル
• モデルハブ
• GitHub の課題