scvi-tools

scvi-tools 深度学习 Skill

本 Skill 提供基于深度学习的单细胞分析指导,使用 scvi-tools。scvi-tools 是单细胞基因组学中概率模型领域的领先框架。

如何使用本 Skill

1. 根据下方的模型/工作流表格,确定合适的工作流
2. 阅读对应的参考文件,了解详细步骤与代码
3. 使用 scripts/ 中的脚本,避免重复编写常见代码
4. 如遇安装或 GPU 问题,请参阅 references/environment_setup.md
5. 如需调试,请参阅 references/troubleshooting.md

何时使用本 Skill

• 提及 scvi-tools、scVI、scANVI 或相关模型时
• 需要基于深度学习的批次校正或整合时
• 处理多模态数据(CITE-seq、multiome)时
• 需要参考图谱映射或标签迁移时
• 分析 ATAC-seq 或空间转录组数据时
• 学习单细胞数据的潜在表示时

模型选择指南

数据类型	模型	主要用途
scRNA-seq	scVI	无监督整合、差异表达、插补
scRNA-seq + 标签	scANVI	标签迁移、半监督整合
CITE-seq(RNA+蛋白)	totalVI	多模态整合、蛋白去噪
scATAC-seq	PeakVI	染色质可及性分析
Multiome(RNA+ATAC)	MultiVI	联合模态分析
空间 + scRNA 参考	DestVI	细胞类型解卷积
RNA velocity	veloVI	转录动力学
跨技术	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	使用 totalVI 分析蛋白+RNA
Multiome 分析	references/multiome_multivi.md	使用 MultiVI 分析 RNA+ATAC
空间解卷积	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	常见问题与解决方案

命令行脚本

用于常见工作流的模块化脚本。可根据需要串联或修改。

流程脚本

脚本	用途	用法
prepare_data.py	质控、过滤、高变基因选择	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	差异表达分析	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、layer 设置）
train_scvi()	训练 scVI 或 scANVI
evaluate_integration()	计算整合指标
get_marker_genes()	提取差异表达标记基因
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 Issues