企业官网建设流程全解析

空间转录组分析做到第五讲，终于来到合并样本这一步。前面我们用 spaceranger count 搞定了单个样本的定量与坐标定位，但实验设计里，极少有只拿一个样本发文章的情况——生物学重复、多组学比较、疾病分型……这时候手里攥着的不是多份独立的outs文件夹，而是一堆需要放进同一张 UMAP 共舞的数据。今天这篇，就把 spaceranger aggr 从原理到实操，从参数坑到批次效应排查，一次性讲透，适合已经跑完 count、正准备做多样本整合的同学。

1. 为什么需要 aggr：多样本空间转录组的硬需求

1.1 生物学背景：单样本无法回答组学问题

空间转录组技术测的不是一锅粥里的平均值，而是每个空间 spot 里的转录本分布。单个样本能告诉你"这个组织中特定区域有哪些基因在活跃表达"，但要说"这种活跃是普遍规律还是个体偶发"，就得靠多个样本的重复和比较。

我在实际项目中遇到过典型的场景：某课题组研究某组织区域的退行性病变，用同一代动物取材、同一批次建库，跑了三个样本。如果只对每个样本单独画点图，会发现三张图上的簇 5 都是阳性的，但簇 5 在样本 A 里和簇 3 挨得近，在样本 B 里却和簇 2 挨得近——这到底是真实生物学差异，还是建库偏好和测序深度的技术噪声？不做合并分析，根本说不清。

高端空间转录组分析的核心不是"跑出基因表达矩阵"这种机械操作，而是"让不同样本里的同一种细胞状态可以被公平地比较"。aggr 就是官方给的一个重要工具，它把多个样本的基因表达矩阵、空间坐标和图像信息整合在一起，基于合并后的数据重新定义跨样本的聚类和基因共表达模式。

1.2 aggr 到底做了什么：不只是把数据拼接在一起

很多人以为 aggr 就是把几个样本的矩阵用rbind拼起来，其实远不止如此。它至少做了三件关键的事：

• 深度归一化：不同样本的测序深度天差地别，一个样本可能每个 spot 平均 5000 个 UMI，另一个可能只有 2000 个。aggr 会计算样本间的深度差异，并基于所有样本的合并信息进行归一化，把表达值拉齐到可比的水平。
• 聚类与批次校正：它会在合并矩阵上重新跑聚类，同时输出样本来源信息，允许后续分析检查是否存在样本特异性的批次簇。虽然不是那种复杂的深度学习批次校正，但它用更简单的权重方法尽量避免"哪来的样本"来主导聚类。
• 统一坐标与聚类标签：多个样本的 tissue 切片位置偏移、旋转角度都有差异，aggr 会在输出中保留每个 spot 的原始坐标，但聚类标签是合并全局重新定义的。

所以，你拿到的数据不再是"样本 1 的簇 1、样本 2 的簇 3"，而是"全合并集的簇 1"——这才是跨样本比较的前提。

2. 输入准备与参数解析：把样本清单捋明白

2.1 每个样本的前置处理：spaceranger count 的规范性

aggr 不是凭空起高楼，它的输入是每个样本已经跑完spaceranger count的输出目录。严格来说，你必须保证以下几点，否则 aggr 会直接报错或者给你算出一堆莫名其妙的数字：

• 版本一致性：所有样本的 count 调用必须使用同一个spaceranger版本，最好同一个参考转录组版本，不然基因 id 比对会出现错位，甚至有的基因根本匹配不上。
• 输出目录完整性：每个样本需要保留outs/filtered_feature_bc_matrix、outs/spatial等核心输出。别为了省硬盘把中间文件删了，aggr 需要读取原来的molecule_info.h5。
• 样本名称规范：样本 id 里不要用_或空格，统一用字母数字组合。我见过有人故意取sample_1_rep2，结果 aggr 的 CSV 解析器直接把它拆成了三列，一脸懵。

如果你前面的 count 跑得乱七八糟，现在先别急着重跑。可以先用spaceranger aggr --help看看帮助信息，确认当前版本对输入输出目录的预期结构。

2.2 aggr 的 CSV 配置文件：格式、字段与踩坑点

aggr 用一个 CSV 文件传入样本清单，这就是它合并的"地图"。CSV 一般放在某个工作目录里，格式非常简单：

sample_id,molecule_h5_path sampleA,/data/count/sampleA/outs/molecule_info.h5 sampleB,/data/count/sampleB/outs/molecule_info.h5

看起来人畜无害，但有几个细节我踩过坑：

• 首行必须写对：sample_id和molecule_h5_path是固定列名，大小写不能错。少了molecule_h5_path它会直接告诉你"CSV missing column"。
• 路径必须写绝对路径：相对路径有时候能过，有时候不行，取决于你从哪个目录调用命令。与其和它猜谜，不如一律用绝对路径。
• 样本 id 会和后续分析强烈挂钩：sample_id决定了输出的样本标签、报告里的名字。你如果给它取1、2，后面画图注释时自己都容易看混。

另外一个很重要的可选列是reference_path或genome，具体看版本。某些版本允许你指定每个样本的参考转录组，但建议所有样本用同一个，不然你会给自己的分析埋下一个随时炸的雷。

3. 实操全流程：从命令行到结果输出

3.1 运行 spaceranger aggr 的标准命令

环境假定你已经装好spaceranger，并且配好了10x的cellranger类似的路径。实际运行时，我一般这样做：

export PATH=/opt/10x/spaceranger-2.1.0:$PATH spaceranger aggr \ --id=merged_5_samples \ --csv=/data/projects/aggr_input/library.csv \ --normalize=slm \ --nosecondary

这里值得拆开来解释：

• --id：指定输出的结果目录名，最终会生成一个叫merged_5_samples的文件夹，里面包含outs。
• --csv：指向上面的配置文件。
• --normalize=slm：slm 是 default 的归一化方式，全称是"sample-level normalization"，它会基于每个样本的总 UMI 数来调整表达权重。另一个选项是--normalize=mapped，基于 mapping rate 来归一化。通常推荐 slm，因为把样本的转录本总数视为更可靠的参考。
• --nosecondary：如果你只需要合并和聚类，不需要跑后续的 secondary analysis（如 marker 探究、富集），建议加上这个参数。它能把运行时间缩短不少。但如果你想要整套自动报告，就别加这个参数，让它跑出完整的analysis目录。

运行期间会有日志输出，特别重要的是中间会显示 Normalizing、Clustering 和 Visualizing。有一次我跑一个三样本项目，卡在 Clustering 步骤大概 40 分钟没动静，一度以为死机了，后来发现它只是在一个巨大的矩阵上做迭代离差分析，属于正常现象。

3.2 结果文件解读：合并矩阵、聚类与报告

跑完 aggr，目录结构长这样：

merged_5_samples/ ├── outs/ │ ├── filter_feature_bc_matrix.h5 │ ├── filtered_feature_bc_matrix/ │ ├── analysis/ │ ├── spatial/ │ ├── web_summary.html │ └── metrics_summary.csv

核心产出是：

• filtered_feature_bc_matrix.h5：合并后的表达矩阵，每一行是基因，每一列是sampleID_spotID形式的合并 spot 名。你要做后续任意分析，都是从这个矩阵出发。
• analysis：包含聚类结果（clusters.csv）、差分表达、标记等。clusters.csv里有三列：Barcode、Cluster、Sample，其中Sample告诉你每个 spot 来自哪个样本。
• web_summary.html：一个报告页面，展示合并后的 UMI 分布、测序深度等等。我每次跑完都先翻这个报告，检查有没有异常高或异常低的样本，作为第一批次效应排查的依据。

如果你有组织切片图像，spatial/目录下会保留每个样本的坐标与组织图像信息，可以进行漂亮的可视化。

4. 常见问题与排查经验实录

4.1 批次效应不清、聚类打架怎么办

这是我见到的最高频问题。跑完 aggr 后打开clusters.csv，画图发现某种细胞类型的 spot 全都来自样本 A，而样本 B 几乎看不到，这叫批次效应，而不是真正的生物学信号。你应该先做的一步是：

• 查看web_summary.html里的 Per-Sample UMIs / 基因数。如果样本 B 测序深度远低于 A，先去归一化层面找问题。
• 检查是否某个样本的切片质量特别差、spot 数特别少，这也会导致它的基因捕获率低，聚类时容易被"淹没"。
• 尝试用--normalize=slm但已经用了，还是不行？那就需要手动介入：比如在细胞类型注释时使用合并矩阵里的Sample列进行随机效应回归，而不是纯靠聚类软件。

经验法则：aggr 本质上做得最多的是"剂量校正"，而不是"细胞类型匹配"。你如果想要更强的跨样本整合，可以做基于锚点的整合（比如使用 Seurat 的整合流程），把 aggr 输出当作起点，而不是终点。

4.2 内存爆掉、运行时间过长怎么办

空间转录组数据本质上就是大数据。合并四个样本，每个样本 5000 个 spot，共 20000 个 spot，20k 维矩阵对内存的消耗相当可观。我遇到过 64GB 内存的服务器直接 OOM，排查后发现是一个样本的 H5 文件损坏导致读取异常，矩阵维度膨胀。

一般建议：

• 先确认内存：至少 128GB 起步，尤其是跑 secondary analysis。
• 如果只做合并聚类，务必加--nosecondary，能把时间缩短 30%-40%。
• 在超大数据集上，考虑把样本分拆跑多个 aggr 任务，然后再用其他工具（比如 scanpy）进行二次整合。
• 磁盘剩余空间也盯紧，合并过程中的临时文件动辄 200GB 以上。

4.3 一个小但常犯的坑：样本 id 里带连字符

有人喜欢在sample_id里写Ctrl-24h，结果 aggr 在输出 CSV 时把这个当成减号，后续 R 语言读取时Ctrl-24h会被当成运算式。规范的样本 id 应该是字母数字组合，例如ctrl24h、treat48h。这个细节虽然不致命，但会浪费你一个多小时去排查。

5. 合并后数据的延伸分析与个人心得

5.1 下游分析的衔接：聚类注释与空间可视化

aggr 跑出来的合并数据是通用的，你可以直接用 Seurat 或者 scanpy 读入以后做常规的单细胞分析。空间信息的可视化方面，spatial/目录下的tissue_positions_list.csv和scalefactors_json.json可以配合 plotly 或 R 的SpatialExperiment画组织切片上的基因表达。

我个人常用的路径是：读入filtered_feature_bc_matrix.h5，用Seurat::CreateSeuratObject创建对象，assay 设为Spatial，然后利用images参数把空间坐标引进去。这时候如果你做的是一块肿瘤组织，就能把某条通路的活性直接映射到组织空间的特定区域，结合样本来源着颜色，一眼看出不同样本的克隆差异。

5.2 从业者的避坑建议

最后分享几条我摸爬滚打出来的经验：

• 每次做新项目前先跑一个小样例：哪怕只有两个样本，先合并跑一遍，确认 CSV、路径、版本没问题，再动全量数据。别高估自己对命令行的熟练度，省那二十分钟的检查时间往往要付出一小时的后期排查代价。
• 完整保留 aggr 日志文件和 metrics summary：文章补实验做原图时，这些文件是给审稿人看的直接证据。有一次我需要倒回去说明我做过归一化，结果日志没存，差点查无可查。
• 不要把 aggr 预计的必要重复看得太重：它给的metrics_summary.csv里有各项质量指标，甚至包含一些清洗建议，但它不像 count 阶段那样做细胞质量过滤。你如果想做严格的质控过滤，要在读入 Seurat 后自己设定阈值。
• 版本锁定是压倒一切的优先级：同一个项目哪怕只隔两周，重新下载一个新版 spaceranger 跑 aggr，有可能产生完全不同的聚簇。生物信息学上这叫"版本漂移"，你会发现旧结果很难复现。所以一旦用一个版本跑到满意的结果，这个项目就焊死在那个版本上，不要在结束前随便升级。

空间转录组的多样本合并，说难也难，说简单也简单。难在你要理解归一化背后的逻辑，简单在照抄命令加初始配置就能产出结果。但是，结果够不够可靠，最终还是靠你对样本来源、切片质量和实验设计的把握。我见过太多人只看spaceranger aggr输出的那个 HTML 报告就以为万事大吉，直到画图时发现样本和簇完全混淆才回头补课——真希望他们早点看到这篇。