3. 数据格式：H5、MEX、SpaceRanger 输出归纳总结
做多批次质控，第一步就得搞清楚数据长什么样。
Visium 的数据格式，说白了就三种：H5、MEX 和 SpaceRanger 的标准输出。我第一次接触这些格式时，觉得有点绕，尤其是它们各自藏了哪些信息。今天咱们就坐下来捋清楚。
3.1 核心数据格式概览
我个人习惯把这三者的关系看作“原材料→半成品→成品”的流程。下面这张图能帮你快速建立整体认知。
嗯，这张图把三者的关系讲清楚了。咱们接着深入每个格式的细节。
3.2 H5 格式详解
H5 格式（.h5 文件）是 HDF5 格式的简称。它在生物信息学里用得挺多，特别是单细胞领域。我个人觉得它的优点是能把所有数据打包在一个文件里，管理起来很方便。
3.2.1 H5 文件内容
一个典型的 Visium H5 文件包含以下数据组：
- matrix：稀疏表达矩阵，包含基因计数
- obs：细胞/点注释信息（如 n_counts、n_genes）
- var：基因特征信息（如基因名、符号）
- obsm/uns：组织位置坐标、降维结果等
我们读取 H5 文件常用 scanpy 或 anndata：
import scanpy as sc
# 读取 H5 文件
adata = sc.read_10x_h5("filtered_feature_bc_matrix.h5")
# 检查基础信息
print(adata)
# 输出示例：AnnData object with n_obs × n_vars = 4782 × 36601提示： 读取时要注意版本。SpaceRanger 3.x 的 H5 结构与 2.x 有细微变化，最好用对应版本的读取函数。
3.2.2 多批次处理时要小心的事
我记得有一次做批次整合时，发现两个批次的 H5 文件维度不一致。一个批次有 35501 个基因，另一个只有 32000 个。查了半天，原来是不同版本的参考基因组导致的。
所以，质控前第一件事就是检查基因集的统一性：
# 检查两个批次是否基因一致
print(batch1.var_names.equals(batch2.var_names))
# False 的话，需要取交集3.3 MEX 格式详解
MEX 格式是另一种常见选择。它其实是三个文件的组合，我更喜欢叫它“三件套”。
3.3.1 三件套内容
| 文件 | 作用 | 样例 |
|---|---|---|
| matrix.mtx | 稀疏矩阵，存储表达计数 | MTX 格式（Market Exchange Format） |
| barcodes.tsv | 所有点的 barcode 列表 | AAACCCAAGAAACTCA-1 |
| features.tsv | 基因特征列表 | ENSG00000243485 MIR1302-2HG Gene Expression |
读取 MEX 格式也非常简单：
# 读取 MEX 格式
adata = sc.read_10x_mtx("raw_feature_bc_matrix/")
# 或者手动指定路径
adata = sc.read_10x_mtx("raw_feature_bc_matrix/", var_names='gene_symbols')注意： MEX 格式的 barcodes.tsv 和 features.tsv 文件是 TSV（制表符分隔）格式。用文本编辑器打开时，有时会被 Excel 自动转换成空格或逗号，导致读取报错。我曾经因为这个问题排查了整整一个下午……
3.4 SpaceRanger 输出归纳
SpaceRanger 运行完，会输出一个完整的文件夹。这个文件夹里包含的东西比较多，我挑重点说。
3.4.1 输出目录结构
sample_output/
├── outs/
│ ├── filtered_feature_bc_matrix.h5 # 过滤后的 H5 文件
│ ├── filtered_feature_bc_matrix/ # 过滤后的 MEX 文件
│ ├── raw_feature_bc_matrix.h5 # 原始 H5 文件
│ ├── raw_feature_bc_matrix/ # 原始 MEX 文件
│ ├── spatial/ # 空间信息
│ │ ├── tissue_positions_list.csv # 组织点位置
│ │ ├── scalefactors_json.json # 缩放参数
│ │ └── tissue_hires_image.png # 组织图像
│ └── web_summary.html # 网页报告3.4.2 常用的文件
- filtered_feature_bc_matrix.h5：我个人建议多批次质控优先使用这个文件。它已经做了基础的过滤（比如空液滴），节省很多时间。
- spatial/tissue_positions_list.csv：存储每个点的空间坐标，质控时可以用来做空间分布检验。
- web_summary.html：SpaceRanger 的质控报告，包含测序饱和度、组织覆盖率等指标。嗯，这个可以帮你快速判断数据质量。
3.5 我的选择建议
说了这么多，到底该用哪种格式？我给出我的建议：
| 场景 | 推荐格式 | 理由 |
|---|---|---|
| 单批次快速测试 | H5 | 一个文件搞定，加载快 |
| 多批次整合分析 | H5（统一版本后） | 便于统一管理，避免文件缺失 |
| 调试或手动检查 | MEX | 三个文件可单独查看，便于理解 |
| 数据交付 | H5 + MEX 都提供 | 兼容不同用户的习惯 |
3.6 实践中的避坑指南
关键一步： 拿到数据后，无论是什么格式，先把以下几个问题搞清楚：
- 基因数量是否一致？不一致的话，取交集做后续分析。
- barcode 命名是否统一？有些批次可能会加后缀，需要标准化。
- 文件路径是否正确？特别是 MEX 格式，三个文件必须在同一目录下。
我曾经遇到过这样一个坑：两个批次的 H5 文件都是 SpaceRanger 生成的，但一个是 v2.0，另一个是 v3.1。读取后发现基因 ID 的格式完全不同——一个用了 Ensembl ID，一个用了 Gene Symbol。你说头疼不头疼？
所以，多批次质控的第一步，不是跑任何算法，而是先把数据格式统一好。格式都没统一，后面的分析全是白做。
3.7 小结
嗯，今天咱们把 H5、MEX、SpaceRanger 输出这三种格式的来龙去脉讲清楚了。记住一句话：理解数据格式，就是理解分析的起点。