摘要: Assemblytics 是一款用于基因组结构变异检测与分析的生物信息学工具，通过将待分析的基因组装配序列（query assembly）与参考基因组进行比对，识别两者之间的结构差异。其核心流程包括以下几个步骤：首先，利用"唯一锚定过滤"机制，仅保留在查询序列中具有足够唯一性覆盖的比对片段（默认最小唯一锚定长度为 10,000 bp），以确保变异调用来自高可信、非重复区域；其次，分别在相邻比对片段的间隙处和单个比对片段内部识别结构变异，涵盖插入、缺失、串联重复扩张/收缩及重复序列扩张/收缩等类型；最后，对所有检测到的变异进行整合分类，并生成统计摘要与可视化图表（如点图、N统计图和变异大小分布图）。在使用上，Assemblytics 推荐配合 MUMmer 4 工具包中的 nucmer -maxmatch 命令进行序列比对，并建议输入 contig 序列而非 scaffold，以避免因序列中 N 的数量不匹配导致假阳性结果。该工具提供在线分析平台，用户上传 delta 比对文件即可完成分析，适用于基因组组装质量评估与结构变异研究。

Assemblytics：基于基因组组装的结构变异检测工具¶

概述¶

Assemblytics 是一款专为宏基因组和比较基因组学设计的生物信息学工具，核心功能是通过将基因组组装结果（query assembly）与参考基因组（reference genome）或另一组装版本进行比对，从而系统性地检测和分析结构变异（Structural Variants, SVs）。

在基因组研究中，结构变异（如大片段的插入、缺失、重复扩张/收缩等）往往与物种演化、基因功能差异和疾病发生密切相关。然而，基于短读长测序的变异检测工具在面对重复序列区域时准确性大幅下降。Assemblytics 的设计出发点正是利用基因组组装（通常基于长读长测序技术）产生的连续序列，在全基因组尺度上高置信度地识别这类变异。

该工具提供两种使用模式：一是通过 assemblytics.com 提供的 Web 界面上传比对结果文件直接分析，无需本地安装，且所有计算均在用户浏览器客户端完成，数据不会上传至服务器；二是通过 Python 命令行工具集成至自动化分析流程（pipeline）。Assemblytics 已发表于生物信息学期刊 Bioinformatics，是该领域有据可查的主流工具之一。

核心原理与功能¶

整体流程设计¶

Assemblytics 的输入为 MUMmer 工具包中 nucmer 产生的 .delta 格式比对文件。整个分析流程由以下五个关键步骤构成：

1. 唯一锚定过滤（Unique Anchor Filtering）¶

这是 Assemblytics 区别于其他工具的核心设计。对于每一条比对记录（alignment），Assemblytics 计算该 query 序列中有多少碱基是"唯一"比对的——即不被其他任何比对所覆盖的部分。

默认最小唯一锚定长度（unique anchor length）为 10,000 bp
仅保留满足该长度要求的比对，确保变异检测来自高可信度的非重复区域
对于小基因组（如细菌），建议将该阈值调低至 1,000 bp

该过滤策略与 MUMmer 自带的 delta-filter 工具有根本性区别：delta-filter -q 仅需单个碱基的差异即可倾向于某一比对，而 Assemblytics 要求至少 10 kb 的唯一锚定区才保留比对，从而有效排除重复序列带来的假阳性。

2. 比对间变异检测（Calling Variants Between Alignments）¶

Assemblytics 识别同一 query 序列相邻比对之间的间隙（gap）中发生的变异，包括：

插入（Insertion）
缺失（Deletion）
串联重复扩张/收缩（Tandem Expansion/Contraction）

当组装序列与参考基因组在相邻比对末尾不完全衔接时，这些间隙即反映了潜在的结构变异。

3. 比对内变异检测（Calling Variants Within Alignments）¶

除比对间隙外，流程还扫描单条比对内部，通过比较参考侧（reference side）与 query 侧（query side）的 gap 大小差异来识别嵌入在比对内部的变异。

4. 整合与分类（Integration and Categorization）¶

所有检测到的变异被统一汇总，并按以下类型进行分类：

变异类型	说明
Insertion（插入）	query 中存在而参考中缺失的序列
Deletion（缺失）	参考中存在而 query 中缺失的序列
Tandem Expansion/Contraction（串联重复扩张/收缩）	局部串联重复单元数量的增加或减少
Repeat Expansion/Contraction（重复扩张/收缩）	发生在缺乏唯一锚定序列的过滤间隙中，gap 大小相对参考增大（扩张）或减小（收缩）

需要特别注意的是：重复序列本身不会被报告为结构变异，只有其大小发生改变（扩张或收缩）才会被记录。

5. 可视化与统计摘要（Visualization and Summary）¶

分析完成后，工具自动生成以下输出：

过滤后比对的点图（dot plot）
组装的 N 统计图表（Nchart）
所有检测到的变异按大小分布的直方图
汇总统计数据

染色体间变异（Interchromosomal / Long-range Variants）¶

默认情况下，跨越两条不同参考染色体的候选变异（Interchromosomal variants）不包含在主结果中，因为其中大多数来自错误组装（misassembly）而非真实变异。通过 --long-range 参数可将这些候选变异单独输出至 assemblytics_long_range_variants.bed 文件，供人工审查。

安装与使用¶

方式一：Web 界面（无需安装）¶

访问 assemblytics.com，上传 .delta 或 .delta.gz 文件即可。所有计算在浏览器客户端通过 Pyodide（Python 编译为 WebAssembly）完成，数据不会离开本地计算机。

方式二：Python 命令行工具¶

环境要求： Python 3.8+，依赖 numpy、pandas、matplotlib

pip install assemblytics
# 通过 pip 安装 assemblytics 及其所有依赖

基本用法：

assemblytics -d <delta_file> -o <output_dir>
# -d: 指定输入的 .delta 或 .delta.gz 文件路径
# -o: 指定输出目录

第一步：安装 MUMmer 并生成比对文件¶

Assemblytics 专为 nucmer -maxmatch 的输出设计，以下参数对唯一锚定过滤的正确运行至关重要：

# 1. 从 GitHub 下载安装 MUMmer 4
# 参考: https://github.com/mummer4/mummer/releases

# 2. 使用 nucmer 将组装序列比对到参考基因组
nucmer -maxmatch -l 100 -c 500 REFERENCE.fa ASSEMBLY.fa -prefix OUT
# -maxmatch: 报告所有最大唯一匹配（对唯一锚定过滤至关重要）
# -l 100:   最小匹配长度为 100 bp（默认推荐值，降低此值会增加敏感性但增大文件）
# -c 500:   最小簇长度为 500 bp
# REFERENCE.fa: 参考基因组 FASTA 文件
# ASSEMBLY.fa:  待分析的基因组组装 FASTA 文件
# -prefix OUT: 输出文件前缀，生成 OUT.delta

# 3. 可选：对输出文件进行 gzip 压缩（Assemblytics 支持直接读取 .delta.gz）
gzip OUT.delta

重要提示： 请使用 contig（连续序列）而非 scaffold（含 N 的支架序列）作为输入。Scaffold 中 N 的数量若与参考基因组中对应距离不完全匹配，会引入假阳性变异。

第二步：运行 Assemblytics 分析¶

assemblytics -d OUT.delta.gz -o my_output_dir
# -d: 输入前一步生成的 delta 文件
# -o: 指定结果输出目录

开发模式安装（从源码运行）¶

git clone https://github.com/MariaNattestad/assemblytics.git
# 克隆项目源码到本地
cd assemblytics
pip install -e .
# 以可编辑模式安装，便于修改源码后立即生效
assemblytics
# 验证安装是否成功

本地运行 Web 应用¶

cd assemblytics
python3 -m http.server 8000 --directory public
# 启动一个静态文件服务器，在本地端口 8000 提供 Web 界面
# 启动后在浏览器中访问 http://localhost:8000

Web 应用运行在 public/ 目录下，Python 源代码位于仓库根目录的 assemblytics/ 中。Web 应用通过 Pyodide 的 micropip 在运行时加载 Python wheel 包（public/assemblytics-2.0.0-py3-none-any.whl）。

修改 Python 源码后，需重新构建 wheel 再测试：

make wheel
# 执行 python3 -m build --wheel 并将结果复制到 public/ 目录
# 注意：若在 pyproject.toml 中更新了版本号，需同步修改 public/worker.js 第 18 行的文件名

实战示例¶

示例一：分析大肠杆菌（E. coli）数据¶

assemblytics -d input_examples/ecoli.delta.gz -o ecoli_output
# 使用内置 E. coli 示例数据运行完整流程
# 输出结果应与 output_examples/ecoli/ 目录下的预计算结果一致

注意：E. coli 为小基因组，建议将唯一锚定长度调整为 1000 bp：

assemblytics -d input_examples/ecoli.delta.gz -o ecoli_output -l 1000
# -l 1000: 将唯一锚定长度从默认的 10000 bp 调低至 1000 bp，适合细菌等小基因组

示例二：输出染色体间候选变异¶

assemblytics -d input_examples/ecoli.delta.gz -o ecoli_output --long-range
# --long-range: 启用该参数后，除常规输出外，还会额外生成：
#   ecoli_output/assemblytics_long_range_variants.bed
# 该文件包含跨染色体的候选变异，通常为错误组装，偶尔为真实易位或大规模重排
# 建议人工审查后再纳入分析

示例三：回归测试（验证流程一致性）¶

output_examples/ 目录保存了五个物种的预计算结果，用于验证流程的正确性。核心比对文件为 assemblytics_structural_variants.bed（最终结构变异调用集合）。

# 酵母菌（Saccharomyces cerevisiae）
assemblytics -d input_examples/yeast.delta.gz -o /tmp/assemblytics_test/yeast
diff <(tail -n +2 /tmp/assemblytics_test/yeast/assemblytics_structural_variants.bed | sort) \
     <(tail -n +2 output_examples/yeast/Saccharomyces_cerevisiae_example.Assemblytics_structural_variants.bed | sort) \
     && echo "yeast: OK"
# tail -n +2: 跳过 BED 文件的表头行
# sort: 对内容排序，使比较与变异 ID 的生成顺序无关
# diff 无输出 + 打印 "yeast: OK" 表示结果一致

# 拟南芥（Arabidopsis thaliana）
assemblytics -d input_examples/arabidopsis.delta.gz -o /tmp/assemblytics_test/arabidopsis
diff <(tail -n +2 /tmp/assemblytics_test/arabidopsis/assemblytics_structural_variants.bed | sort) \
     <(tail -n +2 output_examples/arabidopsis/Arabidopsis_example.Assemblytics_structural_variants.bed | sort) \
     && echo "arabidopsis: OK"

# 果蝇（Drosophila melanogaster）
assemblytics -d input_examples/drosophila.delta.gz -o /tmp/assemblytics_test/drosophila
diff <(tail -n +2 /tmp/assemblytics_test/drosophila/assemblytics_structural_variants.bed | sort) \
     <(tail -n +2 output_examples/drosophila/Drosophila_example.Assemblytics_structural_variants.bed | sort) \
     && echo "drosophila: OK"

# 人类（NA12878 组装与 hg19 比对，文件最大，耗时最长）
assemblytics -d input_examples/human.delta.gz -o /tmp/assemblytics_test/human
diff <(tail -n +2 /tmp/assemblytics_test/human/assemblytics_structural_variants.bed | sort) \
     <(tail -n +2 output_examples/human/Human_NA12878_to_hg19.Assemblytics_structural_variants.bed | sort) \
     && echo "human: OK"

常见问题¶

Q1：各种变异类型有何区别？Tandem Expansion 与 Repeat Expansion 有什么不同？¶

Assemblytics 将变异分为四类：

Insertion（插入）/ Deletion（缺失）：在具有唯一锚定序列的比对间隙中检测到的直接序列增减。
Tandem Expansion/Contraction（串联重复扩张/收缩）：发生在局部串联重复区域，重复单元数量相对参考增加或减少。
Repeat Expansion/Contraction（重复扩张/收缩）：发生在唯一锚定过滤后被移除的比对所对应的间隙中。若 gap 在 query 侧更大则为扩张，在参考侧更大则为收缩。重复序列本身不被报告，只有大小变化才被记录为变异。

Q2：唯一锚定过滤的目的是什么？为什么不直接使用 delta-filter？¶

基因组中的重复元件可以同时比对到参考基因组的多个位置，导致假阳性变异。delta-filter 使用最长递增子序列（Longest Increasing Subsequence, LIS）动态规划算法过滤重复比对，但在实践中，单个碱基的差异即可决定保留哪条比对（-q 模式），过于激进。

Assemblytics 的唯一锚定过滤则要求每条比对在 query 侧有至少 10 kb 的序列仅比对到参考基因组的唯一位置，从根本上消除了来自重复区域的低置信度比对。对于小基因组（如细菌），建议将该阈值调整为 1,000 bp。

Q3：分析需要多长时间？¶

大多数基因组：几秒内完成
人类基因组示例（6 MB gzipped delta 文件）：约 50 秒
时间与文件大小近似线性正比，预计每 10 MB 至少需要 1 分钟
Web 版本在用户本地浏览器客户端运行，速度取决于本地 CPU 性能

如需加速，可在 nucmer 步骤中适当提高 -l 参数值（如 -l 10000），以减小输出文件大小，但会损失部分比对敏感性，不建议用于正式分析，可用于快速预检。

Q4：可以使用 MUMmer 以外的比对工具吗？¶

不推荐。 Assemblytics 专为 MUMmer 的 .delta 格式输出设计，且工具中许多关于保留哪些比对的策略决策都是基于 MUMmer 的行为特性调优的。MUMmer 3 和 MUMmer 4 均兼容，MUMmer 4 虽然也支持 SAM/BAM 格式输出，但 Assemblytics 只处理 .delta 文件。使用其他比对器（如 minimap2 等产生 SAM/BAM 输出的工具）不适用于 Assemblytics。

Q5：为什么默认不报告易位（translocations）？¶

跨越两条不同参考染色体的候选变异（Interchromosomal variants）在实践中大多来自错误组装（misassembly）而非真实的染色体间易位。因此，默认情况下这些候选变异被排除在主结果之外。

如需检查这些候选变异，可使用 --long-range 参数，Assemblytics 会将其单独输出至 assemblytics_long_range_variants.bed 文件，与高置信度的主调用集明确区分。建议在将其纳入结论之前进行人工审查。

总结¶

Assemblytics 是一款专注于从基因组组装比对中检测结构变异的工具，其核心优势在于独特的唯一锚定过滤（Unique Anchor Filtering）机制，有效规避了重复序列导致的假阳性问题。工具支持 Web 界面和 Python 命令行两种使用模式，分别适合交互式分析和流程化集成。使用时需配合 MUMmer 的 nucmer -maxmatch 命令生成 .delta 格式输入，并建议使用 contig 而非 scaffold 以避免引入噪声。对于不同大小的基因组，应适当调整唯一锚定长度参数。工具内置多物种测试数据，便于验证流程的正确性与可重复性。