Cactus: reference-free whole-genome alignment built on cactus graphs

Reference-free means the graph is the primary output, not a side effect

Cactus is a reference-free whole-genome alignment program, as well as a pangenome graph construction toolkit. Both halves are in that one sentence, and the first half is the unusual part.

Most genome alignment still involves a reference. You pick a reference sequence, align every other genome to it, and the result is a set of coordinates in that reference's frame. Reference-free alignment removes the reference from the centre of the model. The project description puts the tool as the official home of a genome aligner based upon the notion of Cactus graphs, and the alignment documentation is the Progressive Cactus document, with a request to cite the Progressive Cactus paper when using Cactus.

The reason a graph is the natural output rather than a converted afterthought is structural. In a reference-free model, the shared structure between genomes is the alignment itself, and that structure is not linear. It branches. A region present in one genome and absent in another is a branch, and there is no single coordinate system that expresses it. A cactus graph is the structure that does express it, and Cactus computes it directly.

The audience is comparative genomists and pangenome researchers, in particular the groups working on the Human Pangenome style projects where aligning many large genomes and then building a graph over them is the whole point. The project also has a second mode, the Minigraph-Cactus pangenome pipeline, for aligning genomes from the same species and building pangenome graphs, with its own paper to cite.

It also ships a set of HAL tools, for which there is a separate paper to cite.

Two pipelines, two papers, two kinds of question

The documentation splits the work by the biological question rather than by feature, and the split is worth understanding because the two pipelines share the engine but not the goal.

For genomes from different species, the Progressive Cactus documentation applies. The paper to cite is the Progressive Cactus paper, and the readme also points to descriptions of the core algorithms, one on the algorithm itself and one on an earlier formulation of the same idea.

For genomes from the same species, and for building pangenome graphs, the Minigraph-Cactus Pangenome Pipeline documentation applies, with the Minigraph-Cactus paper to cite. This is the pipeline that assembles a pangenome across many individuals of one species.

The HAL tools have their own citation request, which is the bioinformatics paper on the HAL alignment method.

Cactus also depends on LastZ, a separate pairwise aligner, and the readme is explicit that the HAL tools should be cited when you use them. This is a nice property of the project for a scientific tool. When a tool chain this size is assembled from a dozen other people's algorithms, the risk is that a result gets used without the right attribution, and Cactus handles that by listing the required citations next to the tool that needs them rather than burying them in a paper.

There is also a practical warning about one specific tool: Bob Harris is credited with providing endless support for LastZ, the pairwise, blast-like genome alignment tool, which tells you that the lastz component is load bearing and not a casual dependency.

Taking the binaries instead of compiling the world

The project is refreshingly direct about who should build it. Everyone else should try to use the precompiled binaries (Linux X86) or Docker image from the latest release, and the manual source instructions are described as meant primarily for developers.

That framing is justified by what the source build actually involves. Cactus contains many submodules, so it is necessary to clone with --recursive or to run git submodule update --init --recursive inside the cactus directory after cloning:

git clone https://github.com/ComparativeGenomicsToolkit/cactus.git --recursive

The Makefile shows the scale of it. The submodule list runs to sonLib, cPecan, hal, matchingAndOrdering, pinchesAndCacti, abPOA, lastz, paffy, red, collapse-bubble, FASTGA, FASTAN, alntools and pgrealign, with minipoa added conditionally and cactus2hal in a second pass because it depends on both cactus and sonLib. The modules built on top of those are api, setup, caf, bar, hal, reference, pipeline and preprocessor.

So a source build is not a single library compile. It is a coordinated build of about fifteen third-party bioinformatics tools, each of which has its own configuration, and the sequencing of that build is the interesting part.

The dependency list in setup.py explains what the Python side pulls in. sonLib and pgrealign are installed from the local submodule paths, and the rest are decorator, networkx with a version constraint excluding 2.8.1, pytest, biopython and pysam. The python_requires is >=3.10, and the package is marked not zip_safe because it uses the __file__ attribute.

The tree also carries api, bar, caf, hal, preprocessor, pipeline and reference directories, which correspond to the components the pipelines are assembled from, along with build-tools, submodules, examples, test, a Dockerfile, Dockerfile.ci-base, Dockerfile.kegalign, a Makefile and include.mk.

The Python front end is the interface, the binaries are the engine

The architecture has one idea that explains most of the design, and it is stated in the install instructions.

The top-level cactus interface, which is cactus, cactus-pangenome, cactus-hal2maf, cactus-phast and the rest, is always a Python package that is pip installed into a Python virtualenv. This package runs several other tools as subprocesses, which are compiled into binaries.

That is a two-layer system, and the consequences are practical. The entry points declared in setup.py are console scripts, one per command, each mapping to a module in the cactus package, so the user-facing surface is Python and the working surface is compiled tools invoked as subprocesses.

Building the Python side means creating a virtualenv and pointing it at the right directories, and the documented sequence does that with three environment variables appended to the activate script: PATH so the compiled binaries are found, PYTHONPATH so the Python package is found, and LD_LIBRARY_PATH so the compiled libraries are found. Then the package and its requirements are installed:

python3 -m pip install -U setuptools pip wheel
python3 -m pip install -U .
python3 -m pip install -U -r ./toil-requirement.txt

The toil-requirement.txt file is a clue about what the pipeline is built on. Toil is a workflow management system, and its presence means the alignment is not a straight-line program but a staged pipeline with job dependencies, which is how you make a multi-genome alignment survive the failure of one stage.

The setup.py script also does something that looks odd until you read it. It deletes src/cactus/shared/version.py if it exists, and deletes a readme.md under the updating-alignment source, then runs git rev-parse HEAD and writes the commit hash into the version file as cactus_commit. The package version therefore records the exact commit it was built from, which is the right thing to do for a tool whose output depends on the alignment code underneath.

Cactus requires Python >= 3.10 along with Python development headers and libraries.

Docker and Singularity, and the version compatibility trap

There is a third route that sits between the binaries and a source build, and it has a specific catch.

If you have Docker installed, you can now run Cactus, and all binaries, such as lastz and cactus-consolidated, will be run via Docker using the latest release. By default, cactus will use the image corresponding to the latest release when running docker binaries, which is usually okay, but can be overridden with the CACTUS_DOCKER_ORG environment variable.

That default is worth thinking about for a research tool. A Docker image that follows the latest release means two runs a month apart are not necessarily the same code, and an alignment that is reproducible needs the version pinned. The override is one environment variable, and the documentation points at it, but the default is the moving one.

The Singularity alternative is where the sharp edge is. Singularity binaries can be used in place of docker binaries with the --binariesMode singularity flag, and you must use Singularity 2.3 to 2.6 or Singularity 3.1.0 or later. Singularity 3 versions below 3.1.0 are incompatible with cactus, with two issue links given. That is a precise and unfriendly constraint, since Singularity 3.0 exists and is exactly the range that does not work.

The Dockerfile shows the build in detail and contains a portability decision worth noting. It starts from a quay.io ubuntu 22.04 builder image, installs a long apt list including hts, boost, jemalloc, libdeflate, zstd and lz4, copies the tree in, and then sets two environment variables that override defaults. ENV avx2 1 exists because abpoa should not build with -march=native but with something more portable, and there is a comment explaining the compromise, since sse41 would be more portable but leads to segfaults in rare cases, with a link to the upstream issue. ENV CACTUS_PORTABLE_BUILD 1 pins include.mk's portable baseline explicitly rather than relying on it being the default.

The image also downloads Phast to enable halPhyloP compilation, and the UCSC browser libraries to compile UDC remote access.

Where Cactus is the wrong tool

There are cases where reaching for Cactus adds work without answering your question.

The first is if you want a plain pairwise alignment between two genomes. That is what LastZ is for, and the readme credits Bob Harris with providing endless support for the pairwise, blast-like genome alignment tool. Cactus is a framework that happens to use it. If your question is a two-genome comparison, a pairwise aligner is the right size of tool, and Cactus is a large amount of machinery around it.

The second is if you are working within a single individual. Cactus is for comparing genomes across individuals and across species, and building graphs over those comparisons. A single human reference, or a single individual's variants against that reference, is a different problem with different tools.

The third is the operational profile. This is a tool that aligns large genomes and builds graphs over them, which means it wants memory, and the Docker and Singularity paths add a container runtime dependency to a pipeline that already depends on a workflow manager. If your compute environment is already awkward, this makes it more awkward. The examples directory is a good indication of scale, with files such as 10way-mhc.txt, evolverMammals.txt, evolverPrimates.txt and yeastPangenome.txt describing real multi-genome runs.

The fourth is the version pinning problem again, from the research angle. Because the Docker default follows the latest release, and because the source build records only a commit hash rather than a tagged release, keeping a result reproducible means doing the pinning work yourself. That is a few minutes of configuration, but it is work the tool does not do for you.

And the fifth is the licence and the build. The repository is recorded as a custom licence that GitHub cannot classify, with the terms in the LICENSE.txt file, and a source build means compiling a dozen vendored third-party tools whose own licences and build requirements you inherit. For a commercial pipeline that is a compliance conversation, not a formality. The repository is not archived and the last push was on 2026-10-19, with v3.2.0 on 2026-05-06, v3.2.1 on 2026-05-20 and v3.3.0 on 2026-08-11.

The tool chain behind the tool

The acknowledgements section is unusually long, and reading it explains a lot about what Cactus actually is.

Cactus uses many different algorithms and individual code contributions, principally from Joel Armstrong, Glenn Hickey, Mark Diekhans and Benedict Paten. Beyond those, the credits list a chain of tools that are used inside the pipeline.

There is the 3-edge connected components program code from Yung H. Tsin and Nima Norouzi, described as crucial in constructing the cactus graph structure, with the citation to their Theory of Computing Systems paper. There is KegAlign, the GPU-accelerated version of LastZ, and the repository carries a Dockerfile.kegalign to match. There is abPOA for partial order alignment, and minipoa as an optional alternative base aligner in BAR, with a recent paper for the latter.

The rest is a set of tools that most people would consider separate projects: minigraph, minimap2, gfatools and dna-rnn from Heng Li, GFAffix from Dany Doerr, used to optionally clean pangenome graphs, the vg team for vg, used to process pangenome graphs, Mash, odgi for the graph handling, RED, and vcfwave from Erik Garrison and co-authors, plus merge_duplicates as a vcf cleanup script from Han Cao, and panacus for optional pangenome coverage and growth statistics, reachable through the cactus-graphmap-join command.

The last group is the alignment engines themselves: FastGA, FasTAN and alntools from Gene Myers, Richard Durbin and Chenxi Zhou.

What this list makes clear is that Cactus is a coordinating framework. It is not one algorithm but an orchestration of a dozen specialised ones, and the value of the project is in choosing the right combination for a given alignment, keeping the interfaces between them consistent, and producing a graph at the end. It also means the citation burden is distributed, and the readme asks for each of these to be cited when its output is used, including odgi and panacus specifically.

The three papers on the core algorithms are linked alongside the tool list, which is a good sign of a project that expects its output to appear in print.

Editorial conclusion

Adopt Cactus if you are aligning genomes across species or building pangenome graphs and want a reference-free method that produces a graph rather than a coordinate-based alignment. Skip it if you need a same-species multiple alignment of a single individual or you need the pairwise LastZ aligner on its own, since the project points to a separate pipeline for that. Verify first that the release artefact you install matches the documentation version you are reading, that the machine has the memory the alignment needs, and that your other tools can consume the output formats the graph pipeline produces.

Frequently asked questions

Official sources

1. ComparativeGenomicsToolkit/cactus on GitHub
2. Issues
3. README
4. Releases