单细胞测序数据分析这几年在生信领域越来越常见而 Scanpy 作为 Python 生态中最主流的单细胞分析框架配合 Jupyter Notebook 的交互式环境几乎成了入门单细胞分析的标配组合。不过很多初学者在配置环境、读取数据、理解 AnnData 结构这些环节就被卡住了。本文将围绕 Jupyter Notebook 基础操作和 Scanpy 入门实战展开从环境搭建到完整分析流程逐步拆解帮你建立一套可以直接上手复用的分析路径。写这篇文章的初衷很简单我在学习单细胞数据分析时最大的障碍不是算法本身而是工具链不熟练。Jupyter Notebook 的交互特性非常适合单细胞数据这种“探索式分析”而 Scanpy 的 API 设计又高度依赖这种交互模式两者结合能极大提升分析效率。文中会覆盖环境准备、Notebook 基础操作、AnnData 数据结构、Scanpy 完整分析流程、常见报错排查和工程化建议新手可以按顺序阅读有基础的读者可以直接跳到实战部分。1. 背景与核心概念1.1 什么是 Jupyter NotebookJupyter Notebook 是一个开源的 Web 交互式计算环境允许你在浏览器中创建和共享包含代码、文本、公式、图像和可视化图表的文档。它最初是 IPython Notebook 项目后来发展为独立的 Jupyter 项目目前已经成为数据科学和科研计算领域最常用的工具之一。对于生信分析来说Jupyter Notebook 的核心价值在于“分块执行”。传统 Python 脚本是一次性运行整个文件而 Notebook 允许你按 Cell单元格逐段执行代码随时查看中间结果发现异常可以立即修改再重新运行。这种工作方式非常适合单细胞数据分析——因为单细胞分析是一个高度迭代的过程你需要反复调整质控阈值、聚类分辨率、可视化参数并在每一步都观察结果分布。Jupyter Notebook 支持两种核心 Cell 类型Code Cell 用于执行 Python 代码Markdown Cell 用于写说明文档。分析过程中的每个步骤都可以用 Markdown 记录思路、用 Code 执行代码、用输出区域展示图表最终导出的 HTML 或 Markdown 文件本身就是一份完整可复现的分析报告。1.2 什么是 ScanpyScanpySingle-Cell Analysis in Python是一个基于 Python 的高效单细胞数据分析工具包专门用于处理大规模单细胞转录组测序数据。它提供了从数据读取、质控过滤、归一化、降维、聚类到差异表达分析、可视化的一整套流程。Scanpy 底层依赖 AnnData 数据结构来组织和存储数据。AnnData 的设计灵感来自 R 语言生态中的 Seurat 对象它把基因表达矩阵、细胞元数据、基因元数据和降维结果统一封装在一个对象中使得数据操作和分析流程更加系统化。Scanpy 与 Seurat 是当前单细胞分析领域两大主流工具。两者的选择主要取决于你的技术背景如果你更熟悉 Python 生态对数据科学库NumPy、Pandas、Matplotlib有基础那么 Scanpy 是更自然的选择如果你或者你的团队长期使用 R那么 Seurat 可能更顺手。但需要说明的是Scanpy 在处理超大样本量例如十万级细胞时通常比 Seurat 更高效这也是很多生信流程选择 Scanpy 的原因之一。1.3 Jupyter Notebook 与 Jupyter Lab 的区别很多初学者会纠结 Jupyter Notebook 和 Jupyter Lab 到底选哪个。简单来说Jupyter Lab 是 Jupyter Notebook 的下一代界面它保留了 Notebook 的全部核心功能同时增加了文件管理、多窗口分栏、终端支持等能力。对比维度Jupyter NotebookJupyter Lab界面风格单一文档界面较简洁多标签页工作台可自由分栏文件管理需要回到 Dashboard 管理文件左侧内置文件浏览器多文档操作不支持同时编辑多个 Notebook支持并排查看多个 Notebook终端支持不支持内置终端可执行 Shell 命令插件生态较少支持丰富扩展插件适用场景快速上手、轻量使用复杂分析流程、多文件协作如果你是刚入门直接用 Jupyter Notebook 就够了不必要在工具选择上花太多时间。等后续分析流程复杂化、需要同时查看多个文档时再切换到 Jupyter Lab 会更合适。2. 环境准备与版本说明2.1 安装 AnacondaAnaconda 是目前最推荐的 Python 发行版它内置了 Jupyter Notebook、Jupyter Lab、NumPy、Pandas、Matplotlib 等数据科学常用库省去了手动安装依赖的麻烦。访问 Anaconda 官网下载对应系统的安装包即可。下载时建议选择最新的稳定版本安装过程中保持默认选项。Windows 用户安装时需要注意勾选“Add Anaconda to my PATH environment variable”选项部分新版本默认不勾选否则后续在命令行中调用 conda 命令会失败。安装完成后打开命令行工具Windows 用户可以使用 Anaconda PromptmacOS/Linux 用户使用 Terminal输入以下命令验证安装conda --version如果能看到版本号输出就说明 Anaconda 安装成功。版本号会因你下载的安装包而异比如常见的conda 24.x.x本文后续命令在不同版本下均可使用。2.2 创建独立的 Python 环境单细胞分析涉及大量依赖库不同的项目可能需要不同版本的工具包。为了避免环境混乱强烈建议为单细胞分析创建一个独立的 conda 环境。在命令行中执行conda create -n scanpy-env python3.10 -y这里-n scanpy-env指定环境名称你可以按自己的习惯命名例如scrna或sc-analysis。python3.10指定 Python 版本具体版本号请根据你安装的 Anaconda 版本和 Scanpy 官方要求调整不必完全一致。创建完成后激活环境conda activate scanpy-env激活成功后命令行提示符前面会出现(scanpy-env)字样表示当前处于独立环境中。2.3 安装 Scanpy 及相关依赖激活环境后安装 Scanpy。建议使用 conda 安装因为 conda 会自动处理底层依赖如 HDF5、BLAS 等的兼容问题conda install -y scanpy如果 conda 安装速度较慢也可以使用 pip 安装。但需要注意pip 安装 Scanpy 时可能会遇到部分底层库的编译问题建议优先尝试上面的 conda 方式。安装完成后验证python -c import scanpy as sc; print(sc.__version__)如果输出版本号说明安装成功。Scanpy 的版本更新比较频繁新版本会不断优化算法性能和 API 细节本文示例代码在常见版本下均可运行但如果遇到 API 报错请以当前版本的官方文档为准。同时确认 Jupyter Notebook 在当前环境中可用jupyter notebook --version如果提示找不到命令需要执行conda install -y jupyter notebook2.4 启动 Jupyter Notebook在已激活的 scanpy-env 环境中进入你想要存放分析项目的目录然后启动 Jupyter Notebookcd ~/projects/scanpy-tutorial jupyter notebook启动后默认浏览器会自动打开 Jupyter Notebook 的 Dashboard 页面地址通常是http://localhost:8888。你可以在这里新建 Notebook、浏览文件、管理目录。如果你是在服务器或远程环境中使用启动时建议添加--no-browser参数同时指定端口jupyter notebook --no-browser --port8899然后在本地浏览器中通过http://服务器IP:8899访问必要时需要配置 SSH 隧道。3. Jupyter Notebook 基础操作3.1 创建与保存 Notebook在 Jupyter Notebook Dashboard 页面右上角点击“New”选择“Python 3”即可创建一个新的 Notebook。新建后Notebook 默认包含一个 Code Cell你可以在其中输入 Python 代码并按Shift Enter执行。Notebook 的保存使用Ctrl SmacOS 为Command S也可以点击工具栏上的保存图标。Notebook 文件以.ipynb为扩展名本质上是 JSON 格式里面保存了代码、输出结果、Markdown 文本等全部内容。这里需要特别注意Notebook 保存的是代码和输出不是运行时的变量状态。如果你关闭浏览器但没有保存未保存的代码和输出会丢失但已经运行过的变量内存状态也会随着内核关闭而清空。所以每次分析结束前记得手动保存并且导出分析结果。3.2 Cell 类型与快捷键Notebook 中的 Cell 分为三种类型Code Cell执行 Python 代码显示代码输出结果。Markdown Cell编写富文本说明支持 LaTeX 公式、图片、表格等。Raw Cell保持原始文本输出不会渲染也不会执行。工具栏的下拉菜单可以切换 Cell 类型键盘快捷键M切换为 MarkdownY切换回 Code。下面列出最常用的快捷键快捷键功能Shift Enter执行当前 Cell 并移动到下一个Ctrl Enter执行当前 Cell不移动Alt Enter执行当前 Cell 并在下方插入新 CellA/B在当前 Cell 上方 / 下方插入新 CellD D删除当前 CellM/Y切换为 Markdown / Code 类型Ctrl S保存文件Z撤销删除 Cell当你按快捷键没反应时先检查当前是否处于编辑模式。Notebook 有命令模式和编辑模式之分按Esc进入命令模式按Enter进入编辑模式绝大多数快捷键都只会在命令模式下生效。3.3 Magic 命令Magic 命令是 IPython 提供的一组以%开头的增强命令在单细胞分析中非常实用。最常用的几个# 在 Notebook 中显示 matplotlib 图像 %matplotlib inline # 计时执行 %time some_function() # 查看变量的内存占用 %whos%matplotlib inline是数据分析中最常用的 Magic 命令它保证绘图结果显示在 Notebook 输出区域中而不是弹出独立窗口。Scanpy 的可视化函数都是基于 Matplotlib 的所以每次新建分析 Notebook 后建议在第一个代码块中执行这个命令。另外还有一个%load_ext和%autoreload组合用于自动加载修改过的代码模块在自定义函数较多时会很有帮助。3.4 在 PyCharm 中使用 Jupyter Notebook很多初学者在 PyCharm 中接触 Jupyter Notebook这里单独说明一下。PyCharm 专业版内置了 Jupyter Notebook 支持用 PyCharm 打开.ipynb文件后可以直接在 IDE 中逐 Cell 运行代码并且能看到图像输出。使用步骤在 PyCharm 中打开项目文件夹。双击.ipynb文件。PyCharm 会提示选择 Jupyter 服务器选择“Managed Server”由 PyCharm 自动管理即可。检查右下角的 Python 解释器是否为你的 scanpy-env 环境。点击 Cell 左侧的绿色运行按钮执行代码。如果你使用的是 PyCharm 社区版则默认不支持 Jupyter Notebook需要安装 Jupyter 插件注意插件支持情况随版本变化或者继续使用浏览器方式运行 Notebook。3.5 如何在其他浏览器中打开 Jupyter Notebook默认情况下 Jupyter Notebook 会调用系统默认浏览器。如果你希望使用 Chrome 或其他浏览器打开可以修改 Jupyter 配置文件。生成配置文件jupyter notebook --generate-config然后编辑生成的配置文件# 找到以下行并取消注释替换为你的浏览器路径 c.NotebookApp.browser C:/Program Files/Google/Chrome/Application/chrome.exeWindows 用户可以打开配置文件后搜索NotebookApp.browser关键字修改后保存并重新启动 Jupyter Notebook 即可。另一个更快的临时方案是复制终端输出的带token的完整 URL手动粘贴到目标浏览器的地址栏中。3.6 Windows 下 Jupyter Notebook 打开后空白怎么办Windows 用户经常遇到 Jupyter Notebook 页面显示空白或无法加载的问题常见原因和解决方案如下原因一浏览器代理或防火墙拦截。如果你开启了一些代理工具local host 请求可能被拦截。解决方案是以无代理模式访问或者将localhost:8888以及127.0.0.1加入代理例外列表。原因二Jupyter 版本和浏览器缓存冲突。可以尝试清除浏览器缓存或者在启动时指定--no-browser然后手动从终端复制 URL 访问。原因三安装问题导致静态资源加载失败。运行以下命令修复 Jupyter Notebookjupyter contrib nbextension install --user jupyter nbextension enable --py --sys-prefix widgetsnbextension如果依然空白可以考虑升级 notebook 版本pip install --upgrade notebook原因四使用 Edge 或 IE 等兼容性问题。建议优先使用 Chrome 或 Firefox 访问 Notebook。4. Scanpy 核心数据结构AnnData4.1 AnnData 是什么AnnDataAnnotated Data是 Scanpy 和整个 Python 单细胞生态的数据容器。它由一个 Python 类anndata.AnnData定义核心设计是“一张表达矩阵 两组元数据 多组分析结果”。一个 AnnData 对象主要有以下几个核心部分X表达矩阵行为细胞列为基因通常是稀疏矩阵以减少内存占用。obs细胞层面的元数据DataFrame 格式每一行对应一个细胞例如样本编号、批次、细胞类型注释等。var基因层面的元数据DataFrame 格式每一行对应一个基因例如基因名称、高变基因标记等。obsm细胞层面的降维结果例如 PCA、UMAP、tSNE 坐标。varm基因层面的降维数据。uns非结构化的分析结果和注释信息例如聚类配色方案、差异表达结果。layers多个表达矩阵层用于存储原始计数、归一化后数据等。4.2 创建 AnnData 对象虽然实际分析中绝大多数 AnnData 对象都是通过读取数据文件生成的但为了理解数据结构我们可以手动创建一个最小的 AnnData 对象import numpy as np import pandas as pd import anndata as ad # 构造一个 3 个细胞、5 个基因的表达矩阵 X np.array([ [1, 0, 3, 0, 0], [2, 1, 0, 4, 0], [0, 0, 1, 0, 5], ]) # 细胞元数据 obs pd.DataFrame( { cell_type: [T cell, B cell, NK cell], sample_id: [s1, s1, s2], }, index[cell_1, cell_2, cell_3], # 必须指定索引 ) # 基因元数据 var pd.DataFrame( { gene_symbol: [GENE1, GENE2, GENE3, GENE4, GENE5], highly_variable: [True, False, True, False, True], }, index[gene_1, gene_2, gene_3, gene_4, gene_5], # 必须指定索引 ) # 创建 AnnData 对象 adata ad.AnnData(XX, obsobs, varvar) print(adata)输出结果AnnData object with n_obs × n_vars 3 × 5 obs: cell_type, sample_id var: gene_symbol, highly_variable4.3 AnnData 的常用操作访问表达矩阵# 获取表达矩阵 print(adata.X) print(adata.X.shape)访问 obs / var 元数据# 细胞元数据 print(adata.obs.head()) # 基因元数据 print(adata.var.head())筛选细胞或基因# 筛选 T cell adata_t adata[adata.obs[cell_type] T cell] print(adata_t) # 筛选高变基因 adata_hvg adata[:, adata.var[highly_variable]] print(adata_hvg)AnnData 的索引方式与 Pandas DataFrame 类似adata[行筛选, 列筛选]行是细胞列是基因。这个操作在后续质控和特征筛选时会频繁用到。5. Scanpy 完整单细胞分析实战5.1 数据读取Scanpy 支持多种单细胞数据格式最常见的包括10x Genomics 标准输出使用sc.read_10x_h5()读取 h5 文件或sc.read_10x_mtx()读取 mtx 目录。H5AD 格式Scanpy 原生格式使用sc.read_h5ad()读取保存时使用write_h5ad()。CSV / TSV / TXT 表达矩阵使用sc.read_csv()、sc.read_text()读取。为了便于入门演示这里使用 Scanpy 内置的 PBMC 3K 数据集来自 10x Genomics 的外周血单个核细胞包含约 2700 个细胞。这个数据集是 Scanpy 官方教程的标准示例非常适合学习流程。import scanpy as sc # 设置图像显示 sc.settings.verbosity 3 # 输出信息详细程度 sc.settings.set_figure_params(dpi100, dpi_save200) # 图像分辨率 # 读取内置数据 adata sc.datasets.pbmc3k() print(adata)输出结果AnnData object with n_obs × n_vars 2700 × 32738 var: gene_ids, n_cells可以看到数据集包含 2700 个细胞、32738 个基因var中有gene_idsEnsembl 基因 ID和n_cells信息。由于基因 ID 是 Ensembl 格式不方便阅读我们将其转换为人易读的基因符号。使用 Scanpy 内置的基因注释功能在较新版本中可以这样操作# 使用内置基因符号 adata.var[gene_symbol] adata.var_names注意不同版本的 Scanpy 对基因注释的处理方式略有不同如果你的数据读取后已经有基因符号可以跳过这一步。5.2 质量控制单细胞数据中不可避免会包含低质量细胞和无效基因。质量控制的核心是设置合理阈值过滤掉异常值。首先计算质控指标Scanpy 的sc.pp.calculate_qc_metrics可以生成线粒体基因比例、基因计数等指标。线粒体基因通常以MT-前缀开头adata.var[mt] adata.var_names.str.startswith(MT-) # 计算质控指标 sc.pp.calculate_qc_metrics(adata, qc_vars[mt], percent_topNone, inplaceTrue) print(adata.obs[[n_genes_by_counts, total_counts, pct_counts_mt]].head())结果输出六个示例细胞的数据包含三个关键指标每个细胞检测到的基因数量、总 UMI 计数、线粒体基因比例。然后进行过滤# 过滤细胞基因数量在 200 到 2500 之间线粒体比例低于 5% sc.pp.filter_cells(adata, min_genes200) sc.pp.filter_cells(adata, max_genes2500) sc.pp.filter_cells(adata, min_counts500) # 过滤线粒体高比例细胞 adata adata[adata.obs[pct_counts_mt] 5, :] # 过滤基因至少在 3 个细胞中表达 sc.pp.filter_genes(adata, min_cells3) print(adata)质控后的数据规模发生了变化AnnData object with n_obs × n_vars 2638 × 137145.3 数据标准化与对数化原始 UMI 计数受测序深度影响很大需要在细胞之间进行标准化消除这种技术差异。Scanpy 的标准流程是使用sc.pp.normalize_total将每个细胞的总计数归一化到目标总数通常为 1e4然后进行对数变换# 归一化到每个细胞 1e4 的总数 sc.pp.normalize_total(adata, target_sum1e4) # 对数变换 sc.pp.log1p(adata)对数变换的目的是压缩数据动态范围消除极端高表达基因的影响。log1p即log(1 x)在保留零值不变的同时降低高表达值的数值跨度。5.4 高变基因识别高变基因Highly Variable Genes是细胞间表达差异显著的基因。只使用高变基因进行后续降维和聚类可以去除技术噪声和无关基因的影响同时大幅减少计算量# 识别高变基因 sc.pp.highly_variable_genes(adata, n_top_genes2000, flavorseurat) # 将数据限制为高变基因 adata_hvg adata[:, adata.var[highly_variable]] print(adata_hvg)这里n_top_genes2000指定选取 2000 个高变基因flavorseurat表示使用 Seurat 的方法来识别高变基因Scanpy 也支持其他方法。你也可以用sc.pl.highly_variable_genes(adata)可视化高变基因的分布情况直观观察选择是否合理。5.5 主成分分析PCA降维高变基因仍有数千个维度直接聚类会面临维数灾难。PCA 将高维表达数据压缩到少数主成分保留最主要的变异信息# 使用高变基因数据做主成分分析 sc.pp.pca(adata_hvg, n_comps50) # 可视化主成分方差比 sc.pl.pca_variance_ratio(adata_hvg, n_pcs50, logTrue)通过主成分方差比图可以判断需要保留多少个主成分。一般是看曲线在哪里趋于平缓拐点选择保留前 20 到 30 个主成分即可。本文示例中我们使用 30 个主成分你也可以根据实际数据调整。5.6 邻域图构建与聚类PCA 降维后Scanpy 需要构建细胞间的近邻图再基于图结构进行聚类。最常用的聚类方法是 Leiden 算法# 基于 PCA 结果构建邻域图 sc.pp.neighbors(adata_hvg, n_neighbors10, n_pcs30) # Leiden 聚类 sc.tl.leiden(adata_hvg, resolution0.5) # 查看聚类结果 print(adata_hvg.obs[leiden].value_counts())n_neighbors10表示每个细胞考虑 10 个近邻n_pcs30指定使用前 30 个主成分resolution0.5控制聚类粒度数值越大得到的簇越多。聚类结果会保存在adata_hvg.obs[leiden]中每个细胞被赋予一个簇标签。5.7 UMAP 与 tSNE 可视化聚类完成后通常用 UMAP 或 tSNE 将高维数据映射到二维平面进行可视化。UMAP 速度快、全局结构保持较好是目前的主流选择# 使用 UMAP 降维可视化 sc.tl.umap(adata_hvg) # 绘制按聚类着色的 UMAP 图 sc.pl.umap(adata_hvg, colorleiden)运行后会在 Notebook 输出区域显示 UMAP 图每个颜色代表一个聚类簇。如果希望用 tSNE 可视化可以这样sc.tl.tsne(adata_hvg, n_pcs30) sc.pl.tsne(adata_hvg, colorleiden)需要提醒的是tSNE 计算较慢且每次运行结果会有一定随机性。如果只是初步查看分群效果优先选择 UMAP。5.8 标记基因识别聚类完成后需要找出每个簇的特征基因从而推断细胞类型。使用sc.tl.rank_genes_groups实现差异表达分析# 对每个聚类簇进行差异表达分析 sc.tl.rank_genes_groups(adata_hvg, groupbyleiden, methodwilcoxon) # 可视化前 25 个标记基因的热图 sc.pl.rank_genes_groups(adata_hvg, n_genes25, shareyFalse)输出会以表格和可视化形式展示每个簇的标记基因。如果你想查看特定簇的标记基因列表可以用以下方式result adata_hvg.uns[rank_genes_groups] groups result[names].dtype.names # 打印 cluster 0 的前 10 个标记基因 for group in groups[:3]: print(fCluster {group}:) genes list(result[names][group][:10]) print(genes)根据标记基因你可以结合文献知识注释细胞类型。例如PBMC 3K 数据集中常见的注释结果是Cluster 0/1CD4 T 细胞标记基因 CD3D、IL7RCluster 2CD8 T 细胞标记基因 CD8A、GZMKCluster 3NK 细胞标记基因 NKG7、GNLY、KLRD1Cluster 4B 细胞标记基因 MS4A1、CD79ACluster 5单核细胞标记基因 LYZ、S100A8Cluster 6树突状细胞标记基因 FCER1A、CST3将注释结果写回 AnnData 对象后可以重新绘图展示细胞类型# 手动注释结果 new_cluster_names [ CD4 T, CD4 T, CD8 T, NK, B, Mono, DC, CD8 T, Platelet, ] adata_hvg.obs[cell_type] adata_hvg.obs[leiden].map( dict(zip(adata_hvg.obs[leiden].cat.categories, new_cluster_names)) ) # 绘制细胞类型注释图 sc.pl.umap(adata_hvg, colorcell_type)5.9 保存分析结果分析完成后建议将 AnnData 对象保存为 H5AD 格式方便后续加载和继续分析# 保存完整 AnnData 对象 adata_hvg.write_h5ad(pbmc3k_analysis.h5ad) # 只保存核心结果到 CSV adata_hvg.obs.to_csv(pbmc3k_cell_metadata.csv) adata_hvg.obsm.to_df().to_csv(pbmc3k_umap_coords.csv)加载 H5AD 文件时使用sc.read_h5ad(pbmc3k_analysis.h5ad)即可。6. Jupyter Notebook 与 Scanpy 可视化技巧6.1 图像内嵌显示Scanpy 的绘图函数基于 Matplotlib默认情况下在 Notebook 中执行sc.pl.umap()会在输出区域直接显示图像这在 Notbook 中优先需要设置%matplotlib inline对于高分辨率图片导出可以设置sc.settings.set_figure_params(dpi100, dpi_save200, frameonFalse)6.2 交互式图表静态图片在某些场景下不够直观。Scanpy 支持通过napari或cellxgene查看交互式单细胞数据但最简单的方式是使用scanpy的sc.pl.umap通过color_map和size参数控制不同维度的展示并结合sc.pl.matrixplot、sc.pl.dotplot等函数进行多角度观察。另一个实用技巧是使用 IPython 的display将多张图并列展示from IPython.display import display # 同时展示两个基因的表达 sc.pl.umap(adata_hvg, color[CD3D, NKG7], ncols2, size20)6.3 结果导出分析完成后可以将 Notebook 导出为多种格式用于报告和协作# 在 Jupyter Notebook 中导出 HTML通过菜单操作 # File → Download as → HTML也可以通过命令行批处理导出jupyter nbconvert --to html pbmc3k_analysis.ipynb jupyter nbconvert --to markdown pbmc3k_analysis.ipynb导出为 HTML 后图片会以 base64 形式嵌入可以在任意浏览器中查看不依赖 Jupyter 环境。7. 常见问题与排查思路7.1 Scanpy 安装与导入问题问题现象常见原因解决思路import scanpy报错 ModuleNotFoundError当前环境未安装 Scanpy或解释器路径不对确认环境激活状态使用conda install -c conda-forge scanpy安装安装时提示依赖冲突conda 或 pip 包版本与现有环境冲突创建全新环境重新安装避免与 base 环境混用导入时提示libhdf5相关错误HDF5 库版本不匹配使用 conda 安装h5py并重装 Scanpy运行sc.pp.pca时内存不足数据量过大或未限制高变基因先过滤基因再使用n_comps控制主成分数量7.2 Scanpy 文件读取问题问题现象常见原因解决思路sc.read_10x_h5读取失败文件路径错误或不是标准 MEX/h5 格式检查文件前缀确认是 10x 标准输出使用sc.read_10x_mtx读取目录读取后基因名称为 Ensembl ID数据本身是 h5 格式包含 gene_ids手动映射基因符号或者下载带基因注释的文件读取后adata.X为 None部分格式需要指定X层查看数据结构用adata.layers检查是否存在原始计数7.3 Jupyter Notebook 使用问题问题现象常见原因解决思路Notebook 打开后空白浏览器代理 / 缓存 / notebook 版本问题清除缓存用--no-browser启动升级 notebookShift Enter运行没有反应处于编辑模式或内核未连接按Esc退出编辑模式检查右上角内核状态Kernel → Restart图像在非默认浏览器中打不开浏览器未配置按本文 3.5 方式修改配置文件PyCharm 中运行 .ipynb 提示找不到内核项目解释器不是 scanpy-env在 PyCharm 设置中切换 Python 解释器为 conda 环境7.4 Scanpy 分析流程报错问题现象常见原因解决思路sc.tl.leiden报错ValueError: You need to runsc.pp.neighborsfirst聚类之前没有构建邻域图先执行sc.pp.neighbors再聚类sc.pl.umap提示 UMAP 坐标不存在没有运行sc.tl.umap先运行sc.tl.umap再绘图聚类结果全是 0 或簇过多邻域图参数或分辨率设置不合理调整n_neighbors、n_pcs和resolution参数rank_genes_groups结果为空表达矩阵中存在 NaN 或全零基因检查质控过滤是否合理必要时重新归一化8. 最佳实践与工程建议8.1 使用独立环境管理依赖单细胞分析依赖大量生物信息学库依赖版本冲突是最常见的问题。建议为每个分析项目创建独立的 conda 环境并在项目根目录维护一个environment.yml文件记录环境配置方便团队复现name: scanpy-env channels: - conda-forge - bioconda dependencies: - python3.10 - scanpy - jupyter - jupyterlab - numpy - pandas - matplotlib - seaborn创建环境conda env create -f environment.yml8.2 记录分析过程和版本信息单细胞分析的可复现性非常关键。在 Notebook 开头建议记录环境信息和数据文件信息import scanpy as sc import anndata as ad import numpy as np import pandas as pd print(fscanpy version: {sc.__version__}) print(fanndata version: {ad.__version__}) print(fnumpy version: {np.__version__}) print(fpandas version: {pd.__version__})这样每次分析结果都有版本记录后续排查问题或重复分析时容易定位差异。8.3 合理控制分析参数质控阈值、聚类分辨率、PCA 主成分数这些参数都会显著影响分析结果。在实战中不要盲目套用固定的参数组合。建议质控之前先用直方图观察total_counts、n_genes_by_counts、pct_counts_mt的分布再确定合理阈值。聚类分辨率可以从 0.3 开始逐步调整到 0.8观察分群是否合理。标记基因识别后用sc.pl.dotplot或sc.pl.matrixplot检查标记基因在各类细胞中的表达特异性确认注释可靠。8.4 注意随机种子Leiden 聚类和 tSNE 算法带有随机性不同运行产生的簇标签可能有细微差异。为了确保分析结果可复现建议在随机步骤前设置种子import numpy as np np.random.seed(1)Scanpy 也提供了全局随机种子设置sc.settings.seed 18.5 分析中的安全与伦理边界单细胞数据通常包含人类受试者的遗传信息。处理这类数据时需要注意确保数据获取符合相关伦理审批和知情同意要求。不要直接在公开仓库中上传未脱敏的原始测序数据。在分析报告中不要泄露受试者的敏感身份信息。如果使用云平台分析注意数据加密和权限控制。这些都是分析流程之外容易被忽略但非常重要的工程问题。9. 总结与后续学习建议到了这一步你已经走完了 Jupyter Notebook 基础操作和 Scanpy 单细胞分析的核心流程包括环境搭建、数据读取、质控、标准化、降维、聚类、可视化和标记基因识别。这套流程是单细胞分析的骨架基本上任何单细胞转录组项目都会覆盖这些步骤。接下来可以按以下方向拓展学习深入理解数据标准化方法SCTransformSeurat、中位数归一化和正则化负二项模型。多批次数据整合Harmony、BBKNN、scVI 这些工具在多样本整合时会用到。细胞类型自动注释SingleR、CellTypist 等工具可以辅助标注细胞类型。轨迹分析Monocle 3R 语言、Scanpy 中的 PAGA 和 diffusion pseudotime。在实际项目中我更建议你把重点放在“数据质量判断”上。参数调优和算法选择都是经验积累的过程但数据质量决定分析的天花板。每一次质控过滤之前先用可视化了解数据的分布特征每一次聚类完成后不要只盯着 UMAP 图上的分离程度要结合标记基因表达确认簇的生物学意义。如果你在跟着本文操作时遇到问题优先查看报错信息中提示的缺失步骤大多数 Scanpy 报错都指向了流程顺序或参数设置问题。也可以把本文的代码逐段复制到 Jupyter Notebook 中运行结合输出结果理解每一步的作用。欢迎在评论区交流你的分析结果和踩坑经历。如果本文对你有所帮助可以收藏备用后续遇到单细胞分析相关问题也能快速查阅。也可以关注后续更新我会继续整理 Scanpy 进阶分析、多样本整合和细胞注释方面的实战教程。 Jupyter Notebook+Scanpy单细胞分析实战：从环境配置到聚类注释
单细胞测序数据分析这几年在生信领域越来越常见而 Scanpy 作为 Python 生态中最主流的单细胞分析框架配合 Jupyter Notebook 的交互式环境几乎成了入门单细胞分析的标配组合。不过很多初学者在配置环境、读取数据、理解 AnnData 结构这些环节就被卡住了。本文将围绕 Jupyter Notebook 基础操作和 Scanpy 入门实战展开从环境搭建到完整分析流程逐步拆解帮你建立一套可以直接上手复用的分析路径。写这篇文章的初衷很简单我在学习单细胞数据分析时最大的障碍不是算法本身而是工具链不熟练。Jupyter Notebook 的交互特性非常适合单细胞数据这种“探索式分析”而 Scanpy 的 API 设计又高度依赖这种交互模式两者结合能极大提升分析效率。文中会覆盖环境准备、Notebook 基础操作、AnnData 数据结构、Scanpy 完整分析流程、常见报错排查和工程化建议新手可以按顺序阅读有基础的读者可以直接跳到实战部分。1. 背景与核心概念1.1 什么是 Jupyter NotebookJupyter Notebook 是一个开源的 Web 交互式计算环境允许你在浏览器中创建和共享包含代码、文本、公式、图像和可视化图表的文档。它最初是 IPython Notebook 项目后来发展为独立的 Jupyter 项目目前已经成为数据科学和科研计算领域最常用的工具之一。对于生信分析来说Jupyter Notebook 的核心价值在于“分块执行”。传统 Python 脚本是一次性运行整个文件而 Notebook 允许你按 Cell单元格逐段执行代码随时查看中间结果发现异常可以立即修改再重新运行。这种工作方式非常适合单细胞数据分析——因为单细胞分析是一个高度迭代的过程你需要反复调整质控阈值、聚类分辨率、可视化参数并在每一步都观察结果分布。Jupyter Notebook 支持两种核心 Cell 类型Code Cell 用于执行 Python 代码Markdown Cell 用于写说明文档。分析过程中的每个步骤都可以用 Markdown 记录思路、用 Code 执行代码、用输出区域展示图表最终导出的 HTML 或 Markdown 文件本身就是一份完整可复现的分析报告。1.2 什么是 ScanpyScanpySingle-Cell Analysis in Python是一个基于 Python 的高效单细胞数据分析工具包专门用于处理大规模单细胞转录组测序数据。它提供了从数据读取、质控过滤、归一化、降维、聚类到差异表达分析、可视化的一整套流程。Scanpy 底层依赖 AnnData 数据结构来组织和存储数据。AnnData 的设计灵感来自 R 语言生态中的 Seurat 对象它把基因表达矩阵、细胞元数据、基因元数据和降维结果统一封装在一个对象中使得数据操作和分析流程更加系统化。Scanpy 与 Seurat 是当前单细胞分析领域两大主流工具。两者的选择主要取决于你的技术背景如果你更熟悉 Python 生态对数据科学库NumPy、Pandas、Matplotlib有基础那么 Scanpy 是更自然的选择如果你或者你的团队长期使用 R那么 Seurat 可能更顺手。但需要说明的是Scanpy 在处理超大样本量例如十万级细胞时通常比 Seurat 更高效这也是很多生信流程选择 Scanpy 的原因之一。1.3 Jupyter Notebook 与 Jupyter Lab 的区别很多初学者会纠结 Jupyter Notebook 和 Jupyter Lab 到底选哪个。简单来说Jupyter Lab 是 Jupyter Notebook 的下一代界面它保留了 Notebook 的全部核心功能同时增加了文件管理、多窗口分栏、终端支持等能力。对比维度Jupyter NotebookJupyter Lab界面风格单一文档界面较简洁多标签页工作台可自由分栏文件管理需要回到 Dashboard 管理文件左侧内置文件浏览器多文档操作不支持同时编辑多个 Notebook支持并排查看多个 Notebook终端支持不支持内置终端可执行 Shell 命令插件生态较少支持丰富扩展插件适用场景快速上手、轻量使用复杂分析流程、多文件协作如果你是刚入门直接用 Jupyter Notebook 就够了不必要在工具选择上花太多时间。等后续分析流程复杂化、需要同时查看多个文档时再切换到 Jupyter Lab 会更合适。2. 环境准备与版本说明2.1 安装 AnacondaAnaconda 是目前最推荐的 Python 发行版它内置了 Jupyter Notebook、Jupyter Lab、NumPy、Pandas、Matplotlib 等数据科学常用库省去了手动安装依赖的麻烦。访问 Anaconda 官网下载对应系统的安装包即可。下载时建议选择最新的稳定版本安装过程中保持默认选项。Windows 用户安装时需要注意勾选“Add Anaconda to my PATH environment variable”选项部分新版本默认不勾选否则后续在命令行中调用 conda 命令会失败。安装完成后打开命令行工具Windows 用户可以使用 Anaconda PromptmacOS/Linux 用户使用 Terminal输入以下命令验证安装conda --version如果能看到版本号输出就说明 Anaconda 安装成功。版本号会因你下载的安装包而异比如常见的conda 24.x.x本文后续命令在不同版本下均可使用。2.2 创建独立的 Python 环境单细胞分析涉及大量依赖库不同的项目可能需要不同版本的工具包。为了避免环境混乱强烈建议为单细胞分析创建一个独立的 conda 环境。在命令行中执行conda create -n scanpy-env python3.10 -y这里-n scanpy-env指定环境名称你可以按自己的习惯命名例如scrna或sc-analysis。python3.10指定 Python 版本具体版本号请根据你安装的 Anaconda 版本和 Scanpy 官方要求调整不必完全一致。创建完成后激活环境conda activate scanpy-env激活成功后命令行提示符前面会出现(scanpy-env)字样表示当前处于独立环境中。2.3 安装 Scanpy 及相关依赖激活环境后安装 Scanpy。建议使用 conda 安装因为 conda 会自动处理底层依赖如 HDF5、BLAS 等的兼容问题conda install -y scanpy如果 conda 安装速度较慢也可以使用 pip 安装。但需要注意pip 安装 Scanpy 时可能会遇到部分底层库的编译问题建议优先尝试上面的 conda 方式。安装完成后验证python -c import scanpy as sc; print(sc.__version__)如果输出版本号说明安装成功。Scanpy 的版本更新比较频繁新版本会不断优化算法性能和 API 细节本文示例代码在常见版本下均可运行但如果遇到 API 报错请以当前版本的官方文档为准。同时确认 Jupyter Notebook 在当前环境中可用jupyter notebook --version如果提示找不到命令需要执行conda install -y jupyter notebook2.4 启动 Jupyter Notebook在已激活的 scanpy-env 环境中进入你想要存放分析项目的目录然后启动 Jupyter Notebookcd ~/projects/scanpy-tutorial jupyter notebook启动后默认浏览器会自动打开 Jupyter Notebook 的 Dashboard 页面地址通常是http://localhost:8888。你可以在这里新建 Notebook、浏览文件、管理目录。如果你是在服务器或远程环境中使用启动时建议添加--no-browser参数同时指定端口jupyter notebook --no-browser --port8899然后在本地浏览器中通过http://服务器IP:8899访问必要时需要配置 SSH 隧道。3. Jupyter Notebook 基础操作3.1 创建与保存 Notebook在 Jupyter Notebook Dashboard 页面右上角点击“New”选择“Python 3”即可创建一个新的 Notebook。新建后Notebook 默认包含一个 Code Cell你可以在其中输入 Python 代码并按Shift Enter执行。Notebook 的保存使用Ctrl SmacOS 为Command S也可以点击工具栏上的保存图标。Notebook 文件以.ipynb为扩展名本质上是 JSON 格式里面保存了代码、输出结果、Markdown 文本等全部内容。这里需要特别注意Notebook 保存的是代码和输出不是运行时的变量状态。如果你关闭浏览器但没有保存未保存的代码和输出会丢失但已经运行过的变量内存状态也会随着内核关闭而清空。所以每次分析结束前记得手动保存并且导出分析结果。3.2 Cell 类型与快捷键Notebook 中的 Cell 分为三种类型Code Cell执行 Python 代码显示代码输出结果。Markdown Cell编写富文本说明支持 LaTeX 公式、图片、表格等。Raw Cell保持原始文本输出不会渲染也不会执行。工具栏的下拉菜单可以切换 Cell 类型键盘快捷键M切换为 MarkdownY切换回 Code。下面列出最常用的快捷键快捷键功能Shift Enter执行当前 Cell 并移动到下一个Ctrl Enter执行当前 Cell不移动Alt Enter执行当前 Cell 并在下方插入新 CellA/B在当前 Cell 上方 / 下方插入新 CellD D删除当前 CellM/Y切换为 Markdown / Code 类型Ctrl S保存文件Z撤销删除 Cell当你按快捷键没反应时先检查当前是否处于编辑模式。Notebook 有命令模式和编辑模式之分按Esc进入命令模式按Enter进入编辑模式绝大多数快捷键都只会在命令模式下生效。3.3 Magic 命令Magic 命令是 IPython 提供的一组以%开头的增强命令在单细胞分析中非常实用。最常用的几个# 在 Notebook 中显示 matplotlib 图像 %matplotlib inline # 计时执行 %time some_function() # 查看变量的内存占用 %whos%matplotlib inline是数据分析中最常用的 Magic 命令它保证绘图结果显示在 Notebook 输出区域中而不是弹出独立窗口。Scanpy 的可视化函数都是基于 Matplotlib 的所以每次新建分析 Notebook 后建议在第一个代码块中执行这个命令。另外还有一个%load_ext和%autoreload组合用于自动加载修改过的代码模块在自定义函数较多时会很有帮助。3.4 在 PyCharm 中使用 Jupyter Notebook很多初学者在 PyCharm 中接触 Jupyter Notebook这里单独说明一下。PyCharm 专业版内置了 Jupyter Notebook 支持用 PyCharm 打开.ipynb文件后可以直接在 IDE 中逐 Cell 运行代码并且能看到图像输出。使用步骤在 PyCharm 中打开项目文件夹。双击.ipynb文件。PyCharm 会提示选择 Jupyter 服务器选择“Managed Server”由 PyCharm 自动管理即可。检查右下角的 Python 解释器是否为你的 scanpy-env 环境。点击 Cell 左侧的绿色运行按钮执行代码。如果你使用的是 PyCharm 社区版则默认不支持 Jupyter Notebook需要安装 Jupyter 插件注意插件支持情况随版本变化或者继续使用浏览器方式运行 Notebook。3.5 如何在其他浏览器中打开 Jupyter Notebook默认情况下 Jupyter Notebook 会调用系统默认浏览器。如果你希望使用 Chrome 或其他浏览器打开可以修改 Jupyter 配置文件。生成配置文件jupyter notebook --generate-config然后编辑生成的配置文件# 找到以下行并取消注释替换为你的浏览器路径 c.NotebookApp.browser C:/Program Files/Google/Chrome/Application/chrome.exeWindows 用户可以打开配置文件后搜索NotebookApp.browser关键字修改后保存并重新启动 Jupyter Notebook 即可。另一个更快的临时方案是复制终端输出的带token的完整 URL手动粘贴到目标浏览器的地址栏中。3.6 Windows 下 Jupyter Notebook 打开后空白怎么办Windows 用户经常遇到 Jupyter Notebook 页面显示空白或无法加载的问题常见原因和解决方案如下原因一浏览器代理或防火墙拦截。如果你开启了一些代理工具local host 请求可能被拦截。解决方案是以无代理模式访问或者将localhost:8888以及127.0.0.1加入代理例外列表。原因二Jupyter 版本和浏览器缓存冲突。可以尝试清除浏览器缓存或者在启动时指定--no-browser然后手动从终端复制 URL 访问。原因三安装问题导致静态资源加载失败。运行以下命令修复 Jupyter Notebookjupyter contrib nbextension install --user jupyter nbextension enable --py --sys-prefix widgetsnbextension如果依然空白可以考虑升级 notebook 版本pip install --upgrade notebook原因四使用 Edge 或 IE 等兼容性问题。建议优先使用 Chrome 或 Firefox 访问 Notebook。4. Scanpy 核心数据结构AnnData4.1 AnnData 是什么AnnDataAnnotated Data是 Scanpy 和整个 Python 单细胞生态的数据容器。它由一个 Python 类anndata.AnnData定义核心设计是“一张表达矩阵 两组元数据 多组分析结果”。一个 AnnData 对象主要有以下几个核心部分X表达矩阵行为细胞列为基因通常是稀疏矩阵以减少内存占用。obs细胞层面的元数据DataFrame 格式每一行对应一个细胞例如样本编号、批次、细胞类型注释等。var基因层面的元数据DataFrame 格式每一行对应一个基因例如基因名称、高变基因标记等。obsm细胞层面的降维结果例如 PCA、UMAP、tSNE 坐标。varm基因层面的降维数据。uns非结构化的分析结果和注释信息例如聚类配色方案、差异表达结果。layers多个表达矩阵层用于存储原始计数、归一化后数据等。4.2 创建 AnnData 对象虽然实际分析中绝大多数 AnnData 对象都是通过读取数据文件生成的但为了理解数据结构我们可以手动创建一个最小的 AnnData 对象import numpy as np import pandas as pd import anndata as ad # 构造一个 3 个细胞、5 个基因的表达矩阵 X np.array([ [1, 0, 3, 0, 0], [2, 1, 0, 4, 0], [0, 0, 1, 0, 5], ]) # 细胞元数据 obs pd.DataFrame( { cell_type: [T cell, B cell, NK cell], sample_id: [s1, s1, s2], }, index[cell_1, cell_2, cell_3], # 必须指定索引 ) # 基因元数据 var pd.DataFrame( { gene_symbol: [GENE1, GENE2, GENE3, GENE4, GENE5], highly_variable: [True, False, True, False, True], }, index[gene_1, gene_2, gene_3, gene_4, gene_5], # 必须指定索引 ) # 创建 AnnData 对象 adata ad.AnnData(XX, obsobs, varvar) print(adata)输出结果AnnData object with n_obs × n_vars 3 × 5 obs: cell_type, sample_id var: gene_symbol, highly_variable4.3 AnnData 的常用操作访问表达矩阵# 获取表达矩阵 print(adata.X) print(adata.X.shape)访问 obs / var 元数据# 细胞元数据 print(adata.obs.head()) # 基因元数据 print(adata.var.head())筛选细胞或基因# 筛选 T cell adata_t adata[adata.obs[cell_type] T cell] print(adata_t) # 筛选高变基因 adata_hvg adata[:, adata.var[highly_variable]] print(adata_hvg)AnnData 的索引方式与 Pandas DataFrame 类似adata[行筛选, 列筛选]行是细胞列是基因。这个操作在后续质控和特征筛选时会频繁用到。5. Scanpy 完整单细胞分析实战5.1 数据读取Scanpy 支持多种单细胞数据格式最常见的包括10x Genomics 标准输出使用sc.read_10x_h5()读取 h5 文件或sc.read_10x_mtx()读取 mtx 目录。H5AD 格式Scanpy 原生格式使用sc.read_h5ad()读取保存时使用write_h5ad()。CSV / TSV / TXT 表达矩阵使用sc.read_csv()、sc.read_text()读取。为了便于入门演示这里使用 Scanpy 内置的 PBMC 3K 数据集来自 10x Genomics 的外周血单个核细胞包含约 2700 个细胞。这个数据集是 Scanpy 官方教程的标准示例非常适合学习流程。import scanpy as sc # 设置图像显示 sc.settings.verbosity 3 # 输出信息详细程度 sc.settings.set_figure_params(dpi100, dpi_save200) # 图像分辨率 # 读取内置数据 adata sc.datasets.pbmc3k() print(adata)输出结果AnnData object with n_obs × n_vars 2700 × 32738 var: gene_ids, n_cells可以看到数据集包含 2700 个细胞、32738 个基因var中有gene_idsEnsembl 基因 ID和n_cells信息。由于基因 ID 是 Ensembl 格式不方便阅读我们将其转换为人易读的基因符号。使用 Scanpy 内置的基因注释功能在较新版本中可以这样操作# 使用内置基因符号 adata.var[gene_symbol] adata.var_names注意不同版本的 Scanpy 对基因注释的处理方式略有不同如果你的数据读取后已经有基因符号可以跳过这一步。5.2 质量控制单细胞数据中不可避免会包含低质量细胞和无效基因。质量控制的核心是设置合理阈值过滤掉异常值。首先计算质控指标Scanpy 的sc.pp.calculate_qc_metrics可以生成线粒体基因比例、基因计数等指标。线粒体基因通常以MT-前缀开头adata.var[mt] adata.var_names.str.startswith(MT-) # 计算质控指标 sc.pp.calculate_qc_metrics(adata, qc_vars[mt], percent_topNone, inplaceTrue) print(adata.obs[[n_genes_by_counts, total_counts, pct_counts_mt]].head())结果输出六个示例细胞的数据包含三个关键指标每个细胞检测到的基因数量、总 UMI 计数、线粒体基因比例。然后进行过滤# 过滤细胞基因数量在 200 到 2500 之间线粒体比例低于 5% sc.pp.filter_cells(adata, min_genes200) sc.pp.filter_cells(adata, max_genes2500) sc.pp.filter_cells(adata, min_counts500) # 过滤线粒体高比例细胞 adata adata[adata.obs[pct_counts_mt] 5, :] # 过滤基因至少在 3 个细胞中表达 sc.pp.filter_genes(adata, min_cells3) print(adata)质控后的数据规模发生了变化AnnData object with n_obs × n_vars 2638 × 137145.3 数据标准化与对数化原始 UMI 计数受测序深度影响很大需要在细胞之间进行标准化消除这种技术差异。Scanpy 的标准流程是使用sc.pp.normalize_total将每个细胞的总计数归一化到目标总数通常为 1e4然后进行对数变换# 归一化到每个细胞 1e4 的总数 sc.pp.normalize_total(adata, target_sum1e4) # 对数变换 sc.pp.log1p(adata)对数变换的目的是压缩数据动态范围消除极端高表达基因的影响。log1p即log(1 x)在保留零值不变的同时降低高表达值的数值跨度。5.4 高变基因识别高变基因Highly Variable Genes是细胞间表达差异显著的基因。只使用高变基因进行后续降维和聚类可以去除技术噪声和无关基因的影响同时大幅减少计算量# 识别高变基因 sc.pp.highly_variable_genes(adata, n_top_genes2000, flavorseurat) # 将数据限制为高变基因 adata_hvg adata[:, adata.var[highly_variable]] print(adata_hvg)这里n_top_genes2000指定选取 2000 个高变基因flavorseurat表示使用 Seurat 的方法来识别高变基因Scanpy 也支持其他方法。你也可以用sc.pl.highly_variable_genes(adata)可视化高变基因的分布情况直观观察选择是否合理。5.5 主成分分析PCA降维高变基因仍有数千个维度直接聚类会面临维数灾难。PCA 将高维表达数据压缩到少数主成分保留最主要的变异信息# 使用高变基因数据做主成分分析 sc.pp.pca(adata_hvg, n_comps50) # 可视化主成分方差比 sc.pl.pca_variance_ratio(adata_hvg, n_pcs50, logTrue)通过主成分方差比图可以判断需要保留多少个主成分。一般是看曲线在哪里趋于平缓拐点选择保留前 20 到 30 个主成分即可。本文示例中我们使用 30 个主成分你也可以根据实际数据调整。5.6 邻域图构建与聚类PCA 降维后Scanpy 需要构建细胞间的近邻图再基于图结构进行聚类。最常用的聚类方法是 Leiden 算法# 基于 PCA 结果构建邻域图 sc.pp.neighbors(adata_hvg, n_neighbors10, n_pcs30) # Leiden 聚类 sc.tl.leiden(adata_hvg, resolution0.5) # 查看聚类结果 print(adata_hvg.obs[leiden].value_counts())n_neighbors10表示每个细胞考虑 10 个近邻n_pcs30指定使用前 30 个主成分resolution0.5控制聚类粒度数值越大得到的簇越多。聚类结果会保存在adata_hvg.obs[leiden]中每个细胞被赋予一个簇标签。5.7 UMAP 与 tSNE 可视化聚类完成后通常用 UMAP 或 tSNE 将高维数据映射到二维平面进行可视化。UMAP 速度快、全局结构保持较好是目前的主流选择# 使用 UMAP 降维可视化 sc.tl.umap(adata_hvg) # 绘制按聚类着色的 UMAP 图 sc.pl.umap(adata_hvg, colorleiden)运行后会在 Notebook 输出区域显示 UMAP 图每个颜色代表一个聚类簇。如果希望用 tSNE 可视化可以这样sc.tl.tsne(adata_hvg, n_pcs30) sc.pl.tsne(adata_hvg, colorleiden)需要提醒的是tSNE 计算较慢且每次运行结果会有一定随机性。如果只是初步查看分群效果优先选择 UMAP。5.8 标记基因识别聚类完成后需要找出每个簇的特征基因从而推断细胞类型。使用sc.tl.rank_genes_groups实现差异表达分析# 对每个聚类簇进行差异表达分析 sc.tl.rank_genes_groups(adata_hvg, groupbyleiden, methodwilcoxon) # 可视化前 25 个标记基因的热图 sc.pl.rank_genes_groups(adata_hvg, n_genes25, shareyFalse)输出会以表格和可视化形式展示每个簇的标记基因。如果你想查看特定簇的标记基因列表可以用以下方式result adata_hvg.uns[rank_genes_groups] groups result[names].dtype.names # 打印 cluster 0 的前 10 个标记基因 for group in groups[:3]: print(fCluster {group}:) genes list(result[names][group][:10]) print(genes)根据标记基因你可以结合文献知识注释细胞类型。例如PBMC 3K 数据集中常见的注释结果是Cluster 0/1CD4 T 细胞标记基因 CD3D、IL7RCluster 2CD8 T 细胞标记基因 CD8A、GZMKCluster 3NK 细胞标记基因 NKG7、GNLY、KLRD1Cluster 4B 细胞标记基因 MS4A1、CD79ACluster 5单核细胞标记基因 LYZ、S100A8Cluster 6树突状细胞标记基因 FCER1A、CST3将注释结果写回 AnnData 对象后可以重新绘图展示细胞类型# 手动注释结果 new_cluster_names [ CD4 T, CD4 T, CD8 T, NK, B, Mono, DC, CD8 T, Platelet, ] adata_hvg.obs[cell_type] adata_hvg.obs[leiden].map( dict(zip(adata_hvg.obs[leiden].cat.categories, new_cluster_names)) ) # 绘制细胞类型注释图 sc.pl.umap(adata_hvg, colorcell_type)5.9 保存分析结果分析完成后建议将 AnnData 对象保存为 H5AD 格式方便后续加载和继续分析# 保存完整 AnnData 对象 adata_hvg.write_h5ad(pbmc3k_analysis.h5ad) # 只保存核心结果到 CSV adata_hvg.obs.to_csv(pbmc3k_cell_metadata.csv) adata_hvg.obsm.to_df().to_csv(pbmc3k_umap_coords.csv)加载 H5AD 文件时使用sc.read_h5ad(pbmc3k_analysis.h5ad)即可。6. Jupyter Notebook 与 Scanpy 可视化技巧6.1 图像内嵌显示Scanpy 的绘图函数基于 Matplotlib默认情况下在 Notebook 中执行sc.pl.umap()会在输出区域直接显示图像这在 Notbook 中优先需要设置%matplotlib inline对于高分辨率图片导出可以设置sc.settings.set_figure_params(dpi100, dpi_save200, frameonFalse)6.2 交互式图表静态图片在某些场景下不够直观。Scanpy 支持通过napari或cellxgene查看交互式单细胞数据但最简单的方式是使用scanpy的sc.pl.umap通过color_map和size参数控制不同维度的展示并结合sc.pl.matrixplot、sc.pl.dotplot等函数进行多角度观察。另一个实用技巧是使用 IPython 的display将多张图并列展示from IPython.display import display # 同时展示两个基因的表达 sc.pl.umap(adata_hvg, color[CD3D, NKG7], ncols2, size20)6.3 结果导出分析完成后可以将 Notebook 导出为多种格式用于报告和协作# 在 Jupyter Notebook 中导出 HTML通过菜单操作 # File → Download as → HTML也可以通过命令行批处理导出jupyter nbconvert --to html pbmc3k_analysis.ipynb jupyter nbconvert --to markdown pbmc3k_analysis.ipynb导出为 HTML 后图片会以 base64 形式嵌入可以在任意浏览器中查看不依赖 Jupyter 环境。7. 常见问题与排查思路7.1 Scanpy 安装与导入问题问题现象常见原因解决思路import scanpy报错 ModuleNotFoundError当前环境未安装 Scanpy或解释器路径不对确认环境激活状态使用conda install -c conda-forge scanpy安装安装时提示依赖冲突conda 或 pip 包版本与现有环境冲突创建全新环境重新安装避免与 base 环境混用导入时提示libhdf5相关错误HDF5 库版本不匹配使用 conda 安装h5py并重装 Scanpy运行sc.pp.pca时内存不足数据量过大或未限制高变基因先过滤基因再使用n_comps控制主成分数量7.2 Scanpy 文件读取问题问题现象常见原因解决思路sc.read_10x_h5读取失败文件路径错误或不是标准 MEX/h5 格式检查文件前缀确认是 10x 标准输出使用sc.read_10x_mtx读取目录读取后基因名称为 Ensembl ID数据本身是 h5 格式包含 gene_ids手动映射基因符号或者下载带基因注释的文件读取后adata.X为 None部分格式需要指定X层查看数据结构用adata.layers检查是否存在原始计数7.3 Jupyter Notebook 使用问题问题现象常见原因解决思路Notebook 打开后空白浏览器代理 / 缓存 / notebook 版本问题清除缓存用--no-browser启动升级 notebookShift Enter运行没有反应处于编辑模式或内核未连接按Esc退出编辑模式检查右上角内核状态Kernel → Restart图像在非默认浏览器中打不开浏览器未配置按本文 3.5 方式修改配置文件PyCharm 中运行 .ipynb 提示找不到内核项目解释器不是 scanpy-env在 PyCharm 设置中切换 Python 解释器为 conda 环境7.4 Scanpy 分析流程报错问题现象常见原因解决思路sc.tl.leiden报错ValueError: You need to runsc.pp.neighborsfirst聚类之前没有构建邻域图先执行sc.pp.neighbors再聚类sc.pl.umap提示 UMAP 坐标不存在没有运行sc.tl.umap先运行sc.tl.umap再绘图聚类结果全是 0 或簇过多邻域图参数或分辨率设置不合理调整n_neighbors、n_pcs和resolution参数rank_genes_groups结果为空表达矩阵中存在 NaN 或全零基因检查质控过滤是否合理必要时重新归一化8. 最佳实践与工程建议8.1 使用独立环境管理依赖单细胞分析依赖大量生物信息学库依赖版本冲突是最常见的问题。建议为每个分析项目创建独立的 conda 环境并在项目根目录维护一个environment.yml文件记录环境配置方便团队复现name: scanpy-env channels: - conda-forge - bioconda dependencies: - python3.10 - scanpy - jupyter - jupyterlab - numpy - pandas - matplotlib - seaborn创建环境conda env create -f environment.yml8.2 记录分析过程和版本信息单细胞分析的可复现性非常关键。在 Notebook 开头建议记录环境信息和数据文件信息import scanpy as sc import anndata as ad import numpy as np import pandas as pd print(fscanpy version: {sc.__version__}) print(fanndata version: {ad.__version__}) print(fnumpy version: {np.__version__}) print(fpandas version: {pd.__version__})这样每次分析结果都有版本记录后续排查问题或重复分析时容易定位差异。8.3 合理控制分析参数质控阈值、聚类分辨率、PCA 主成分数这些参数都会显著影响分析结果。在实战中不要盲目套用固定的参数组合。建议质控之前先用直方图观察total_counts、n_genes_by_counts、pct_counts_mt的分布再确定合理阈值。聚类分辨率可以从 0.3 开始逐步调整到 0.8观察分群是否合理。标记基因识别后用sc.pl.dotplot或sc.pl.matrixplot检查标记基因在各类细胞中的表达特异性确认注释可靠。8.4 注意随机种子Leiden 聚类和 tSNE 算法带有随机性不同运行产生的簇标签可能有细微差异。为了确保分析结果可复现建议在随机步骤前设置种子import numpy as np np.random.seed(1)Scanpy 也提供了全局随机种子设置sc.settings.seed 18.5 分析中的安全与伦理边界单细胞数据通常包含人类受试者的遗传信息。处理这类数据时需要注意确保数据获取符合相关伦理审批和知情同意要求。不要直接在公开仓库中上传未脱敏的原始测序数据。在分析报告中不要泄露受试者的敏感身份信息。如果使用云平台分析注意数据加密和权限控制。这些都是分析流程之外容易被忽略但非常重要的工程问题。9. 总结与后续学习建议到了这一步你已经走完了 Jupyter Notebook 基础操作和 Scanpy 单细胞分析的核心流程包括环境搭建、数据读取、质控、标准化、降维、聚类、可视化和标记基因识别。这套流程是单细胞分析的骨架基本上任何单细胞转录组项目都会覆盖这些步骤。接下来可以按以下方向拓展学习深入理解数据标准化方法SCTransformSeurat、中位数归一化和正则化负二项模型。多批次数据整合Harmony、BBKNN、scVI 这些工具在多样本整合时会用到。细胞类型自动注释SingleR、CellTypist 等工具可以辅助标注细胞类型。轨迹分析Monocle 3R 语言、Scanpy 中的 PAGA 和 diffusion pseudotime。在实际项目中我更建议你把重点放在“数据质量判断”上。参数调优和算法选择都是经验积累的过程但数据质量决定分析的天花板。每一次质控过滤之前先用可视化了解数据的分布特征每一次聚类完成后不要只盯着 UMAP 图上的分离程度要结合标记基因表达确认簇的生物学意义。如果你在跟着本文操作时遇到问题优先查看报错信息中提示的缺失步骤大多数 Scanpy 报错都指向了流程顺序或参数设置问题。也可以把本文的代码逐段复制到 Jupyter Notebook 中运行结合输出结果理解每一步的作用。欢迎在评论区交流你的分析结果和踩坑经历。如果本文对你有所帮助可以收藏备用后续遇到单细胞分析相关问题也能快速查阅。也可以关注后续更新我会继续整理 Scanpy 进阶分析、多样本整合和细胞注释方面的实战教程。