用途：在本地对用户自己的 AnnData 文件训练并应用 scvi-tools 的概率深度学习模型，用于单细胞组学的批次校正与整合。适用于强或非线性批次效应、CITE-seq（RNA+蛋白）、multiome（RNA+ATAC）、空间+单细胞参考、参考映射/标签转移，以及带不确定性的 RNA 速率。纯 scanpy QC/聚类、Harmony 校正、bulk RNA-seq DESeq2、FASTQ 质控等应使用其他技能。
主要能力与模型选择：scRNA-seq 无标签整合用 scVI；有部分/全部细胞类型标签用 scANVI；CITE-seq 用 totalVI；scATAC-seq 用 PeakVI；multiome 用 MultiVI；空间+单细胞参考用 DestVI；RNA 速率用 veloVI；新数据映射到已有参考用 scANVI + load_query_data。可用 python scripts/validate_adata.py your.h5ad --batch-key batch --suggest 获取数据驱动的推荐。
使用方式：先检查环境与数据，再准备数据（QC、HVG 选择、将原始计数存入 counts 层），然后训练模型，之后做基于后验的差异表达，可选做标签转移。示例命令：python scripts/validate_adata.py raw.h5ad --batch-key batch --suggest；python scripts/prepare_data.py raw.h5ad prepared.h5ad --batch-key batch；python scripts/train_model.py prepared.h5ad results/ --model scvi --batch-key batch；python scripts/differential_expression.py results/scvi_model results/adata_scvi_trained.h5ad de.csv --groupby leiden；python scripts/transfer_labels.py results/scanvi_model prepared.h5ad query.h5ad results/。totalVI/MultiVI/DestVI 的模态输入形状与 DestVI 两阶段拟合见 references/multimodal_workflows.md。
限制与约定：必须使用原始整数计数，脚本会校验并拒绝归一化/对数数据；训练前会如实打印使用 GPU（CUDA/MPS）还是 CPU；若未安装 scvi-tools，脚本会打印 pip install scvi-tools 并退出，不猜测结果；不得伪造潜在空间、训练曲线或差异表达结果；输出写入单独目录/文件，绝不覆盖输入文件。其他参考文档包括 model_selection.md、scrna_integration.md、troubleshooting.md。