手上有 10X Genomics 单细胞数据却只拿到一串 GEO 编号或者想拿公开数据做自己的分析验证这大概是每个做单细胞的人都会撞上的第一道坎。NCBI 上堆着海量公共 10X 单细胞测序原始数据GEO 页面挂着的是整理好的表达矩阵真正能重新跑 Cell Ranger 的原始测序数据藏在 SRA 里从 SRR 条目到 ENA 镜像再到官方 BAM看着都能下但下下来之后文件名不对、read 顺序反了、化学版本认不出来Cell Ranger 照样直接给你报错退出。这篇就把这条链路从头到尾拆一遍怎么在 NCBI 上定位到正确的原始数据怎么用 SRA Toolkit 或 ENA 镜像把 fastq 拿下来怎么组织文件命名让 Cell Ranger 认得出来以及跑 count 的时候核数、内存、参考基因组这些参数该怎么定。不管你是刚接触单细胞、只会点鼠标的湿实验同学还是天天跟命令行打交道但没怎么碰过公共数据的数据分析人员按这篇的步骤走一遍应该都能把一份 SRR 数据跑成带注释的 count 矩阵。1. 先搞清楚 NCBI 上的 10X 数据到底长什么样1.1 SRR、SRX、SRP、PRJNA 四层结构的关系很多人第一次点进 SRA 页面会懵因为同一个研究在 NCBI 上有四五个不同的编号PRJNA 开头、SRP 开头、SRX 开头、SRR 开头还有一个 GEO 的 GSE 号到底该抄哪个去下载。这四层其实是一个从大到小的包含关系理解了这个层级你就能明白为什么有时候明明只想下一个样本却下回来一堆文件。PRJNABioProject最大的容器代表一个完整的项目可能横跨多个实验、多个物种、多个测序平台。你在论文的 Data Availability 里看到的通常就是这个或者 GEO 号。SRPStudy一个具体的研究比如某篇论文的全部测序数据。一个 PRJNA 下面可以有多个 SRP。SRXExperiment一个实验单元对应一种文库构建方式、一个样本的某一种处理。这是样本这一层。SRRRun真正落盘的测序数据文件。一个 SRX 可能对应多个 SRR也就是同一个文库跑了好几条 lane 或者多次测序。这里有个特别容易踩的坑一个 SRX 拆成多条 SRR 的时候这几条 SRR 是同一个文库的技术重复原则上需要合并后再跑 Cell Ranger。如果你只下了一条 SRR 就跑了分析得到的细胞数可能只有真实值的三分之一甚至更少。我在做一份心肌细胞的数据时就吃过这个亏——论文里写测了 8000 个细胞我用单条 SRR 跑出来只有 2400 个回头查 SRX 才发现下面挂着 4 条 SRR。反过来还有一种情况一个 SRP 下面每条 SRR 代表一个独立样本这时候每条 SRR 都要单独跑一次 Cell Ranger得到独立的 count 矩阵最后用 Seurat 或者 Scanpy 合并。判断标准很简单看 SRX 下面挂了几条 SRR如果 SRX 数量等于 SRR 数量基本就是一比一如果 SRR 数量是 SRX 的好几倍那大概率是拆 lane 的技术重复。1.2 SRA 里一条 10X run 的真实内容点开一条 SRR 记录你会看到一堆元数据Library Strategy 写 RNA-Seq、Library Layout 写 PAIRED、Instrument 写 Illumina NovaSeq 6000、Read Length 写 28/91 之类。这几项里面判断这是不是 10X 数据最关键的两个字段是Library Layout和Read Length。标准 10X Chromium 3 或 5 文库一定是双端测序而且两端的长度是不对称的一端 26bp 或 28bp装的是 16bp barcode 加 10bp 或 12bp UMI另一端 90bp 以上装的是 cDNA 插入片段。所以如果你看到 Read Length 写的是 28 91基本可以确定是 10X如果写的是 150 150那更可能是 bulk RNA-seq 或者 ATAC。另一个字段是Library Selection10X 数据通常写 cDNA 或者 unspecified。还有Design Description里有时候会直接写 10x Genomics Chromium。真正下下来之后一条 10X 的 SRR 会解压成两个或者三个文件一个 26/28bp 的短 read 文件R1barcode UMI一个 90bp 以上的长 read 文件R2cDNA有时候还有第三个文件I1sample index。这三者的顺序不是靠文件名保证的而是靠read 长度判断——这是后面章节里最重要的一条经验。1.3 三条下载路线各自适合什么场景从 NCBI 拿 10X 原始数据实际可走的路线有三条不是所有场景都适合同一条路选错了可能白白多花几个小时甚至一整天。路线数据源优点缺点适用场景SRA ToolkitNCBI SRA官方渠道元数据最全速度慢SRA Lite 格式容易出幺蛾子数据只在 NCBI 有或者需要严格溯源ENA 镜像EBI ENA直接给 fastq.gz速度通常快一个量级极少数数据集镜像不完整绝大多数场景首选官方 BAM 反拆GEO supplementary跳过下载原始测序数据文件可能更小需要 bamtofastq 工具BAM 可能已被裁剪GEO 提供 BAM 且 SRA 数据不好下把 ENA 排在首选不是没有理由的。NCBI 和 EBI 之间有数据同步协议绝大多数 SRA 数据在 ENA 上都有镜像而且 ENA 直接以标准 fastq.gz 格式提供不用经过 fasterq-dump 这一层转换省掉了一个巨大的中间文件和解压步骤。唯一的例外是某些非常新的数据可能还没同步过去或者某些受控访问的数据。所以我的习惯是先去 ENA 搜搜不到再回 SRA Toolkit。2. 10X fastq 的命名逻辑与 Cell Ranger 的读取规则2.1 R1、R2、I1 里到底装了什么这是整个流程里最容易被忽略、但错了就直接报废的一环。10X 的测序策略决定了它的 read 分工和普通双端测序完全不一样R1Read 1长度 26bp 或 28bp。前 16bp 是cell barcode用来标记这条 read 来自哪个液滴也就是哪个细胞剩下的 10bpv2 化学或 12bpv3 化学是UMI用来标记这条 read 来自哪个原始 mRNA 分子。R2Read 2长度 91bp 或 150bp。装的是cDNA 序列也就是真正要比对到参考基因组上的部分。I1Index Read10bp 左右装的是sample index。这是 Illumina 层面的样本标签只有在多样本混池测序、需要跑cellranger mkfastq做拆分的时候才用得上。关键点从 SRA 或 ENA 下载下来的 fastq已经完成了样本拆分I1 通常用不上。所以你要跑的是cellranger count不是cellranger mkfastq。这一点下面还会再强调。那怎么确认哪个文件是 R1看文件里第一条 read 的长度。用一条命令就能判断# 看前4行第2行是序列 zcat SRR1234567_1.fastq.gz | head -2 | tail -1 | awk {print length($0)} zcat SRR1234567_2.fastq.gz | head -2 | tail -1 | awk {print length($0)}输出 26 或 28 的那个就是 R1输出 91 或 150 的那个是 R2。这个动作花不了十秒钟但能帮你避开后面一小时的排错。我见过太多次有人想当然地把_1当 R1 直接用结果跑出来的 valid barcode 比例只有 3%还以为是数据质量问题。2.2 Cell Ranger 认的文件名长什么样Cell Ranger 不是随随便便给个 fastq 就能读的它对文件名有非常严格的 glob 匹配规则。cellranger count在--fastqs指定的目录里按照下面的模式去匹配文件{sample}_S*_L00*_R1_00*.fastq.gz {sample}_S*_L00*_R2_00*.fastq.gz其中{sample}就是你通过--sample参数传进去的字符串。也就是说标准命名应该长这样SRR1234567_S1_L001_R1_001.fastq.gz SRR1234567_S1_L001_R2_001.fastq.gz而 SRA 或 ENA 下载下来的文件名通常是这样的SRR1234567_1.fastq.gz SRR1234567_2.fastq.gz这两个名字对不上直接跑会报 No fastq files found 或者 Sample not found。解决办法就是重命名这是整个流程里最枯燥但绝不能跳过的一步cd /data/fastq/SRR1234567 mv SRR1234567_1.fastq.gz SRR1234567_S1_L001_R1_001.fastq.gz mv SRR1234567_2.fastq.gz SRR1234567_S1_L001_R2_001.fastq.gzS1表示 sample 序号L001表示 lane 号001是文件分块序号。这些数字本身对单样本分析没有实际意义只要满足格式、且同名样本的两端文件编号一致就行。注意--sample传的值必须和文件名的前缀完全一致包括大小写。SRR1234567和srr1234567在 Cell Ranger 眼里是两个完全不同的样本。2.3 化学版本怎么判断判断错了会怎样10X 的化学版本经历了几次迭代barcode 和 UMI 的长度、barcode 白名单都不一样化学版本R1 长度Barcode 长度UMI 长度Cell Ranger 参数3 v126bp16bp10bpSC3Pv13 v226bp16bp10bpSC3Pv23 v3 / v3.128bp16bp12bpSC3Pv35 v1 / v226bp16bp10bpSC5P-PE / SC5P-R25 v328bp16bp12bpSC5P-PE / SC5P-R2好消息是 Cell Ranger 默认的--chemistryauto会自动检测绝大多数情况下不用手动指定。但自动检测不是万能的遇到以下几种情况就需要人工干预数据经过裁剪R1 长度不是标准的 26 或 28bp数据是 5 文库但检测成了 3测序质量差barcode 白名单匹配率太低检测逻辑拿不到足够信号。判断化学版本最直接的办法是看 R1 长度26bp 就是 v2/5v228bp 就是 v3。如果数据是最近三年产生的基本都是 v3 或 v3.1直接用 auto 就行。如果化学版本判断错了会怎样最典型的表现是valid barcode 比例极低。正常样本这个值应该在 80% 到 95% 之间如果你看到只有 5% 到 20%基本可以断定是 R1/R2 搞反了或者化学版本填错了。这时候先别急着怀疑数据质量先回头检查这两个参数。3. 动手下载从 SRR 到可分析的 fastq3.1 SRA Toolkit 的安装与必要配置SRA Toolkit 是 NCBI 官方提供的下载和解压工具装起来不复杂但有几个默认配置不改会很难受尤其是磁盘空间。# 下载预编译版本 wget https://ftp-trace.ncbi.nlm.nih.gov/sra/sdk/current/sratoolkit.current-ubuntu64.tar.gz tar -xzvf sratoolkit.current-ubuntu64.tar.gz export PATH$PATH:$(pwd)/sratoolkit.3.1.1-ubuntu64/bin # 验证安装 fastq-dump --version第一件必须改的事是cache 目录。SRA Toolkit 默认把中间文件放在~/ncbi下面而你 home 目录大概率没那么多空间。一条 30GB 的 SRA 数据在解压过程中会产生几十 GB 的临时文件空间不够会直接把任务搞崩。vdb-config --set /repository/user/main/public/root/data/sra_cache mkdir -p /data/sra_cache也可以用交互式界面改vdb-config --interactive进去之后在 Cache 标签页里把路径改掉。顺便把 Prefetch 的最大文件大小限制也调一调默认 20GB10X 数据经常超标。第二件必须改的事是临时目录。fasterq-dump 会把中间文件写到一个临时目录默认是/tmp很多服务器上/tmp是个小容量的内存盘几十 GB 数据一进去就爆。这个在命令里用--temp指定就行下面会写。3.2 prefetch fasterq-dump 组合拳标准的 SRA Toolkit 下载分两步prefetch负责把.sra文件下到本地fasterq-dump负责把它转成 fastq。# 第一步下载 sra 文件 prefetch SRR1234567 \ --max-size 100G \ --output-directory /data/sra_cache # 第二步转成 fastq fasterq-dump /data/sra_cache/SRR1234567/SRR1234567.sra \ --split-files \ --threads 16 \ --temp /data/tmp \ --outdir /data/fastq_raw \ --progress几个参数值得单独说明--max-size 100G不设这个超过 20GB 的数据 prefetch 会直接拒绝下载--split-files把双端 read 拆成两个文件。不加这个参数会输出到同一个文件里10X 数据必须加--threads 16fasterq-dump 的多线程效果还算明显16 线程比单线程大概快 3 到 4 倍--temp /data/tmp指定临时目录这是防炸/tmp的关键。如果这条 SRR 带有 index readfasterq-dump 默认不会输出它。需要加--include-technical才会生成第三个文件SRR1234567_3.fastq。不过前面说过从 SRA 下的数据已经拆好样本了index read 用不上不用加这个参数。再说一个实操细节fasterq-dump输出的 fastq 是未压缩的。一份 1.5 亿 reads 的 10X 数据两个 fastq 加起来可能有 40GB 到 60GB而 gzip 压缩后只有 8GB 到 12GB。所以转换完之后立刻压缩不然磁盘会涨得很快pigz -p 16 /data/fastq_raw/SRR1234567_1.fastq pigz -p 16 /data/fastq_raw/SRR1234567_2.fastq用pigz而不是gzip多核压缩能把这一步的时间从十几分钟压到一两分钟。3.3 ENA 镜像直连下载速度快一个量级如果你的数据在 ENA 上有镜像我强烈建议走这条路。ENA 直接提供.fastq.gz不用经历 下载 sra → 解压成 fastq → 再压缩 这个来回折腾省下的时间和磁盘空间相当可观。拿真实下载地址最稳妥的方式是通过 ENA 的 Portal API 查询而不是自己拼 URLcurl -s https://www.ebi.ac.uk/ena/portal/api/filereport?accessionSRR1234567resultread_runfieldsrun_accession,fastq_ftp,fastq_bytes,library_layout,read_countformattsv | column -t输出里fastq_ftp那一列就是真实的下载路径。拿到之后直接 wgetwget -c ftp://ftp.sra.ebi.ac.uk/vol1/fastq/SRR123/007/SRR1234567/SRR1234567_1.fastq.gz wget -c ftp://ftp.sra.ebi.ac.uk/vol1/fastq/SRR123/007/SRR1234567/SRR1234567_2.fastq.gz提示ENA 的目录结构是按 accession 的位数生成的不同位数的编号路径层级不一样自己手拼 URL 很容易拼错。用 API 拿真实路径或者用 SRA Explorer 这类在线工具一键生成下载脚本都比手拼靠谱。如果要整批下载一个项目的所有 run可以这样写curl -s https://www.ebi.ac.uk/ena/portal/api/filereport?accessionPRJNA123456resultread_runfieldsrun_accession,fastq_ftpformattsv \ | tail -n 2 \ | cut -f2 \ | tr ; \n \ | sed s|^|https://| \ | wget -c -i -这段脚本的意思是调 API 拿整个 BioProject 下所有 run 的 fastq 路径跳过表头取第二列把一行里用分号分隔的多条路径拆成多行加上 https 前缀然后批量下载。配合-c断点续传网络抖动也不怕。实测下来同样一份数据用 ENA 下载通常比 SRA Toolkit 快三到五倍。3.4 从 10X 官方 BAM 反拆 fastq有些数据集在 GEO 的 supplementary files 里直接挂了 BAM这时候就多了一条路。但不是所有 BAM 都能反拆这一点必须分清楚可以反拆测序公司交付的、或者提交到 GEO 的比对前 BAM通常叫*.bam里面 read 是原始的barcode 序列完整保留可以尝试Cell Ranger 输出的possorted_genome_bam.bam里面 R1 的 barcode 序列还在但需要确认 read 没有被裁剪不能反拆只有filtered_feature_bc_matrix或者raw_feature_bc_matrix这种三件套矩阵。矩阵里已经没有任何原始序列信息了想跑 Cell Ranger 只能回头去下 SRA 或 ENA。工具有两个选择10X 官方出的bamtofastq或者samtools配合手写脚本。强烈推荐前者因为它会自动识别 10X 的 read 结构输出标准命名的文件。# 下载预编译二进制 wget https://github.com/10XGenomics/bamtofastq/releases/download/v1.4.1/bamtofastq_linux chmod x bamtofastq_linux # 反拆 ./bamtofastq_linux --nthreads16 input.bam /data/fastq_bam/跑完之后输出目录里会是这样的文件bamtofastq_S1_L001_I1_001.fastq.gz bamtofastq_S1_L001_R1_001.fastq.gz bamtofastq_S1_L001_R2_001.fastq.gz这个命名已经完全符合 Cell Ranger 的要求了直接--samplebamtofastq就能跑省掉了重命名这一步。注意 I1 文件也会被生成出来cellranger count不会用它可以忽略也可以删掉。3.5 重命名、压缩与目录组织不论走哪条路下来最后都要落到一个统一的目录结构上。我的习惯是这样/data/scRNA/ ├── ref/ │ └── refdata-gex-GRCh38-2020-A/ ├── fastq/ │ ├── SRR1234567/ │ │ ├── SRR1234567_S1_L001_R1_001.fastq.gz │ │ └── SRR1234567_S1_L001_R2_001.fastq.gz │ └── SRR1234568/ │ ├── SRR1234568_S1_L001_R1_001.fastq.gz │ └── SRR1234568_S1_L001_R2_001.fastq.gz └── results/ ├── SRR1234567_run/ └── SRR1234568_run/每个样本一个独立子目录好处是多个样本放在同一个父目录下也不会互相干扰——因为cellranger count是按--sample前缀去匹配的只要前缀不同就行。当然把每个样本单独放一个目录更清爽也避免--fastqs指错目录把别的样本文件也扫进去。重命名我通常写成一个小循环for d in /data/scRNA/fastq/SRR*/; do s$(basename $d) mv ${d}/${s}_1.fastq.gz ${d}/${s}_S1_L001_R1_001.fastq.gz 2/dev/null mv ${d}/${s}_2.fastq.gz ${d}/${s}_S1_L001_R2_001.fastq.gz 2/dev/null done跑之前先在测试目录里跑一遍确认改名逻辑没问题再上真实数据。改错名比不改名更麻烦因为 Cell Ranger 可能匹配上了错误的文件却不报错直接给你一堆垃圾结果。3.6 参考基因组的下载与校验Cell Ranger 不自带参考基因组需要单独下载。10X 官方提供了几个预构建好的物种参考基因组包大小适用 Cell Ranger 版本人refdata-gex-GRCh38-2020-A约 11GB5.0 及以上小鼠refdata-gex-mm10-2020-A约 10GB5.0 及以上人鼠混合需自行构建--cd /data/scRNA/ref wget -c https://cf.10xgenomics.com/supp/cell-exp/refdata-gex-GRCh38-2020-A.tar.gz tar -xzvf refdata-gex-GRCh38-2020-A.tar.gz # 校验完整性 wget -c https://cf.10xgenomics.com/supp/cell-exp/refdata-gex-GRCh38-2020-A.tar.gz.md5 md5sum -c refdata-gex-GRCh38-2020-A.tar.gz.md5校验这一步别省。参考基因组下载失败是很隐蔽的问题10GB 的文件下载中断了但 wget 没报错跑 Cell Ranger 的时候会报一堆莫名其妙的错。花三十秒做一次 md5 校验能省掉后面几小时的困惑。如果你的样本是混合物种比如人细胞打到小鼠体内做异种移植或者物种不在官方列表里比如斑马鱼、果蝇就需要用cellranger mkref自己构建。构建需要两个输入参考基因组 fasta 和 GTF 注释文件两者的染色体命名必须一致都带chr或者都不带否则构建会失败或者后续比对率极低。这个坑我在做一份大鼠数据的时候踩过GTF 里的染色体名带chrfasta 里不带mkref 跑完了但比对率只有 12%排查了半天才找到原因。4. Cell Ranger count 的完整跑法与参数取舍4.1 最小可用命令准备工作做完之后实际跑 count 的命令本身很简单cd /data/scRNA/results cellranger count \ --idSRR1234567_run \ --transcriptome/data/scRNA/ref/refdata-gex-GRCh38-2020-A \ --fastqs/data/scRNA/fastq/SRR1234567 \ --sampleSRR1234567 \ --expect-cells5000 \ --localcores16 \ --localmem64--id是输出目录的名字跑完之后会在results/下面生成一个同名目录里面包含outs/filtered_feature_bc_matrix/过滤后的表达矩阵这是后续分析的主要输入outs/raw_feature_bc_matrix/包含空液滴的原始矩阵outs/possorted_genome_bam.bam比对结果如果不需要可以关掉outs/web_summary.html质控报告一定要看outs/metrics_summary.csv关键指标方便批量整理。4.2 关键参数逐个拆解--expect-cells是最容易被低估的参数。默认值是 3000它不影响细胞识别的算法结果只影响报告里的一些归一化展示和对 multiplet 的估算。但如果你事先知道论文里说这个样本有 8000 个细胞填 3000 会让报告里的 Estimated Number of Cells 显示不准虽然矩阵本身差不多。所以习惯上我会去论文的 Methods 或者 GEO 页面找一下细胞数按真实值填。--localcores和--localmem直接决定跑多久、会不会崩。这两个参数要根据服务器的实际配置来不能贪心。--localmem填的值必须小于服务器物理内存因为 Cell Ranger 还需要额外的空间做中间计算。如果服务器是 128GB 内存填 100 到 110 比较稳妥填 128 大概率会在最后阶段 OOM。--create-bam默认是 true会生成一个几 GB 到几十 GB 的 BAM。如果这次分析只是想要表达矩阵加上--create-bamfalse能省下大量磁盘和一部分时间。--nosecondary会跳过二次分析也就是自动的聚类、降维、差异表达只做比对和定量。跑完矩阵自己用 Seurat 或 Scanpy 分析的话可以加上这个参数通常能省 20% 到 30% 的时间。不过第一次跑某个数据我建议还是开着因为 web_summary 里的聚类图能帮你快速判断这次定量是不是正常。--chemistry前面说过了默认 auto。只有自动检测失败的时候才手动指定比如--chemistrySC3Pv3。4.3 资源规划核数、内存、时间怎么估很多人跑 Cell Ranger 之前完全没有资源概念开了 8 核 32GB 就去跑一个大样本结果跑到一半 OOM白等了几个小时。这里给一套可以照着算的估算方法。第一步估 reads 数量。10X 3 文库每个细胞的有效 read 对数通常在 20000 到 50000 之间。假设你的样本是 5000 个细胞按每个细胞 30000 对估算5000 细胞 × 30000 对/细胞 1.5 亿对 reads第二步估 fastq 大小。每对 read 的数据量是 R1 加 R2 的长度和v3 化学下是28bp 91bp 119bp 1.5 亿对 × 119bp 178.5 亿碱基 ≈ 17.85 GB未压缩fastq 的 gzip 压缩率大约在 4 到 5 倍之间所以压缩后大约 3.5GB 到 4.5GB。这个数字可以用来核对下载文件是否完整——如果你预估是 4GB 但只下了 400MB那肯定是断了。第三步估内存。Cell Ranger 的内存占用和 reads 数量、参考基因组大小强相关人基因组下有个粗略的经验值reads 数量建议内存建议核数预计耗时5000 万对32GB830-60 分钟1.5 亿对64GB161.5-3 小时4 亿对128GB24-324-8 小时8 亿对以上200GB328 小时以上这张表是经验值实际会因为磁盘 IO 速度、参考基因组版本、样本复杂度浮动。比如服务器用的是机械硬盘同样的任务可能要多花一倍时间如果是全 NVMe 存储速度会明显快一些。第四步估磁盘。Cell Ranger 运行过程中会在输出目录写大量中间文件峰值占用大约是输入 fastq 大小的 5 到 10 倍。所以跑一个 4GB fastq 的样本至少要预留 40GB 以上空间。加上 BAM预留 100GB 更保险。5. 报错与异常排查实录5.1 下载与解压阶段的坑坑一fasterq-dump 输出长度异常或者报 SRA Lite 相关的提示。NCBI 从 2023 年开始对新提交的数据使用新的归档格式用旧版本的 SRA Toolkit 处理这类数据时可能出现 read 长度不对、质量值异常或者直接报错的情况。遇到这种情况别硬刚直接把 accession 丢到 ENA 上查一下只要有镜像就换 ENA 下载。我自己的做法是能走 ENA 就不碰 SRA Toolkit除非 ENA 上确实没有。坑二prefetch 下到一半卡住不动进度条长时间不变。大概率是网络抖动或者 NCBI 那边限速。CtrlC 中断后重新执行 prefetch它会自动断点续传不用删掉已有的部分。如果反复卡在同一个位置可以试试--resume参数或者干脆换成 ENA。坑三fasterq-dump 报磁盘空间不足但 df 显示还有空间。十有八九是临时目录写满了。前面强调过的--temp参数就是为了这个如果没设默认写到/tmp而/tmp在很多服务器上是个小容量的 tmpfs。检查一下df -h /tmp如果/tmp只有几个 GB那问题就找到了。重新跑的时候加上--temp /data/tmp。坑四下载下来的 fastq 只有一条 read。检查是不是漏了--split-files参数或者这条 SRR 本身是单端测序。单端的 10X 数据非常少见如果真是单端那基本不适合拿来做标准分析。5.2 Cell Ranger 报错对照表报错信息可能原因处理方式No fastq files found matching the pattern文件名不符合{sample}_S*_L00*_R*_00*.fastq.gz按 2.2 节的规则重命名Sample not found in the fastq directory--sample传的值和文件名前缀不一致检查大小写和前缀Chemistry detection failedR1 长度非标准或质量太差手动指定--chemistryInsufficient memory--localmem设得太大或 reads 太多调小 localmem 或换更大的机器Barcode not found in whitelistR1/R2 搞反了或化学版本不对用 2.1 节的方法检查 R1 长度Reference genome is incompatible参考基因组版本和 Cell Ranger 版本不匹配下载对应版本的 refdata关于 Barcode not found in whitelist 这个报错还想多说一句。它有时候不会直接报错而是把 valid barcode 比例压到很低然后正常跑完、正常出结果。这种静默失败最危险因为你会以为分析成功了。所以每次跑完都去看一眼 web_summary.html 里的 Fraction of Reads with Valid Barcodes正常值 80% 以上低于 60% 就要警觉低于 30% 基本可以判定输入数据有问题。5.3 结果层面的异常与判断跑完不报错不代表结果可信几个关键指标得自己会看Estimated Number of Cells和论文报告的数量差太多就要找原因。差个 10% 到 20% 正常差 5 倍就是数据选错了或者 SRR 没合并。Median Reads per Cell正常 20000 到 50000。如果只有几千说明测序深度不够或者选错了 SRR。Median Genes per Cell人的 PBMC 样本通常在 1200 到 2500 之间组织样本会低一些。低于 500 基本没法做后续分析。Fraction of Reads in Cells正常 70% 以上。太低说明空液滴太多可能是细胞悬液质量差。Sequencing Saturation正常 70% 到 90%。太低说明测序深度还有余量太高说明已经测饱和了。把这些指标从metrics_summary.csv里批量提取出来对比是判断一批样本能不能放在一起分析的第一步for f in /data/scRNA/results/*/outs/metrics_summary.csv; do echo $(basename $(dirname $(dirname $f))) cat $f done如果发现某个样本的所有指标都明显偏离其他样本先别急着加进分析回头查它的 SRR 编号和下载记录。6. 一些不太好写进文档的经验6.1 数据溯源这件事做一次省十次每下载一份数据我都会在样本目录里放一个README.txt记录四件事PRJNA 号、SRP 号、每条 SRR 号对应的样本描述、下载日期和下载方式。听起来有点啰嗦但你做三个月后回头看或者把数据交给合作者的时候这份记录能救命。尤其是有时候一个 SRP 下面挂着几十条 SRR每条对应一个患者或者一个时间点元数据表格和 SRR 编号的对应关系全靠 GEO 页面上的那张表。把那张表下载下来存一份比每次去网页上翻要靠谱得多。# 把 GEO 的样本元数据存下来 wget -O GSE123456_metadata.txt.gz https://www.ncbi.nlm.nih.gov/geo/query/acc.cgi?accGSE123456targselfformtextviewbrief6.2 我自己的处理习惯分享几个我这些年固定下来的习惯不一定是最优解但确实帮我少踩了很多坑。先下一条 SRR 试跑再批量下。一个项目动辄几十条 SRR全下下来可能几百 GB。先挑一条 SRR 走完整流程从下载、改名到 Cell Ranger 跑通确认参考基因组、化学版本、参数都没问题再批量处理剩下的。这个习惯帮我避免过好几次下了 300GB 数据发现参考基因组选错了的悲剧。用 md5 记录下载完整性。ENA 下载完之后算一次 md5 存起来如果后面发现解压报错或者 Cell Ranger 报文件损坏至少知道是哪一步出的问题。md5sum *.fastq.gz md5sums.txt不要在输出目录上省钱。Cell Ranger 的输出目录会非常大尤其是带 BAM 的情况下。宁可多留空间也不要跑到最后一步因为磁盘满而失败。样本命名带上项目前缀。如果你同时在做几个项目SRR1234567_S1_L001_R1_001.fastq.gz这种纯 accession 命名在一堆文件里很难辨认。可以在--id和输出目录上加上项目前缀比如--idGSE123456_SRR1234567这样后面整理结果的时候一目了然。最后补充一个我觉得挺有用的小技巧如果你的分析需要把 Cell Ranger 的矩阵导入 Seuratfiltered_feature_bc_matrix目录可以用Read10X()直接读但要注意 features.tsv 里的基因名可能带版本号比如ENSG00000223972.5不同样本的版本号可能不一致合并的时候会出问题。我一般会在读入之后统一去掉版本号后缀或者在跑 Cell Ranger 的时候就用不带版本号的 GTF。这个细节看起来小但在整合多个数据集的时候能省掉不少麻烦。