10x Visium数据分析从入门到精通 - 第4节

1. 开始之前：你真的装对了吗？

Space Ranger 是 10x Genomics 官方的核心分析工具。说白了，它就是一道桥——把你手里的原始测序数据，转成能直接做分析的结果。

我第一次用 Space Ranger 的时候，犯过一个低级错误：没装依赖就急着跑，结果报了半小时错。嗯，后来学乖了。下面这些准备工作，一个都不能少。

1.1 系统环境

Space Ranger 只能在 Linux 上跑。我试过 macOS 和 Windows 虚拟机，都不行。官方最低要求是这样的：

项最低要求我建议
操作系统CentOS 7 / Ubuntu 18.04+Ubuntu 20.04 / CentOS 8
CPU8 核16 核或更多
内存32 GB64 GB（10x Visium 数据很吃内存）
硬盘200 GB 空闲1 TB SSD（临时文件巨大）
Python3.6+3.8 以上

记得提前装好 bcl2fastq（一定要 2.20 以上版本），Space Ranger 的 mkfastq 命令依赖它把 BCL 文件转成 FASTQ。我在项目里踩过坑：装了个 2.19 版，结果跑 spaceranger mkfastq 时直接报「bcl2fastq version not supported」。白等了两小时。

1.2 下载与安装

安装包在 10x Genomics 官网的「Support - Software & Data」页面下。需要注册账号，免费。下载下来是一个 .tar.gz 压缩包，大概 2~3 GB。

# 假设下载到 ~/downloaded/
cd /opt
sudo tar -xzf ~/downloaded/spaceranger-3.0.0.tar.gz

# 添加环境变量（写入 ~/.bashrc）
export PATH=/opt/spaceranger-3.0.0:$PATH
source ~/.bashrc

# 验证安装
spaceranger --version

第一次运行 spaceranger --version 如果能看到版本号，就说明装好了。我习惯把 Space Ranger 解压到 /opt 下，比较整洁。如果你只有普通用户权限，也可以放到 ~/tools/ 里。

1.3 下载参考基因组（转录组）

10x Visium 数据需要与参考基因组进行比对。官方提供预构建好的参考包（比如 GRCh38 人类、mm10 小鼠），也支持你自己用 spaceranger mkref 构建。

我个人建议直接用官方参考，省时间。

# 下载人 GRCh38 参考（约 4 GB）
wget https://cf.10xgenomics.com/supp/cell-exp/refdata-gex-GRCh38-2020-A.tar.gz
tar -xzf refdata-gex-GRCh38-2020-A.tar.gz -C /opt/references/

# 检查目录结构
ls /opt/references/refdata-gex-GRCh38-2020-A/
# 应该看到 fasta/ 和 genes/ 等子目录
提示：如果你的数据来自小鼠，就用 mm10 参考。千万别搞混——有一次我拿人参考跑小鼠数据，比对率不到 5%，白跑了半天。

2. 核心流程：从 BCL 到表达矩阵

Space Ranger 有三个核心命令：mkfastq、count、aggr。数据流向大概是这样的：

Space Ranger 核心流程 原始 BCL 文件 mkfastq BCL → FASTQ FASTQ 文件 count 比对 + 定量 表达矩阵 H5 / MEX / CSV aggr（可选） 多个样本归一化 虚线表示可选步骤（aggr），单样本分析不需要

2.1 第一步：mkfastq（BCL → FASTQ）

拿到 Illumina 测序仪下机的 BCL 文件后，第一步就是用 spaceranger mkfastq 把它转成 FASTQ。你想想看，下游所有的分析都是基于 FASTQ 的，这一步做不好后面都是白费。

# 示例命令
spaceranger mkfastq \
    --run=/path/to/flowcell \
    --csv=SampleSheet.csv \
    --output-dir=/path/to/output/fastq
  • --run：测序 flowcell 目录，里面是 Data/Intensities/BaseCalls/ 等子目录。
  • --csv：样本表（SampleSheet.csv），指定每个样本的 Index 序列和名称。
  • --output-dir：输出目录，生成的 FASTQ 文件会按样本名分文件夹存放。
注意：SampleSheet 的格式必须严格遵守 10x 要求。我曾经有一次忘记在 SampleSheet 中指定 Sample_Project 列，结果 mkfastq 把所有样本混到一起，惨不忍睹。

2.2 第二步：count（比对 + 定量）

拿到 FASTQ 之后，核心步骤就是 spaceranger count。它会完成：

  • 将 reads 与参考基因组比对（STAR 比对器）。
  • 将能比对到转录组的 reads 分配到基因上。
  • 把空间条形码（Spatial Barcode）与基因表达量关联起来。
  • 输出表达矩阵（H5 格式、MEX 格式）以及组织切片图像配准结果。
spaceranger count \
    --id=Sample1 \
    --transcriptome=/opt/references/refdata-gex-GRCh38-2020-A \
    --fastqs=/path/to/output/fastq/Sample1 \
    --sample=Sample1 \
    --image=/path/to/HE_image.tif \
    --slide=V11A01-002 \
    --area=A1 \
    --localcores=16 \
    --localmem=64

这里有几个参数我特别说明一下：

  • --id：输出结果的项目名称，会创建一个以它命名的目录。
  • --image：H&E 染色后的组织切片全幅图像（TIFF），一定要跟该切片对应的 slide 和 area 匹配。我见过有人传错图片，结果配准图完全错位。
  • --slide 和 --area：来自 Visium 芯片编号。每个芯片有多个捕获区域（比如 A1、B1、C1、D1），选错了数据就废了。
  • --localcores 和 --localmem：指定使用的 CPU 核数和内存（GB）。别设得比实际硬件多，否则系统会卡死。
输出结果结构：运行完成后，在 Sample1/outs/ 目录下你会看到：
  • filtered_feature_bc_matrix.h5：过滤后的表达矩阵（HDF5 格式），最常用。
  • spatial/tissue_hires_image.png：配准后的高分辨率图像。
  • spatial/tissue_positions_list.csv：每个 spot 的空间坐标。
  • summary.csv：统计数据（比对率、测序饱和度等）。

2.3 第三步（可选）：aggr——合并多个样本

如果你有多个 Visium 切片数据，想合并成一个分析（比如找共同的亚群），就需要 spaceranger aggr。它会做深度归一化并消除批次效应。

# 先创建一个 CSV 文件，列出各个样本的 count 结果路径
# 文件内容示例：library_id,molecule_h5
# Sample1,/path/to/Sample1/outs/molecule_info.h5
# Sample2,/path/to/Sample2/outs/molecule_info.h5

spaceranger aggr \
    --id=all_samples \
    --csv=/path/to/aggr_csv \
    --normalize=mapped

--normalize=mapped 是官方推荐的归一化方法。我个人习惯用完 aggr 后，多跑几个主成分检查一下是否还有明显的批次效应。如果还有，那就得考虑更复杂的整合方法了。

3. 运行中常见问题（避坑指南）

1. 内存不足
count 步骤对内存要求很高，特别是 Visium 数据（每个 spot 约 5000 个 transcript）。我曾在一个只有 48GB 的服务器上跑，结果被 kill 了。后来加了 64GB swap 才跑完。建议直接上 128GB。
2. 样本 ID 冲突
多个样本共用同一个 --id 会覆盖之前的输出。所以在每个样本的 count 命令中，--id 必须唯一。我习惯用样本名+日期做 ID，比如 Sample1_20250328。
3. 软链接导致路径问题
Space Ranger 默认会解析符号链接。如果 FASTQ 或参考基因组是通过软链接存放的，有时会报错“path too long”或“cannot access”。最好的办法就是直接用真实路径做输入。

4. 快速验证：跑一个测试数据集

装好之后，我建议先用官方提供的测试数据跑一遍，确认环境没问题。

# 下载测试数据（约 500 MB）
wget https://cf.10xgenomics.com/samples/spatial-exp/1.3.0/Visium_Human_Breast_Cancer/Visium_Human_Breast_Cancer_fastqs.tar
tar -xf Visium_Human_Breast_Cancer_fastqs.tar

# 快速运行 count（用 4 核 16GB 测试）
spaceranger count \
    --id=test_breast \
    --transcriptome=/opt/references/refdata-gex-GRCh38-2020-A \
    --fastqs=./Visium_Human_Breast_Cancer_fastqs \
    --sample=Visium_Human_Breast_Cancer \
    --image=/dev/null \   # 测试时可以不传图片
    --slide=V11A01-002 \
    --area=A1 \
    --localcores=4 \
    --localmem=16

正常情况下 10~30 分钟能跑完。检查 test_breast/outs/summary.csv，看看比对率是否超过 70%，测序饱和度是否合理。如果一切正常，恭喜你——Space Ranger 安装和基本运行已经搞定了！

← 上一章 📖 返回目录 下一章 →