单细胞深度学习分析技能：用 scvi-tools 一站式完成 QC、整合与多模态建模
核心结论速览
- 它是谁：
bio-single-cell（中文名：单细胞深度学习分析技能）是一个面向单细胞组学分析的 AI 技能，把 scvi-tools + scverse 生态的深度学习建模能力与标准 QC 流程封装成可被 AI 直接调用的工作流。 - 它能干什么：覆盖 scVI/scANVI 数据整合与批处理校正、PeakVI（ATAC）、totalVI（CITE-seq）、MultiVI（RNA+ATAC）、DestVI（空间解卷积）、veloVI（RNA 速度）以及标签转移、参考映射和质控分析共 8 大类任务。
- 它怎么用：先跑 QC 保证数据质量，再按数据类型选择模型，最后用模块化 CLI 脚本串成"校验 → 预处理 → 训练 → 聚类 → 差异表达"的流水线。
- 适合谁：需要处理多批次、多模态单细胞数据的生信工程师、计算生物学研究者和做单细胞课题的临床科研人员。
- 门槛在哪：技能声明依赖
python与bash，脚本与参考资料位于 Bio-Informatics Pack 内，安装与 GPU 环境问题需参考包内references/environment_setup.md。
1. 该技能叫什么？如何一键安装 AI 技能提升开发效率？
基本信息
| 项目 | 内容 |
|---|---|
| 技能中文名 | 单细胞深度学习分析技能 |
| 技能英文名 | bio-single-cell |
| 技能ID | 13827 |
| 依赖环境 | python、bash |
| 所属资源包 | Bio-Informatics Pack |
它解决什么问题
单细胞分析的真实痛点不在于"没有算法"，而在于三件事：
- 选型难：面对 scVI、scANVI、totalVI、PeakVI、MultiVI、DestVI、veloVI、sysVI 这一串模型，新手很难判断"我手上这份数据到底该用哪个"。
- 流程长：从读取
.h5ad、质控过滤、高变基因选择、训练模型、降维聚类到差异表达，每一步都要手写代码，参数一旦写错，结果不可复现。 - 踩坑多：批次键写错、数据格式不兼容、GPU 环境装不上，这些问题往往比建模本身更耗时。
这个技能的价值就在于：它把"决策知识（什么数据用什么模型）"和"可执行脚本（scripts/ 目录下的模块化 CLI）"打包在一起，让 AI 既能给出判断，也能直接跑通流程。
一键安装的思路与步骤
需要说明的是，具体安装命令、技能市场入口与按钮位置请以官方说明为准，这里给出的是通用流程与验证方法：
- 确认前置环境：本技能声明
requires: [python, bash]，先在本地或服务器确认 Python 与 bash 可用，并准备好可用的 scvi-tools / scverse 运行环境。 - 在技能入口中检索并安装：在 AI 客户端的技能（Skill）管理界面或技能市场中，用中文名「单细胞深度学习分析技能」或英文名
bio-single-cell搜索并安装（具体入口与命令以官方说明为准）。 - 确认资源包就位：安装完成后，检查 Bio-Informatics Pack 是否已落地，脚本路径应为：
src-tauri/resources/packs/bio-informatics-pack/single-cell-analysis/scripts/同时确认references/下存在scverse_qc_guidelines.md与environment_setup.md。 - 验证是否生效：用一句话触发技能，例如"帮我做单细胞 QC，数据是 raw.h5ad，批次列叫 batch"。如果技能被正确唤起，并给出 QC 或建模工作流建议、引用到对应脚本，说明安装成功。也可直接执行一次
validate_adata.py做冒烟测试。 - 触发词备忘：
scVI、scANVI、totalVI、QC、quality control、batch correction、integration、multi-modal—— 命中这些词时技能应被激活。
这种"一键安装"的思路本质是把专业领域的 SOP 变成可加载的能力单元：装一次，之后每次对话都自带单细胞分析的领域知识与脚本工具，不必每次从零描述需求。
2. 该技能的主要功能和特点
八大核心能力
- 数据整合与批次校正（scVI / sysVI）：scVI 面向 scRNA-seq 的无监督整合、差异表达与插值；sysVI 用于跨技术平台等"系统级"批次效应的校正。
- 半监督整合与标签转移（scANVI）：在已有带标签参考数据的前提下，把细胞类型标签迁移到新查询数据上。
- 染色质可及性分析（PeakVI）：针对 scATAC-seq 数据建模。
- 多模态分析（totalVI）：面向 CITE-seq（RNA + 蛋白）的联合建模与蛋白信号去噪。
- 多组学联合分析（MultiVI）：RNA + ATAC 的联合模态建模。
- 空间转录组解卷积（DestVI）：结合 scRNA 参考，估计空间spot中的细胞类型构成。
- RNA 速度分析（veloVI）：刻画转录动态。
- 标准 QC 工作流：在跑任何深度学习模型之前，先做一遍质控，输出质控后的
.h5ad。
模型选择指南（技能内置决策表）
| 数据类型 | 推荐模型 | 主要用例 |
|---|---|---|
| scRNA-seq | scVI | 无监督整合、差异表达、插值 |
| scRNA-seq + 标签 | scANVI | 标签转移、半监督整合 |
| CITE-seq（RNA + 蛋白） | totalVI | 多模态整合、蛋白去噪 |
| scATAC-seq | PeakVI | 染色质可及性分析 |
| 多组学（RNA + ATAC） | MultiVI | 联合模态分析 |
| 空间 + scRNA 参考 | DestVI | 细胞类型解卷积 |
| RNA 速度 | veloVI | 转录动态 |
| 跨技术平台 | sysVI | 系统级批处理校正 |
模块化 CLI 脚本
| 脚本 | 目的 |
|---|---|
prepare_data.py |
QC、过滤、高变基因（HVG）选择 |
train_model.py |
训练任意 scvi-tools 模型 |
cluster_embed.py |
近邻图、UMAP、Leiden 聚类 |
differential_expression.py |
差异表达分析 |
transfer_labels.py |
基于 scANVI 的标签转移 |
integrate_datasets.py |
多数据集整合 |
validate_adata.py |
数据兼容性检查 |
和普通工具比强在哪
- 不只是"能跑"，而是"知道该跑哪个"：内置数据模型对照表，AI 会先判断数据类型再选模型，避免用 totalVI 去跑纯 RNA 数据这类错配。
- 强制 QC 前置：技能明确要求"在运行任何深度学习模型之前，确保数据质量"，把容易跳过的质控环节写进了流程。
- 脚本可链接、可修改：模块化设计，既可以按示例串成流水线，也可以单独抽出来改造成自己项目的一部分。
- 有文档兜底：阈值细节查
scverse_qc_guidelines.md，环境与 GPU 问题查environment_setup.md，不靠猜。
3. 如何使用该技能？
第 1 步：确认技能被正确唤起
在对话中直接描述任务，并带上触发词。例如：
“我有一份多批次 scRNA-seq 数据
raw.h5ad，批次信息在batch列，想做整合和批次校正，用 scVI 还是 scANVI？”
第 2 步：校验数据兼容性
在正式跑流程前，先用校验脚本检查数据是否满足要求，并让它给出建议：
python $SC_SCRIPTS/validate_adata.py raw.h5ad --batch-key batch --suggest
输出用于确认 .h5ad 结构、批次键是否正确，以及是否需要先补做某项处理。
第 3 步：运行 QC（先跑，别跳）
python src-tauri/resources/packs/bio-informatics-pack/single-cell-analysis/scripts/qc_analysis.py input.h5ad output_qc.h5ad
具体指标阈值请参考包内 references/scverse_qc_guidelines.md。
第 4 步：数据准备与高变基因选择
python $SC_SCRIPTS/prepare_data.py raw.h5ad prepared.h5ad --batch-key batch --n-hvgs 2000
这一步完成 QC、过滤与 HVG 选择，输出 prepared.h5ad。
第 5 步：训练模型
python $SC_SCRIPTS/train_model.py prepared.h5ad results/ --model scvi --batch-key batch
--model 换成 scanvi、totalvi、peakvi 等即可切换模型，模型目录会保存到 results/。
第 6 步：降维与聚类
python $SC_SCRIPTS/cluster_embed.py results/adata_trained.h5ad results/ --resolution 0.8
输出近邻图、UMAP 坐标与 Leiden 聚类标签，--resolution 控制聚类粒度。
第 7 步：下游分析
差异表达：
python $SC_SCRIPTS/differential_expression.py model/ adata.h5ad de.csv --groupby leiden
标签转移：
python $SC_SCRIPTS/transfer_labels.py ref_model/ query.h5ad results/
多数据集整合：
python $SC_SCRIPTS/integrate_datasets.py results/ data1.h5ad data2.h5ad
完整示例工作流
# 设置脚本路径
$SC_SCRIPTS = "src-tauri/resources/packs/bio-informatics-pack/single-cell-analysis/scripts"
# 1. 验证输入数据
python $SC_SCRIPTS/validate_adata.py raw.h5ad --batch-key batch --suggest
# 2. 准备数据（QC、HVG 选择）
python $SC_SCRIPTS/prepare_data.py raw.h5ad prepared.h5ad --batch-key batch --n-hvgs 2000
# 3. 训练模型
python $SC_SCRIPTS/train_model.py prepared.h5ad results/ --model scvi --batch-key batch
# 4. 聚类和可视化
python $SC_SCRIPTS/cluster_embed.py results/adata_trained.h5ad results/ --resolution 0.8
输入与输出说明：输入统一为 .h5ad 格式的表达矩阵与可选的批次键；输出为质控后的 .h5ad、模型目录、带聚类与降维结果的 .h5ad，以及 CSV 格式的差异表达表。
4. 同类型竞品对比分析
| 方案名称 | 定位 | 核心功能 | 安装/使用门槛 | 适用场景 | 优势与不足 |
|---|---|---|---|---|---|
| 单细胞深度学习分析技能（bio-single-cell） | AI 技能，封装 scvi-tools 深度学习工作流 | 模型选型建议 + QC + 整合 + 多模态 + 空间解卷积 + 标签转移 + RNA 速度 | 需 python、bash 环境；技能一键安装，脚本开箱即用 | 希望用对话驱动完成标准化单细胞建模流程的用户 | 优势：选型知识内嵌、流程标准化、脚本可改；不足：强依赖 scvi-tools 体系，非深度模型的传统方法不在覆盖范围内 |
| Scanpy / scverse 手工编码流程 | 通用单细胞分析 Python 库 | 质控、归一化、降维、聚类、可视化等全套基础能力 | 需自行编写代码，学习曲线较陡 | 需要高度自定义分析逻辑的资深生信人员 | 优势：灵活、生态成熟；不足：模型选型与流程编排全靠自己，容易出错且不易复现 |
| Seurat（R 生态） | R 语言单细胞分析框架 | 质控、整合（CCA/RPCA 等）、聚类、差异表达 | 需 R 环境与 R 编程能力 | R 背景团队、传统单细胞分析流程 | 优势：社区大、教程多；不足：与 Python 生态割裂，深度学习模型集成不如 scvi-tools 直接 |
| NF-core / 自建流水线 | 命令行工作流编排 | 自动化跑通固定分析步骤 | 需 Docker/Nextflow 等基础设施 | 大规模批量样本、需要生产级可复现 | 优势：可复现、可批量；不足：调整模型与参数不灵活，前期搭建成本高 |
| 通用大模型直接对话 | 无领域技能加持的通用问答 | 解释概念、生成代码片段 | 零门槛 | 学习概念、临时查资料 | 优势：上手快；不足：不了解本地数据格式与脚本路径，无法直接串起可执行流程，易产生幻觉参数 |
怎么选：如果你手上是 scRNA-seq / CITE-seq / scATAC-seq / 空间转录组这类需要深度学习建模的数据，且希望用最少的编排成本跑通标准化流程，本技能是更贴合的选择；如果分析逻辑高度定制或团队强依赖 R 生态，则 Scanpy / Seurat 更合适。
5. 该技能的典型应用场景与实际体验情况
场景一：多批次 scRNA-seq 数据整合（生信工程师）
- 痛点：不同测序批次、不同时间点采样的数据合并后，UMAP 上细胞按批次而非按细胞类型聚开，下游差异表达全是批次假阳性。
- 使用方式：先用
validate_adata.py确认batch列可用，再依次执行prepare_data.py --batch-key batch与train_model.py --model scvi --batch-key batch，最后cluster_embed.py出图。 - 实际体验情况：上手难度较低，流程是"一条命令一件事"，把原本需要手写几十行 scvi-tools 代码的建模流程压缩成固定步骤；效果上重点在于批次键是否传对，这是最容易出错的一环，建议每次先跑校验脚本。注意事项：训练耗时与数据规模、是否使用 GPU 相关，环境问题查
environment_setup.md。
场景二：参考图谱标签转移（做疾病队列的研究者）
- 痛点：已有一份注释完善的参考数据集，新的查询样本没有标签，人工注释成本高且主观性强。
- 使用方式：用参考数据训练 scANVI 模型（
train_model.py --model scanvi），再执行transfer_labels.py ref_model/ query.h5ad results/完成标签迁移。 - 实际体验情况：技能的"数据 + 标签 → scANVI"决策表让选型这一步几乎没有歧义；注意事项是参考与查询数据的基因空间需一致，标签体系要提前对齐，否则迁移结果会出现无法解释的类别。
场景三：CITE-seq 与多组学联合分析（免疫学 / 单细胞多模态研究）
- 痛点：RNA 与蛋白（或 RNA 与 ATAC）来自同一批细胞，分开分析会丢失模态间的互补信息，蛋白信号还存在背景噪声。
- 使用方式：CITE-seq 走 totalVI，RNA + ATAC 走 MultiVI，通过
train_model.py --model totalvi/--model multivI切换。 - 实际体验情况：技能内置的模型对照表在这里价值最大——它能避免"拿 scVI 硬跑蛋白数据"这类常见错配；注意事项是多模态数据对 QC 更敏感，务必先跑
qc_analysis.py。
场景四：空间转录组解卷积（肿瘤微环境研究）
- 痛点：空间数据每个 spot 混合了多种细胞，需要借助 scRNA 参考推断细胞类型构成。
- 使用方式：以 scRNA 参考训练模型，再用 DestVI 做解卷积，配合
integrate_datasets.py组织多份数据。 - 实际体验情况：整体属于进阶用法，需要对空间与单细胞数据的对应关系有一定理解；建议先用小规模数据跑通链路，再扩展到全样本。
6. 该技能能为用户带来的价值
- 把"选模型"这件专业事变成一次对话：技能内置的数据类型—模型对照表，覆盖 scVI、scANVI、totalVI、PeakVI、MultiVI、DestVI、veloVI、sysVI 共 8 类模型，用户不必先读完 scvi-tools 文档才能动手。
- 把流程标准化，减少隐性返工：强制"先 QC 再建模"的顺序，配合
validate_adata.py的前置校验，可以在流程早期发现格式与批次键问题，而不是训练几小时后才发现结果不可用。 - 把重复编码变成可复用脚本：7 个模块化 CLI 脚本覆盖预处理、训练、聚类、差异表达、标签转移与多数据集整合，既可以按示例串起来，也可以单独修改参数复用，长期看是一套可沉淀的资产。
- 降低跨模态分析的门槛：CITE-seq、scATAC-seq、RNA+ATAC、空间转录组这些原本需要专门学习的模态，在这里被统一到一致的调用方式下。
- 可复现性提升：每条命令显式声明
--model、--batch-key、--n-hvgs、--resolution等参数，分析过程天然留下可追溯的记录，方便写进论文方法学部分或交接给同事。
7. 常见问题 FAQ
Q1：这个技能怎么安装？需要提前准备什么？
先在 AI 客户端的技能管理入口搜索「单细胞深度学习分析技能」或英文名 bio-single-cell 并安装（具体安装入口与命令以官方说明为准）。安装前请确认本地已具备 python 与 bash 环境，这是技能声明的依赖。安装后检查 Bio-Informatics Pack 中的 single-cell-analysis/scripts/ 与 references/ 是否存在，再用一句带触发词的话（如"用 scVI 做批次校正"）验证技能是否被唤起。
Q2：这个技能收费吗？
技能本身的计价方式与可用范围以官方说明为准。需要注意的是，它调用的是 scvi-tools / scverse 这类开源生态组件，建模所需的算力（尤其是 GPU）由你自己的运行环境提供，这部分成本需另行考虑。
Q3：它适合谁用？没有生信背景能用吗？
最适合有一定单细胞数据基础的生信工程师、计算生物学研究者和单细胞课题的科研人员。技能能帮你解决"选哪个模型、按什么顺序跑"的问题，但仍需理解 .h5ad、批次键、HVG、Leiden 聚类这些基本概念；完全没有接触过单细胞分析的用户，建议先补齐基础概念再用它加速流程。
Q4：它和直接用 Scanpy / Seurat 有什么区别？
Scanpy、Seurat 是通用的分析库，提供底层能力，怎么组合由你决定；本技能是在 scvi-tools 基础上封装的带决策与流程的工作流——它会先判断你的数据类型（scRNA / CITE-seq / ATAC / 多组学 / 空间 / 速度），再给出对应模型和可直接执行的脚本命令。如果你需要高度定制的分析逻辑，直接用库更灵活；如果你想要标准化、可复现、少踩坑的深度建模流程，本技能更省事。
Q5：模型训练报错或者 GPU 装不上怎么办？
技能自带了环境说明文档，安装或 GPU 相关问题请参考 Bio-Informatics Pack 中的 references/environment_setup.md；质控指标阈值问题参考 references/scverse_qc_guidelines.md。另外，绝大多数"训练失败"其实源于数据本身，建议先用 validate_adata.py --suggest 校验一遍输入数据再排查环境。