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-seqscRNA-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.12scanpy 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/。脚本速查表脚本用途典型调用run_pipeline.py一条命令完成全流程加载 → QC → 归一化 → HVG → PCA →批量校正→ UMAP → Leiden → 标志基因python scripts/run_pipeline.py raw.h5ad -o processed.h5adinspect_data.py摘要未知数据集形状、obs/var、layers、已计算内容、raw 与归一化状态python scripts/inspect_data.py data.h5adconvert.py加载任意格式10x 目录/.h5、csv、loom、mtx并写出.h5adpython scripts/convert.py 10x_dir/ -o data.h5adqc_analysis.pyQC 指标、前后对比图、过滤、可选 Scrublet 双细胞检测python scripts/qc_analysis.py raw.h5ad -o qc.h5ad --scrubletpreprocess.py归一化、log1p、HVG、可选 scale/regress保留countslayer 与rawpython scripts/preprocess.py qc.h5ad -o norm.h5adreduce_dimensions.pyPCA 方差图、neighbors、UMAP、可选 t-SNEpython scripts/reduce_dimensions.py norm.h5ad -o red.h5adbatch_correct.py整合harmony / bbknn / combatpython scripts/batch_correct.py red.h5ad -o int.h5ad --method harmony --batch-key samplecluster.py一个或多个分辨率下的 Leiden或 louvain聚类python scripts/cluster.py red.h5ad -o clu.h5ad --resolution 0.3 0.6 1.0find_markers.pyrank_genes_groups 每簇 CSV 标志基因图python scripts/find_markers.py clu.h5ad --groupby leiden -o clu.h5adannotate.py从 JSON/CSV 将簇映射为细胞类型可选标志基因参考 dotplotpython scripts/annotate.py clu.h5ad -o ann.h5ad --mapping map.jsonscore_genes.py基因签名打分JSON和/或细胞周期分期python scripts/score_genes.py ann.h5ad -o scored.h5ad --gene-sets sigs.jsonpseudobulk.py按样本 × 细胞类型聚合计数矩阵供 pydeseq2 使用python scripts/pseudobulk.py ann.h5ad --by sample cell_type --out-prefix pbsubset.py按 obs 值或基因列表取子集可选清除过期嵌入python scripts/subset.py ann.h5ad -o tcells.h5ad --obs cell_type --keep T cellsplot.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底层公共模块一切脚本的一致性保证所有脚本共享的 skills/scanpy/scripts/_common.py 提供了四个关键能力理解它就能理解整个工具包的行为约定configure_scanpy()统一设置sc.settings.verbosity、set_figure_params(dpi120, facecolorwhite)、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(dpi80, facecolorwhite) 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) # 来自 h5adAnnData 格式 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.h5adadata 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该文件含完整代码与每步关键参数核心要点如下质量控制——先过滤细胞与基因在选定阈值前检查线粒体比例与计数分布而不是照抄默认值归一化与预处理——归一化、log 变换、选择高变基因HVG并保留.raw供后续绘图使用降维——先 PCA再构建邻居图最后 UMAP聚类——选择与研究问题匹配的 Leiden 分辨率而非默认值标志基因鉴定——每个簇的基因排名细胞类型注释——根据标志基因把簇映射为细胞类型保存结果——写出注释好的 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_varsqc_vars, percent_topNone, log1pFalse, inplaceTrue) sc.pl.violin(adata, [n_genes_by_counts, total_counts, pct_counts_mt], jitter0.4, multi_panelTrue, showFalse, save_qc_before_violin.png) sc.pp.filter_cells(adata, min_genes200) sc.pp.filter_genes(adata, min_cells3) adata adata[adata.obs[pct_counts_mt] 5, :].copy()归一化与预处理preprocess.py先把原始计数存入adata.layers[counts]再归一化、log1p、选 HVG并把完整的归一化 log 矩阵存入adata.raw使后续 marker/表达图能用use_rawTrueadata.layers[counts] adata.X.copy() sc.pp.normalize_total(adata, target_sum1e4) sc.pp.log1p(adata) sc.pp.highly_variable_genes(adata, n_top_genes2000, flavorseurat, batch_keyNone) adata.raw adata # 可选 sc.pp.regress_out(adata, [total_counts, pct_counts_mt]) sc.pp.scale(adata, max_value10)降维reduce_dimensions.py注意区分--n-comps计算的主成分数默认 50代码会自动取min(n_comps, n_vars-1, n_obs-1)与--n-pcs用于 kNN 图的 PC 数默认 40。写出 PCA 方差比肘形图帮助选--n-pcssc.tl.pca(adata, n_compsn_comps, svd_solverarpack) sc.pl.pca_variance_ratio(adata, n_pcsn_comps, logTrue, showFalse, save_variance.png) sc.pp.neighbors(adata, n_neighbors15, n_pcs40, use_repNone) sc.tl.umap(adata) # 可选 sc.tl.tsne(adata, use_repX_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随后可直接聚类需要bbknncombat原地校正表达矩阵sc.pp.combat内置于 scanpy。聚类cluster.py在预先计算好的邻居图上运行支持一次传入多个分辨率多分辨率时 obs 键命名为algorithm_ressc.tl.leiden(adata, resolution0.5, key_addedleiden, flavorigraph, n_iterations2, directedFalse)flavorigraph是 scanpy 1.12 默认推荐的 Leiden 后端。标志基因鉴定find_markers.pysc.tl.rank_genes_groups(adata, leiden, methodwilcoxon, use_rawTrue) sc.pl.rank_genes_groups(adata, n_genes25, shareyFalse, showFalse, save_markers.png) sc.pl.rank_genes_groups_dotplot(adata, n_genes5, showFalse, save_markers_dotplot.png) sc.pl.rank_genes_groups_heatmap(adata, n_genes10, showFalse, save_markers_heatmap.png)脚本会为每个簇写出单独的markers_groupby_group.csv并合并为markers_groupby_all.csv。关键参数速查与调节建议质量控制min_genes每个细胞的最少基因数通常 200–500min_cells每个基因的最少细胞数通常 3–10pct_counts_mt线粒体比例阈值通常 5–20%归一化target_sum每个细胞归一化后的目标计数默认 1e4特征选择n_top_genesHVG 数量通常 2000–3000min_mean、max_mean、min_dispHVG 选择参数降维n_pcs主成分数量参考方差比图确定n_neighbors邻居数通常 10–30聚类resolution聚类粒度0.4–1.2越大簇越多从脚本到自定义一键流水线的内部调用链run_pipeline.py 把上述步骤串联成 8 个阶段其内部的关键设计值得在自定义时借鉴加载与去重load_anndataadata.var_names_make_unique()QC 与过滤标记线粒体基因 →calculate_qc_metrics→ 小提琴图 →filter_cells/filter_genes→ 按max_genes与mt_threshold切片 → 可选sc.pp.scrublet去掉predicted_doublet归一化 log1p HVG先存layers[counts]然后依据hvg_flavor决定 HVG 是在归一化前seurat_v3要求原始计数还是后执行最后adata.raw adata可选 scale/regress只在高变基因子集work上进行adata[:, adata.var[highly_variable]]减少内存PCA 批量校正sc.tl.pca(work, svd_solverarpack)harmony 写出X_pca_harmony作为后续use_repcombat 则校正后重跑 PCANeighbors UMAP在指定use_rep上构建图Leiden 聚类flavorigraph, n_iterations2, directedFalse输出leiden上色 UMAP标志基因在全基因对象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, ...}或两列 CSVcluster,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-cyclePseudobulk 差异表达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常见陷阱与最佳实践始终保存原始计数在过滤基因前执行adata.raw adata仔细检查 QC 图根据数据质量调整阈值而不是照搬默认使用 Leiden 聚类sc.tl.louvain在 scanpy 1.12 中已弃用尝试多个聚类分辨率找到最优粒度验证细胞类型注释使用多个标志基因交叉确认基因表达图用use_rawTrue显示来自.raw的归一化计数检查 PCA 方差比确定最优 PC 数保存中间结果长工作流可能中途失败关键节点要写 checkpointDE 请用 pseudobulk不要把rank_genes_groups的 p 值当作组间严谨差异表达证据find_markers.py 与 pseudobulk.py 的 docstring 都明确强调了这一统计陷阱通过设置保存图形用sc.settings.autosave而非已弃用的绘图函数save参数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.mdAgent 运行手册覆盖在 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.htmlscverse 生态https://scverse.org/相关工具squidpy、scvi-tools、cellrankR 互操作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 阈值与分析设置保存检查点在关键步骤写出中间结果。【免费下载链接】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创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考