Cell Ranger 安装与上游分析：自检、FASTQ 和参考文件 ​

10x 单细胞分析入门 · 第 04 篇

这篇处理“只有 GEX FASTQ，怎样得到表达矩阵”。先安装并自检，再检查输入，最后给出单文库 count 的运行模板。已有矩阵的读者可以直接进入Seurat 导入。

命令基线为 Cell Ranger 8.0.1，适用于该版本支持的常规非混样 GEX 文库。新试剂、Flex、混样或配套多文库需要先查对应版本的支持表。它不是一个可覆盖所有 10x 数据的通用命令。

本轮没有完整复跑 FASTQ 上游。这里的安装和流程命令依据官方文档编写，运行路径与样本名前缀为示意；后面的 PBMC 3k Seurat 演示直接使用官方已经生成的旧版矩阵，不会重现为本节的 Cell Ranger 8 输出。

先检查硬件，别先下载参考 ​

Cell Ranger 面向受支持的 Intel/AMD 64 位 Linux 环境。本教程验证 Seurat 所用的 ARM64 环境不符合这条上游路线。Windows 本机的 cmd 和 macOS ARM 终端不能直接套用下面的原生 Linux 命令。

bash
uname -m
lscpu
free -h
df -h "$HOME"
ulimit -n

CPU 指令集、内存、空间和操作系统均应与10x 系统要求核对。官方基线包含 8 核 Intel/AMD、64 GB 内存；参考、BAM 和临时文件还会使用较多空间。--localmem 只约束软件可用内存，不会给机器增加物理内存。

下载、解压与验证命令 ​

在 10x Cell Ranger 下载中心选择对应版本，按官网给出的地址下载。下载链接可能含有效期，不把临时链接固定进教程。将下载包放在自己的 ~/Downloads，确认文件名后执行：

bash
mkdir -p ~/apps ~/sc-course/logs
tar -tzf ~/Downloads/cellranger-8.0.1.tar.gz | head
tar -xzf ~/Downloads/cellranger-8.0.1.tar.gz -C ~/apps
export PATH="$HOME/apps/cellranger-8.0.1:$PATH"
command -v cellranger
cellranger --version

若下载的版本不同，压缩包名和目录名要一起修改。先用当前终端的 export 验证，成功后再写入自己的 shell 配置，不要覆盖整个 PATH。

bash
cd ~/sc-course
cellranger sitecheck > logs/cellranger-sitecheck.txt 2>&1
less logs/cellranger-sitecheck.txt

sitecheck 生成的是环境报告，要读其中的 CPU、内存、磁盘和资源限制。随后在新建的测试目录中运行安装测试：

bash
mkdir -p ~/sc-course/upstream-test
cd ~/sc-course/upstream-test
cellranger testrun --id=check_install

成功标志按官方安装教程核对。testrun 成功仅验证小型测试数据能运行，不代表你的参考、FASTQ 配对和文库设计均正确。

准备真实输入的三项检查 ​

假设你自己的文库前缀为 PBMC_A，FASTQ 文件类似：

text
PBMC_A_S1_L001_R1_001.fastq.gz
PBMC_A_S1_L001_R2_001.fastq.gz

先核对以下材料：

输入要确认什么
FASTQ 目录文件来自同一文库，lane 完整，压缩包校验通过
--sample填真实 FASTQ 样本前缀，不是完整文件名，也不是随意取的展示名称
转录组参考目录物种和注释版本正确，目录包含预建索引；不能只给一个 FASTA
bash
find ~/sc-course/data/fastq -maxdepth 1 -name '*.fastq.gz' -print
gzip -t ~/sc-course/data/fastq/*.fastq.gz
ls ~/refs/refdata-gex-GRCh38-2020-A

上述参考名称只是固定版本示例，需从官方获取兼容的预建参考。不要将不同基因组版本的 FASTA、GTF 和 STAR 索引混在同一个目录里。

运行单个 GEX 文库 ​

下面是命令模板，只有实际准备好这些文件和资源后才执行。Bash 中启用 pipefail，避免 tee 成功掩盖了 Cell Ranger 失败。

bash
set -o pipefail
mkdir -p ~/sc-course/upstream ~/sc-course/logs
cd ~/sc-course/upstream
cellranger count \
  --id=PBMC_A_count \
  --transcriptome="$HOME/refs/refdata-gex-GRCh38-2020-A" \
  --fastqs="$HOME/sc-course/data/fastq" \
  --sample=PBMC_A \
  --create-bam=true \
  --localcores=8 \
  --localmem=64 \
  2>&1 | tee "$HOME/sc-course/logs/PBMC_A_count.log"

资源参数须符合分配给你的服务器额度，并为系统留出内存。运行目录已经存在时，工具可能尝试恢复先前任务；改了输入或参考后，使用新的运行 ID，别把两个分析混入同一输出目录。

本例保留自动细胞判定。不要为了得到预期细胞数就随意使用 --force-cells。涉及多文库和混样时，转去核对 multi 配置，不能靠增加几个文件名让单文库模板适用。

完成后核对输出，而不是只看进程消失 ​

常规 count 结果的 outs/ 应包含 Web Summary、指标表以及表达矩阵。以实际版本输出为准：

bash
ls ~/sc-course/upstream/PBMC_A_count/outs
test -s ~/sc-course/upstream/PBMC_A_count/outs/web_summary.html
test -s ~/sc-course/upstream/PBMC_A_count/outs/filtered_feature_bc_matrix.h5
tail -n 30 ~/sc-course/logs/PBMC_A_count.log

日志是否正常完成、输出是否完整、Web Summary 是否有告警，都需要检查。No input FASTQs were found 先查目录和 --sample；内存或进程被杀先查资源与调度记录。删除输出重跑之前，保留失败日志。

最后把运行 ID、软件版本、参考名称和 FASTQ 清单保存到日志目录。接着用报告阅读练习判断产物是否值得进入下游。

参数依据：Cell Ranger 8 count。