运行 Cell Ranger

· Analysis Notes

运行 Cell Ranger

TL;DR: 安装和运行 Cell Ranger 用于 10x Genomics 单细胞 RNA-seq 数据分析的完整指南。涵盖安装、参考基因组设置、FASTQ 处理，以及用于标准实验和多重实验的 count 和 multi 流程。

平台说明: Cell Ranger 在类 Linux 系统上运行，不提供对 MacOS 或 Windows 的原生支持。Mac 用户可考虑使用 salmon/alevin、kallisto/bustools 或 STARsolo（其输出与 Cell Ranger 4.x 几乎相同）。

Cell Ranger 工作流程

先决条件

  • 具有足够 RAM 的 Linux 服务器（推荐 64GB+）
  • 用于安装的 root 或 sudo 权限
  • 10x Genomics scRNA-seq FASTQ 文件

1. 安装

从 10x Genomics 下载页面 下载并安装最新版本的 Cell Ranger：

# 导航到安装目录
cd $HOME

# 下载预编译二进制文件（以 v8.0.1 为例）
curl -o cellranger-8.0.1.tar.gz "https://cf.10xgenomics.com/releases/cell-exp/cellranger-8.0.1.tar.gz?Expires=1721274397&Key-Pair-Id=APKAI7S6A5RYOXBWRPDA&Signature=Wlo3LN3WMS52GnZDbPSo3rPiRzKxt7wlMo3cezn3HPyxH~WwyIKV8iXyVbHLJZtRnA6Vce9XP3iCQpllUxnydIqF9BKXaAk90voClEFVKiJsoNEwdQ6c9FconFLJn3KXL-up71jThOJJ-Uk6I6rTJlRkGCVU8WxiHQl-blxrrTn4AKehY3fmUK~c-fD7itd9zEoMVfsY1~qD2YGKDwNbrkAVzCyrN-~zimz3YbZRskbCV7Yd3HeOqv6ZPgvNOypnQZaMDPyU9lhU4Z2YNVyqFCC6spWjG4oC4U3Pk81333SsoH~tE-TN28Plk0zLT8clRTq0GFK2X-FYIQoc8czn3w__"

# 解压
tar -xzvf cellranger-8.0.1.tar.gz

# 添加到 PATH（添加到 .bashrc/.zshrc 以实现永久访问）
export PATH="$HOME/cellranger-8.0.1:$PATH"

# 验证安装
which cellranger
cellranger testrun --id=tiny

预期输出: 测试运行应在几分钟内成功完成。

2. 下载参考基因组

为您的生物体选择合适的参考基因组：

# 人类 + 小鼠（用于异种移植实验）
wget "https://cf.10xgenomics.com/supp/cell-exp/refdata-gex-GRCh38_and_GRCm39-2024-A.tar.gz"

# 仅人类 (GRCh38)
wget "https://cf.10xgenomics.com/supp/cell-exp/refdata-gex-GRCh38-2024-A.tar.gz"

# 仅小鼠 (GRCm39)
wget "https://cf.10xgenomics.com/supp/cell-exp/refdata-gex-GRCm39-2024-A.tar.gz"

# 解压
tar -xvzf refdata-gex-*.tar.gz

3. 准备 FASTQ 文件

选项 A: 将 BAM 转换为 FASTQ（如果需要）

如果您的原始数据是 BAM 格式，请使用 Cell Ranger 的 bamtofastq 工具：

bamtofastq /path/to/data.bam /path/to/output \
  --nthreads 12

性能说明: 一个约 20GB 的 BAM 文件使用 12 个线程大约需要 20 分钟。输出的 FASTQ 文件大小约为 BAM 文件的 1.5 倍。

选项 B: FASTQ 命名约定

Cell Ranger 要求严格的 FASTQ 命名。格式如下：

<样本名称>_S<样本编号>_L<泳道编号>_R<读段编号>_<集合编号>.fastq.gz

示例:

sample1_S1_L001_R1_001.fastq.gz  # 读段 1，泳道 1
sample1_S1_L001_R2_001.fastq.gz  # 读段 2，泳道 1
sample1_S1_L002_R1_001.fastq.gz  # 读段 1，泳道 2
sample1_S1_L002_R2_001.fastq.gz  # 读段 2，泳道 2

文件组织：两种方法

独立文件夹（推荐）

project/
├── sample1/
│   ├── sample1_S1_L001_R1_001.fastq.gz
│   └── sample1_S1_L001_R2_001.fastq.gz
└── sample2/
    ├── sample2_S1_L001_R1_001.fastq.gz
    └── sample2_S1_L001_R2_001.fastq.gz

✅ 样本编号 (S1) 可以相同 — 文件夹结构区分样本。

同一文件夹

project/fastqs/
├── sample1_S1_L001_R1_001.fastq.gz
├── sample1_S1_L001_R2_001.fastq.gz
├── sample2_S2_L001_R1_001.fastq.gz  # 注意: S2
└── sample2_S2_L001_R2_001.fastq.gz

⚠️ 样本编号必须不同 (S1, S2, ...) 以区分样本。

4. 运行 cellranger count（标准流程）

用于常规 3' 或 5' 基因表达文库（无多重标记）：

cellranger count \
  --id=sample_name \                        # 输出目录名称
  --transcriptome=/path/to/refdata-gex-GRCh38-2024-A \  # 参考基因组
  --fastqs=/path/to/fastq_folder \          # FASTQ 目录
  --sample=sample1 \                        # 必须与 FASTQ 前缀匹配
  --create-bam=false \                      # 禁用以节省时间/空间
  --localcores=24 \                         # CPU 核心数
  --localmem=128                            # RAM（单位 GB）

关键输出

Cell Ranger 创建一个包含以下内容的 outs/ 文件夹：

文件 描述
filtered_feature_bc_matrix/ 基因 × 细胞矩阵（仅细胞）
raw_feature_bc_matrix/ 基因 × 细胞矩阵（所有条形码）
web_summary.html 质控指标和 t-SNE 可视化
possorted_genome_bam.bam 比对后的读段（如果 --create-bam=true）
cloupe.cloupe 用于交互式探索的 Loupe Browser 文件

需要检查的质量指标

打开 web_summary.html 并验证：

指标 目标值
估计细胞数 500–10,000
平均读段数/细胞 >20,000（最低 10,000）
有效条形码 >75%
RNA 读段中 Q30 碱基 >65%
比对到转录组的读段 >30%
反义比对读段 <10%

5. 运行 cellranger multi（多重样本）

用于细胞哈希或多重标记实验（例如，BioLegend TotalSeq）：

步骤 1: 创建特征参考 CSV

TotalSeq-A 哈希标签示例：

id,name,read,pattern,sequence,feature_type
A0301,Sample1,R2,^(BC),ACCCACCAGTAAGAC,Multiplexing Capture
A0302,Sample2,R2,^(BC),GGTCGAGAGCATTCA,Multiplexing Capture
A0303,Sample3,R2,^(BC),CTTGCCGCATGTCAT,Multiplexing Capture

查找序列: BioLegend TotalSeq 条形码查询

步骤 2: 创建 Multi 配置文件 CSV

[gene-expression]
reference,/path/to/refdata-gex-GRCh38-2024-A
create-bam,false

[feature]
reference,/path/to/feature_reference.csv

[libraries]
fastq_id,fastqs,feature_types
gex1,/path/to/fastqs,Gene Expression
mux1,/path/to/fastqs,Multiplexing Capture

[samples]
sample_id,cmo_ids
Sample1,A0301
Sample2,A0302
Sample3,A0303

步骤 3: 运行 Multi 流程

cellranger multi --id=multiplexed_experiment --csv=multi_config.csv

Cell Ranger 将对样本进行解复用，并为每个样本生成独立的输出。

故障排除

"xxx 不是 pipestance 目录"

原因: FASTQ 目录名称包含样本 ID。
修复: 使用通用文件夹名称（例如，使用 fastqs/ 而不是 PRN1/）。

"未找到输入 FASTQ 文件"

原因: 样本名称与 FASTQ 文件前缀不匹配。
修复: 验证 --sample 是否与 FASTQ 文件名中的 <样本名称> 匹配。

比对读段数低 (<30%)

可能原因:

  • 错误的参考生物体
  • 测序质量差
  • 文库制备问题

检查: 在原始 FASTQ 文件上运行 FastQC 以评估质量。

后续步骤

  1. 质量控制: 将过滤后的矩阵加载到 Seurat 或 Scanpy
  2. 交互式探索: 在 Loupe Browser 中打开 .cloupe 文件
  3. RNA 速率分析: 将 BAM 文件与 Velocyto 或 scVelo 一起使用

另请参阅:

Cell Ranger