📚 课程目录第3章 Cell Ranger数据处理

Cell Ranger 数据处理：命令行运行、质量报告解读、常见问题处理

好了，咱们聊到 Cell Ranger 了。这是 10x Genomics 官方给的流程，说白了就是把你的原始测序数据，处理成我们能用的表达矩阵。我个人习惯把它看作一道「工序流水线」——从 FASTQ 进去，一路经过比对、计数，最后吐出我们最关心的结果文件。

核心观点：Cell Ranger 不是简单的脚本堆叠，它内置了 STAR 比对器、UMI 计数校正、barcode 白名单过滤等关键模块。理解它的每一步，能帮你省掉后面 80% 的排坑时间。

命令行运行：基础与进阶

先看最基础的跑法。假设你拿到的就是标准的 10x 数据，一个样本对应一个 FASTQ 目录。

cellranger count --id=sample1 \
                 --transcriptome=/ref/refdata-gex-GRCh38-2024-A \
                 --fastqs=/data/sample1_fastqs \
                 --sample=Sample1 \
                 --localcores=16 \
                 --localmem=64

这里我简单拆解一下参数：

--id：输出目录的名字，我习惯用样本名加日期，比如 sample1_20250118。
--transcriptome：参考基因组路径。注意版本号，别忘了加绝对路径。
--fastqs：FASTQ 所在目录，不是具体文件。
--sample：匹配 FASTQ 文件名中的样本前缀，大小写敏感。
--localcores / --localmem：指定线程和内存。我建议内存不低于 64GB，否则可能会卡在「Mapping」那一步。

经验之谈：我刚开始跑的时候，以为 --fastqs 可以直接给文件列表，结果抛了个找不到文件的错。后来才发现它只认目录，而且里面不能有其他无关的 FASTQ。你想想看，我那次排查了一下午才找到原因。

另外，有个参数我经常用但容易被忽略：--chemistry。如果你用的是 10x 新版试剂（比如 v3 或 v3.1），建议显式指定：

cellranger count --id=sample2 \
                 --transcriptome=/ref/refdata-gex-GRCh38-2024-A \
                 --fastqs=/data/sample2_fastqs \
                 --sample=Sample2 \
                 --chemistry=auto \
                 --localcores=16 \
                 --localmem=64

设置 --chemistry=auto 会自动检测，但有时候检测不准。我记得有一次项目急着出结果，auto 模式误判成了 v2 试剂，导致后面分析时基因检出率偏低，浪费了 3 天时间重跑。现在我都会先看一眼细胞数，再手动指定。

质量报告解读：四个核心维度

跑完之后，Cell Ranger 会在输出目录生成一个 web_summary.html。这个文件打开后，别只看一眼就关掉。我一般会从四个维度逐项检查。

维度	关键指标	理想值	警告线
有效条形码	Valid Barcodes	> 90%	< 70%
测序饱和度	Sequencing Saturation	50% - 80%	< 30% 或 > 95%
比对结果	Confidently Mapped to Transcriptome	> 30%	< 20%
细胞识别	Estimated Number of Cells	与预期误差 < 20%	差异 > 50%

咱们一个一个说。

第一，有效条形码比例。这个值偏低，通常意味着 index 交叉污染或者样本混淆。如果你发现低于 70%，我建议先检查一下 FASTQ 文件名后缀，确认没有混入其他样本的 reads。

第二，测序饱和度。这是个很微妙的指标。饱和度低，说明测序深度不够，很多基因还没测到；饱和度高到 95% 以上，说明 reads 严重冗余，你其实浪费了很多数据。我个人习惯控制在 60% 左右，这时候捕获的基因数基本稳定，又不至于过度测序。

第三，比对率。重点看「Confidently Mapped to Transcriptome」。如果这个值低于 20%，要么参考基因组不对，要么样本质量太差。我有一次遇到只有 15% 的比对率，查了一圈发现是参考基因组版本和测序试剂不匹配——我是用小鼠参考组去比对人的数据，你说离谱不离谱？

第四，细胞数。Cell Ranger 会估算一个细胞数，但你最好留个心眼。它有时候会高估或低估，特别是当细胞活性低、碎片多的时候。我会结合我的实验设计，比如我上机时计了 10000 个细胞，那么估算值在 8000-12000 之间我认为是正常的。

避坑指南：我曾经遇到过一个样本，所有指标看起来都正常，唯独基因检出中位数低得离谱。我找了两天，最后发现是 Cell Ranger 的版本兼容性问题。旧版本（3.0 之前）对 barcode 白名单的处理有 bug。升级到 7.0 后一切正常。

常见问题处理

说几个我实际项目中遇到最多的痛点。

问题 1：内存不足导致进程被 kill。

表现是运行日志最后一行写着 Killed 或者 Out of memory。通常是因为参考基因组太大，或者 FASTQ 文件巨多。解决办法有两个：

缩小 --localmem 到你机器实际可用内存的 75%。比如机器有 128GB，那就设成 96GB。
如果还不行，试试 --jobmode=local --localcores=8 --localmem=48，降低并行度。

问题 2：比对率极低但清楚样本没问题。

遇到过吗？我有一次就是，比对率只有 5%，赶紧检查参考基因组路径。原来是我在写 --transcriptome 时路径写错了软链接，实际指向了一个空目录。重建软链接后，比对率直接跳到 40%。

问题 3：细胞数估算异常。

如果估算的细胞数远大于预期，多半是捕获了大量的空油滴或碎片。可以尝试调整 cellranger 的 --force-cells 参数，但我不建议盲目设置。更好的方法是先查看 barcoded.fastq.gz 的复杂度，确认干扰比较明显时再手动指定细胞数。

cellranger count --id=sample3 \
                 --transcriptome=/ref/refdata-gex-GRCh38-2024-A \
                 --fastqs=/data/sample3_fastqs \
                 --sample=Sample3 \
                 --force-cells=5000 \
                 --localcores=16 \
                 --localmem=64

建议：永远保留 cellranger count 的原始运行日志。它包含了每一步的时间和资源消耗，是排查问题的第一手资料。我习惯在项目结束后把日志打包成 logs.zip 和结果一起归档。

嗯，Cell Ranger 这块基本就这些。理解它的输入输出，会看质量报告，能处理常见错误，后面做拟时序分析才不会被垃圾数据带偏思路。下面我用一张图总结一下 Cell Ranger 的完整流程。

图上清楚展示了 FASTQ 经过四步处理——校正、比对、计数、细胞判别，每一步都对应一个质控关卡。你跑完 Cell Ranger 后，对照着图去读 web_summary，会清晰很多。