RagTag: reference guided scaffolding for genome assemblies

Four tasks, all of them using a reference

RagTag is a collection of software tools for scaffolding and improving modern genome assemblies, and the readme lists the tasks it covers.

Homology-based misassembly correction. Homology-based assembly scaffolding and patching. Scaffold merging. And RagTag also provides command line utilities for working with common genome assembly file formats.

Every one of those tasks is homology based, and that is the single fact that defines the tool. RagTag does not assemble a genome from reads. It takes a draft assembly you already have and a reference assembly that is related to it, and uses the shared sequence between the two to improve the draft. The reference is the source of the large-scale structure, the chromosomes and their order, and the draft is the source of the contig sequence.

That is the standard situation in a genome sequencing project. You may have a long-read or hybrid assembly that is accurate at the contig level but fragmented, and you may have a related species with a published chromosome-level assembly, and you want to borrow the latter's scaffolding to order the former's contigs. RagTag exists for exactly that transfer.

The four tasks are the stages of that transfer, and they are not independent. Correcting misassemblies is a prerequisite for scaffolding, because a misassembled contig will be placed wrongly or not at all. Scaffold merging combines the outputs of several scaffolding runs into one. Patching fills the gaps in a target using sequences taken from a query, which is a slightly different operation from scaffolding and is the step that turns gaps into sequence.

The project is MIT licensed, the author is Michael Alonge, and the recent releases are v2.1.1 from 2026-10-01, v2.1.0 from 2021-10-31 and v2.0.1 from 2021-05-30, with the last push on 2026-10-01.

The command line, and the order the steps run in

The getting started section is a single block of shell commands, and reading them in order tells you how the tool is meant to be used.

# install with conda
conda install -c bioconda ragtag

# correct a query assembly
ragtag.py correct ref.fasta query.fasta

# scaffold a query assembly
ragtag.py scaffold ref.fasta query.fasta

# scaffold with multiple references/maps
ragtag.py scaffold -o out_1 ref1.fasta query.fasta
ragtag.py scaffold -o out_2 ref2.fasta query.fasta
ragtag.py merge query.fasta out_*/*.agp other.map.agp

# use Hi-C to resolve conflicts
ragtag.py merge -b hic.bam query.fasta out_*/*.agp other.map.agp

# make joins and fill gaps in target.fa using sequences from query.fa
ragtag.py patch target.fa query.fa

The pattern is visible. The first argument is always the subcommand and the rest are files, with the reference first and the query second. The output directory is given with -o, and the merge command then takes the query, a glob of the per-reference AGP files, and another map.

The multi-reference case is the interesting one. You scaffold the same query against two different references, each into its own output directory, and then merge the two AGP maps into one consensus scaffold. That is how you handle a reference that is close but not identical to your organism, which is the normal case when you are working across strains or breeds.

The Hi-C line is the conflict resolution step. When two references disagree about where a contig belongs, the -b option brings in a Hi-C alignment file, and the merge uses the chromatin contact data to break the tie. That is a genuinely better source of truth than either reference, because it comes from the sample itself.

And the last command is patch, which makes joins and fills gaps in the target using sequences from the query. So RagTag does not only reorder your contigs, it can also close the gaps between them with the sequence that the reference tells you belongs there.

Note that the tool is invoked as ragtag.py with the extension, which is the older convention but is what the script is called.

Dependencies, and the aligner you choose

The dependency list is where the practical friction is.

The alignment stage needs one of three programs: Minimap2, Unimap, or Nucmer. The choice is yours, and it is a meaningful one, because these are different algorithms with different sensitivities and speeds, and RagTag is designed to work with whichever you prefer or whichever is already in your pipeline.

The Python side is Python 3 with four packages that are auto-installed: numpy, intervaltree, pysam and networkx. The setup module confirms the same four as install_requires, and they are the same set the readme lists, so the documentation and the packaging agree.

Each of those earns its place in a way that reflects what RagTag does. intervaltree is for interval queries over the reference, which is how it finds where a contig's alignment falls. pysam is the Python binding for SAM files, which is how the Hi-C alignments are read. networkx is a graph library, and scaffolding is fundamentally a graph problem where you have contigs as nodes and homology relationships as edges. numpy does the numeric work.

The install_requires list in the setup module is the four packages and nothing else, and the Python floor is 3.6. The scripts are picked up with a glob over the top level for files matching the pattern, which is how the many small command line utilities in the repository root become console entry points.

The primary installation route is Bioconda, with conda install -c bioconda ragtag, and there is also a Zenodo DOI for the release, which is the convention in the bioinformatics world for citing a specific software version permanently.

One thing to plan for is the version gap. The releases jump from v2.1.0 in October 2021 to v2.1.1 in October 2026, so five years of development sit behind a patch version number. The changelog is the place to find out what changed.

What is in the repository, and the utilities around the main tool

The repository is mostly a collection of small scripts at the top level, and the naming tells you what the toolkit covers.

There is ragtag.py, which is the entry point that dispatches the subcommands. Alongside it sit the subcommand implementations as separate modules: ragtag_correct.py, ragtag_scaffold.py, ragtag_patch.py and ragtag_merge.py.

Then there is a set of format utilities that are not the headline features but are what you need to use the results. ragtag_agp2fa.py converts an AGP map into a FASTA file, and ragtag_agpcheck.py checks an AGP file. ragtag_create_links.py and ragtag_splitasm.py deal with the structure of the assembly, creating symlinks and splitting it. ragtag_break_query.py breaks a query assembly into pieces, and ragtag_splitasm.py is its counterpart. ragtag_paf2delta.py and ragtag_delta2paf.py convert between PAF and delta formats, which is the alignment interchange format the aligners use. ragtag_asmstats.py and ragtag_stats.py report statistics on an assembly. ragtag_rename.py renames things, and ragtag_update_gff.py updates a GFF annotation against a new assembly.

That last group is the interesting part for an evaluation. Scaffolding produces a new contig naming and a new coordinate system, and every downstream annotation file you have becomes wrong. The utilities around it are the recognition that scaffolding is not just producing a better assembly but invalidating everything that referenced the old one.

The ragtag_utilities directory holds the shared code, and it is the only package installed by the setup module, with a package_dir mapping to the directory. The version is not read from a file but computed at build time by a helper called get_ragtag_version, with the first element stripped, which is the usual arrangement for reading a version out of a git tag or a compile time constant.

The tests directory sits at the root, and the project carries a Zenodo DOI badge, a release badge and a Bioconda download badge, which is the standard trio for a bioinformatics tool.

Where RagTag sits against its predecessor and its inspirations

The readme's citation section says RagTag supersedes RaGOO, and it cites both papers.

The RagTag paper is Alonge and colleagues, Automated assembly scaffolding elevates a new tomato system for high-throughput genome editing, published in Genome Biology in 2022. That title is worth reading carefully, because it explains the domain in a sentence. The system described is a tomato genome, and the point of the work is high-throughput genome editing, which means the output of the scaffolding is not a publication artefact but something a plant breeder uses to find and modify genes. The stakes of a misassembled contig are a wasted edit.

The RaGOO paper is Alonge and colleagues, RaGOO: fast and accurate reference-guided scaffolding of draft genomes, in Genome Biology 20.1 in 2019.

The acknowledgements section names the people behind the improvements, and it is unusually specific about the borrowing. Aleksey Zimin, lead developer of the MaSuRCA assembler, provided many of the major algorithmic improvements relative to RaGOO's first release. Luca Venturini suggested and initially implemented many feature enhancements, such as the pysam integration. RagTag merge was inspired by CAMSA, and its developer Sergey Aganezov helped review relevant RagTag code. RagTag patch was inspired by Grafter, a scaffolding tool by Melanie Kirsche, who also provided guidance for the RagTag implementation. And Michael Schatz has provided guidance for the whole project.

So the merge and patch subcommands are not original inventions but adapted from other tools, and the readme says so. That is good practice rather than a weakness, and it tells you something about the design: the merge step exists because a merge algorithm from a different project was a better fit than the one RaGOO had, and the patch step exists because a dedicated tool for it did the job.

For a team choosing between tools, the practical question is what you already have in the pipeline. If you are coming from RaGOO, RagTag is the same shape of tool with more capability and a documented successor relationship. If you are choosing between reference guided scaffolders in general, the citation trail tells you which algorithms each one is built on.

Editorial conclusion

Adopt RagTag if you have a draft assembly and a related reference and you want the reference's chromosome structure imposed on the draft, which is the standard route to a contig-level genome. Do not adopt it as a de novo assembler, because it is a post-processor that needs an existing assembly and a reference, and note that the version numbers have a gap, with v2.1.0 in 2021 and v2.1.1 in 2026, so check the changelog for what changed in the intervening years. Before you commit, install through Bioconda so the aligner dependencies resolve, and run correct before scaffold, since the order of the two changes the result substantially.

Frequently asked questions

Official sources

1. Issues
2. License: MIT
3. malonge/RagTag on GitHub
4. README
5. Releases