HapHiC v1.0.7 安装与使用--生信工具095

HapHiC 

https://github.com/zengxiaofei/HapHiC #官网

Version 1.0.7

安装说明

HapHiC 已在搭载 Intel Xeon、AMD EPYC、海光 C86 处理器的 Linux 服务器上完成测试与验证。

（1）从 GitHub 下载源码

git clone https://github.com/zengxiaofei/HapHiC.git

（2）安装依赖环境

强烈推荐使用 Conda 一键部署依赖；若需手动安装，请参考脚本 HapHiC/conda_env/create_conda_env_py310.sh。 仓库HapHiC/conda_env/目录下同时提供 Python3.11、3.12 版本环境配置文件。

# 创建Python3.10环境
conda env create -f HapHiC/conda_env/environment_py310.yml
# 激活环境
conda activate haphic
# 或使用conda完整路径激活
source /path/to/conda/bin/activate haphic

（3）校验全部依赖是否安装成功

/path/to/HapHiC/haphic check

（4）查看全部子命令

/path/to/HapHiC/haphic -h

重要提示

Bioconda 渠道的 HapHiC 非官方维护版本，存在已知缺陷会导致流程中途崩溃。为保证安装成功，请严格按照上述官方方式搭建 Conda 运行环境。

快速上手

第一步：Hi-C 测序数据比对至组装序列生成 BAM 文件

官方推荐完整比对流程

bwa index asm.fa
bwa mem -5SP -t 28 asm.fa /path/to/read1_fq.gz /path/to/read2_fq.gz | samblaster | samtools view – -@ 14 -S -h -b -F 3340 -o HiC.bam

/path/to/HapHiC/utils/filter_bam HiC.bam 1 –nm 3 –threads 14 | samtools view – -b -@ 14 -o HiC.filtered.bam

配套说明

第二步：运行 HapHiC 完整挂载流水线

（1）一键式完整流程命令

haphic pipeline可一次性执行全部挂载步骤，必填参数：

• asm.fa：FASTA 格式基因组组装序列
• HiC.filtered.bam：上一步过滤后的 BAM（1.0.3 及以上版本也支持 chromap 输出的.pairs 文件）
• nchrs：基因组预期染色体条数，即最终输出 scaffold 数量

/path/to/HapHiC/haphic pipeline asm.fa HiC.filtered.bam nchrs

（2）限制性酶切位点参数 –RE

默认酶切位点为GATC（MboI/DpnII），可通过–RE修改；无酶切原位 Hi-C 文库可保留默认值。

# HindIII酶切文库
/path/to/HapHiC/haphic pipeline asm.fa HiC.filtered.bam nchrs –RE "AAGCTT"
# Arima双酶切体系
/path/to/HapHiC/haphic pipeline asm.fa HiC.filtered.bam nchrs –RE "GATC,GANTC"
# Arima四酶切体系
/path/to/HapHiC/haphic pipeline asm.fa HiC.filtered.bam nchrs –RE "GATC,GANTC,CTNAG,TTAA"

（3）contig 纠错参数 –correct_nrounds

基于 Hi-C 互作信号拆分错误连接的 contig，使用该参数开启纠错并设置迭代轮次：

# 常规2轮纠错即可满足需求
/path/to/HapHiC/haphic pipeline asm.fa HiC.filtered.bam nchrs –correct_nrounds 2

提示：当前 hifiasm 等高精度长读组装软件极少产生错误连接，该参数非必需，甚至会降低组装连续性；少量组装错误可后续在 Juicebox 中手动拆分校正。

（4）分型错误容错参数 –remove_allelic_links

若输入为分型基因组、单倍型间序列分化低导致分型切换错误率高，添加该参数过滤等位 contig 间的 Hi-C 互作，提升容错；数值为基因组倍性。

# 同源四倍体分型组装，倍性设为4
/path/to/HapHiC/haphic pipeline asm.fa HiC.filtered.bam nchrs –remove_allelic_links 4

提示：分型基因组若使用 chromap 等其他工具比对，同样建议添加该参数，抵消错误比对带来的干扰。

（5）性能线程参数

–threads：读取 BAM 文件线程数；–processes：contig 排序定向多进程数

/path/to/HapHiC/haphic pipeline asm.fa HiC.filtered.bam nchrs –threads 8 –processes 8

更多参数说明执行：haphic pipeline –help

流水线最终输出文件

提示

一键流程虽简便，但极少数场景下自动参数适配失败，会造成组装质量差或流程中断。出现该问题时，建议分步手动运行各模块、自定义参数，或使用下文快速预览模式。

分步运行完整流程

步骤 1：分群聚类 cluster

聚类前程序会完成预处理：拆分错误连接、过滤短片段 / 错误组装 contig、去除等位基因间 Hi-C 互作；随后采用 MCL 马尔可夫聚类算法将 contig 划分至不同染色体群。 区别于 LACHESIS、ALLHiC 使用的凝聚层次聚类（AHC，固定分群数量），MCL 依靠膨胀系数 inflation控制分群数量：数值越大，拆分出的群越多。 层次聚类的缺陷：即便预设染色体数量，不同染色体 contig 仍可能混入同一群，在分型二倍体 / 多倍体基因组中尤为常见。 HapHiC 会遍历一系列膨胀系数（由–min_inflation/–max_inflation/–inflation_step控制）完成聚类，结合输入预期染色体数nchrs与各群长度分布，自动推荐最优膨胀系数。

/path/to/HapHiC/haphic cluster asm.fa HiC.filtered.bam nchrs

参数详情查看：haphic cluster –help

核心输出文件

• corrected_asm.fa：纠错后组装序列（仅开启纠错时生成）
• corrected_ctgs.txt：所有被拆分纠错的 contig ID 清单
• full_links.pkl：二进制文件，存储全部 contig 两两间 Hi-C 互作计数
• HT_links.pkl：二进制文件，记录每条 contig 前后半段之间的互作数量
• paired_links.clm：记录成对 Hi-C reads 的位置信息文本
• inflation_*：不同膨胀系数对应的输出目录
  • group*.txt：每群 contig 基础信息（长度、酶切位点数量，对应 ALLHiC 的 counts_RE.txt）
  • mcl_inflation_*.clusters.txt：MCL 聚类分群结果

最优膨胀系数查看

日志文件HapHiC_cluster.log中会打印推荐值，示例： 2022-11-07 17:50:08 <HapHiC_cluster.py> [recommend_inflation] You could try inflation from 1.20 (length ratio = 0.75) 若程序无法输出最优系数，多为参数设置不当或组装错误过多；需核对参数，调整纠错、互作过滤、MCL 聚类相关参数，日志示例： 2022-11-19 13:20:38 <HapHiC_cluster.py> [recommend_inflation] It seems that some chromosomes were grouped together (length ratio = 0.5)…

步骤 2：重新分配 reassign

聚类步骤中部分 contig 会被过滤或分配至错误分群；同时 MCL 输出分群总数可能超过预设染色体数nchrs。本步骤用于回收无归属 contig、修正分群归属，必要时通过层次聚类合并相近分群。 输入文件：full_links.pkl、最优膨胀系数对应的mcl_inflation_x.clusters.txt、paired_links.clm（x 为最优膨胀系数）

/path/to/HapHiC/haphic reassign asm.fa full_links.pkl mcl_inflation_x.clusters.txt paired_links.clm –nclusters nchrs

提示：若已执行 contig 纠错，输入 FASTA 需替换为corrected_asm.fa。 参数详情查看：haphic reassign –help

核心输出文件

• final_groups/group*.txt：重分配后每群 contig 基础信息
• final_groups/final_cluster.txt：最终聚类分群总表
• split_clms/：分群独立 CLM 互作文件目录

步骤 3：排序定向 sort

整合 3D-DNA 与 ALLHiC 两套算法实现 contig 排序与方向校正：

/path/to/HapHiC/haphic sort asm.fa HT_links.pkl split_clms final_groups/group*.txt –processes 8

提示：若已执行 contig 纠错，输入 FASTA 需替换为corrected_asm.fa。 参数详情查看：haphic sort –help

核心输出文件

• group*.tour.sav：单群 contig 快速排序中间结果
• group*.tour：ALLHiC 优化后单群 contig 排布与方向
• final_tours/group*.tour：全部群最终 contig 排序定向结果

步骤 4：构建 scaffold build

依据group*.tour内染色体分群、排序、方向信息拼接伪染色体 scaffold；默认输出 scaffold 按序列长度降序排列。

场景 1：未开启 contig 纠错

/path/to/HapHiC/haphic build asm.fa asm.fa HiC.filtered.bam final_tours/group*.tour

场景 2：已开启 contig 纠错

首参数替换为纠错后序列corrected_asm.fa；必须通过–corrected_ctgs传入纠错 contig 清单，否则生成的 YaHS 规范 AGP 会出错。

/path/to/HapHiC/haphic build corrected_asm.fa asm.fa HiC.filtered.bam final_tours/group*.tour –corrected_ctgs corrected_ctgs.txt

提示：自 1.0.1 版本起，第二个原始基因组asm.fa与过滤 BAM 为必填，用于生成 Juicebox 可视化脚本。 参数详情查看：haphic build –help

核心输出文件

实测案例

仅 8 线程时，多数基因组可在 1 小时内完成挂载；contig 碎片化的大型基因组通常不超过半天。HapHiC 已在多类物种组装中验证有效，包括高等植物、人、鸟类、两栖类、鱼类、昆虫、软体动物、环节动物。完整案例与数据详见论文补充材料。

表格

结合 hifiasm 分型组装使用说明

若对 hifiasm 分型组装进行挂载，可直接传入 hifiasm 输出的 GFA 文件。 分型组装定义：通过家系分型 / Hi-C 分型算法得到的分相初级 contig（*.hap*.p_ctg.gfa）、分相 unitig（*.p_utg.gfa）。 HapHiC 会读取 GFA 内测序深度信息，聚类前过滤潜在压缩型 contig/unitig；传入多份 GFA 时，程序判定为不同单倍型文件，聚类时依据分型信息消除 / 削弱单倍型间 Hi-C 互作，避免不同单倍型 contig 混入同一染色体群。 注意：GFA 内序列 ID 必须与 FASTA 完全匹配，支持.gfa与noseq.gfa两种格式。

1. hifiasm 原始 unitig（*.p_utg.gfa）

仅利用 GFA 深度信息过滤压缩 unitig：

/path/to/HapHiC/haphic pipeline p_utg.fa HiC.filtered.bam nchrs –gfa p_utg.gfa

2. 多套分型初级 contig（*.hap*.p_ctg.gfa）

除深度过滤外，依据 GFA 分型信息去除单倍型间互作，默认完全清除，不同单倍型 contig 不会分至同一群：

/path/to/HapHiC/haphic pipeline allhaps.fa HiC.filtered.bam nchrs –gfa "hap1.p_ctg.gfa,hap2.p_ctg.gfa"

参数–phasing_weight

控制分型信息置信权重；设为 0 代表完全忽略分型结果；0~1 区间则同时兼顾 hifiasm 与 HapHiC 分型，允许少量跨单倍型分群：

/path/to/HapHiC/haphic pipeline allhaps.fa HiC.filtered.bam nchrs –gfa "hap1.p_ctg.gfa,hap2.p_ctg.gfa" –phasing_weight 0

提示

该功能非必需，可按需选用：

快速预览模式 quick_view

适用场景：

快速预览模式仅执行快速排序排布全部 contig，不做分群聚类，效果等同于 3D-DNA 输出的*.0.hic；大部分参数失效，但仍可使用–correct_nrounds执行 contig 纠错。搭配 hifiasm 分型 GFA 时，仍可依据文件区分单倍型 contig。

# nchrs可填任意整数，程序自动忽略
/path/to/HapHiC/haphic pipeline asm.fa HiC.filtered.bam nchrs –quick_view
# 预览模式同时开启contig纠错
/path/to/HapHiC/haphic pipeline asm.fa HiC.filtered.bam nchrs –quick_view –correct_nrounds 2
# 预览模式下区分不同单倍型
/path/to/HapHiC/haphic pipeline allhaps.fa HiC.filtered.bam nchrs –quick_view –gfa "hap1.p_ctg.gfa,hap2.p_ctg.gfa"

Juicebox 人工校正流程

提供两种生成 Juicebox 可视化.assembly与.hic文件的方案，推荐第二种。

方案 1：基于 SALSA 规范 scaffolds.agp（不推荐）

前置依赖

3D-DNA、matlock、Juicebox 配套脚本

操作步骤

/path/to/matlock bam2 juicer HiC.filtered.bam out.links.mnd
sort -k2,2 -k6,6 out.links.mnd > out.sorted.links.mnd

/path/to/juicebox_scripts/agp2assembly.py scaffolds.agp scaffolds.assembly

bash /path/to/3d-dna/visualize/run-assembly-visualizer.sh -p false scaffolds.assembly out.sorted.links.mnd

重大缺陷

若 HapHiC 拆分纠错了 contig，必须将 Hi-C reads 重新比对至corrected_asm.fa并重新过滤，不能使用原始 BAM；纠错后 contig ID 发生变更，原始 BAM 无对应互作信号，Juicebox 中无热图。

一键封装命令

/path/to/HapHiC/haphic juicer

校正后导出基因组

Juicebox 编辑保存scaffolds.review.assembly，执行脚本输出最终 FASTA：

/path/to/juicebox_scripts/juicebox_assembly_converter.py -a scaffolds.review.assembly -f asm.fa -s

方案 2：基于 YaHS 规范 scaffolds.raw.agp（官方推荐）

自 1.0.1 版本新增，无需重新比对 Hi-C 数据。该 AGP 不修改原始 contig ID，仅记录片段在原始序列内坐标，完全复用 YaHS 可视化流程。 完整挂载结束后，程序自动生成juicebox.sh可视化脚本；系统需提前安装 Java、samtools 并写入环境变量，使用 bash 执行（不可用 sh）：

bash juicebox.sh

版本更新说明

1.0.6 及以上版本无需手动在 Juicebox 设置缩放系数；导出的.review.assembly可被软件正常识别。 大型基因组需修改脚本内 Java 内存参数（如-Xmx64G及以上），避免内存溢出、提速绘图。

人工校正后导出最终基因组

Juicebox 编辑完成输出out_JBAT.review.assembly，搭配流程生成的坐标映射文件out_JBAT.liftover.agp，执行命令导出校正后基因组：

/path/to/HapHiC/utils/juicer post -o out_JBAT out_JBAT.review.assembly out_JBAT.liftover.agp asm.fa

自 HapHiC 1.0.2 版本起，软件新增haphic plot子命令，可生成高度自定义的 Hi-C 交互热图。该命令需要两个输入文件：过滤后的 BAM 文件HiC.filtered.bam、scaffold 组装 AGP 文件（AGP 内 contig ID 必须与 BAM 文件中的序列 ID 完全匹配）。

用法 1：可视化 HapHiC 原始挂载结果

/path/to/HapHiC/haphic plot scaffolds.raw.agp HiC.filtered.bam

用法 2：可视化 Juicebox 人工校正完成后的组装结果

/path/to/HapHiC/haphic plot out_JBAT.FINAL.agp HiC.filtered.bam

程序输出可视化交互热图文件contact_map.pdf。若 BAM 文件体积较大，绘图速度会偏慢，每 10GiB 的 BAM 文件约耗时数分钟。 运行结束后会生成二进制文件contact_matrix.pkl，后续绘图可直接使用该文件替代原始 BAM，绘图速度大幅提升（仅需约 1 分钟），方便反复微调热图样式相关参数：

# 复用之前生成的contact_matrix.pkl快速绘图
/path/to/HapHiC/haphic plot out_JBAT.FINAL.agp contact_matrix.pkl

重要注意事项

使用contact_matrix.pkl提速绘图时，本次输入的 AGP 文件、分箱参数–bin_size、最短序列过滤阈值–min_len、指定绘制 scaffold 列表–specified_scaffolds必须和初次生成矩阵时保持完全一致。

默认分箱大小为 500 Kbp，仅展示长度大于 1 Mbp 的 scaffold。可通过参数修改这两项设置：

# 设置分箱尺寸1 Mbp，仅展示长度大于5 Mbp的scaffold
/path/to/HapHiC/haphic plot out_JBAT.FINAL.agp HiC.filtered.bam –bin_size 1000 –min_len 5

额外可生成独立分染色体热图文件separate_plots.pdf，每条 scaffold 单独出图：

/path/to/HapHiC/haphic plot out_JBAT.FINAL.agp HiC.filtered.bam –separate_plots

如需修改热图配色方案、坐标原点、边框样式、标准化方法，可参考上文附图中的示例命令。

这套绘图工具不局限于 HapHiC 挂载结果，也能可视化其他 Hi-C 挂载软件的输出：仅需为染色体水平组装序列完成 Hi-C reads 比对、过滤得到 BAM 文件，并生成配套 AGP 文件。

# 脚本根据基因组FASTA生成配套空白AGP文件
/path/to/HapHiC/utils/mock_agp_file.py chr_asm.fa > chr_asm.agp
# 搭配BAM与AGP文件绘图
/path/to/HapHiC/haphic plot chr_asm.agp HiC.filtered.bam

基于参考基因组对完整 scaffold 排序定向

HapHiC 1.0.4 版本新增独立子命令haphic refsort，可依据近缘 / 本物种参考基因组，对全部 scaffold 整体重排、校正方向。

前置准备

使用 minimap2 将 ** 原始 contig（不可用 scaffold）** 比对至染色体水平参考基因组，生成 PAF 比对文件；参考基因组可以为本物种或近缘物种。

# 本物种高质量参考基因组，推荐预设参数asm20
minimap2 -x asm20 ref.fa asm.fa –secondary=no -t 28 -o asm_to_ref.paf
# 也兼容wfmash等其他比对软件
wfmash ref.fa asm.fa -m -n 1 -S 1 -t 28 | cut -f 1-6,8- > asm_to_ref.paf

基于生成的 PAF 文件，运行haphic refsort输出重排后的 AGP 文件，可选同步输出重排后的基因组 FASTA：

# 默认按参考基因组染色体ID字母顺序排列scaffold
haphic refsort 04.build/scaffolds.raw.agp asm_to_ref.paf > scaffolds.refsort.agp

# 手动指定参考染色体排序，逗号分隔、无空格
haphic refsort 04.build/scaffolds.raw.agp asm_to_ref.paf –ref_order "chr1,chr2,chr3,chr4,…" > scaffolds.refsort.agp

# 同步输出重排后的基因组FASTA（默认文件名scaffolds.refsort.fa）
haphic refsort 04.build/scaffolds.raw.agp asm_to_ref.paf –fasta asm.fa > scaffolds.refsort.agp

# 对Juicebox人工校正后的组装文件执行重排
haphic refsort out_JBAT.FINAL.agp asm_to_ref.paf > scaffolds.refsort.agp

输出的scaffolds.refsort.agp可直接用于 Juicebox 人工校正，也可输入haphic plot绘制热图。

重要提示

该功能并非基于参考基因组重新挂载 contig，不会拆分、修改现有 scaffold 内部结构，仅调整全部 scaffold 的整体排布顺序与方向，仅改变可视化展示形式。

自 HapHiC 1.0.7 版本（2025.10.23）起，重排后 AGP 与 FASTA 中的 scaffold ID 会统一重命名为原始ID:参考染色体:方向格式（示例：group4:chr2:-），直观记录原始 scaffold 与参考染色体的对应关系；添加–keep_original_ids参数可保留原始 scaffold 名称不变。

下文为同源四倍体甘蔗 Np-X 组装的实操示例。

常见问题解答（FAQs）

问题 1：挂载率过低该如何处理？

重分配（reassign）步骤有三个参数可调控挂载率：–min_RE_sites、–min_links、–min_link_density，默认值分别为 25、25、0.0001。但不同项目的 contig 连续性、Hi-C 测序深度存在差异，你可以查看01.cluster/inflation_*目录下所有*statistics.txt文件，调试这三个参数，从而提升挂载率。

针对小型基因组，聚类步骤默认参数–Nx 80、重分配步骤默认参数–min_group_len也会拉低挂载效率。解决方案：增大–Nx数值、降低–min_group_len；也可直接彻底关闭两项过滤功能，设置–Nx 100 –min_group_len 0。

问题 2：不清楚物种准确染色体数目，该如何运行 HapHiC？

可使用快速预览模式（quick view）。该模式会忽略nchrs染色体数量参数（可随意填写任意整数），仅对 contig 做排序定向、不执行分群聚类，效果类似 3D-DNA 输出的*.0.hic文件。 在 Juicebox 可视化热图后，可根据交互图谱统计实际染色体条数，再填入数值重新运行完整流水线；你也可以直接在 Juicebox 中手动拆分染色体、完成人工校正。

问题 3：聚类日志提示「部分染色体被合并为同一群」或「最大分群数量小于预期染色体数」如何解决？

该问题成因较复杂。HapHiC 会根据你输入的预期染色体数nchrs与各分群长度分布，自动推荐最优膨胀系数 inflation，出现该报错由多种因素导致：

问题反馈与 Bug 提交

Issue 反馈地址：https://github.com/zengxiaofei/HapHiC/issues 提问前请阅读：重要说明：提供完整信息能帮助开发者更快定位你的问题 配套知识库（基于 DeepSeek，需微信登录）已上线。

引用规范

若你的研究使用了 HapHiC 工具，请引用发表于《Nature Plants》的论文： Zeng Xiaofei, Yi Zili, Zhang Xingtan, Du Yuhui, Li Yu, Zhou Zhiqing, Chen Sijie, Zhao Huijie, Yang Sai, Wang Yibin, Chen Guoan. Chromosome-level scaffolding of haplotype-resolved assemblies using Hi-C data without reference genomes. Nature Plants, 10:1184-1200. DOI: https://doi.org/10.1038/s41477-024-01755-3

配套短讯简报（Research Briefing）： Zeng Xiaofei, Chen Guoan. Achieving de novo scaffolding of chromosome-level haplotypes using Hi-C data. Nature Plants, 2024, 10:1157-1158. DOI: https://doi.org/10.1038/s41477-024-01756-2

若你使用了工具内整合的 contig 排序定向优化模块，需同步引用 ALLHiC 原文： Zhang Xingtan, Zhang Shengcheng, Zhao Qian, Ray Ming, Tang Haibao. Assembly of allele-aware, chromosomal-scale autopolyploid genomes based on Hi-C data. Nature Plants, 2019, 5:833-845. DOI: https://doi.org/10.1038/s41477-019-0487-8