📚 课程目录第4章数据获取

第4章：数据获取——从10x官网到自己的样本

数据获取这一步，说白了就是搞清楚两件事：

去哪拿现成的示例数据练手
怎么把自己的数据塞进Visium流程

我见过不少新手，一上来就急着用自己的数据跑流程，结果遇到各种格式报错。嗯，我的建议是：先拿官方示例数据跑通一遍，确认环境没问题，再上自己的数据。这样踩坑时至少知道是不是数据本身的问题。

4.1 官方示例数据下载

10x Genomics官网提供了几个经典的Visium数据集。我个人最常用的是小鼠大脑切片和人乳腺癌切片，数据量适中，组织特征明显，非常适合用来测试流程。

具体操作如下：

访问官方数据页面
打开浏览器，进入10x Genomics的「Spatial Gene Expression」数据目录。你会看到一列表的数据集，每个都附带基本信息：组织类型、测序平台、spot总数、基因数等。
选择数据集
我建议第一次跑流程时选小鼠大脑（P56）数据集。为什么？因为这个数据集里皮层和海马体的边界非常清晰，聚类结果一眼就能看出对错。你想想看，如果数据本身一团模糊，你连聚类好坏都判断不了。

下载必要文件
一个完整的Visium数据集通常包含三个文件：

文件类型	文件名示例	说明
基因表达矩阵	`filtered_feature_bc_matrix.h5`	过滤后的barcode-基因计数矩阵
组织位置文件	`tissue_positions_list.csv`	每个spot的物理坐标（像素坐标）
H&E染色图像	`tissue_hires_image.png`	高分辨率组织切片图像（可选但推荐）

下载命令示例
在Linux/Mac下，我习惯用 wget 或 curl 直接拉文件。举个例子：

mkdir -p visium_mouse_brain
cd visium_mouse_brain
wget https://cf.10xgenomics.com/samples/spatial-exp/1.2.0/Parent_SpatialMouseBrain/Parent_SpatialMouseBrain_filtered_feature_bc_matrix.h5
wget https://cf.10xgenomics.com/samples/spatial-exp/1.2.0/Parent_SpatialMouseBrain/Parent_SpatialMouseBrain_tissue_positions_list.csv
wget https://cf.10xgenomics.com/samples/spatial-exp/1.2.0/Parent_SpatialMouseBrain/Parent_SpatialMouseBrain_tissue_hires_image.png

注意下载完整性
我曾经遇到过一个案例：下载中断导致h5文件不完整，SpatialExperiment读入时报错「无法读取HDF5数据」。折腾了半天才发现是文件没下完。建议每次下载后都检查文件大小是否与官网标注一致。

4.2 自有数据上传与组织

如果你的数据是自己测的，那就要把原始数据整理成Visium流程能吃的格式。这里有个常见的误区：很多人以为把fastq文件扔进去就能跑完所有下游分析。实际上Visium聚类流程的输入是已经处理好的表达矩阵，不是原始测序数据。

数据组织的方式主要看两个因素：

数据来源：是自己做实验测的，还是从公共数据库（如GEO、SpatialDB）下载的
数据格式：是标准的10x输出格式（barcodes.tsv / features.tsv / matrix.mtx），还是其他平台的输出

4.2.1 自测数据的组织方式

如果你用的是10x Visium试剂盒，做完测序后会拿到一个由Cell Ranger生成的输出目录。里面包含以下关键文件：

sample_outs/
├── filtered_feature_bc_matrix.h5
├── filtered_feature_bc_matrix/
│   ├── barcodes.tsv.gz
│   ├── features.tsv.gz
│   └── matrix.mtx.gz
├── spatial/
│   ├── tissue_positions_list.csv
│   ├── scalefactors_json.json
│   └── tissue_hires_image.png
└── analysis/
    └── ...（降维、聚类结果，可选）

我建议直接把 filtered_feature_bc_matrix.h5 和 spatial/ 目录下的文件复制到一个新的工作目录下，命名规则采用 项目名_组织名_切片ID 的形式。举个例子：

visium_raw/
└── BC01_BreastCancer_SectionA/
    ├── filtered_feature_bc_matrix.h5
    ├── tissue_positions_list.csv
    ├── scalefactors_json.json
    └── tissue_hires_image.png

4.2.2 来自公共数据库的数据

如果你从GEO或SpatialDB下载数据，格式可能五花八门。我遇到过好几种情况：

标准10x格式：直接能读，省心
HDF5但不是10x标准命名：需要用 h5ls 检查内部结构
CSV/txt格式的矩阵：需要自己重构为 dgCMatrix 格式

处理非标准格式最关键的一步是确认barcode顺序。曾经我拿了一个公共数据，表达矩阵的列顺序和tissue_positions里的barcode顺序不一致，结果跑了半天聚类，发现所有spot的位置全对不上。嗯，从那以后我养成了一个习惯：读入数据后第一件事就是检查barcode是否匹配。

一个快速验证的方法：

# 在R中快速检查barcode一致性
library(SpatialExperiment)
spe <- readVisium(sample_dir)
# 提取barcode
bc_spots <- colData(spe)$barcode
head(bc_spots)

4.3 数据获取流程总览

下面这张图概括了整个数据获取阶段的逻辑。你看一遍就能明白，从源数据到Visium聚类流程之间到底经历了什么。

4.4 常见问题与避坑

tip：下载前先看文件大小
我习惯在下载前先看一眼官网文件列表，记下文件大小。下载完成后用 du -h 或 ls -lh 比对一下。尤其是用校园网或代理时，经常下到一半就断掉，不检查直接跑流程就是浪费人生。

关键文件清单（备忘）
filtered_feature_bc_matrix.h5 — 主表达矩阵，必选
tissue_positions_list.csv — spot坐标，必选
tissue_hires_image.png — 组织图像，强烈推荐
scalefactors_json.json — 图像缩放参数，推荐带上

注意路径不要有中文或空格
Visium下游很多工具是基于C/C++的，对这些东西支持不好。我之前有个项目用「样本1（乳腺癌）」做文件夹名，结果读取路径时报错。从那以后，所有数据路径我全改成英文加下划线。

4.5 本章小结

数据获取是整个聚类流程的起点，也是最容易被忽视的一环。走完这一趟，你应该掌握：

从10x官网下载示例数据的完整步骤
自己测序数据的组织规范
公共数据的兼容性处理要点
数据完整性校验的方法

把这些基础打好，后面读数据、标准化、聚类才会顺。数据拿对了，流程就跑歪不到哪去。