Scanpy：单细胞分析 是做什么的？
概述
Scanpy是一个用于分析单细胞RNA-seq数据的可扩展Python工具包，构建于AnnData之上。应用此技能可完成完整的单细胞工作流程，包括质量控制、标准化、降维、聚类、标记基因鉴定、可视化和轨迹分析。当前稳定版本：scanpy 1.12.x（2026年1月）。
安装
需要Python 3.12+（scanpy 1.12已放弃对Python ≤3.11的支持）和anndata ≥0.10。
uv pip install "scanpy[leiden]"
[leiden]额外安装包会安装python-igraph和leidenalg，这是Leiden聚类所必需的。为重现环境，请固定版本：uv pip install "scanpy[leiden]==1.12.1"。
对于大型或超出核心内存的数据集，许多函数支持Dask数组（实验性）：
uv pip install "scanpy[leiden]" dask
请参阅将dask与Scanpy配合使用教程。如需GPU加速的类似scanpy的操作，请使用独立的rapids-singlecell包。
如果输入是R原生的单细胞对象（.rds、.RData、Seurat或SingleCellExperiment），请先使用R工具将其转换为.h5ad，然后使用Scanpy加载。阅读references/r_interop.md以获取在macOS、Linux和Windows上由代理运行的安装和转换说明。
有关AnnData结构和I/O的详细信息，请使用anndata技能。有关概率模型和批次校正，请使用scvi-tools。
何时使用此技能
此技能应在以下情况使用：
- 分析单细胞RNA-seq数据（.h5ad、10X、CSV格式）
- 使用需要转换为
.h5ad的R友好单细胞数据集（.rds、.RData、Seurat、SingleCellExperiment） - 对scRNA-seq数据集执行质量控制
- 创建UMAP、t-SNE或PCA可视化
- 识别细胞簇并寻找标记基因
- 基于基因表达注释细胞类型
- 进行轨迹推断或伪时间分析
- 生成可用于发表的单细胞图
脚本工具包（优先使用这些脚本而非从头编写代码）
此技能在scripts/目录中捆绑了针对每个常见步骤的即用型CLI脚本。运行这些脚本，而非手动编写scanpy代码——它们能根据扩展名处理文件加载、图形设置、合理的默认值、原始计数保留和进度日志记录。每个脚本都读取和写入.h5ad，因此可以串联使用，并且每个都有其自己的--help。仅当任务未被脚本覆盖或需要异常定制时，才降级为编写scanpy代码。
所有脚本都使用共享的scripts/_common.py辅助模块（加载、保存、图形配置）——请将其与其他脚本放在一起。从技能目录运行或传递完整路径；图形默认保存到./figures/。
| 脚本 | 用途 | 典型调用 |
|---|---|---|
run_pipeline.py | 一条命令完成完整工作流程：加载 → QC → 标准化 → HVG → PCA →（批次）→ UMAP → Leiden → 标记物 | python scripts/run_pipeline.py raw.h5ad -o processed.h5ad |
inspect_data.py | 总结未知数据集（形状、obs/var、层、已计算内容、原始与标准化对比） | python scripts/inspect_data.py data.h5ad |
convert.py | 加载任何格式（10x目录/.h5、csv、loom、mtx）并写入.h5ad | python scripts/convert.py 10x_dir/ -o data.h5ad |
qc_analysis.py | QC度量、前后对比图、过滤、可选的Scrublet双胞体检测 | python scripts/qc_analysis.py raw.h5ad -o qc.h5ad --scrublet |
preprocess.py | 标准化、log1p、HVG、可选缩放/回归（保留counts层 + raw） | python scripts/preprocess.py qc.h5ad -o norm.h5ad |
reduce_dimensions.py | PCA + 方差图、邻域、UMAP、可选的t-SNE | python scripts/reduce_dimensions.py norm.h5ad -o red.h5ad |
batch_correct.py | 整合：harmony / bbknn / combat | python scripts/batch_correct.py red.h5ad -o int.h5ad --method harmony --batch-key sample |
cluster.py | 以一个或多个分辨率进行Leiden（或louvain）聚类 | python scripts/cluster.py red.h5ad -o clu.h5ad --resolution 0.3 0.6 1.0 |
find_markers.py | rank_genes_groups + 每个组的CSV + 标记物图 | python scripts/find_markers.py clu.h5ad --groupby leiden -o clu.h5ad |
annotate.py | 将簇 → 细胞类型从JSON/CSV映射；可选的标记物参考点图 | python scripts/annotate.py clu.h5ad -o ann.h5ad --mapping map.json |
score_genes.py | 对基因签名（JSON）和/或细胞周期阶段进行评分 | python scripts/score_genes.py ann.h5ad -o scored.h5ad --gene-sets sigs.json |
pseudobulk.py | 按样本×细胞类型聚合计数 → 用于pydeseq2的矩阵 | python scripts/pseudobulk.py ann.h5ad --by sample cell_type --out-prefix pb |
subset.py | 按obs值或基因列表子集（可选择清除过时的嵌入） | python scripts/subset.py ann.h5ad -o tcells.h5ad --obs cell_type --keep "T cells" |
plot.py | 从处理后的对象生成umap/tsne/pca/violin/dotplot/heatmap等 | python scripts/plot.py ann.h5ad --kind dotplot --genes CD3D CD14 --groupby cell_type |
一次命令端到端运行
# 计数 → 聚类、标记物注释的对象 + 图形 + 标记物CSV
python scripts/run_pipeline.py raw.h5ad -o processed.h5ad \
--resolution 0.5 --n-top-genes 2000 --scrublet
# 带多样本整合：
python scripts/run_pipeline.py raw.h5ad -o processed.h5ad --batch-key sample --batch-method harmony
# 通过JSON重现参数（键镜像带有下划线的标志名称）：
python scripts/run_pipeline.py raw.h5ad -o processed.h5ad --config params.json
逐步链式运行（当需要在阶段间检查/迭代时）
python scripts/qc_analysis.py raw.h5ad -o qc.h5ad --scrublet
python scripts/preprocess.py qc.h5ad -o norm.h5ad --n-top-genes 2000
python scripts/reduce_dimensions.py norm.h5ad -o red.h5ad --n-pcs 40
python scripts/cluster.py red.h5ad -o clu.h5ad --resolution 0.3 0.5 0.8
python scripts/find_markers.py clu.h5ad -o clu.h5ad --groupby leiden --use-raw
# 检查结果/markers/*.csv，决定标签，写入映射JSON，然后：
python scripts/annotate.py clu.h5ad -o ann.h5ad --mapping celltypes.json
以下部分记录了每个脚本执行的底层scanpy调用——当需要在脚本标志之外进行自定义时阅读它们。
快速开始
基本导入和设置
import scanpy as sc
import pandas as pd
import numpy as np
# 配置设置
sc.settings.verbosity = 3
sc.settings.set_figure_params(dpi=80, facecolor='white')
sc.settings.figdir = './figures/'
sc.settings.autosave = True # 优先于每个图的save=（在scanpy 1.12中已弃用）
加载数据
# 从10X Genomics
adata = sc.read_10x_mtx('path/to/data/')
adata = sc.read_10x_h5('path/to/data.h5')
# 从h5ad（AnnData格式）
adata = sc.read_h5ad('path/to/data.h5ad')
# 从CSV
adata = sc.read_csv('path/to/data.csv')
对于R原生文件，请勿尝试直接在Python中解析Seurat .rds。请先转换：
# 请参阅references/r_interop.md以获取安装R和转换包的说明。
Rscript convert_rds_to_h5ad.R input.rds output.h5ad
adata = sc.read_h5ad('output.h5ad')
理解AnnData结构
AnnData对象是scanpy中的核心数据结构：
adata.X # 表达矩阵（细胞 × 基因）
adata.obs # 细胞元数据（DataFrame）
adata.var # 基因元数据（DataFrame）
adata.uns # 非结构化注释（dict）
adata.obsm # 多维细胞数据（PCA， UMAP）
adata.raw # 原始数据备份
# 访问细胞和基因名称
adata.obs_names # 细胞条形码
adata.var_names # 基因名称
标准分析工作流程
七个步骤，以及每个步骤中重要的参数和代码，位于 references/analysis_workflow.md：
- 质量控制 — 过滤细胞和基因；在选择阈值前检查线粒体比例和计数，不要直接复制默认值。
- 标准化和预处理 — 标准化、对数变换、选择高变基因，并保留
.raw以备后续绘图。 - 降维 — PCA，然后构建邻域图，接着是UMAP。
- 聚类 — 根据问题选择分辨率进行Leiden聚类，而非使用默认值。
- 标记基因鉴定 — 每个簇的基因排序。
- 细胞类型注释 — 根据标记物将簇映射到细胞类型。
- 保存结果 — 写入注释后的
AnnData。
常见的后续任务——发表级图形、轨迹推断、条件间伪批量差异表达、基因集评分和批次校正——都在同一文件中。另请参阅 references/standard_workflow.md 和 references/plotting_guide.md。
需要调整的关键参数
质量控制
min_genes：每个细胞的最小基因数（通常200-500）min_cells：每个基因的最小细胞数（通常3-10）pct_counts_mt：线粒体比例阈值（通常5-20%）
标准化
target_sum：每个细胞的目标计数（默认为1e4）
特征选择
n_top_genes：高变基因数量（通常2000-3000）min_mean、max_mean、min_disp：HVG选择参数
降维
n_pcs：主成分数量（检查方差比图）n_neighbors：邻居数量（通常10-30）
聚类
resolution：聚类粒度（0.4-1.2，越高簇越多）
常见陷阱和最佳实践
- 始终保存原始计数：在过滤基因前执行
adata.raw = adata - 仔细检查QC图：根据数据集质量调整阈值
- 使用Leiden聚类：
sc.tl.louvain在scanpy 1.12中已弃用 - 尝试多个聚类分辨率：找到最佳粒度
- 验证细胞类型注释：使用多个标记基因
- 对基因表达图使用
use_raw=True：显示来自.raw的标准化计数 - 检查PCA方差比：确定最佳PC数量
- 保存中间结果：长工作流程可能中途失败
- 使用伪批量进行差异表达：不要将
rank_genes_groups的p值视为条件间严格的差异表达 - 通过设置保存图：使用
sc.settings.autosave替代绘图函数上已弃用的save= - 在Scanpy之前转换R对象：使用R包将Seurat或SingleCellExperiment
.rds文件转换为.h5ad，保留计数、元数据和基因标识符
捆绑资源
scripts/（CLI工具包）
一套可组合的 .h5ad 输入/.h5ad 输出脚本，覆盖整个工作流程以及一个一键端到端管道。请参阅上方脚本工具包部分以获取完整表格和串联示例。每个脚本都有 --help。文件：
_common.py— 共享的加载/保存/图形辅助模块，由其他脚本导入（非CLI）run_pipeline.py— 一条命令完成整个管道（标志或--configJSON）inspect_data.py、convert.py— 探索并加载/转换任何输入格式qc_analysis.py、preprocess.py、reduce_dimensions.py、batch_correct.py、cluster.py— 管道步骤find_markers.py、annotate.py、score_genes.py、pseudobulk.py— 标记物、注释、评分、DE准备subset.py、plot.py— 按元数据/基因子集；生成任何标准图
在从头编写scanpy代码之前，默认使用这些脚本。
references/standard_workflow.md
完整的逐步工作流程，包含详细说明和代码示例，涵盖：
- 数据加载和设置
- 带可视化的质量控制
- 标准化和缩放
- 特征选择
- 降维（PCA、UMAP、t-SNE）
- 聚类（Leiden）
- 双胞体检测（scrublet）和伪批量聚合
- 标记基因鉴定
- 细胞类型注释
- 轨迹推断
- 差异表达
当从头进行完整分析时，请阅读此参考文档。
references/api_reference.md
按模块组织的scanpy函数快速参考指南：
- 读取/写入数据（
sc.read_*、adata.write_*） - 预处理（
sc.pp.*） - 工具（
sc.tl.*） - 绘图（
sc.pl.*） - AnnData结构和操作
- 设置和实用工具
用于快速查找函数签名和常见参数。
references/plotting_guide.md
全面的可视化指南，包括：
- 质量控制图
- 降维可视化
- 聚类可视化
- 标记基因图（热图、点图、小提琴图）
- 轨迹和伪时间图
- 发表级自定义
- 多面板图形
- 调色板和样式
在创建发表级图形时参考此指南。
references/r_interop.md
代理运行手册，用于在macOS、Linux和Windows上安装R、安装CRAN/Bioconductor转换包、检查 .rds/.RData 输入、将Seurat或SingleCellExperiment对象转换为 .h5ad，并在Scanpy中验证结果。
assets/analysis_template.py
完整的分析模板，提供从数据加载到细胞类型注释的完整工作流程。为新分析复制并自定义此模板：
cp assets/analysis_template.py my_analysis.py
# 编辑参数并运行
python my_analysis.py
该模板包含所有标准步骤、可配置参数和有用的注释。
assets/ JSON模板
可编辑和传递的模板，因此您无需从头创建配置/映射：
assets/pipeline_config.json— 用于run_pipeline.py --config的参数集assets/celltype_mapping.json— 用于annotate.py --mapping的簇 → 细胞类型映射assets/gene_signatures.json— 用于score_genes.py --gene-sets的基因集签名
其他资源
- 官方scanpy文档：https://scanpy.scverse.org/en/stable/
- Scanpy教程：https://scanpy-tutorials.readthedocs.io/en/latest/
- scverse项目：https://scverse.org/
- AnnData文档：https://anndata.readthedocs.io/en/latest/
- 社区论坛：https://discourse.scverse.org/
- GitHub仓库：https://github.com/scverse/scanpy
贡献
此技能作为Scanpy生态系统的独立指南和维护。如需报告问题或提出改进建议，请查阅官方Scanpy仓库。