2、数据获取：从10x官网下载示例数据集（小鼠大脑切片），理解spatial、filtered_feature_bc_matrix等文件夹结构

好，咱们正式开始动手。上一章聊了Visium的原理，现在得先把「原材料」搞到手。

我个人的习惯是，学任何新工具，第一件事就是找个公开的、标准的官方数据集跑一遍。为什么？因为官方数据质量可控，文档匹配，出了问题你能确定是代码不对，而不是数据有坑。这一点在空间转录组里特别重要——你想想看，切片质量、探针效率、测序深度，任何一个环节出问题，后面分析全是白费。

所以这一章，咱们的目标很明确：从10x官网下载小鼠大脑切片的标准示例数据，然后把下载下来的文件夹结构彻底搞清楚。说白了，就是先知道「食材长什么样」，再谈怎么「下锅」。

2.1 为什么选小鼠大脑切片？

10x官方提供的示例数据集有好几个，比如人类乳腺癌、小鼠肾脏、小鼠大脑等等。我建议新手直接拿小鼠大脑切片（Mouse Brain Coronal Section）作为入门。原因很简单：

• 组织形态复杂：大脑有明确的皮层、海马、纹状体等分区，聚类结果肉眼可见，验证起来方便。
• 基因表达差异大：不同脑区的神经元类型不同，表达谱有显著区别，适合检验分析流程的区分度。
• 社区案例多：我在项目中遇到过一个问题，就是用不太常见的数据集跑新工具，出了问题搜不到解决方案。小鼠大脑，你放心，踩过的坑网上基本都有记录。

2.2 如何快速拿到数据？

10x官方把示例数据都放在一个公开的下载页面（别担心链接失效，我待会给你命令行方案）。具体操作分两步：

1. 打开10x Genomics官网的「Datasets」页面，在「Spatial Gene Expression」分类下找到「Mouse Brain Coronal Section (FFPE)」。
2. 下载三个核心文件：一个叫filtered_feature_bc_matrix.h5，一个叫spatial.tar.gz，还有一个是原始测序数据（我们暂时用不到，但心里要有数）。

但说实话，每次手动点网页下载很烦。尤其当你需要批量测试时，鼠标点到手酸。我推荐直接用wget或curl，一行命令搞定。

以下是截至2024年仍有效的下载地址（10x的URL结构很稳定，基本是https://cf.10xgenomics.com/samples/spatial/...这样的模式）：

# 创建项目目录
mkdir -p visium_mouse_brain && cd visium_mouse_brain

# 下载 filtered_feature_bc_matrix.h5（核心表达矩阵）
wget https://cf.10xgenomics.com/samples/spatial-exp/1.2.0/Parent_Visium_Human_DLPFC/Parent_Visium_Human_DLPFC_filtered_feature_bc_matrix.h5

# 下载 spatial 文件夹（包含组织切片图像和坐标）
wget https://cf.10xgenomics.com/samples/spatial-exp/1.2.0/Parent_Visium_Human_DLPFC/Parent_Visium_Human_DLPFC_spatial.tar.gz

# 解压 spatial 文件
tar -xzvf Parent_Visium_Human_DLPFC_spatial.tar.gz

下载完成后，你的目录结构应该长这样：

visium_mouse_brain/
├── filtered_feature_bc_matrix.h5    # 核心文件，表达矩阵
├── filtered_feature_bc_matrix/      # 某些版本会提供解压后的目录
└── spatial/
    ├── tissue_hires_image.png        # 高分辨率组织切片图
    ├── tissue_lowres_image.png       # 低分辨率组织切片图
    ├── tissue_positions_list.csv     # 每个斑点（spot）的空间坐标
    ├── scalefactors_json.json        # 图像缩放参数
    └── aligned_fiducials.jpg         # 对准后的明场图像（有些版本叫这个）

2.3 空间转录组的数据「说明书」

现在文件已经躺在硬盘里了。但说实话，我第一次拿到这些文件时，看着一堆.h5、.csv、.json，脑子是懵的。每一行数据到底是什么意思？哪个文件是主文件，哪个是辅助文件？

别急，我帮你理清。Visium的数据结构可以归纳为三类：

2.4 文件夹结构深度拆解

接下来，咱们把spatial/文件夹里的每个文件挨个过一遍。嗯，这里要注意，很多新手搞不清楚tissue_positions_list.csv和图像文件的关系，导致后续画图时斑点偏移——我当年就吃过这个亏。

2.4.1 tissue_hires_image.png / tissue_lowres_image.png

这是显微镜下拍到的组织切片图像。高分辨率版（hires）用于精细绘图，低分辨率版（lowres）用于快速浏览。实际上，我们跑Seurat或Scanpy时，通常自动用lowres做背景图，因为运算量小。但最终出图时，我会换成hires，美观很多。

2.4.2 tissue_positions_list.csv

这个文件是全流程里最容易出错的地方。它的每一行对应一个斑点，包含以下列：

barcode, in_tissue, row, col, imagerow, imagecol
AAACCTGGTCACTAGA-1, 1, 0, 0, 87.5, 19.5
AAACCTGTCGCGTTCC-1, 1, 0, 1, 77.5, 31.5
...

• barcode：斑点的唯一标识，比如AAACCTGGTCACTAGA-1，这个值必须和filtered_feature_bc_matrix.h5里的列名一一对应。
• in_tissue：0或1。1表示该斑点完全落在组织区域，0表示在背景（即玻片上的空白区域）。filtered_feature_bc_matrix.h5只包含in_tissue=1的斑点。
• row, col：斑点在10x Visium捕获芯片上的物理坐标（基于芯片的网格布局）。
• imagerow, imagecol：斑点在全分辨率组织图像上的像素坐标。这两个值用于将基因表达数据映射回图像。

2.4.3 scalefactors_json.json

这个JSON文件就是为了解决上面那个问题的。它记录了不同分辨率图像之间的缩放比例：

{
  "spot_diameter_fullres": 89.4,
  "tissue_hires_scalef": 0.7,
  "tissue_lowres_scalef": 0.2,
  "fiducial_diameter_fullres": 86.7,
  "fiducial_diameter_fullres": 0.4
}

• spot_diameter_fullres：在全分辨率图像中，单个斑点的直径（像素）。
• tissue_hires_scalef：hires图像相对于全分辨率图像的缩放比例。如果你把全分辨率图像缩小到hires，就要乘以这个值。
• tissue_lowres_scalef：lowres图像的缩放比例。
• fiducial_diameter_fullres：对准标记（fiducial）的直径，一般和spot_diameter很接近。

2.5 谁来负责什么？一张图说清楚

讲了这么多文件，它们之间到底是什么关系？我画了个简图，你一看就明白。

从这张图可以看得很清楚：组织图像和测序数据通过Space Ranger管道处理后，输出三种类型的产品。而咱们做下游分析时，真正需要的就是spatial文件夹 + filtered_feature_bc_matrix.h5。记住这个，后面做数据导入就不会迷路了。

2.6 避坑指南：你可能会遇到的三个常见问题

最后，我还是想啰嗦几句——这些坑，我踩过不止一次。

1. 文件版本不匹配：有时候下载的filtered_feature_bc_matrix.h5是V2格式，而spatial/tissue_positions_list.csv是V1格式，两者Barcode的命名规则不一致。建议统一从官网的同一个样本页面下载。
2. 解压后缺少文件：spatial.tar.gz解压后，如果发现scalefactors_json.json缺失，说明你下载的是旧版数据。可以试试直接官网重新下载，或者手动从10x的GitHub仓库里找补丁文件。
3. Barcode列名顺序：读取tissue_positions_list.csv时，默认第一行是列名。但有些版本的第一行就是数据，没有表头。如果发现斑点数量对不上，请检查列名是否存在。