scanpy

Scanpy：单细胞分析

概述

Scanpy 是基于 AnnData 构建的可扩展 Python 工具包，用于分析单细胞 RNA-seq 数据。使用此技能可完成完整的单细胞工作流，包括质量控制、归一化、降维、聚类、标记基因识别、可视化和轨迹分析。当前稳定版本：scanpy 1.12.x（2026 年 1 月）。

安装

需要 Python 3.12+（scanpy 1.12 不再支持 Python ≤3.11）和 anndata ≥0.10。

uv pip install "scanpy[leiden]"

[leiden] 附加项会安装 Leiden 聚类所需的 python-igraph 和 leidenalg。为确保环境可复现，请固定版本：uv pip install "scanpy[leiden]==1.12.1"。

对于大型数据集或无法全部载入内存的数据集，许多函数支持 Dask 数组（实验性功能）：

uv pip install "scanpy[leiden]" dask

请参阅教程 Using dask with Scanpy。如需使用 GPU 加速、类似 scanpy 的操作，请单独使用 rapids-singlecell 软件包。

如果输入是 R 原生单细胞对象（.rds、.RData、Seurat 或 SingleCellExperiment），请先使用 R 工具将其转换为 .h5ad，然后再使用 Scanpy 加载。请阅读 references/r_interop.md，了解适用于 macOS、Linux 和 Windows 的 Agent 安装与转换说明。

有关 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

一键端到端运行

# Counts → clustered, marker-annotated object + figures + marker CSVs
python scripts/run_pipeline.py raw.h5ad -o processed.h5ad \
    --resolution 0.5 --n-top-genes 2000 --scrublet
# With multi-sample integration:
python scripts/run_pipeline.py raw.h5ad -o processed.h5ad --batch-key sample --batch-method harmony
# Reproducible parameters via JSON (keys mirror flag names with underscores):
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
# inspect results/markers/*.csv, decide labels, write a mapping JSON, then:
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

# Configure settings
sc.settings.verbosity = 3
sc.settings.set_figure_params(dpi=80, facecolor='white')
sc.settings.figdir = './figures/'
sc.settings.autosave = True  # Preferred over per-plot save= (deprecated in scanpy 1.12)

加载数据

# From 10X Genomics
adata = sc.read_10x_mtx('path/to/data/')
adata = sc.read_10x_h5('path/to/data.h5')

# From h5ad (AnnData format)
adata = sc.read_h5ad('path/to/data.h5ad')

# From CSV
adata = sc.read_csv('path/to/data.csv')

对于 R 原生文件，请勿尝试在 Python 中直接解析 Seurat .rds。请先进行转换：

# See references/r_interop.md for installing R and conversion packages.
Rscript convert_rds_to_h5ad.R input.rds output.h5ad

adata = sc.read_h5ad('output.h5ad')

了解 AnnData 结构

AnnData 对象是 scanpy 的核心数据结构：

adata.X          # Expression matrix (cells × genes)
adata.obs        # Cell metadata (DataFrame)
adata.var        # Gene metadata (DataFrame)
adata.uns        # Unstructured annotations (dict)
adata.obsm       # Multi-dimensional cell data (PCA, UMAP)
adata.raw        # Raw data backup

# Access cell and gene names
adata.obs_names  # Cell barcodes
adata.var_names  # Gene names

标准分析工作流

七个步骤及各步骤的重要代码和参数见 references/analysis_workflow.md：

1. 质量控制 — 过滤细胞和基因；在选择阈值前检查线粒体比例和计数，不要直接照搬默认值。
2. 归一化和预处理 — 进行归一化、对数转换，选择高变基因，并保留 .raw 供后续绘图使用。
3. 降维 — 依次进行 PCA、构建邻居图和 UMAP。
4. 聚类 — 根据问题选择 Leiden 分辨率，而不是使用默认值。
5. 标记基因识别 — 对各个簇中的基因进行排序。
6. 细胞类型注释 — 根据标记基因将簇映射到细胞类型。
7. 保存结果 — 写入已注释的 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：高变基因选择参数

降维

• n_pcs：主成分数量（查看方差比例图）
• n_neighbors：邻居数量（通常为 10-30）

聚类

• resolution：聚类粒度（0.4-1.2，值越高，簇越多）

常见问题和最佳实践

1. 始终保存原始计数：过滤基因前执行 adata.raw = adata
2. 仔细检查质量控制图：根据数据集质量调整阈值
3. 使用 Leiden 聚类：sc.tl.louvain 在 scanpy 1.12 中已弃用
4. 尝试多个聚类分辨率：找到最佳粒度
5. 验证细胞类型注释：使用多个标记基因
6. 使用 use_raw=True 绘制基因表达图：显示来自 .raw 的归一化计数
7. 检查 PCA 方差比例：确定最佳 PC 数量
8. 保存中间结果：较长的工作流可能会在中途失败
9. 使用伪批量进行 DE：不要将 rank_genes_groups 的 p 值视为严谨的条件间差异表达分析结果
10. 通过设置保存图表：使用 sc.settings.autosave，不要在绘图函数中使用已弃用的 save=
11. 在使用 Scanpy 前转换 R 对象：使用 R 包将 Seurat 或 SingleCellExperiment .rds 文件转换为 .h5ad，并保留计数、元数据和基因标识符

捆绑资源

scripts/（命令行工具包）

一组可组合的脚本，输入和输出均为 .h5ad，覆盖整个工作流，并提供一条命令即可运行的端到端流程。完整表格和串联示例请参阅上文的 脚本工具包 部分。每个脚本都支持 --help。文件包括：

• _common.py — 由其他脚本导入的通用加载、保存和图表辅助函数（不是命令行工具）
• run_pipeline.py — 一条命令运行完整流程（使用标志或 --config JSON）
• 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 — 标记基因、注释、评分和差异表达分析准备
• 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

Agent 操作手册，介绍如何在 macOS、Linux 和 Windows 上安装 R，安装 CRAN/Bioconductor 转换包，检查 .rds/.RData 输入文件，将 Seurat 或 SingleCellExperiment 对象转换为 .h5ad，并在 Scanpy 中验证结果。

assets/analysis_template.py

完整的分析模板，提供从数据加载到细胞类型注释的完整工作流。新分析时可复制并自定义此模板：

cp assets/analysis_template.py my_analysis.py
# Edit parameters and run
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.scverse.org/en/stable/tutorials/index.html
• 发行说明：https://scanpy.scverse.org/en/stable/release-notes/index.html
• scverse 生态系统：https://scverse.org/（相关工具：squidpy、scvi-tools、cellrank）
• R 互操作性：https://www.bioconductor.org/packages/release/bioc/html/zellkonverter.html and https://mojaveazure.github.io/seurat-disk/
• 最佳实践：Luecken & Theis（2019）“单细胞 RNA-seq 当前最佳实践”

高效分析技巧

1. 从模板开始：使用 assets/analysis_template.py 作为起点
2. 先运行 QC 脚本：使用 scripts/qc_analysis.py 进行初步过滤
3. 按需查阅参考文档：将工作流和 API 参考文档载入上下文
4. 迭代调整聚类：尝试多个分辨率和可视化方法
5. 进行生物学验证：检查标记基因是否符合预期的细胞类型
6. 记录参数：记录 QC 阈值和分析设置
7. 保存检查点：在关键步骤写入中间结果

相关技能

• anndata：用于单细胞分析中带注释矩阵的数据结构。
• scvi-tools：训练并应用 scvi-tools 概率深度生成模型（scVI、scANVI、totalVI、MultiVI、PeakVI、DestVI、Solo、CellAssign、MrVI…
• pydeseq2：使用 PyDESeq2（DESeq2 的 Python 移植版）对 bulk RNA-seq 计数数据进行差异表达分析。