scanpy

用途

Scanpy 是一个基于 AnnData 的可扩展 Python 工具包，用于分析单细胞 RNA 测序数据。该技能适用于完整的单细胞工作流，包括质量控制、标准化、降维、聚类、标记基因识别、可视化以及轨迹分析。当前稳定版本为 scanpy 1.12.x（2026 年 1 月）。

主要能力

该技能覆盖以下分析环节：

分析单细胞 RNA-seq 数据（.h5ad、10X、CSV 格式）
处理需要转换为 .h5ad 的 R 友好单细胞数据集（.rds、.RData、Seurat、SingleCellExperiment）
对 scRNA-seq 数据集执行质量控制
创建 UMAP、t-SNE 或 PCA 可视化
识别细胞簇并查找标记基因
基于基因表达注释细胞类型
进行轨迹推断或伪时间分析
生成出版级单细胞图表

安装

需要 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

如需 GPU 加速的类 scanpy 操作，可使用单独的包 rapids-singlecell。

如果输入是 R 原生单细胞对象（.rds、.RData、Seurat 或 SingleCellExperiment），需先用 R 工具将其转换为 .h5ad，再用 Scanpy 加载。

使用方式

脚本工具包

该技能在 scripts/ 目录中捆绑了可直接运行的 CLI 脚本，覆盖每个常见步骤。建议优先运行这些脚本，而不是从头编写 scanpy 代码——它们会按扩展名处理文件加载、图表设置、合理默认值、原始计数保留和进度日志。每个脚本读写 .h5ad，因此可以相互串联，且每个脚本都有自己的 --help。只有当任务未被脚本覆盖或需要特殊定制时，才需要编写 scanpy 代码。

所有脚本共用 scripts/_common.py 辅助模块（加载、保存、图表配置），需与其他脚本放在一起。可从技能目录运行或传入完整路径；图表默认输出到 ./figures/。

主要脚本包括：

run_pipeline.py：一条命令完成完整工作流：加载 → QC → 标准化 → HVG → PCA →（批次）→ UMAP → Leiden → 标记基因
inspect_data.py：汇总未知数据集（形状、obs/var、layers、已计算内容、原始与标准化状态）
convert.py：加载任意格式（10x 目录/.h5、csv、loom、mtx）并写出 .h5ad
qc_analysis.py：QC 指标、前后对比图、过滤、可选 Scrublet 双细胞检测
preprocess.py：标准化、log1p、HVG、可选 scale/regress（保留 counts 层和 raw）
reduce_dimensions.py：PCA + 方差图、邻居图、UMAP、可选 t-SNE
batch_correct.py：整合：harmony / bbknn / combat
cluster.py：在一个或多个分辨率下执行 Leiden（或 louvain）
find_markers.py：rank_genes_groups + 每组 CSV + 标记基因图
annotate.py：从 JSON/CSV 将簇映射到细胞类型；可选标记参考点图
score_genes.py：对基因签名（JSON）和/或细胞周期阶段打分
pseudobulk.py：按样本 × 细胞类型聚合计数 → 供 pydeseq2 使用的矩阵
subset.py：按 obs 值或基因列表取子集（可选清除过期嵌入）
plot.py：从已处理对象生成 umap/tsne/pca/violin/dotplot/heatmap 等图

快速开始

基本导入与设置：

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

加载数据：

adata = sc.read_10x_mtx('path/to/data/')
adata = sc.read_10x_h5('path/to/data.h5')
adata = sc.read_h5ad('path/to/data.h5ad')
adata = sc.read_csv('path/to/data.csv')

对于 R 原生文件，不要尝试在 Python 中直接解析 Seurat .rds，应先转换：

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        # 原始数据备份

标准分析工作流

七个步骤：

质量控制——过滤细胞和基因；在决定阈值前检查线粒体比例和计数，而不是照搬默认值。
标准化与预处理——标准化、对数变换、选择高变基因，并保留 .raw 供后续绘图。
降维——PCA，然后邻居图，然后 UMAP。
聚类——根据问题选择 Leiden 分辨率，而非默认值。
标记基因识别——每个簇的排序基因。
细胞类型注释——根据标记基因将簇映射到类型。
保存结果——写出带注释的 AnnData。

关键参数

质量控制：min_genes（每细胞最少基因数，通常 200-500）、min_cells（每基因最少细胞数，通常 3-10）、pct_counts_mt（线粒体阈值，通常 5-20%）。

标准化：target_sum（每细胞目标计数，默认 1e4）。

特征选择：n_top_genes（HVG 数量，通常 2000-3000）、min_mean、max_mean、min_disp。

降维：n_pcs（主成分数量，查看方差比图）、n_neighbors（邻居数，通常 10-30）。

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

适用场景

适用于单细胞 RNA-seq 数据的完整分析流程，包括 QC、标准化、降维、聚类、标记基因识别、细胞类型注释、轨迹推断、pseudobulk 差异表达、基因集打分和批次校正等。也适用于需要将 R 原生单细胞对象转换为 .h5ad 后进行分析的场景。

限制与注意事项

需要 Python 3.12+，scanpy 1.12 已放弃 Python ≤3.11。
R 原生文件（.rds、.RData、Seurat、SingleCellExperiment）不能直接在 Python 中解析，必须先用 R 工具转换为 .h5ad。
Dask 数组支持为实验性。
sc.tl.louvain 在 scanpy 1.12 中已弃用，应使用 Leiden 聚类。
不要将 rank_genes_groups 的 p 值视为条件间严格的差异表达结果，应使用 pseudobulk 方法。
绘图函数的 save= 参数在 scanpy 1.12 中已弃用，应使用 sc.settings.autosave。
始终在过滤基因前保存原始计数：adata.raw = adata。
应仔细检查 QC 图，根据数据集质量调整阈值。
应尝试多个聚类分辨率以找到合适粒度。
应使用多个标记基因验证细胞类型注释。
基因表达图应使用 use_raw=True 以显示 .raw 中的标准化计数。
应检查 PCA 方差比以确定最佳 PC 数。
应保存中间结果，长工作流可能中途失败。

技能介绍

用途