Scanpy 单细胞分析实战指南：从 scRNA-seq 原始计数到细胞类型注释的完整 Agent 工作流（scientific-agent-skills 仓库实践）

Scanpy 单细胞分析实战指南：从 scRNA-seq 原始计数到细胞类型注释的完整 Agent 工作流（scientific-agent-skills 仓库实践）

【免费下载链接】scientific-agent-skillsTurn any AI agent into an AI Scientist. The #1 Agent Skills library for science, used by 190,000+ scientists worldwide. 165 ready-to-use validated skills plus 100+ scientific databases covering biology, chemistry, medicine, and drug discovery. Compatible with Cursor, Claude Code, Codex, Pi, Antigravity, and the open Agent Skills standard.项目地址: https://gitcode.com/GitHub_Trending/cl/scientific-agent-skills

导读

本文以 scientific-agent-skills 仓库内置的 scanpy 技能（skills/scanpy/SKILL.md）为主体，系统讲解如何用 Scanpy 完成单细胞 RNA-seq（scRNA-seq）数据的标准分析流水线：质量控制、归一化、降维（PCA/UMAP/t-SNE）、Leiden 聚类、标志基因鉴定、细胞类型注释与可视化。你将掌握两套互补的实战路径：一是直接使用技能捆绑的 14 个 CLI 脚本（含一键端到端流水线），二是理解每个脚本背后的 Scanpy 核心 API 调用与关键参数，从而在需要自定义时能无缝切换到原生代码。该技能适用于 .h5ad、10X、CSV 等常见格式，也覆盖 Seurat / SingleCellExperiment 的.rds文件与.h5ad的互操作转换。

技能概览与适用场景

Scanpy 是什么

Scanpy 是构建在 AnnData 之上的可扩展 Python 单细胞分析工具包，覆盖 QC、归一化、降维、聚类、标志基因鉴定、可视化和轨迹分析等完整单细胞工作流。当前稳定版本为scanpy 1.12.x。在该技能生态中，它与其他技能有明确分工：

• 需要概率模型与批量校正时，使用scvi-tools技能；
• 处理 AnnData 数据结构与 I/O 细节时，使用anndata技能；
• 本文档技能本身则负责标准的探索性 scRNA-seq 分析。

何时使用本技能

根据 skills/scanpy/SKILL.md 的定位，本技能适用于以下场景：

• 分析单细胞 RNA-seq 数据（.h5ad、10X、CSV 格式）；
• 处理需要先转换为.h5ad的 R 生态单细胞数据集（.rds、.RData、Seurat、SingleCellExperiment）；
• 对 scRNA-seq 数据集执行质量控制的筛选；
• 生成 UMAP、t-SNE 或 PCA 可视化；
• 识别细胞簇并寻找标志基因；
• 基于基因表达进行细胞类型注释；
• 开展轨迹推断或拟时（pseudotime）分析；
• 生成出版物级别的单细胞绘图。

安装与环境要求

版本前提

本技能要求Python 3.12+（scanpy 1.12 起不再支持 Python ≤ 3.11）以及anndata ≥ 0.10。推荐使用uv进行安装：

uv pip install "scanpy[leiden]"

[leiden]extra 会安装python-igraph与leidenalg，这是运行 Leiden 聚类的必要依赖。如需可复现环境，请锁定版本：

uv pip install "scanpy[leiden]==1.12.1"

大规模数据与加速选项

对于大型或超出内存（out-of-core）的数据集，Scanpy 的许多函数支持 Dask 数组（实验性功能）：

uv pip install "scanpy[leiden]" dask

需要 GPU 加速的类似 Scanpy 操作时，可将 rapids-singlecell 作为独立包使用。

R 生态输入的转换

如果输入是 R 原生单细胞对象（.rds、.RData、Seurat 或 SingleCellExperiment），应先用 R 工具将其转换为.h5ad，再交给 Scanpy 读取。详细的跨平台（macOS、Linux、Windows）安装与转换说明见 skills/scanpy/references/r_interop.md。

开箱即用的脚本工具包（Script Toolkit）

设计理念：优先使用脚本而非手写代码

这是本技能与普通教程最大的不同：技能捆绑了一套可直接运行的 CLI 脚本，位于 skills/scanpy/scripts/，覆盖流水线的每一个常见步骤。文档明确要求 Agent优先运行这些脚本而不是手写 Scanpy 代码——它们统一处理了文件按扩展名加载、图形设置、合理默认参数、原始计数保留和进度日志。每个脚本都读写.h5ad，因此可以串联成链，且每个脚本都有--help。

所有脚本共享 skills/scanpy/scripts/_common.py 这个公共模块（负责加载、保存、图形配置与日志），运行时应保持它与其余脚本同目录。可从技能目录运行或传完整路径，图形默认输出到./figures/。

脚本速查表

一键端到端运行

# 从计数矩阵到带聚类的、含标志基因注释的对象 + 图形 + 标志基因 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 复现参数（键与下划线形式的 flag 名一致）： 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 # 查看 results/markers/*.csv，确定标签，编写映射 JSON，然后： python scripts/annotate.py clu.h5ad -o ann.h5ad --mapping celltypes.json

底层公共模块：一切脚本的一致性保证

所有脚本共享的 skills/scanpy/scripts/_common.py 提供了四个关键能力，理解它就能理解整个工具包的行为约定：

• configure_scanpy()：统一设置sc.settings.verbosity、set_figure_params(dpi=120, facecolor="white")、figdir与file_format_figs，并自动创建图形目录。默认关闭autosave，因为各脚本通过显式的save=后缀生成可预测的文件名。
• load_anndata()：按扩展名/布局自动分发——目录走sc.read_10x_mtx，.h5ad走sc.read_h5ad，.h5走sc.read_10x_h5，.loom走sc.read_loom，.csv走sc.read_csv，.tsv/.txt走sc.read_text，.mtx/.mtx.gz走sc.read；无法识别的格式会报错退出。
• save_anndata()：自动创建父目录后调用adata.write_h5ad(path)，并打印 "cells x genes" 摘要。
• summarize()：输出对象的细胞×基因维度、obs 列、obsm 键与 layers 键；其中专门过滤掉 anndata ≥ 0.13 在.layers上新增的无名None键（代表 X 本身），避免字符串拼接时报TypeError。

快速上手：基础导入与数据加载

导入与全局设置

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 # scanpy 1.12 推荐，取代已弃用的 per-plot save=

加载数据

# 来自 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文件。先转换再读取：

# 安装 R 与转换包的方法见 references/r_interop.md Rscript convert_rds_to_h5ad.R input.rds output.h5ad

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

理解 AnnData 结构

adata.X # 表达矩阵（细胞 × 基因） adata.obs # 细胞元数据（DataFrame） adata.var # 基因元数据（DataFrame） adata.uns # 非结构化注释（dict） adata.obsm # 多维细胞数据（PCA、UMAP） adata.raw # 原始数据备份 # 访问细胞与基因名称 adata.obs_names # 细胞条形码 adata.var_names # 基因名

标准分析工作流的七个步骤

本技能将标准流程归纳为七步，详见 skills/scanpy/references/analysis_workflow.md（该文件含完整代码与每步关键参数），核心要点如下：

1. 质量控制——先过滤细胞与基因，在选定阈值前检查线粒体比例与计数分布，而不是照抄默认值；
2. 归一化与预处理——归一化、log 变换、选择高变基因（HVG），并保留.raw供后续绘图使用；
3. 降维——先 PCA，再构建邻居图，最后 UMAP；
4. 聚类——选择与研究问题匹配的 Leiden 分辨率，而非默认值；
5. 标志基因鉴定——每个簇的基因排名；
6. 细胞类型注释——根据标志基因把簇映射为细胞类型；
7. 保存结果——写出注释好的 AnnData 对象。

发布级绘图、轨迹推断、条件间 pseudobulk 差异表达、基因集打分与批量校正等常见后续任务也在同一文件中。相关参考还包括 skills/scanpy/references/standard_workflow.md（完整分步工作流）与 skills/scanpy/references/plotting_guide.md（可视化指南）。

各步骤的关键 API 调用（来自脚本源码）

质量控制（qc_analysis.py）：先标记线粒体/核糖体/血红蛋白基因（同时支持人鼠命名，如MT-/mt-/Mt-前缀、RPS/RPL/Rps/Rpl前缀、^HB[^P]正则），再计算 QC 指标：

adata.var["mt"] = adata.var_names.str.startswith(("MT-", "mt-", "Mt-")) qc_vars = annotate_gene_classes(adata) sc.pp.calculate_qc_metrics(adata, qc_vars=qc_vars, percent_top=None, log1p=False, inplace=True) sc.pl.violin(adata, ["n_genes_by_counts", "total_counts", "pct_counts_mt"], jitter=0.4, multi_panel=True, show=False, save="_qc_before_violin.png") sc.pp.filter_cells(adata, min_genes=200) sc.pp.filter_genes(adata, min_cells=3) adata = adata[adata.obs["pct_counts_mt"] < 5, :].copy()

归一化与预处理（preprocess.py）：先把原始计数存入adata.layers["counts"]，再归一化、log1p、选 HVG，并把完整的归一化 log 矩阵存入adata.raw，使后续 marker/表达图能用use_raw=True：

adata.layers["counts"] = adata.X.copy() sc.pp.normalize_total(adata, target_sum=1e4) sc.pp.log1p(adata) sc.pp.highly_variable_genes(adata, n_top_genes=2000, flavor="seurat", batch_key=None) adata.raw = adata # 可选 sc.pp.regress_out(adata, ["total_counts", "pct_counts_mt"]) sc.pp.scale(adata, max_value=10)

降维（reduce_dimensions.py）：注意区分--n-comps（计算的主成分数，默认 50，代码会自动取min(n_comps, n_vars-1, n_obs-1)）与--n-pcs（用于 kNN 图的 PC 数，默认 40）。写出 PCA 方差比肘形图帮助选--n-pcs：

sc.tl.pca(adata, n_comps=n_comps, svd_solver="arpack") sc.pl.pca_variance_ratio(adata, n_pcs=n_comps, log=True, show=False, save="_variance.png") sc.pp.neighbors(adata, n_neighbors=15, n_pcs=40, use_rep=None) sc.tl.umap(adata) # 可选 sc.tl.tsne(adata, use_rep="X_pca")

批量校正（batch_correct.py）支持三种方法，需在已算好 PCA 的归一化对象上运行：

• harmony（默认，最快，推荐）：校正 PCA 嵌入，写入obsm['X_pca_harmony']，需要harmonypy；后续用reduce_dimensions.py --use-rep X_pca_harmony接续；
• bbknn：批量均衡 kNN 图（替代sc.pp.neighbors），随后可直接聚类，需要bbknn；
• combat：原地校正表达矩阵（sc.pp.combat），内置于 scanpy。

聚类（cluster.py）在预先计算好的邻居图上运行，支持一次传入多个分辨率，多分辨率时 obs 键命名为<algorithm>_<res>：

sc.tl.leiden(adata, resolution=0.5, key_added="leiden", flavor="igraph", n_iterations=2, directed=False)

flavor="igraph"是 scanpy 1.12 默认推荐的 Leiden 后端。

标志基因鉴定（find_markers.py）：

sc.tl.rank_genes_groups(adata, "leiden", method="wilcoxon", use_raw=True) sc.pl.rank_genes_groups(adata, n_genes=25, sharey=False, show=False, save="_markers.png") sc.pl.rank_genes_groups_dotplot(adata, n_genes=5, show=False, save="_markers_dotplot.png") sc.pl.rank_genes_groups_heatmap(adata, n_genes=10, show=False, save="_markers_heatmap.png")

脚本会为每个簇写出单独的markers_<groupby>_<group>.csv，并合并为markers_<groupby>_all.csv。

关键参数速查与调节建议

质量控制

• 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：HVG 选择参数

降维

• n_pcs：主成分数量（参考方差比图确定）
• n_neighbors：邻居数（通常 10–30）

聚类

• resolution：聚类粒度（0.4–1.2，越大簇越多）

从脚本到自定义：一键流水线的内部调用链

run_pipeline.py 把上述步骤串联成 8 个阶段，其内部的关键设计值得在自定义时借鉴：

1. 加载与去重：load_anndata+adata.var_names_make_unique()；
2. QC 与过滤：标记线粒体基因 →calculate_qc_metrics→ 小提琴图 →filter_cells/filter_genes→ 按max_genes与mt_threshold切片 → 可选sc.pp.scrublet去掉predicted_doublet；
3. 归一化 + log1p + HVG：先存layers["counts"]，然后依据hvg_flavor决定 HVG 是在归一化前（seurat_v3，要求原始计数）还是后执行，最后adata.raw = adata；
4. 可选 scale/regress：只在高变基因子集work上进行（adata[:, adata.var["highly_variable"]]），减少内存；
5. PCA + 批量校正：sc.tl.pca(work, svd_solver="arpack")，harmony 写出X_pca_harmony作为后续use_rep，combat 则校正后重跑 PCA；
6. Neighbors + UMAP：在指定use_rep上构建图；
7. Leiden 聚类：flavor="igraph", n_iterations=2, directed=False，输出leiden上色 UMAP；
8. 标志基因：在全基因对象adata上（而非 HVG 子集）跑rank_genes_groups，因为簇标签与嵌入已回填到全基因对象中——adata.obs["leiden"] = work.obs["leiden"].values、adata.obsm["X_pca"]、adata.obsm["X_umap"]等——保证标志基因检测使用所有基因。

这种"在 HVG 子集上做计算、把结果回填到全基因对象再测标志基因"的设计，是内存效率与生物学完整性的良好平衡。

细胞类型注释、基因签名打分与 pseudobulk

细胞类型注释

annotate.py 支持两种映射文件：JSON（{"0": "CD4 T cells", ...}）或两列 CSV（cluster,cell_type）。仓库预置了 assets/celltype_mapping.json，包含 8 种经典 PBMC 细胞类型（CD4 T 细胞、CD14+ 单核细胞、B 细胞、CD8 T 细胞、NK 细胞、FCGR3A+ 单核细胞、树突状细胞、血小板）。映射后未命中的簇自动标为Unknown。还可用--markers传入{cell_type: [genes]}JSON，先绘制参考 dotplot 辅助决策：

python scripts/annotate.py clu.h5ad -o ann.h5ad --mapping assets/celltype_mapping.json python scripts/annotate.py clu.h5ad --markers assets/gene_signatures.json --cluster-key leiden

基因签名打分与细胞周期

score_genes.py 为每个命名基因集计算一个<name>_scoreobs 列，内置了 Tirosh et al. (2016) 的人类 S 期（43 个基因）与 G2M 期（54 个基因）列表用于--cell-cycle。预置的 assets/gene_signatures.json 覆盖 T 细胞、B 细胞、单核细胞、NK 细胞、细胞毒性、树突状细胞与耗竭（exhaustion）签名：

python scripts/score_genes.py ann.h5ad -o scored.h5ad --gene-sets assets/gene_signatures.json python scripts/score_genes.py ann.h5ad -o scored.h5ad --cell-cycle

Pseudobulk 差异表达

pseudobulk.py 用sc.get.aggregate在--by（如sample cell_type）分组内对countslayer 的原始计数求和，输出_counts.csv与_samples.csv，供 pydeseq2/edgeR/limma 做严谨的条件比较——这是比逐细胞rank_genes_groups统计上更正确的路径：

python scripts/pseudobulk.py ann.h5ad --by sample cell_type --out-prefix results/pb

分析与绘图模板

assets/analysis_template.py 提供从数据加载到细胞类型注释的完整分析模板，顶部是集中的 CONFIGURATION 区（MIN_GENES、MT_THRESHOLD、N_TOP_GENES、N_PCS、N_NEIGHBORS、LEIDEN_RESOLUTION等），可按需复制定制：

cp assets/analysis_template.py my_analysis.py # 编辑参数后运行 python my_analysis.py

常见陷阱与最佳实践

1. 始终保存原始计数：在过滤基因前执行adata.raw = adata；
2. 仔细检查 QC 图：根据数据质量调整阈值，而不是照搬默认；
3. 使用 Leiden 聚类：sc.tl.louvain在 scanpy 1.12 中已弃用；
4. 尝试多个聚类分辨率：找到最优粒度；
5. 验证细胞类型注释：使用多个标志基因交叉确认；
6. 基因表达图用use_raw=True：显示来自.raw的归一化计数；
7. 检查 PCA 方差比：确定最优 PC 数；
8. 保存中间结果：长工作流可能中途失败，关键节点要写 checkpoint；
9. DE 请用 pseudobulk：不要把rank_genes_groups的 p 值当作组间严谨差异表达证据（find_markers.py 与 pseudobulk.py 的 docstring 都明确强调了这一统计陷阱）；
10. 通过设置保存图形：用sc.settings.autosave而非已弃用的绘图函数save=参数；
11. R 对象先转换再进 Scanpy：用 R 包把 Seurat 或 SingleCellExperiment 的.rds转为.h5ad，保留计数、元数据与基因标识符。

配套资源导航

技能内置了多份高价值参考文档与资源，均可按需加载进上下文：

• skills/scanpy/references/standard_workflow.md：完整分步工作流，含数据加载、带可视化的 QC、归一化与缩放、特征选择、降维（PCA/UMAP/t-SNE）、Leiden 聚类、Scrublet 双细胞检测与 pseudobulk 聚合、标志基因、注释、轨迹推断与差异表达；
• skills/scanpy/references/api_reference.md：按模块组织的 Scanpy 函数速查（sc.read_*/adata.write_*、sc.pp.*、sc.tl.*、sc.pl.*、AnnData 操作、设置与工具函数）；
• skills/scanpy/references/plotting_guide.md：完整可视化指南（QC 图、降维图、聚类图、标志基因热图/dotplot/小提琴图、轨迹与拟时图、出版物级定制、多面板图、调色板与样式）；
• skills/scanpy/references/r_interop.md：Agent 运行手册，覆盖在 macOS/Linux/Windows 安装 R、安装 CRAN/Bioconductor 转换包、检查.rds/.RData输入、把 Seurat 或 SingleCellExperiment 对象转为.h5ad并在 Scanpy 中验证结果。其核心原则是：不要在 Python 里直接解析 Seurat.rds，先用 R 反序列化并写出.h5ad；转换前先检查对象类型（Seurat、SingleCellExperiment 或 list），不要仅凭文件名猜测；转换过程保留原始计数、元数据与降维结果；
• assets/pipeline_config.json：供run_pipeline.py --config使用的完整参数集（键与下划线形式的 flag 名一一对应，例如min_genes、mt_threshold、n_pcs、resolution、batch_method等）；
• 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 与 https://mojaveazure.github.io/seurat-disk/
• 最佳实践参考文献：Luecken & Theis (2019) "Current best practices in single-cell RNA-seq"

高效分析建议

1. 从模板起步：使用assets/analysis_template.py作为起点；
2. 先跑 QC 脚本：用scripts/qc_analysis.py做初始过滤；
3. 按需查阅参考：把工作流与 API 参考加载进上下文；
4. 迭代聚类：尝试多种分辨率与可视化方法；
5. 做生物学验证：核对标志基因是否与预期细胞类型吻合；
6. 记录参数：保存 QC 阈值与分析设置；
7. 保存检查点：在关键步骤写出中间结果。

【免费下载链接】scientific-agent-skillsTurn any AI agent into an AI Scientist. The #1 Agent Skills library for science, used by 190,000+ scientists worldwide. 165 ready-to-use validated skills plus 100+ scientific databases covering biology, chemistry, medicine, and drug discovery. Compatible with Cursor, Claude Code, Codex, Pi, Antigravity, and the open Agent Skills standard.项目地址: https://gitcode.com/GitHub_Trending/cl/scientific-agent-skills