📚 课程目录第3章从原始数据到表达矩阵

3、从原始数据到表达矩阵：Space Ranger的使用经验与参数调优

Space Ranger 这套流程，说白了就是把 Visium 的原始数据转化成我们能用的表达矩阵。我刚开始接触它的时候，总觉得不过是个“黑盒子”——扔进去 FASTQ 和图像，等几个小时就出来了。直到第一次跑出来的结果，组织斑点压根对不上图像位置，我才开始认真研究它到底在干什么。

今天我们就聊聊怎么用好这个工具。我不会把官方文档搬过来，而是把那些踩过的坑和调优经验抖出来。

3.1 准备工作：输入数据别搞错

Space Ranger 的输入其实就四类：FASTQ 测序数据、高分辨率组织切片图像、参考转录组（通常是 pre-mRNA GRCh38 或 mm10）以及 Slide 芯片的序列信息。我见过最常犯的错误就是 FASTQ 命名不规范。

命名的坑：Visium 的 FASTQ 文件名必须包含样品名称的 sample 前缀。比如你的样品叫 "Tumor_A"，那 FASTQ 文件应该是 Tumor_A_S1_L001_R1_001.fastq.gz 这种格式。否则 Space Ranger 会找不到配对文件，直接报错退出。

另一个容易忽略的是图像格式。官方推荐放 .tif 或 .jpg 都行，但如果你用 .png，可能会在配准环节出问题——我踩过这个坑，后来一直只用 .tif 了。

输入文件	格式要求	常见问题
FASTQ (R1/R2)	样本名_S1_L001_R{1,2}_001.fastq.gz	双端文件要配对，R1 包含 barcode + UMI
切片图像	.tif 或 .jpg，建议 300+ DPI	图像尺寸不宜过大，否则配准卡顿
参考基因组	cellranger 格式的 STAR 索引	建议使用 10x 官方提供的 v2020-A 版本
Slide 信息	—slide 参数 + —area 参数	slid 芯片序列号需要贴片前拍照确认

3.2 核心命令与参数调优

命令本身不复杂，跑一个基本任务长这样：

spaceranger count --id=sample_output \
    --transcriptome=/refdata/refdata-gex-GRCh38-2020-A \
    --fastqs=/data/fastq_path \
    --sample=Tumor_A \
    --image=/images/Tumor_A.tif \
    --slide=V10B01-999 \
    --area=A1 \
    --localcores=16 \
    --localmem=64

几个参数我着重聊一下：

--cytoimage（可选）：如果组织做了细胞核染色（cytostain），可以用这个参数提供额外的图像通道。我试过一次，在细胞密度稀疏的区域确实能提高配准精度。
--image 和 --slide/--area：这是配对使用的。芯片上的区域编号（A1、B1、C1、D1）必须和实际贴片位置一致。还有个坑——图像旋转方向。我做过一次，图像默认方向跟芯片标准方向差了 180°，结果斑点全部偏移。后来养成了习惯：先跑一个 quick 模式检查配准。
--reference：我强烈建议用 pre-mRNA 参考，而不是普通 mRNA 参考。因为 Visium 捕获的是 poly-A 尾巴的 RNA，但 pre-mRNA 包含内含子区域，能多捕获 10%~20% 的 reads。不过要注意，官方 pre-mRNA 参考包比较大，下载要留够空间。

个小技巧： 如果样本的 RNA 质量不太好（比如 RIN 偏低），可以考虑加 --chemistry=auto，让 Space Ranger 自动识别建库试剂盒版本。不同版本的 barcode 结构有差异，手动指定错了会丢数据。

3.3 资源调优：跑得快 ≠ 跑得稳

很多新手一上来就设 --localcores=32，结果内存爆了。我自己测试过，Visium 单样本的数据量一般在 5~15 亿 reads，推荐的内存公式是：localmem = 样本总 reads 数（G） × 4 + 8。比如 10G reads，给 48 GB 比较稳。

另外，STAR 比对阶段是多线程的，但后续的 UMI 计数部分是单线程。所以 core 给到 16 基本就到顶了，再多也没用，反而增加进程调度的开销。

# 我的常用资源分配（样本 12G reads 左右）
spaceranger count ... \
    --localcores=16 \
    --localmem=64

3.4 输出文件解读：哪些值得关注

跑完之后，最关键的是 filtered_feature_bc_matrix.h5 和 raw_feature_bc_matrix.h5。前者是去掉了背景噪声的（通过组织区域检测过滤掉组织外的斑点），后者保留了所有斑点。我一般直接用 filtered 版本做下游分析。

还有一个容易被忽略的文件：metrics_summary.csv。里面包含几十项质控指标，我最关心的三个：

指标	理想范围	说明
Valid Barcodes (%)	> 90%	Barcode 正确识别的比例，太低说明可能存在接头污染
Sequencing Saturation	30% ~ 60%	测序饱和度过低表示数据量不足；过高说明浪费了很多测序深度
Fraction Reads in Spots	> 70%	比对到组织斑点内的 reads 比例，低于 60% 要检查图像配准

曾经有一次： 我处理一个石蜡切片样本，Fraction Reads in Spots 只有 45%。折腾了两天，最后发现是图像拍摄时组织边缘有反光，导致配准偏差。重新拍了一张干净的照片，数值就跳到 78% 了。所以记住——图像质量直接决定下游成败。

3.5 避坑指南：我的踩坑合集

FASTQ 的 R1/R2 别弄反： Visium 的 R1 是 28bp barcode + 10bp UMI，R2 是 91bp 的插入片段。交换了会报错“unexpected barcode length”。
参考基因组索引别用错： 10x 的参考包必须用 cellranger 提供的 mkref 构建，不能直接用 STAR 自己建。我图省事试过一次，比对率直接掉到 30%。
图像文件名不要有空格或中文： Space Ranger 内部会对路径做解析，遇到空格会崩溃。嗯，有个同事就因为这个排查了一整天。
Disk 空间： 一个样本的临时文件可能会膨胀到原始数据的 2~3 倍。我建议临时目录至少留 200 GB 以上，不然跑到一半磁盘满了就悲剧了。

3.6 一个实用脚本：批量跑样本

项目里通常有几十个样本，手动一个个跑不现实。我写了个小脚本，配合样本清单自动执行：

#!/bin/bash
# batch_run_spaceranger.sh
while IFS=, read sample slide area image
do
    mkdir -p /outputs/$sample
    spaceranger count --id=$sample \
        --transcriptome=/refdata/GRCh38-2020-A \
        --fastqs=/data/fastq/$sample \
        --sample=$sample \
        --image=/data/images/$image \
        --slide=$slide --area=$area \
        --localcores=16 --localmem=64 \
        --output-dir=/outputs/$sample
done < samples.csv

samples.csv 示例：

Tumor_A,V10B01-999,A1,Tumor_A.tif
Tumor_B,V10B01-999,B1,Tumor_B.tif
Normal_A,V10B01-999,C1,Normal_A.tif

记得给脚本加上 chmod +x 再运行。我第一次用的时候忘了加逗号分隔的空格，导致 slide 参数多了空格，程序报错找不到芯片号——都是细节。

好了，Space Ranger 这部分就先聊到这儿。有了可靠的表达矩阵，下一步才能放心地去做降维聚类。不过那是后面章节的内容了，先把这里每一步跑顺吧。