单细胞测序数据下载与导入：Seurat实操与避坑指南（MD笔记）

做单细胞测序数据分析，十个新手有九个在第一步就被劝退了——“数据到底从哪下”、“下完是哪个文件”、“Read10X怎么老报错”。我见过太多人选好了数据集、装好了R包，结果在导入那一步卡了两整天，还有人把GEO下载的原始测序文件当成表达矩阵硬读，跑出一堆莫名其妙的结果。这篇内容是“scRNA-seq新手操作”系列的第一篇，就把“数据下载与导入”这件事彻底讲透：不仅讲按钮和命令怎么敲，更要把背后那套文件结构、数据库编号逻辑和格式原理拆开揉碎，再配上一份Markdown（MD）格式的实操笔记模板，让你的每一步都有迹可循。

这篇内容适合完全没碰过scRNA-seq的生信小白、想系统理顺流程的入门者，也适合需要带新人的课题组导师。已经跑通全流程的朋友可以直接跳到第四部分抄避坑清单。另外我要强调一个观点：新手入门第一步，优先用公开数据集里“已经处理好的表达矩阵”，暂时绕开原始fastq，否则你会在一开始就被测序数据量和比对耗时折磨到怀疑人生。

1. 先看清全局：数据下载与导入在整个流程里到底扮演什么角色

很多人上来就急着跑代码，结果连自己在流程的哪一环都不知道。scRNA-seq分析跟做菜很像：先买菜（原始数据）、再洗菜切菜（比对定量得到表达矩阵）、然后下锅（质控、降维、聚类）、最后装盘（可视化和注释）。数据下载和导入就是“买菜”和“确认食材已经切好”这两步，一旦这里的文件结构没搞明白，后面所有环节都是空中楼阁。

1.1 完整分析流程到底跑几步

scRNA-seq从测序仪下机到最终出图，大致分为四个阶段。第一阶段是原始数据获取，也就是从测序中心拿到或从公共数据库下载fastq文件；第二阶段是表达定量，需要把reads比对到参考基因组，并分配到每个细胞、每个基因上，目前最常用的是10x平台的Cell Ranger流程，也有STARsolo、kallisto等开源方案；第三阶段是质控与预处理，这一步在Seurat、Scanpy这类工具里完成，包括低质量细胞过滤、双细胞去除、数据标准化；第四阶段才是主菜，降维聚类、marker基因鉴定、细胞类型注释、轨迹分析等。

新手最容易犯的错误就是直接从第一阶段跳到第三阶段，拿fastq文件当表达矩阵去读。严格来说，Seurat读的应当是一张“基因×细胞”的计数矩阵，而不是原始测序read。Cell Ranger这类工具已经把原始fastq转录成了表达计数矩阵，整个流程的逻辑是这样的：fastq文件 → 比对参考基因组 → 生成barcode-gene计数矩阵 → 质量控制 → 下游分析。

所以“数据的下载与导入”实际上包含两种场景：一种是下载别人已经处理好的计数矩阵（比如10x官方示例数据，或GEO补充文件里的矩阵），直接导入Seurat；另一种是下载原始fastq，自己用Cell Ranger跑定量。我强烈建议新手在第一步选前者，用最低成本跑通完整的Seurat流程，等彻底理解了矩阵的结构，再去碰fastq和比对工具，那时候你会有一种“一切都通了”的感觉。

1.2 为什么先从公开数据集练手，以及MD笔记的价值

公开数据集是新手最稳妥的起点。好处很实在：第一，不用花钱，也不占自己的测序资源；第二，这些数据大多有文献配套，你分析完可以和作者的注释结果对一对，看看自己的聚类和细胞类型注释准不准；第三，踩坑的人多，搜任何一个报错信息都能找到前人的经验。

以10x官方示例的PBMC 3k为例，这是10x公司用来演示标准流程的经典数据集，大约2700个外周血单个核细胞，文件体积小，普通笔记本跑起来完全没压力。用它跑一遍，你能看到典型的10x数据长什么样，也能验证软件环境是否配置正确。

这里我要特意讲讲MD笔记。生信项目跟实验室实验不一样，实验有纸质本子记录，代码操作却容易忘记。数据在哪个目录下、用的是哪个版本参考基因组、wget下来的文件校验和是多少，三天不碰就全忘了。Markdown文档在生信圈子里越来越普及，因为它本质是纯文本，可以用任何编辑器打开，GitHub或GitLab直接渲染，也方便跟别人协作。你在记录下载信息时顺手写一个表格，把样本编号、下载链接、文件大小、日期全部记下来，以后复现项目时不用从零开始猜，这也是“数据的下载与导入/MD”这个标题里包含MD的用意——实操笔记和数据分析一样重要。

2. 数据从哪来：数据库、编号体系和文件格式一次讲清楚

下载数据最怕的不是下不动，而是下错了文件还不知道。很多人在NCBI GEO页面上看到一堆链接，完全分不清哪些是表达矩阵、哪些是原始数据、哪些是平台注释。这一节我用最直接的方式把数据库编号和文件格式讲透。

2.1 GEO、GSE、GSM、SRA到底什么关系

在GEO上搜单细胞数据，你一定见过这些编号：GSE、GSM、SRR、GPL。它们之间的层级关系可以这样理解：GSE（Series）是一个研究项目，对应一篇论文或一项实验；GSM（Sample）是该项目下的一个样本，每个GSM有自己独立的平台和描述；GPL是测序平台编号，比如GPL24676是10x Genomics的某个版本；SRR则是存放原始测序reads的SRA数据库编号。

单细胞转录组数据通常是以“补充文件”的形式挂在GSE页面底部的Supplementary file区域，这才是我们要下载的重点。GSE页面中部那些关于实验设计的文字描述，只是帮你判断这个数据适不适合做你的课题。原始fastq文件默认放在SRA数据库里，体积巨大，一个10x样本的fastq动辄几十个GB，新手现阶段可以直接绕开。

许多老的数据集挂在GEO上的补充文件可能只有原始数据，没有处理好的计数矩阵。这种情况的解决路径只有两条：要么去文章正文的数据可用性声明里找作者上传的矩阵链接，要么老老实实用SRA工具下载fastq自己跑Cell Ranger。后者比较费时费力，但这属于进阶内容，后面我会专门写一篇。

2.2 10x格式的“三件套”：barcodes、features、matrix

scRNA-seq的计数矩阵最常见的形式是10x平台的“三件套”，三个文件各自承担一个角色。barcodes.tsv是一列细胞条码，代表你检测到的每个细胞；features.tsv（旧版本叫genes.tsv）是基因注释，通常两列，第一列是Ensembl基因ID或基因符号，第二列是基因符号；matrix.mtx则是一个稀疏矩阵文件，记录了三样东西：基因数、细胞数、非零表达值的总数，然后是无数行“基因索引、细胞索引、表达值”。

这三个文件靠行顺序对应起来，可以理解为：矩阵的每一列对应barcodes.tsv里的一行，每一行对应features.tsv里的一行，而matrix.mtx只记录非零的数值。为什么这么做？因为单细胞矩阵通常有上万个基因和几千上万个细胞，全量储存会产生大量零值，白白浪费内存和磁盘空间。用稀疏格式存非零值，文件体积可以缩小数十倍。

你可以用生活里的Excel表格来类比：barcodes是Excel的行名，features是列名，matrix.mtx是单元格里的数值，只不过它只存了非空白的单元格。搞懂这个结构，后面所有导入操作的报错原因你都能一眼看穿。

2.3 Cell Ranger输出目录长什么样

如果你决定从原始数据自己跑定量，那一定会接触Cell Ranger的输出目录。Cell Ranger是10x官方的比对和定量工具，跑完后会在outs目录下生成一整包结果。我们下游分析真正要用的核心目录叫filtered_feature_bc_matrix，里面的内容正是上面说的三件套，只是文件名都带.gz压缩后缀。与之并列的还有raw_feature_bc_matrix，那是做过简单过滤前的矩阵，细胞数非常多，包含大量背景液滴，新手在导入阶段优先使用filtered版本就好。

你还会在outs下看到analysis目录，里面有聚类、差异表达等官方预计算结果，不过这些主要以json和h5格式存在，大多数人在Seurat里会重新做一遍。另外会有一个cloupe.cloupe文件，那是给10x自家Loupe Browser软件看的可视化文件，在R里用不上。

我之所以花篇幅讲目录结构，是因为在GEO下载到的很多tar.gz压缩包，解压后就是按照这种目录结构组织的。你只要看到filtered_feature_bc_matrix这样的路径，就知道该把data.dir指向哪里，而不是瞎猜。

3. 上手实操：用10x官方数据完成下载与导入

现在进入正题。我们从10x官方示例数据PBMC 3k出发，完成一次从下载到导入Seurat的完整流程。整个操作建议在Linux服务器或Mac上做，Windows用户用浏览器下载tar包也可以，后面我会专门说明。

3.1 准备工作：环境与R包

先确认环境。R版本建议4.2以上，RStudio或命令行运行R都可以。你需要安装Seurat以及它依赖的SeuratObject包。国内网络环境下，直接install.packages连CRAN可能很慢，建议配置清华或中科大镜像。

options(repos = c(CRAN = "https://mirrors.tuna.tsinghua.edu.cn/CRAN/")) install.packages("Seurat")

如果Bioconductor系列包缺失，还要配BiocManager。一次装不成功很常见，关键是看报错里缺哪个系统依赖，比如Ubuntu上缺libcurl、libxml2，用apt装上再回去重装R包就行。装完以后建议把包版本记录到MD笔记里，这是可复现的第一步。

sessionInfo()

输出的内容直接复制到笔记里，以后你遇到“为什么我的Seurat版本跑出的结果和教程不一样”这种问题，回头对比sessionInfo就能定位。

3.2 下载PBMC 3k压缩包并解压

打开10x官网的sample数据集页面，找到PBMC 3k版本，下载filtered_gene_bc_matrices.tar.gz。在Linux终端操作的话，命令大概是这样：

mkdir -p scRNA_practice/pbmc3k cd scRNA_practice/pbmc3k wget https://cf.10xgenomics.com/samples/cell-exp/3.0.0/pbmc_3k/pbmc_3k_filtered_gene_bc_matrices.tar.gz tar -xzvf pbmc_3k_filtered_gene_bc_matrices.tar.gz find . -type f

解压后你应能看到类似filtered_gene_bc_matrices/hg19/的目录，里面躺着barcodes.tsv、genes.tsv、matrix.mtx三个文件。老版本数据用的是genes.tsv，新版本用features.tsv，这只是命名习惯的差异，内容作用相同。Windows用户没有wget的话，可以直接用浏览器下载tar.gz，然后用7-Zip或RStudio里File菜单解压，注意解压时选择“解压到当前目录”，别又套一层同名文件夹。

我建议你下载完立刻执行md5sum，把校验值记进MD笔记，确保文件没损坏。

md5sum pbmc_3k_filtered_gene_bc_matrices.tar.gz

3.3 在R中导入数据并初步检查

打开R或RStudio，运行以下代码：

library(Seurat) counts <- Read10X(data.dir = "filtered_gene_bc_matrices/hg19") class(counts) dim(counts)

data.dir指的是包含三件套的那个目录，不是更外层目录。Read10X能自动识别带.gz的文件，不需要提前解压。counts的类型是dgCMatrix，这是R里常用的稀疏矩阵类，行是基因，列是细胞，和普通矩阵比内存占用小得多。

检查完矩阵维度就可以创建Seurat对象：

pbmc <- CreateSeuratObject(counts = counts, project = "pbmc3k", min.cells = 3, min.features = 200) pbmc

如果一切正常，你会看到一个显示2700个样本、将近14000个特征的Seurat对象。这意味着数据导入成功，你的scRNA-seq分析之旅正式开始了。

3.4 CreateSeuratObject参数到底代表什么

新手最容易忽略的是CreateSeuratObject里的两个过滤参数min.cells和min.features。min.cells=3表示一个基因至少在3个细胞里有表达才保留；min.features=200表示一个细胞至少要检测到200个基因才保留。前者用来剔除在极少数细胞中出现的零星表达，往往对应背景噪音；后者用来剔除空液滴或破损细胞，没有足够基因数的细胞是不完整的。

这两个参数配合起来，相当于在第一道关卡就帮我们丢掉明显低质量的数据。你可以试着把min.features调成1000，看看保留了多少细胞，再把调成50，看看混入了多少异常值。亲手尝试一次，比对一下Seurat对象里细胞数量的变化，你对质控的理解会深很多。

4. 常见问题与排查技巧实录

这一部分是我最想写的内容，因为很多坑是教程里不会告诉你的。下面按问题频率从高到低整理成速查表格，后面逐条展开。

4.1 下到的文件不是预期的东西

这是最常见也最坑的。GEO页面的下载链接很多，有些人看到GSM编号就一路点进去，最后下载了一个样本级的tar包，里面装的可能是cellranger count的中间输出，也可能是bam文件。应对办法很简单：先看文件后缀和大小，三件套的压缩文件通常只有几十到几百MB，整个单细胞样本的表达矩阵不会大到几个GB。如果下到的是几十GB的文件，那八成是原始测序数据没跑了。

另一个判断技巧是看GEO页面底部的文件说明列，标注h5、mtx.gz或csv的才是矩阵类文件；标注sra、fastq.gz的属于原始数据。如果有多个样本，注意看一下每个GSM对应的是哪个样本，别把不同样本的细胞混在一起。

4.2 tar包解压报错或解压后找不到文件

wget下载途中网络抖动，可能导致tar包不完整。Linux解压时会直接报gzip: stdin: unexpected end of file，这时重新下载并对比md5值即可。还有一种情况是磁盘满了，解压到一半报错，用df -h检查剩余空间。我个人的习惯是下载后先不急着解压，先记录文件大小和md5，再解压，能省去不少“到底哪个文件坏了”的纠结。

解压后找不到三件套的另一个常见原因是tar包里带了一层多余的目录，比如解压出的是filtered_gene_bc_matrices/hg19/。新手如果只盯着最外层，自然看不到文件。用find . -type f列出所有文件，看清楚真实层级再设置data.dir。

4.3 Read10X报错：cannot open gzfile或file not found

很多人的data.dir设置错误，指到了包含压缩包的上一层目录，里面根本没有barcodes.tsv。Read10X内部逻辑是到data.dir下找这三个固定文件名的文件，你必须保证这三个文件直接位于data.dir下，而不是再套子目录。如果你解压后的目录是filtered_gene_bc_matrices/hg19，data.dir就要写“filtered_gene_bc_matrices/hg19”，不带引号里的父路径。

如果文件名是genes.tsv而不是features.tsv，新版Seurat也能兼容。真正麻烦的是某些GEO上传者把文件改成了自定义名字，比如ref_genes.tsv，这种时候Read10X就找不到标准文件名了，解决方法是复制成标准文件名再读，或者就直接用data.table读取并自己构造稀疏矩阵，不过后者对新手不友好。

4.4 基因注释版本不一致的问题

导入成功不代表万事大吉。我遇到过几次这种情况：读入后基因名全是Ensembl ID，而后面想标注marker基因时需要的是基因符号；或者不同数据集的基因注释版本不同，合并时匹配不上。经验做法是在matadata笔记里第一时间记录参考基因组版本和注释来源，比如“使用的10x GRCh38参考基因组、gene symbol命名”或“Ensembl v93注释”，并统一用symbol或ID保存。

如果你需要把Ensembl ID转成symbol，可以用AnnotationDbi或Seurat的辅助函数，但注意转换过程中会有部分基因因为版本差异找不到对应符号，这是正常现象，记录丢弃的比例即可，不用慌。版本问题在合并多个数据集时尤其致命，我会在后续文章里单独展开。

4.5 数据集太大，内存根本读不进去

新手很容易一上来就下载一个几十万细胞的数据集，试图在16G内存的笔记本上跑。单细胞矩阵虽然稀疏，但几十万细胞仍然会让内存告急。解决顺序是这样的：先确认自己分析的目的，如果只是练手，用pbmc 3k这种几千细胞的样本就好；如果必须处理大数据，优先申请服务器；读入后尽早检查矩阵维度，如果基因数特别高，可以先按表达比例过滤一波。另外读入时可以用Read10X自带的参数只读取部分行，快速查看数据结构，但真正跑分析时还是建议一次性加载到内存里，反复读取反而更慢。

5. 实际跑完这些坑之后，我留下的一些小习惯

最后分享一点个人的工作习惯，不算是技术内容，但我觉得比单纯讲代码更重要。第一，我现在的每个scRNA-seq项目都会建一个固定的目录结构，比如data放原始下载文件，scripts放R和shell脚本，notebook放MD笔记，这样无论过多久回来，都能快速找到东西。第二，下载数据的第一时间就把链接、文件名、md5、下载日期写进MD笔记的表格里，这个习惯帮我避免了好几次“这个数据到底从哪来的”的窘境。第三，遇到任何报错，第一反应不是盲目搜索网上的答案，而是先保存报错原文和sessionInfo，再带着这两样东西去搜索，效率会高很多。

这篇文章写到这已经把scRNA-seq的数据下载与导入部分讲完整了。我用的是PBMC 3k这个经典数据集，路径相对简单，适合新手建立信心。等你把这份操作跑完，可以在Seurat对象上继续做标准化、PCA、聚类和UMAP可视化，你会发现前面这些关于文件结构、稀疏矩阵、路径配置的知识，在后面每一步都在发挥作用。数据结构理解得越扎实，后续分析出错的概率就越低。下一篇文章我打算讲一讲质量控制中那些“看起来能跑，但结果不对”的隐藏陷阱，如果你在这篇实操中遇到了我提到的任何一个问题，或者有其他奇怪的报错，欢迎带着报错信息来聊。