10X HD Visium上游流程更新：Space Ranger V4及图像校准

生信菜鸟团

发布于 2025-08-11 10:29:25

26200

代码可运行

运行总次数：0

代码可运行

上期教程介绍了10X HD Visium数据的上游分析流程【一文打通10X HD Visium上游：从软件部署到上游分析】，主要是基于spaceranger-3.1.3，原先我计划后续更新一些关于细胞分割的教程。没想到10X官网最近推出了Space Ranger V4，最大的特点就是内置了细胞分割的pipeline，主要的更新内容包括：

Space Ranger v4.0 now supports Visium HD 3' Gene Expression!
Cell and nucleus segmentation are now included for Visium HD and Visium HD 3' data with H&E images.
Space Ranger v4.0 now features a new UMI-based registration algorithm for Visium HD and Visium HD 3' data.
Starting with v4.0, anonymized telemetry data is collected and sent to 10x Genomics.
You can now visualize and analyze Visium HD / Visium HD 3' cell segmentation in Loupe Browser v9.

这里看一下不同Space Ranger的特点：

image-20250617115431027

一. 什么是“细胞分割”？

（1）什么是细胞分割（Cell Segmentation）？

细胞分割是指在图像中自动识别并划分出每一个单独的细胞的过程，其结果通常是一个细胞掩码（mask），其中每个像素都被标记为属于哪个细胞或背景。

这通常用于：

组织切片图像（如HE染色）中精确定位每个细胞轮廓
为每个细胞分配一个 ID，用于后续表达量统计、细胞类型分类等分析
利用图像特征（如形状、染色强度）进行组织结构定量分析

（2） Visium HD空转平台为何需要进行细胞分割？

Visium HD空转平台是一种亚细胞分辨率的空间转录组技术，相比传统 Visium 技术，其每个“bin”分辨率更高，可以接近单细胞甚至细胞亚结构水平。因此，HD 每个 bin（2um/8um/16um）可能只覆盖部分细胞，需要分割轮廓来归属表达信号。通过分割轮廓，统计其对应 bin 内的 RNA reads，从而得到每个细胞的转录组信息。进而基于“真实的细胞”辅助空间聚类、分群等后续分析。

简而言之，

未进行细胞分割的Visium HD空转数据只是2um/8um/16um分辨率的分bin数据，可能只覆盖部分细胞
而进行细胞分割之后，基于分割后的坐标信息进行表达矩阵的合bin，得到的是类似与true single cell的空间表达信息，当然不可否认的是，这个过程会存在假阳性和假阴性错误。

（3）除了新推出Space Ranger v4+是基于StarDist算法，当前常见的细胞分割工具还包括bin2cell、Cellpose等算法。实际上，除了 Visium HD空转平台以外，10X的Xenuim平台也需要进行细胞分割。

二. 10X HD Visium Space Ranger V4流程更新

（1）环境部署

参考教程详见：https://www.10xgenomics.com/support/software/space-ranger/latest

相关软件以及参考基因组下载见这个页面：https://www.10xgenomics.com/support/software/space-ranger/downloads

wget -O spaceranger-4.0.1.tar.gz "https://cf.10xgenomics.com/releases/spatial-exp/spaceranger-4.0.1.tar.gz?Expires=1750230791&Key-Pair-Id=APKAI7S6A5RYOXBWRPDA&Signature=bmafD9QVvKCO5XpFFTm~hxHxL~oORme2LTFzpXX6yiXVTi9NJVVb~c~DA7WMUw8mDYEpBNhQZTwW9taceLupdU9WkEYfDhILQearAzBDOkWjFaVUXeIjuLM574YP1K1c5Q2SSoohfvPg~BgPsuYkiHLgv~AdJDabIYldvrD8mb54C58hL0yCj7o-Kv0g6pKIki8U1s5qmXyHU~HOKz-LJV02uz8oM2S5Kw0Yb7SpNEsxoeO~M3EvaJoRc21Lzc~YIl~6uMbZqDxdQQl2Mo~Z64~yPqqh1~m4mPsVwDTiKLdmIyq17x7Xwh7UeMgvP1oOC4TdJ7~uMyiOZvC8su~Zuw__"

##解压
tar -xzvf spaceranger-4.0.1.tar.gz
export PATH=~/software_install/spaceranger-4.0.1:$PATH

##绑定邮箱
spaceranger sitecheck > sitecheck.txt
spaceranger upload xxx@xxx.xxx sitecheck.txt

## 我喜欢在10x环境下跑上游
# ln -s ~/software_install/spaceranger-4.0.1/bin/spaceranger ~/miniconda3/envs/10x/bin/

## 参考基因组下载，按需下载：
wget "https://cf.10xgenomics.com/supp/cell-exp/refdata-gex-GRCh38-2024-A.tar.gz"
wget "https://cf.10xgenomics.com/supp/cell-exp/refdata-gex-GRCm39-2024-A.tar.gz"
wget "https://cf.10xgenomics.com/supp/cell-exp/refdata-gex-GRCh38_and_GRCm39-2024-A.tar.gz"

## Probe Sets下载
wget https://cf.10xgenomics.com/supp/spatial-exp/probeset/Visium_Human_Transcriptome_Probe_Set_v2.0_GRCh38-2020-A.csv
wget https://cf.10xgenomics.com/supp/spatial-exp/probeset/Visium_Mouse_Transcriptome_Probe_Set_v2.0_mm10-2020-A.csv

（2）关于10X空转的image

在进行前spaceranger count之前，务必要了解一下输入文件的格式，例如fastq文件，image文件等。FASTQ文件的获取，这里跳过了，一般是自测为主的。论文中公开的fastq数据比较复杂，大多数是缺胳膊少腿的，或者格式不统一。

这里我们可以先了解一下10X空转的Image类型的介绍（https://www.10xgenomics.com/support/software/space-ranger/latest/analysis/inputs/image-image-recommendation）：

Here is a summary of image input types and formats:

	Image Format	Space Ranger Arguments	Automatic Fiducial Alignment	Automatic Image Registration
Brightfield Image	24-bit color TIFF/BigTIFF or a JPEG 16-bit grayscale TIFF/BigTIFF or a JPEG	--image	Supported	Supported#
Fluorescence Image	8 or 16-bit grayscale single, multi-page TIFF/BigTIFF 8 or 16-bit grayscale multiple single-page TIFF/BigTIFF or a JPEG	--darkimage--dapi-index	Visium H2, Visium v2: Supported Visium v1: Not supported (must use manual fiducial alignment in Loupe Browser)	Supported#
Fluorescence Image	24-bit single colored image TIFF/BigTIFF or a JPEG	--colorizedImage--dapi-index	Visium H2, Visium v2: Supported Visium v1: Not supported (must use manual fiducial alignment in Loupe Browser)	Supported#
CytAssist Image	24-bit color TIFF	--cytaimage	Supported	Supported#

# Optionally can use manual alignment in Loupe Browser.

高清 HE 图像：Brightfield Image是高清图像，通常由显微镜单独扫描，图像质量高，但与转录本坐标存在旋转、翻转、缩放等偏差。比较大，一般在1个G到10几个G不等，是细胞分割工具的input文件。如果缺少这个高清图像，一般无法进行细胞分割。这个文件是spaceranger流程可选的，没有的话默认不执行细胞分割。
CytAssist 图像：而CytAssist Image是spaceranger流程必需的，与空间转录本定位信息（barcodes）一一对应。一般不大，100MB之内都很正常。

这里再看看image的尺寸，可以看到Visium Spatial和Visium HD slide都是6.5mm大小：

Slide Version	Minimum Input Image Size	Space Ranger Downsampled Size (tissue_hires_image.png)
Visium Spatial Gene Expression slide (v1, 6.5 mm).	2,000 pixels in either dimension	2,000 pixels in either dimension
Visium CytAssist Spatial Gene Expression slide (v2, 6.5 mm)	CytAssist image at 3,000 pixels in both dimensions	2,000 pixels in both dimensions
Visium CytAssist Spatial Gene Expression slide (v2, 11 mm)	CytAssist image at 3,000 pixels in both dimensions	2,000 pixels in both dimensions
Visium HD slide (6.5 mm)	CytAssist image at 3,200 x 3,000 pixels	6,000 pixels in both dimensions

还有一些额外的细节，由于本文篇幅有限，详见https://www.10xgenomics.com/support/software/space-ranger/latest/analysis/inputs/image-image-recommendation

（3）关于10X空转的图片校准

另外，相较于Brightfield Image，CytAssist Image经常发生了镜像/翻转。甚至相较于Brightfield Image，有的组织在CytAssist Image是缺失的。原因是实验操作过程导致部分组织脱落。因此需要我们了解“图片对齐/图片校准”这个概念。

虽然10X官网明确注明：在大多数情况下，Space Ranger会自动将显微镜图像与 Visium 载玻片上采集的 CytAssist 图像和表达数据进行比对。如果需要手动比对，请选择最适合您实验的选项。

但是，有国内科服技术朋友告诉我，可以先让Space Ranger自动校准看看效果，但是一般推荐手动校准。特别是有细胞分割需求的情况，比较推荐用户手动进行图片校准。

具体流程如下（https://www.10xgenomics.com/support/software/space-ranger/latest/analysis/inputs/visium-hd-loupe-alignment）：

Loupe Browser 提供了 Visium HD 手动对齐工具，使用户能够以交互方式将图像与载玻片的基准标记位置对齐，执行精确的组织选择，并导出 JSON 文件以供使用spaceranger count。

a. 打开 Loupe Browser 并单击左下角的链接以访问 Loupe Browser 的 Visium 手动对齐选项。

img

b. 对于 Visium HD 数据，请选择Visium HD 标题下的 Visium HD 手动对齐选项（其他工作流程专用于 Visium v1/v2）。

img

c. 第一步是上传 CytAssist 图像。

img

d. 上传 CytAssist 图像后，请使用预览图像和文件名确认图像是否正确。

img

e. 在此示例中，Visium 载玻片序列号和捕获区域是通过读取 CytAssist 图像元数据自动填充的。您也可以手动输入这些信息，或提供载玻片布局文件。点击“下一步”继续。

img

f. 按照屏幕上的说明找到正方形、六边形和三角形的基准点。

img

g. 识别每个基准点时，将出现一个框来跟踪您的进度。识别完所有三个基准点后，点击“下一步”继续。

img

h. 单击“自动优化”以算法方式优化对齐。

img

i. 您还可以使用屏幕上的工具目视检查比对结果。自动优化完成后，单击“下一步” 。

img

j. 使用套索或画笔工具选择组织区域，或者跳过此步骤并让 Space Ranger 自动识别组织区域。

img

k. 以下是使用套索工具的示例。完成后，点击“下一步”继续。

img

l. 在此步骤中，您可以选择导出比对 JSON 文件。否则，请继续下一步。

img

在此阶段，大多数用户希望继续操作而不导出。但是，在某些情况下，需要提前导出并退出。例如，如果 Space Ranger 最初未能检测到足够的基准点，您可以运行手动对准器的初始步骤，包括基准点和组织识别。然后，您可以导出 JSON 文件，让 Space Ranger 自动将 CytAssist 图像与显微镜图像对齐。请确保将 JSON 文件传递给spaceranger count带有相应--loupe-alignment选项的程序。

m. 上传高分辨率显微镜图像（H＆E 或 IF）。

img

本教程中的文件大小为 12.6 GB。上传图片至 Loupe 可能需要几分钟甚至更长时间。

n. 对于 H&E 图像（如本例中），请选择明场。

img

o. 为了获得精确的对齐，必须固定标记。组织边缘和其他结构可以作为良好的标记。

img

放置地标时请务必放大以获得最佳精度。

img

在这个例子中，我们将使用六个地标。在大多数情况下，放置五到八个地标对于自动优化算法来说就足够了。

img

p. 单击“下一步”进入下一步。

img

强烈建议使用自动优化，这可能需要几分钟才能完成。如果初始地标位置不够精确，此步骤可能无法完成。如果是这样，建议重复上一步。

（4）spaceranger count及细胞分割

spaceranger v4软件的核心函数就是spaceranger count了，如果不进行细胞分割的话，代码其实很简单，和spaceranger v3是一样的：

 spaceranger count --id=hd_count \
 --transcriptome=/path/to/refdata-gex-GRCh38-2020-A \
 --fastqs=/path/to/fastq \
 --probe-set=/path/to/Visium_Human_Transcriptome_Probe_Set_v2.0_GRCh38-2020-A.csv \
 --slide=H1-YD7CDZK \
 --area=A1 \
 --cytaimage=/path/to/CAVG10539_2023-11-16_14-56-24_APPS115_H1-YD7CDZK_A1_S11088.tif \ #低清图片
 --create-bam=false
#image高清图片可选

如果需要进行细胞分割的话，需要加入image参数（此文件必需），以及图像校准的json文件（此文件可选）:

spaceranger count --id=hd_count \
 --transcriptome=/path/to/refdata-gex-GRCh38-2020-A \
 --fastqs=/path/to/fastq \
 --probe-set=/path/to/Visium_Human_Transcriptome_Probe_Set_v2.0_GRCh38-2020-A.csv \
 --slide=H1-YD7CDZK \
 --area=A1 \
 --cytaimage=/path/to/CAVG10539_2023-11-16_14-56-24_APPS115_H1-YD7CDZK_A1_S11088.tif \ #低清图片
 --image=/path/to/APPS115_11088_rescan_01.btf \   #高清图片，btf或者tif
 --create-bam=false \
 --loupe-alignment=test.json #图像校准的json文件可选

参数	文件类型	来源说明
--transcriptome	参考转录组文件夹（10X格式）	从10X官网下载
--fastqs	测序数据 FASTQ 文件	Illumina测序仪输出
--probe-set	v2版本的探针CSV文件	从10X官网下载
--slide	Slide编号	样本记录表/玻片标签
--area	玻片区域（A1-D1）	实验设计决定
--cytaimage	低分辨率组织扫描图像（tif）	CytaScope仪器生成
--image	高分辨率图像（.btf 或 .tif）	Zeiss扫描或原始图像，可选
--create-bam	是否生成 BAM 文件（false 推荐）	自定义

（5）结果解读

详见：https://www.10xgenomics.com/support/software/space-ranger/latest/analysis/outputs/space-ranger-metrics-summary

例如：https://cf.10xgenomics.com/samples/spatial-exp/4.0.1/Visium_HD_3prime_Human_Ovarian_Cancer/Visium_HD_3prime_Human_Ovarian_Cancer_web_summary.html

适用于 Visium 3’（polyA捕获）的常规空间表达指标

Metric	Description
Number of Spots Under Tissue	位于组织下的 barcode（spot）数量。
Number of Reads	分配给该文库的 reads 对总数。
Mean Reads per Spot	每个组织下的 spot 平均 reads 数（包含组织外区域）。
Mean Reads Under Tissue per Spot	每个组织下的 spot 平均 reads 数（仅组织区域）。
Fraction of Spots Under Tissue	位于组织下的 spots 占总 spots 的比例。
Median Genes per Spot	每个组织 spot 检测到的基因数中位数（≥1 UMI 即视为检测）。
Median UMI Counts per Spot	每个组织 spot 的 UMI 计数中位数。
Valid Barcodes	经纠错后匹配 inclusion list 的有效 barcode 占比。
Valid UMIs	合法 UMI 的 reads 占比（无 N，非 homopolymer）。
Sequencing Saturation	表示测序饱和度：有多少 reads 来自已观测到的 UMI。
Q30 Bases in Barcode/RNA Read/UMI	barcode、RNA read（Read2）和 UMI 中 Q≥30 的碱基占比。
Reads Mapped to Genome	映射到基因组的 reads 占比。
Reads Mapped Confidently to Genome	唯一映射到基因组的 reads 占比。
Reads Mapped Confidently to Intergenic Regions	唯一映射到基因组间区的 reads 占比。
Reads Mapped Confidently to Intronic Regions	唯一映射到内含子区域的 reads 占比。
Reads Mapped Confidently to Exonic Regions	唯一映射到外显子区域的 reads 占比。
Reads Mapped Confidently to Transcriptome	唯一映射到转录组（并符合剪接位点）的 reads 占比，用于 UMI 计数。
Reads Mapped Antisense to Gene	映射到与注释基因反向链上的 reads 占比。
Fraction Reads in Spots Under Tissue	映射到组织区域的 reads 占总有效 reads 的比例。
Total Genes Detected	在组织区域内，至少被 1 个 UMI 检测到的基因数。

使用探针集（probe set）时的指标（针对 Visium HD）

Metric	Description
Reads Mapped to the Probe Set	映射到探针参考序列的 reads 占比（至少一个 reads 半段能匹配）。
Reads Mapped Confidently to the Probe Set	两个 reads 半段都唯一匹配到探针参考的 reads 占比。
Reads Mapped Confidently to the Filtered Probe Set	唯一匹配到过滤后的探针参考的 reads 占比（过滤掉可能与非目标位点发生非特异性杂交/连接的探针）。若禁用过滤，该指标显示为 “None”。
Genes Detected	在组织覆盖区域内，至少有 1 个 UMI 的探针集中的基因数量（过滤后的探针集）。
Number of Genes	探针集中定义的基因总数。
Number of Genes ≥ 10 UMIs	在组织区域内，UMI 数量 ≥ 10 的基因数量，用于计算每个基因的富集度。

Visium HD 中的细胞和细胞核分割指标（Space Ranger v4.0 起）

Metric	Description
Number of Cells Detected	检测到的细胞数量（每个细胞至少含有一个唯一分子标识符 UMI）。
Reads in Cells	分配给细胞的 reads 占总 reads 数的比例。
UMIs in Cells	在组织区域内，位于细胞内的 UMI 占比。
Mean Reads per Cell	每个细胞平均的 reads 数。
Median Genes per Cell	每个细胞检测到的基因数的中位数（不计入检测为 0 的细胞）。
Median UMIs per Cell	每个细胞检测到的 UMI 数的中位数（不计入检测为 0 的细胞）。
Median Cell Area (μm²)	每个细胞的面积（单位为平方微米），按 2μm × 2μm 像素块计数求和。
Median Nucleus Area (μm²)	每个细胞核的面积，按其覆盖的像素块求和。
Maximum Nucleus Diameter (pixels)	检测到的最大细胞核直径（单位为像素）。用于保证跨 tile 的细胞核不会被截断。