标准单细胞 RNA-seq 分析流程：质控、归一化、降维、聚类、差异表达与可视化，并可将 Seurat 等 R 生态格式转换为 h5ad。深度学习模型请用 scvi-tools。

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] 附加包会安装 python-igraph 和 leidenalg，这是 Leiden 聚类所必需的。为保证环境可复现，建议固定版本号：uv pip install "scanpy[leiden]==1.12.1"。

对于大型或核外（out-of-core）数据集，许多函数支持 Dask 数组（实验性）：

uv pip install "scanpy[leiden]" dask

参见在Scanpy中使用dask 教程。对于GPU加速的scanpy风格操作，请使用独立的 rapids-singlecell 软件包。

如果输入是R原生的单细胞对象（.rds、.RData、Seurat 或 SingleCellExperiment），请先用R工具将其转换为 .h5ad，再用Scanpy加载。有关在 macOS、Linux 和 Windows 上由代理执行的安装和转换说明，请阅读 references/r_interop.md。

有关AnnData结构和I/O细节，请使用 anndata 技能。有关概率模型和批次校正，请使用 scvi-tools 技能。

何时使用此技能

当您需要以下操作时，应使用此技能：

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

脚本工具集（优先于从零编写代码）

本技能在 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、layers、已计算的内容、原始与归一化状态） | 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 layer + 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实现可复现的参数配置（键名与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

以下各节记录了每个脚本背后调用的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。请先进行转换：

# 有关安装R和转换所需软件包的说明，参见 references/r_interop.md。
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        # 非结构化注释（字典）
adata.obsm       # 多维细胞数据（PCA、UMAP）
adata.raw        # 原始数据备份

# 访问细胞和基因名称
adata.obs_names  # 细胞条形码
adata.var_names  # 基因名称

标准分析工作流程

1. 质量控制

识别并过滤低质量细胞和基因：

# 识别线粒体基因
adata.var['mt'] = adata.var_names.str.startswith('MT-')

# 计算QC指标
sc.pp.calculate_qc_metrics(adata, qc_vars=['mt'], inplace=True)

# 可视化QC指标
sc.pl.violin(adata, ['n_genes_by_counts', 'total_counts', 'pct_counts_mt'],
             jitter=0.4, multi_panel=True)

# 过滤细胞和基因
sc.pp.filter_cells(adata, min_genes=200)
sc.pp.filter_genes(adata, min_cells=3)
adata = adata[adata.obs.pct_counts_mt < 5, :]  # 移除高MT%细胞

双细胞（doublet）检测（可选，在归一化前对原始计数执行）：

sc.pp.scrublet(adata)  # 自scanpy 1.10起为核心API（此前位于scanpy.external.pp）
adata = adata[~adata.obs['predicted_doublet'], :].copy()

使用QC脚本进行自动化分析（从技能目录运行，或传入完整路径）：

python skills/scanpy/scripts/qc_analysis.py input_file.h5ad --output filtered.h5ad

2. 归一化和预处理

# 归一化到每个细胞10,000计数
sc.pp.normalize_total(adata, target_sum=1e4)

# 对数转换
sc.pp.log1p(adata)

# 保存原始计数供以后使用
adata.raw = adata

# 识别高可变基因
sc.pp.highly_variable_genes(adata, n_top_genes=2000)
sc.pl.highly_variable_genes(adata)

# 子集到高可变基因
adata = adata[:, adata.var.highly_variable]

# 回归掉不需要的变异
sc.pp.regress_out(adata, ['total_counts', 'pct_counts_mt'])

# 缩放数据
sc.pp.scale(adata, max_value=10)

3. 降维

# PCA
sc.tl.pca(adata, svd_solver='arpack')
sc.pl.pca_variance_ratio(adata, log=True)  # 检查肘图

# 计算邻域图
sc.pp.neighbors(adata, n_neighbors=10, n_pcs=40)

# UMAP可视化
sc.tl.umap(adata)
sc.pl.umap(adata, color='leiden')

# 替代方案：t-SNE
sc.tl.tsne(adata)

4. 聚类

# Leiden聚类（推荐）
sc.tl.leiden(adata, resolution=0.5)
sc.pl.umap(adata, color='leiden', legend_loc='on data')

# 尝试多个分辨率以找到最佳粒度
for res in [0.3, 0.5, 0.8, 1.0]:
    sc.tl.leiden(adata, resolution=res, key_added=f'leiden_{res}')

5. 标记基因识别

rank_genes_groups 仅应用于探索性的簇标记基因分析。由于细胞并非独立观测值，逐细胞的统计检验会使p值虚高。对于条件或样本之间严谨的差异表达分析，应先进行伪批量（pseudobulk）处理（见下文），再使用 pydeseq2 等工具。

# 为每个簇找到标记基因（探索性）
sc.tl.rank_genes_groups(adata, 'leiden', method='wilcoxon')

# 可视化结果
sc.pl.rank_genes_groups(adata, n_genes=25, sharey=False)
sc.pl.rank_genes_groups_heatmap(adata, n_genes=10)
sc.pl.rank_genes_groups_dotplot(adata, n_genes=5)

# 获取结果为DataFrame
markers = sc.get.rank_genes_groups_df(adata, group='0')

6. 细胞类型注释

# 为已知细胞类型定义标记基因
marker_genes = ['CD3D', 'CD14', 'MS4A1', 'NKG7', 'FCGR3A']

# 可视化标记
sc.pl.umap(adata, color=marker_genes, use_raw=True)
sc.pl.dotplot(adata, var_names=marker_genes, groupby='leiden')

# 手动注释
cluster_to_celltype = {
    '0': 'CD4 T cells',
    '1': 'CD14+ Monocytes',
    '2': 'B cells',
    '3': 'CD8 T cells',
}
adata.obs['cell_type'] = adata.obs['leiden'].map(cluster_to_celltype)

# 可视化注释类型
sc.pl.umap(adata, color='cell_type', legend_loc='on data')

7. 保存结果

# 保存处理后的数据
adata.write('results/processed_data.h5ad')

# 导出元数据
adata.obs.to_csv('results/cell_metadata.csv')
adata.var.to_csv('results/gene_metadata.csv')

常见任务

创建Publication质量的图表

保存图表时优先使用 sc.settings.autosave 和 sc.settings.figdir。在scanpy 1.12中，逐图的 save= 参数已被弃用。

# 设置高质量默认值
sc.settings.set_figure_params(dpi=300, frameon=False, figsize=(5, 5))
sc.settings.file_format_figs = 'pdf'
sc.settings.figdir = './figures/'
sc.settings.autosave = True

# 带有自定义样式的UMAP（通过autosave保存为figures/umap.pdf）
sc.pl.umap(adata, color='cell_type',
           palette='Set2',
           legend_loc='on data',
           legend_fontsize=12,
           legend_fontoutline=2,
           frameon=False)

# 标记基因热图
sc.pl.heatmap(adata, var_names=genes, groupby='cell_type',
              swap_axes=True, show_gene_labels=True)

# 点图
sc.pl.dotplot(adata, var_names=genes, groupby='cell_type')

请参考references/plotting_guide.md获取全面的可视化示例。

轨迹推断

# PAGA（基于分区的图抽象）
sc.tl.paga(adata, groups='leiden')
sc.pl.paga(adata, color='leiden')

# 扩散伪时间
adata.uns['iroot'] = np.flatnonzero(adata.obs['leiden'] == '0')[0]
sc.tl.dpt(adata)
sc.pl.umap(adata, color='dpt_pseudotime')

条件间的伪批量与差异表达

按样本和细胞类型进行伪批量处理，然后使用规范的差异表达工具（如pydeseq2），而不是逐细胞的 rank_genes_groups：

# 按样本和细胞类型聚合计数（scanpy 1.12中兼容dask）
pb = sc.get.aggregate(
    adata,
    by=['sample', 'cell_type'],
    func='sum',
    layer='counts',  # 如果有，使用原始计数layer
)
# 下游：导出pb，使用pydeseq2进行条件比较

对于簇内的快速探索性比较，rank_genes_groups 是可以接受的，但要谨慎解读p值：

adata_subset = adata[adata.obs['cell_type'] == 'T cells']
sc.tl.rank_genes_groups(adata_subset, groupby='condition',
                         groups=['treated'], reference='control')
sc.pl.rank_genes_groups(adata_subset, groups=['treated'])

基因集评分

# 对基因集表达进行细胞评分
gene_set = ['CD3D', 'CD3E', 'CD3G']
sc.tl.score_genes(adata, gene_set, score_name='T_cell_score')
sc.pl.umap(adata, color='T_cell_score')

批次校正

# ComBat批次校正
sc.pp.combat(adata, key='batch')

# 替代方案：使用Harmony或scVI（单独的包）

关键参数调整

质量控制

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，越高=更多簇）

常见陷阱和最佳实践

始终保存原始计数：在过滤基因前使用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 为输入输出的脚本，覆盖整个工作流程，并附带一条命令即可完成的端到端流程。完整的表格和链式调用示例参见上面的脚本工具集一节。每个脚本都有 --help。文件列表：

_common.py — 供其他脚本导入的共享加载/保存/图表配置辅助模块（不是CLI）
run_pipeline.py — 一条命令完成完整流程（通过flag或--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

全面的可视化指南，包括：

质量控制图
降维可视化
聚类可视化
标记基因图（热图、点图、小提琴图）
轨迹和伪时间图
Publication质量定制
多面板图
颜色 palette 和样式

创建 publication 就绪图表时参考。

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.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"

有效分析的提示

从模板开始：使用assets/analysis_template.py作为起点
首先运行QC脚本：使用scripts/qc_analysis.py进行初始过滤
根据需要参考：将工作流程和API参考加载到上下文中
在聚类上迭代：尝试多种分辨率和可视化方法
生物学验证：检查标记基因是否与预期细胞类型匹配
记录参数：记录QC阈值和分析设置
保存检查点：在关键步骤写入中间结果

Scanpy：单细胞分析