# 附录 C 示例数据与代码清单

> 本附录是“复现全书”的总索引：10 个配套脚本按什么顺序跑、每个脚本干什么、示例数据从哪来。所有脚本位于 `code/`，教学图位于 `figures/`。

## C.1 配套代码清单

全书配套 10 个 R 脚本（00-SPEC 第 3 节），按分析流程编号命名，与章节目录无关。**建议运行顺序就是编号顺序**：每个脚本的输出是下一个脚本的输入，请勿跳号运行。运行时长均为估计值，依机器配置（CPU/内存/网速）而异，仅供参考。

全书配套 10 个 R 脚本（00-SPEC 第 3 节），按分析流程编号命名，与章节目录无关。**建议运行顺序就是编号顺序**：每个脚本的输出是下一个脚本的输入，请勿跳号运行。运行时长均为估计值，依机器配置（CPU/内存/网速）而异，仅供参考。全部脚本位于 `code/` 目录：

1. **第 1 步 · `code/01_setup.R`（对应第 06 章，30–60 分钟）**：环境与包——安装/加载 Seurat v5、CellChat v2、BayesSpace 等并检查版本；
2. **第 2 步 · `code/02_download.R`（对应第 07 章，10–30 分钟）**：下载 10x Visium 人乳腺癌 demo（H5 + spatial 目录），校验 md5 并登记数据清单；
3. **第 3 步 · `code/03_preprocess.R`（对应第 08 章，10–20 分钟）**：预处理与质控——QC 指标、过滤、SCTransform、PCA、聚类、UMAP、空间可视化；
4. **第 4 步 · `code/04_annotation.R`（对应第 09 章，30–60 分钟）**：细胞类型注释——marker 打分 + cell2location 去卷积调用说明（Python 部分见同目录 `.py` 脚本）；
5. **第 5 步 · `code/05_spatial_domain.R`（对应第 10 章，30–60 分钟）**：生态位识别——BayesSpace 空间聚类 + Squidpy 邻域富集（Python 调用）+ 生态位命名与特征化；
6. **第 6 步 · `code/06_cellchat.R`（对应第 11 章，20–40 分钟）**：CellChat 基础——构建对象、通讯概率、通路聚合、经典可视化（气泡/网络）；
7. **第 7 步 · `code/07_niche_cellchat.R`（对应第 12 章，30–60 分钟）**：生态位分区通讯——按生态位 subset 后分别建 CellChat，比较生态位特异的通讯程序；
8. **第 8 步 · `code/08_differential_comm.R`（对应第 13 章，20–40 分钟）**：差异通讯/重编程——compareInteractions、netVisual_diff、通路对比 + COMMOT 空间活性（可选）；
9. **第 9 步 · `code/09_visualization.R`（对应第 14 章，10–20 分钟）**：论文级图表——统一字号/配色/300 dpi 导出；
10. **第 10 步 · `code/10_summary.R`（对应第 15 章，5–10 分钟）**：汇总输出——生成结果表（CSV）、图表-文字对应表草稿、方法参数汇总。

**运行总览（文字版流程图）**：脚本间依赖与章节目对应如下，箭头表示“前一产物是后一输入”：

```text
02_download.R  ──►  03_preprocess.R  ──►  04_annotation.R  ──►  05_spatial_domain.R
(07 章 数据)       (08 章 预处理)         (09 章 注释)            (10 章 生态位)
      ▲
      │ 数据
      │
01_setup.R（06 章 环境，先于一切）

05_spatial_domain.R ──► 06_cellchat.R ──► 07_niche_cellchat.R ──► 08_differential_comm.R
(生态位标签)            (11 章 CellChat)  (12 章 分区通讯)        (13 章 差异/重编程)

08_differential_comm.R ──► 09_visualization.R ──► 10_summary.R
(差异表/通路活性)          (14 章 论文级图表)       (15 章 汇总报告)
```

按章节对应关系再读一遍：**07 章数据（02 脚本）→ 08 章预处理产物（03 脚本）→ 09 章注释（04 脚本）→ 10 章生态位（05 脚本）→ 11 章 CellChat（06 脚本）→ 12 章分区通讯（07 脚本）→ 13 章差异/重编程（08 脚本）→ 14 章图表（09 脚本）→ 15 章写作汇总（10 脚本）**。跳过任何一环，下游脚本都会因缺输入报错。

## C.2 示例数据说明

### C.2.1 10x Visium 人乳腺癌 demo（主示例数据）

- **获取**：10x Genomics 官网数据集页（`https://www.10xgenomics.com/datasets`）搜索 “Human Breast Cancer”（Visium 系列），下载两项：① “filtered feature-barcode matrix (H5)”；② `spatial/` 目录（含 `tissue_positions_list.csv`、`scalefactors_json.json`、`tissue_hires_image.png`、`tissue_lowres_image.png`）。下载命令与校验见 `code/02_download.R` 与第 07 章。
- **结构**（00-TECH 第 1 节）：捕获区 6.5×6.5 mm、约 5000 个 spot（直径≈55 μm、中心距 100 μm）；H5 内含 `barcodes`（spot 条形码）、`features`（基因）、`matrix`（计数，稀疏格式）；`spatial/` 提供坐标、缩放因子与 H&E 图像。
- **为什么选它**：乳腺癌组织结构典型、四种生态位（肿瘤核心/侵袭前沿/免疫浸润区/基质区）分明，适合新手一眼看懂生态位概念（第 07 章）。
- **登记要求**：下载后按 data-inventory 规范登记样本 id、URL、md5 与授权（10x demo 为公开可用，引用注明来源）。

### C.2.2 教学模拟数据 `data/sim_visium.npz`

- **用途**：教学图（fig07–fig17）的“数据分析结果”类图全部基于**模拟数据演示**（00-FIGURES 声明），让新手在**无需下载大文件**的情况下看到“真实分析会长什么样”。模拟数据体积小、生成快，适合课堂与快速试跑。
- **结构与读取**：`data/sim_visium.npz` 为 numpy 压缩格式，含模拟的 spot×基因计数矩阵、坐标、生态位/细胞类型标签等键（键名以脚本内注释为准）。用 `numpy.load` 读取即可。

```python
# 目的：查看模拟数据的键与形状（快速试跑用）
import numpy as np
d = np.load("data/sim_visium.npz")
print(list(d.keys()))          # 如 counts / coords / niche / celltype ...
print(d["counts"].shape)       # (n_spots, n_genes)
```

- **生成脚本**：位于 `code/figures/`，其中 `gen_figures_partA_schematics.py` 生成概念示意图（fig01–fig06），`gen_figures_partB_analysis.py` 生成模拟分析结果并产出 `data/sim_visium.npz` 与全部模拟结果图（fig07–fig17）。运行该脚本会重新生成模拟数据与教学图，可用于核对图注与数据的一致性。
- **重要提醒**：模拟数据只用于**学方法**，不可用于真实课题结论；真实课题请用 10x demo 或自己的数据（第 07 章）。

## C.3 复现全书的最低路径

想最快看完全书流程长什么样，按此顺序：

1. 跑 `code/01_setup.R` 装好环境（首次约 1 小时）；
2. 跑 `code/02_download.R` 下载 demo 数据；
3. 依次跑 `03 → 04 → 05 → 06 → 07 → 08`（合计约 3–4 小时，cell2location 部分可选）；
4. 跑 `09_visualization.R` 得到论文级图表，对照 `figures/` 中的教学图检查；
5. 跑 `10_summary.R` 生成汇总表，作为第 15 章写作的素材。

每跑完一个脚本，对照该章“运行结果解读”检查输出是否符合预期；不符合就先排错（第 16 章）再继续，不要带着错误往下跑。
