Puzzler: scalable one-command platinum-quality genome assembly from HiFi and Hi-C

Abstract

Motivation

Chromosome-level assemblies are essential for modern genomics, from comparative genomics and evolutionary studies to precision breeding. While integrated HiFi and Hi-C data now enable accurate chromosome-scale genome assemblies, the bioinformatic process remains complex and involves specialized tools and expertise. With large-scale pan-genomic efforts requiring dozens to hundreds of platinum quality chromosome-scale genomes, there is a need for scalable, portable, and user-friendly pipelines that streamline and standardize high-quality genome assembly workflows.

Results

We introduce Puzzler, a containerized, scalable pipeline for chromosome-scale de novo genome assembly using PacBio HiFi and Hi-C data. Designed for portability and minimal user input, Puzzler automates contig assembly, duplicate purging, Hi-C-based scaffolding, and chromosome assignment via synteny, even with highly diverged reference taxa. Optional modules generate input files for manual Hi-C curation or operate reference-free. Quality control is integrated and includes Hi-C contact maps, BUSCO, yak k-mer completeness, and BlobTools contamination screening. A checkpointing system ensures that previously completed tasks are not re-executed, while a simple sample sheet input structure supports scalable batch processing. Puzzler has been validated on genomes ranging from 24 Mbp to 6.5 Gbp, delivering highly contiguous assemblies with <10 min of user input, enabling high-throughput platinum-quality genome assembly.

Availability and implementation

Puzzler is released into the public domain under 17 U.S.C. §105. Source code, documentation, and tutorials are available at https://github.com/merondun/puzzler and archived on Zenodo: https://doi.org/10.5281/zenodo.15733730 and https://doi.org/10.5281/zenodo.15693025. Pre-configured runtime environments including dependencies are provided via both a Conda environment (https://anaconda.org/heritabilities/puzzler) and an Apptainer hosted both on Zenodo and Sylabs (https://cloud.sylabs.io/library/merondun/default/puzzler).

1 Introduction

High-quality, chromosome-level genome assemblies are instrumental across many areas of genomics. Accurate and contiguous assemblies are essential for investigating structural variation, evolutionary dynamics, and gene regulation (Rhie et al. 2021, Wright et al. 2024, Yoo et al. 2025). Moreover, pan-genomic approaches require dozens to hundreds of chromosome-scale assemblies (Liao et al. 2023, Secomandi et al. 2025). Advances in long-read sequencing, particularly PacBio high-fidelity (HiFi) reads with high accuracy, now enable construction of near-error-free gapless contigs. In parallel, Hi-C sequencing provides chromosome-scale contact information that facilitates scaffolding into chromosome-length assemblies. Together, these technologies can yield telomere-to-telomere assemblies and even phase haplotypes in diploid or polyploid organisms. Despite these advances, scalable and reproducible assembly remains a bottleneck. Some tools provide end-to-end tools for assembly, scaffolding, and quality control (Almeida et al. 2023, Larivière et al. 2024), while others address only isolated steps within the assembly workflow (Driguez et al. 2021, Angelova et al. 2022).

At present, building chromosome-scale genome assemblies typically requires pairing a long-read assembler with one or more Hi-C-based scaffolders (Rhie et al. 2021). Additional steps often include synteny-based labeling of chromosomes for comparative and pan-genomic applications (Liu et al. 2018). For small labs or users new to genome assembly, implementing best-practice workflows remains challenging, especially given that the final genome assembly is merely the starting point for downstream analyses (Jung et al. 2020). Scalability and reproducibility further compound the difficulty. Pan-genomic efforts benefit from standardized genome processing, necessitating pipelines that are both computationally efficient and easily portable across environments (Groza et al. 2024, Heumos et al. 2024). Existing workflows often rely on complex computing environments or manual curation, which hinder reproducibility and complicate scaling (Almeida et al. 2023, Larivière et al. 2024).

Fully automated, containerized pipelines that incorporate best practices are increasingly needed to streamline genome assembly and reduce the technical burden for non-specialist users. To address this need, we developed Puzzler: a simple, modular, checkpoint-based shell pipeline that automates de novo assembly, scaffolding, and quality control of PacBio HiFi and Hi-C data, with optional support for manual curation steps. With under 10 min of user input including manual curation, Puzzler produced chromosome-level assemblies with accuracy and contiguity comparable to published platinum-quality genomes from fungi to frogs, across a size range of 24 Mbp to 6.5 Gbp.

2 Methods and implementation

Puzzler runs from a single command configured by a sample sheet, with all dependencies containerized through Sylabs and Conda for portability. It performs genome assembly, scaffolding, chromosome renaming, and quality control, automatically skipping completed steps. All assembly steps were run using default or developer-recommended settings from tutorials, except for HapHiC, where an elevated --max_inflation parameter was applied to ensure sufficient search space for variable genomes. Puzzler is designed for chromosome-scale primary (collapsed) genome assembly using high-accuracy long-read sequencing data in combination with Hi-C chromatin contact maps for scaffolding (Fig. 1A). Puzzler begins with assembly of HiFi long reads into primary contigs using hifiasm v0.25.0-r726 (Cheng et al. 2021). Duplicate haplotigs are removed with purge_dups v1.2.6 using minimap2 v2.29 -r1283 (Li 2018, Guan et al. 2020); purging can be skipped with --no_purge. The resulting contigs are then scaffolded into chromosome-scale structures using HapHiC v1.0.6 (Zhang et al. 2019, Zeng et al. 2024), which leverages chromatin contact data from Hi-C libraries aligned with bwa-mem2 v2.21, filtered using samblaster v0.1.26 and samtools v1.21 (Faust and Hall 2014, Vasimuddin et al. 2019, Danecek et al. 2021). A priori expected chromosome number is used as a target for scaffolding. If HapHiC fails to produce an assembly within ±4 chromosomes of this target, the pipeline automatically invokes YAHS v1.2.2 as a fallback scaffolder (Zhou et al. 2023).

Figure 1.

Overview of the Puzzler pipeline and benchmarking inputs. (A) Simplified workflow from genome assembly through quality control, with optional duplication purging and manual curation steps. (B) Summary of assembly inputs showing reference contig N50 and allelic heterozygosity (points), alongside HiFi and Hi-C input coverage.

Following successful scaffolding, Puzzler runs Juicer v1.2 (Durand et al. 2016) to generate .hic and .assembly files for manual curation in Juicebox. Manual curation enables visual inspection and correction of scaffolding errors, such as misjoins or misplaced contigs, improving assembly accuracy (Howe et al. 2021). If a related species reference genome is provided, scaffolds are ordered using HapHiC’s refsort module (Zeng et al. 2024). This step reorders scaffolds to match the reference assembly but does not modify scaffold sequences and does not constitute reference-guided assembly. Puzzler is then re-executed with the resulting .review file to finalize the curated assembly. Alternatively, users can bypass manual curation entirely by specifying --no_juice, completing the entire Puzzler pipeline in a single command.

To assign chromosome labels, MashMap v3.1.3 (Kille et al. 2023) aligns scaffolds against the related species reference assembly, which is computationally efficient even for giga-base sized chromosomes. Alignments are parsed to assign chromosome names, assigning unlocalized fragmented scaffolds into labels such as “Chr1_unloc1”. Scaffold orientation is corrected by reverse-complementing scaffolds as needed with seqkit v2.10.0 (Shen et al. 2024). This reference-based chromosome naming has been internally validated across species diverged over 50 million years, including those with whole-genome duplications. While not strictly necessary for genome assembly, providing a chromosome-level reference with standardized chromosome labels improves interpretability of downstream analyses. This is especially useful in pan-genomic studies where consistent chromosomal labeling prevents misassignments and comparison errors.

Puzzler then proceeds to final quality control, including: (i) Hi-C contact map visualizations with HapHiC v1.0.6 (Zeng et al. 2024); (ii) k-mer-v0.1-r69 (Cheng et al. 2021); (iii) gene completeness via BUSCO v5.8.3 (Simão et al. 2015); and (iv) contamination screening with BlobTools v1.1.1 (Laetsch and Blaxter 2017) using blastn v2.16.0+ (Camacho et al. 2009) against NCBI’s nt RefSeq database. Assembly metrics such as contig and scaffold N50 are calculated with assembly_stats v0.1.2 (Trizna 2020), and a final summary report is generated providing key statistics on genome size, contiguity, completeness, and potential contamination. Because Puzzler uses a sample sheet input and is check-point based, assembly can be executed at scale, facilitating high-throughput genome assembly.

3 Results

We benchmarked Puzzler against 12 publicly available chromosome-scale eukaryotic genome assemblies generated from PacBio HiFi and Hi-C data, encompassing a wide taxonomic and genomic size spectrum (Table 1, available as supplementary data at Bioinformatics Advances online). All tests were conducted across three distinct HPC environments using Puzzler v1.9, tested using both Sylabs containers and Conda environments. Test species included a ∼24 Mbp fungal genome, a ∼533 Mbp plant genome, an ∼821 Mbp insect genome, and large vertebrate genomes, including a ∼3.4 Gbp whale and a ∼6.5 Gbp amphibian. All comparisons used assemblies constructed solely from HiFi and Hi-C reads, for which we used identical input files for Puzzler genome assembly (Table 2, available as supplementary data at Bioinformatics Advances online). Assemblies encompassed a range of HiFi input coverage (mean = 59.5×, range = 22.2–183.0×), mean HiFi read lengths (mean = 12.8 Kbp, range = 6.9–23.9 Kbp), and Hi-C input coverage (mean = 139×, range = 34.5–540.0×) (Fig. 1B). Only weak associations were observed between read inputs and assembly contiguity (maximum Pearson correlation = 0.43, Fig. 2, available as supplementary data at Bioinformatics Advances online).

Using 64 cores and 512 GB RAM, Puzzler demonstrated high computational efficiency across diverse genome sizes, with a mean assembly throughput of 1.8 Mbp/min (range = 0.5 –3.8) (Table 3, available as supplementary data at Bioinformatics Advances online). Excluding manual curation and BlobTools, runtimes spanned from 32 min for the fungal genome (24.8 Mbp), to 3 h and 38 min for the fly genome (817 Mbp), and 44 h and 19 min for an amphibian genome (6478 Mbp). Resource monitoring showed a mean peak CPU usage of 39 cores (range = 13–47) and mean RAM usage of 336 GB (range = 58–512), indicating diminishing returns above 48 CPUs (Table 4, available as supplementary data at Bioinformatics Advances online). Notably, all genomes smaller than 1.4 Gbp were successfully assembled using 16 CPUs and 128 GB of RAM, although this increased assembly time by nearly 1.5-fold (mean = 1.5×, range = 0.2–2.4×; Table 5, available as supplementary data at Bioinformatics Advances online). BlobTools substantially increases runtimes; fly genome (821 Mbp) screening with 48 cores against NCBI nt took an extra 24 h.

Puzzler generated high-quality, chromosome-scale assemblies across diverse taxa and genome sizes as evidenced by clear chromosome structures in the Hi-C contact maps (Fig. 1, available as supplementary data at Bioinformatics Advances online). For the 12 test species, assemblies generated with Puzzler–incorporating a manual curation step–exhibited a median contig N50 of 12.6 Mbp (range = 1.4–68.7 Mbp) and a scaffold N50 of 72.7 Mbp (range = 1.8–743.5 Mbp) (Fig. 2 and Table 6, available as supplementary data at Bioinformatics Advances online). The median BUSCO completeness score across all Puzzler assemblies was 98.6% (range = 93.8 –99.5%), slightly outperforming their corresponding published references (mean Δ = +0.2%, range = −0.3%–1.8%; Fig. 2 and Table 7, available as supplementary data at Bioinformatics Advances online). Similarly, scaffold N50 (mean Δ% = +5.2%, range = −1.1%–27.1%) was higher in Puzzler assemblies, although they also contained more sequences (150.9%, range = −78.3%–1361.9%). Overall, assembly sizes showed only minor deviations from the reference, with a median percent change of just 1.4% (range = −7.7%–8.3%; Fig. 2 and Table 8, available as supplementary data at Bioinformatics Advances online). We note that case-specific attention is needed for duplicate purging, as this step showed highly variable outcomes across the 12 assemblies tested (Fig. 4, available as supplementary data at Bioinformatics Advances online).

Figure 2.

Comparative metrics for Puzzler versus reference assemblies, with deltas showing relative differences (positive = higher in Puzzler, negative = higher in reference). Statistics for Puzzler assemblies are shown with and without manual curation.

Overall, performance was consistent across genomes of varying size and complexity, from a ∼24 Mbp fungal genome to a ∼6.5 Gbp amphibian genome, demonstrating that Puzzler scales effectively across a broad range of chromosomal structures. This holds across genomes with heterozygosity ranging from haploid Rhizosphaera kalkhoffii to over 2% in Ascidia mentula, highlighting Puzzler’s ability to handle both low-diversity and highly heterozygous assemblies (Table 9, available as supplementary data at Bioinformatics Advances online). Whole-genome alignments confirmed highly syntenic assemblies between Puzzler and published references, even when run in fully automated, uncurated mode using—no_juice (Fig. 3). Across all samples, Puzzler yielded 33 fully gapless chromosomes out of 220 total (15.0%), compared to 43 (19.5%) in the corresponding reference assemblies (Fig. 5, available as supplementary data at Bioinformatics Advances online). Notably, only three chromosomes were absent from the Puzzler assemblies (chromosomes 30–32 in the Eurasian Crane, lengths 1.7–2.1 Mbp). These chromosomes were recovered in the—no_juice assemblies without manual curation but appear to have been misjoined during juicer curation. This illustrates the complexity of manual curation (Fig. 3, available as supplementary data at Bioinformatics Advances online), where detailed scrutiny and iterative validation are essential to ensure that small, structurally complex chromosomes are correctly resolved.

Figure 3.

Whole-genome alignments between reference genomes and Puzzler draft assemblies generated with and without manual curation. Dotplots show synteny (reference on y-axis, Puzzler on x-axis; Mbp scale), assembly times reported for 64 cores and 512 GB RAM.

4 Conclusion

Our findings demonstrate that automated workflows are capable of matching, if not surpassing, the structural standards established by platinum-grade reference assemblies curated by expert bioinformatics teams. As chromosome-level assemblies become increasingly central to functional, ecological, and evolutionary genomics, Puzzler provides a scalable and reproducible solution for generating high-contiguity assemblies across large sample sets.

Puzzler is a containerized, end-to-end pipeline for de novo genome assembly and Hi-C scaffolding using long-read data. It automates best-practice workflows with a single command, combining contig assembly, scaffolding, and quality control into a reproducible and user-friendly framework. Designed for scalability and reproducibility, Puzzler supports genome sizes from fungi to frogs, generates Juicebox-compatible outputs for manual curation, and embeds checkpoints to prevent re-computation, facilitating integration into large assembly projects and pan-genomic efforts.

Supplementary material

Supplementary material is available at Bioinformatics Advances online.

Conflicts of interest

None declared.

Funding

This work was supported by National Institute of Food and Agriculture (NIFA)—Specialty Crop Research Initiative (SCRI) [2022-51181-38241 to Q.Y.].

Data availability

Videos detailing manual curation available at: https://www.youtube.com/watch?v=rMUiNqZwEpA.