# 第 07 章 数据获取：Visium 公开数据集

> 本章解决“分析什么数据”的问题。本书全部实操基于 10x Genomics 官网公开的人乳腺癌 Visium demo 数据（组织结构典型、生态位分明、可免费下载）。数据下载看似简单，但“从哪来、多大、校验值多少、能不能用”这四个问题必须留下书面记录——这是 data-inventory（数据清单）的基本纪律，也是你论文方法节要写的素材。

## 本章目标

学完本章，你应该能够：

1. 说明为什么选 10x Visium 人乳腺癌 demo 作为主示例数据，以及结直肠癌数据何时作为拓展；
2. 走通 10x 官网的下载流程，说清每个下载文件的用途；
3. 认识三条备选数据渠道：spatialLIBD、GEO、Zenodo，知道各自适合什么场景；
4. 用 data-inventory 思想为数据建立清单（来源、URL、大小、md5 校验值）；
5. 按 data/raw 与 data/processed 组织目录，运行配套下载脚本 code/02_download.R。

## 7.1 数据集选型：为什么是人乳腺癌 demo

选示例数据要同时满足四个条件：**公开可下载、组织结构典型、生态位分明、体积适中**。10x Visium 人乳腺癌（Human Breast Cancer）demo 完美满足：

- **组织结构典型**：乳腺癌组织切片上肿瘤核心（tumor core）、基质区（stroma）、免疫浸润区（immune-infiltrated region）在组织学上清晰可辨，还常有侵袭前沿（invasive front）——正是本书四个教学生态位（第 4 章）的自然载体。
- **生态位分明**：乳腺肿瘤异质性强，导管原位癌/浸润性癌区域的肿瘤细胞密度差异大，免疫浸润与基质成分的空间分布分明，做“生态位 × 通讯”分析信号足、故事好讲。
- **社区成熟**：该数据集是空间转录组方法学的“标准考题”，大量工具论文用它做演示，遇到问题容易搜到答案。
- **体积友好**：单个 Visium 切片约 5000 个 spot、约 2 万个基因（见 00-TECH 第 1 节），H5 文件数百 MB 量级，个人电脑可流畅分析。

从生物学角度看，乳腺癌也是研究空间异质性的理想模型：浸润性癌区域肿瘤细胞密集、增殖信号强；导管原位癌保留导管结构；间质区域富含成纤维细胞与细胞外基质；免疫浸润区域（肿瘤浸润淋巴细胞）的存在与预后及免疫治疗响应密切相关。这些区域在空间上交错分布，意味着同一张切片上就能同时观察到“生长、侵袭、免疫、基质”四种微环境程序，天然适合“生态位 × 通讯”的分析框架；结构相对均一的组织（如某些正常器官）做生态位分析的信号会弱很多。

作为拓展，**结直肠癌**（10x 官网亦有 Visium demo）组织结构同样典型且免疫浸润丰富，适合想验证方法普适性的读者——把第 5 章课题模板里的“肿瘤组织”换成“结直肠癌组织”即可。黑色素瘤、人淋巴结等也可按需替换（00-TECH 第 6 节）。

## 7.2 10x 官网下载流程

下载分六步，全程不需要登录：

1. **打开 10x Genomics 官网**，进入 “Datasets” 页面（Products 下拉菜单 → Datasets，或直接搜索 “10x Genomics Datasets”）。
2. **筛选 Visium 数据**：在页面左侧筛选器中选择产品线 **Spatial → Visium**（如果要做 FFPE 数据，可选 Visium FFPE；本书以新鲜冷冻 Visium 为例）。
3. **找到 Human Breast Cancer**：在列表中定位 “Human Breast Cancer, Ductal Carcinoma In Situ, Invasive Carcinoma (FFPE/FF 均有，选 Fresh Frozen 即可)”，点击进入详情页。列表里每个数据集都标注了组织类型、物种与文件清单。
4. **下载表达矩阵**：点击 **filtered feature-barcode matrix (H5)** 下载单个 H5 文件。这个文件同时包含三个信息：spot 条形码（barcodes）、基因（features）、计数矩阵（matrix），是 `Load10X_Spatial()` 的入口（第 8 章）。
5. **下载空间信息**：下载 **spatial** 目录（官网提供为压缩包，常见 tar.gz 或 zip，解压后内含 4 个文件，见下表）。这一步最容易漏——没有它，数据就没有坐标和图像，无法做任何空间分析。
6. **解压并登记**：把下载内容解压到 data/raw/ 下，并立即按 7.4 节登记清单（含 md5）。

下载前提醒三件事：① 官网界面会改版，筛选器名称可能有出入，认准“Visium”“Human Breast Cancer”“filtered feature-barcode matrix (H5)”三个关键词即可；② 大文件建议在稳定网络下下载，浏览器中断可改用 7.6 的 curl 命令；③ 两个文件要放在同一目录且保持文件名不变，第 8 章 `Load10X_Spatial()` 会按文件名自动识别。

各文件用途如下（与 00-TECH 第 1 节一致）：

| 文件 | 内容与用途 |
| --- | --- |
| `filtered_feature_bc_matrix.h5`（根目录） | spot×基因 计数矩阵（已过滤），Seurat/scanpy 读入表达数据 |
| `spatial/tissue_positions_list.csv` | 每个 spot 的像素坐标与组织内/外标记，空间可视化与邻域计算 |
| `spatial/scalefactors_json.json` | 图像与坐标之间的缩放因子，把表达矩阵对齐到组织图像 |
| `spatial/tissue_hires_image.png` | 高分辨率 H&E 组织图像，高分辨率叠加可视化 |
| `spatial/tissue_lowres_image.png` | 低分辨率 H&E 组织图像，快速预览与默认叠加背景 |

## 7.3 备选数据源

官网下载不是唯一途径。按 00-TECH 第 6 节，还有三条常用渠道：

- **spatialLIBD**（Bioconductor 包）：专用于人脑背外侧前额叶（DLPFC）Visium 数据（Maynard 等 2021 发表的数据集），一条命令即可拉取，适合想在“金标准手工注释”数据上练习生态位识别的读者。示例：`spatialLIBD::fetch_data("visium_IFDLPFC")`（首次运行会提示下载目标目录）。注意它只有脑组织数据，生态位类型与肿瘤不同。
- **GEO**（Gene Expression Omnibus）：NCBI 的公共表达数据库，用关键词 “Visium”“spatial transcriptomics” 检索即可找到大量已发表的空间转录组数据集（如乳腺癌、结直肠癌队列）。GEO 下载是文本化的三件套（barcodes/features/matrix）或补充文件，需要自己整理目录结构——适合想用“真实队列”重跑本书流程的进阶读者。下载时务必记录 GEO accession 号与下载日期。
- **Zenodo**：通用科研数据仓库，很多空间组学论文把补充数据（含处理后的 AnnData 对象）放在这里。检索时用数据集标题或 DOI 定位，**以论文方法节或数据可用性声明（Data Availability）给出的链接为准**，不要凭记忆猜 accession 号。

选渠道的决策很简单：**教学练习用官网 demo，方法对比用 spatialLIBD，真实课题用 GEO/Zenodo 的队列数据**。无论哪个渠道，都要执行 7.4 的登记纪律。

补充一个判断标准：**先看论文的数据可用性声明（Data Availability），再看文件格式**。声明写“GEO accession GSE…”，就去 GEO；写“processed data on Zenodo”，就去 Zenodo；写“available via spatialLIBD”，就一条命令拉取。文件格式上，h5/h5ad 最省事，mtx 三件套需要自己整理，原始测序数据（fastq）则要重跑上游流程——除非你想做对比分析，否则直接下载处理后的表达矩阵即可。

## 7.4 数据清单与校验（data-inventory）

数据下载后第一件事不是跑分析，而是登记。data-inventory 的核心思想是：**每份数据一条记录，含来源、下载命令、校验值、大小、授权**，写入 `data/README.md`（或 manifest.tsv），保证数据丢失时可恢复、论文可追溯。本书示例登记如下（URL 以你在官网实际复制到的为准）：

| 字段 | 内容（示例） |
| --- | --- |
| id | visium-breast-dcis-invasive |
| 类型 | raw / public |
| 来源 | 10x Genomics Datasets 官网（Visium → Human Breast Cancer） |
| 下载命令 | `curl -L -O <官网直链>`（见 7.6 脚本） |
| 文件 | filtered_feature_bc_matrix.h5、spatial.tar.gz |
| 大小 | 约数百 MB（H5 为主） |
| 校验值 | md5: 以 `Get-FileHash` / `md5sum` 实际计算为准（见下） |
| 授权 | 10x 公开 demo 数据集，公开可用，论文注明来源与下载日期即可 |
| 状态 | active |

登记表建议用 `data/README.md`（人读友好）或 `data/manifest.tsv`（机器友好）二选一，全书统一即可。另外建一张 `data/samples.csv`：一行一个样本，列为 sample_id、来源、下载日期、处理状态——它是后续所有分析脚本引用样本的“唯一事实来源”，第 8 章起脚本都从这里读样本信息，而不是硬编码路径。

校验命令（Windows PowerShell 与 Linux/macOS 各一条，二选一）：

```bash
# Linux/macOS：计算 md5
md5sum data/raw/visium-breast/filtered_feature_bc_matrix.h5

# Windows PowerShell：计算 md5（输出即登记表里的校验值）
Get-FileHash -Algorithm MD5 data/raw/visium-breast/filtered_feature_bc_matrix.h5
```

运行结果解读：输出一串 32 位十六进制字符串。把它写进数据清单的“校验值”列；下次数据异常时重算并比对，就能判断是不是文件损坏。**先记校验值、后跑分析**，是数据管理的黄金顺序。

## 7.5 目录组织建议

本书统一采用以下目录结构（第 8 章起所有脚本都按这个约定读写）：

```
spatial-niche-tutorial/
├── data/
│   ├── raw/                      # 原始下载，只读，绝不修改
│   │   └── visium-breast/
│   │       ├── filtered_feature_bc_matrix.h5
│   │       └── spatial/          # 坐标、缩放因子、H&E 图像
│   ├── processed/                # 预处理产物（QC 后对象等，第 8 章起生成）
│   ├── README.md                 # 数据清单（7.4 节登记表）
│   └── samples.csv               # 样本清单（样本 id、来源、下载日期）
├── code/                         # 分析脚本
├── figures/                      # 输出图
└── envs/                         # 环境文件（第 6 章）
```

纪律只有两条：**data/ 不进版本库**（大文件 + 原始数据，git 只留清单与样本表）；**raw/ 只读**——任何修改都在 processed/ 里做，保证原始数据可随时重来。

为什么坚持“raw 只读”？因为原始数据是分析的唯一锚点：第 8 章的过滤阈值、归一化方式改来改去很正常，但只要 raw/ 不动，任何时候都能从原始矩阵重新开始，所有中间结果都可复现。若某次处理真的需要覆盖，先备份到 processed/ 再改，并在 README 留一行记录（改了什么、何时改的、为什么）。

## 7.6 下载脚本：code/02_download.R 核心部分

完整脚本见配套 `code/02_download.R`（含断点续传与错误处理），核心部分如下。脚本会自动建立目录、下载、解压、计算校验值并追加到 `data/README.md`：

```r
# ===== code/02_download.R 核心部分 =====
# 用法：把 URL 换成你在 10x 官网复制到的直链（页面上的 Download 按钮右键复制链接）
# 注意：H5 与 spatial 的直链会随官网改版变化，以下 URL 为占位示例
url_h5    <- paste0("https://cf.10xgenomics.com/samples/spatial-exp/",
                     "filtered_feature_bc_matrix.h5")  # URL 以官网实际为准
url_sp    <- "https://cf.10xgenomics.com/samples/spatial-exp/.../spatial.tar.gz"
dest_dir  <- "data/raw/visium-breast"

dir.create(dest_dir, recursive = TRUE, showWarnings = FALSE)

# 1) 下载表达矩阵（H5）与空间目录
download.file(url_h5,
              file.path(dest_dir, "filtered_feature_bc_matrix.h5"),
              mode = "wb")
download.file(url_sp, file.path(dest_dir, "spatial.tar.gz"), mode = "wb")

# 2) 解压 spatial 目录
untar(file.path(dest_dir, "spatial.tar.gz"), exdir = dest_dir)

# 3) 计算 md5 校验值（Windows 与 Linux 通用写法）
md5_h5 <- tools::md5sum(file.path(dest_dir, "filtered_feature_bc_matrix.h5"))
cat("H5 md5:", md5_h5, "\n")   # 把这串值记进 data/README.md

# 4) 快速检查文件是否齐备
stopifnot(file.exists(file.path(dest_dir, "filtered_feature_bc_matrix.h5")),
          file.exists(file.path(dest_dir, "spatial/tissue_positions_list.csv")))
cat("下载与解压完成，文件齐备。\n")
```

运行结果解读：脚本最后打印 md5 值与“文件齐备”，说明下载成功。如果下载速度慢或中断，可改用浏览器手动下载后放到同一目录（脚本第 3、4 步仍可复用）。

脚本里的 URL 是占位符，务必替换成你在官网复制的直链——10x 的下载链接包含样本专属路径，不同数据集、不同版本都不一样。若官网改版导致直链失效，最稳妥的办法是回浏览器手动下载，再放到脚本指定的 data/raw/visium-breast/ 目录，脚本第 3、4 步（校验与检查）依然可用。下载完成后顺手把下载日期记进 data/README.md（data-inventory 要求记录下载日期）。命令行直接下载的替代写法（bash）：

```bash
# 等价于脚本第 1 步（bash 版，URL 同样换成官网直链）
mkdir -p data/raw/visium-breast
curl -L -o data/raw/visium-breast/filtered_feature_bc_matrix.h5 "<H5直链>"
curl -L -o data/raw/visium-breast/spatial.tar.gz "<spatial直链>"
```

## 7.7 练习：下载并登记

1. 按 7.2 的六步在 10x 官网下载乳腺癌 demo 的 H5 与 spatial 目录；
2. 用 7.6 的脚本（或手工）解压到 `data/raw/visium-breast/`；
3. 用 7.4 的校验命令计算两个文件的 md5，填进 `data/README.md` 的登记表；
4. 回答：如果三个月后 H5 文件损坏，你靠哪条记录能恢复数据？

![图 7-1 本书示例数据的质控总览（模拟数据演示）：上方为按生态位的 UMI 数/基因数/线粒体比例分布，下方为对应指标的空间散点图。第 8 章将详细讲解如何读懂与产出这类图。](figures/fig07_qc.png){width=85%}

## 本章小结

- 主示例数据：10x Visium 人乳腺癌 demo（组织结构典型、生态位分明、公开免费）；拓展可选结直肠癌。
- 下载六步：Datasets 页面 → Visium 筛选 → Human Breast Cancer → H5 表达矩阵 → spatial 目录 → 解压登记。
- 备选渠道：spatialLIBD（人脑，一条命令）、GEO（真实队列）、Zenodo（论文补充数据），按用途选择。
- data-inventory 纪律：来源/URL/大小/md5/授权逐项登记进 data/README.md，先记校验值后跑分析。
- 目录约定：data/raw 只读原始数据，data/processed 放产物，data/ 不进版本库。

## 练习与思考

1. **动手题**：完成 7.7 的下载与登记，把 data/README.md 的登记表填满（含 md5），并提交 data/samples.csv。
2. **判断题**：以下说法对错？（a）只下载 H5 不下载 spatial 目录也能做空间分析；（b）data/ 目录应该提交进 git 方便备份；（c）md5 校验值的作用是判断文件是否损坏。
3. **选择题**：你想在“有金标准手工注释”的数据上练习生态位识别，优先用哪个渠道？（a）10x 官网；（b）spatialLIBD；（c）Zenodo 任意搜索。
4. **思考题**：为什么“先记校验值、后跑分析”？如果数据在分析中途损坏，你如何发现？
5. **讨论题**：真实课题中你想用 GEO 上的某个乳腺癌 Visium 队列，登记表里除了 URL 还需要记什么？请列出至少三条你会在论文方法节写明的信息。
