pggb: turning a set of genomes into a pangenome variation graph

A graph as a multiple sequence alignment

pggb builds pangenome variation graphs from a set of input sequences, and the README explains the concept in one clean sentence: a pangenome variation graph is a kind of generic multiple sequence alignment. It lets us understand any kind of sequence variation between a collection of genomes, showing similarity where genomes walk through the same parts of the graph and differences where they do not.

That framing is the whole point of the tool. A conventional multiple sequence alignment is a table with one row per sequence and columns for positions, and building one across many genomes is notoriously difficult to design, which the README says is exactly the problem pggb aims to reduce. A graph relaxes the column model. Paths through the graph carry the sequences, so an insertion in one genome is a branch rather than a shifted column that pushes everything downstream out of alignment.

The audience is a genomics team working with many genomes at once, typically haplotype-resolved assemblies. The README says pggb has been tested at scale in the Human Pangenome Reference Consortium as a method to build a graph from the draft human pangenome, and it points to the Nature Methods paper for the method, with the full author list and the citation given in the README itself. Documentation lives at pggb.readthedocs.io.

So this is research-grade infrastructure with a peer-reviewed pedigree, packaged so that a lab can run it as one command rather than writing a pipeline.

Five tools under one command

The mechanism is visible in the README because the pipeline is described as a sequence of named stages, each performed by a tool that is maintained elsewhere.

The graph is generated using an all-to-all alignment of the input sequences with wfmash, then graph induction with seqwish, then progressive normalization with smoothxg and gfaffix. After construction, pggb generates diagnostic visualizations of the graph with odgi. A variant call report in VCF, representing both small and large variants, can be generated based on any reference genome included in the graph, using vg.

The stages matter because each one solves a different problem. Alignment finds where the genomes match. Induction turns a set of alignments into a graph. Normalization makes the graph compact and consistent so that the same sequence is not represented in several equivalent ways. Visualization exists so a human can check the result rather than trust it.

The output format is GFAv1, and the README stresses that this is what makes the result usable: the file can be taken as input by numerous genome graph and pangenome tools, such as the vg and odgi toolkits. In other words, pggb is not a closed system. Its deliverable is a standard file that other software can consume.

The repository layout is thin, which is consistent with that design. The top-level entries are the pggb and partition-before-pggb executables, a Dockerfile, docs/, data/, scripts/ and logo/. The primary language of the project is Shell, and the pipeline logic is orchestration rather than new algorithms.

The quick start command and what each flag does

The documented first run starts with data preparation rather than with the tool. You put your sequences in one FASTA file called in.fa, optionally compress it with bgzip, and index it with samtools faidx. If you have many samples or haplotypes, the README recommends the PanSN prefix naming pattern.

Then the build, which for a file with 9 haplotypes, 16 threads, 5kb matches and 90 percent identity looks like this:

pggb -i in.fa \       # input file in FASTA format
     -o output \      # output directory
     -n 9 \           # number of haplotypes (optional with PanSN-spec)
     -t 16 \          # number of threads
     -p 90 \          # minimum average nucleotide identity for segments
     -s 5k \          # segment length for scaffolding the graph
     -V 'ref:1000'    # make a VCF against "ref" decomposing variants <= 1000bp

The comments in that example are more informative than a parameter table, because they tell you the intent of each flag. The -n flag is optional when the PanSN naming pattern is used, since the haplotype count can then be derived from the names.

Where the results land is also documented. The final output matches outdir/in.fa.*final.gfa, and by default the tool renders 1D and 2D visualizations of the graph with odgi, which the README calls very useful to understand the result of the build. The -V flag asks for a VCF against a named reference, decomposing variants up to a given length, which is how you get a variant call report out of a graph that has no single reference of its own.

Installation is a menu rather than a single path: Docker, Singularity, bioconda, guix, or manually building its dependencies. The full documentation and a step-by-step example are linked from the README.

Partitioning whole-genome assemblies before the build

One step in the quick start is marked optional and deserves its own section, because for human-scale data it is the difference between a workable run and an impossible one.

The README says that if you have whole-genome assemblies, you might consider partitioning your sequences into communities, which usually correspond to the different chromosomes of the genomes, and then run pggb on each community independently.

The tool for that is the partition-before-pggb executable, which takes the same shape of arguments:

partition-before-pggb -i in.fa \       # input file in FASTA format
                      -o output \      # output directory
                      -n 9 \           # number of haplotypes (optional with PanSN-spec)
                      -t 16 \          # number of threads
                      -p 90 \          # minimum average nucleotide identity for segments
                      -s 5k \          # segment length for scaffolding the graph
                      -V 'ref:1000'    # make a VCF against "ref" decomposing variants <= 1000bp

What it produces is not a graph. It generates the command lines to run pggb on each community independently, two in the example given, one per chromosome group, and each command carries the full parameter set expanded into the many individual flags. That output is the point: it lets you run the communities in parallel, on separate machines if necessary, and then assemble the pieces.

The trade-off is that you lose the cross-chromosome structure of the graph. A pangenome graph built per chromosome is not the same object as a single whole-genome graph, and the README points to a sequence partitioning tutorial for the details of how communities are derived.

Two things to note. The partition step writes into the output directory with a hash suffix in the file names, so the input and the partition output share a base name, and the README warns in the run section that repeated setup invocations can overwrite configuration and leave data behind, which is the kind of detail that matters when you are iterating on a large run.

Segment length and identity threshold decide the shape of the graph

The README names the two parameters that define the overall structure of the output graph, and it explains them with enough precision to be useful.

Segment length, set with -s, defines the seed length used by the MashMap3 homology mapper in wfmash. Pairwise identity, set with -p, is the minimum allowed pairwise identity between seeds, and it is estimated using a mash-type approximation based on k-mer Jaccard.

The relationship between the two is what matters in practice. A longer seed finds fewer, longer matches, which keeps the graph from fragmenting on short or noisy similarity. The identity threshold decides which candidate matches are considered homologous at all, and raising it makes the graph stricter, dropping diverged sequence, while lowering it keeps more divergent sequence and produces a busier graph.

The default example uses 5kb segments at 90 percent identity, which is a human-scale setting, and the partitioning example expands the same idea into many more flags, including -l 25000, -K 19, -F 0.001, -k 19, -f 0, -B 10000000, -H 9, -j 0, -e 0, -G 700,1100, -P 1,19,39,3,81,1, -O 0.001, -d 100 and a Consensus_ prefix.

That expansion is informative in itself. It shows that the tool exposes a long list of knobs for the alignment, smoothing and consensus stages, and it shows that the sensible values differ between a quick illustrative run and a careful one. The README does not document each of those flags, so the practical reference is the readthedocs documentation rather than the README.

The container image is a toolchain, not an application

The Dockerfile shows what pggb actually is to deploy: a collection of dependencies plus an orchestration script.

The base is debian:bookworm-slim, and the image carries labels for the authors, the software, the homepage and the licence, with about.license set to SPDX:MIT. The apt install list is long and revealing. It includes the compiler and build tooling (cmake, make, g++-11, build-essential, pkg-config), the Python pieces (python3-dev, python3-pip, python3-venv, pybind11-dev), the sequence libraries (libhts-dev, libbz2-dev, zlib1g-dev, libzstd-dev, libgsl-dev), the command line tools a genomics user expects (samtools, tabix, pigz, bc, parallel, wget, curl, unzip), and some that reveal what the pipeline draws (libcairo2-dev for plotting, gnuplot, r-base).

Even bcftools is built from source in the image rather than installed from the distribution, pinned to the 1.19 release tarball.

That dependency surface is the honest cost of this tool. pggb itself is a script, but the software it drives has its own build requirements, and pinning them means the image is large and the build is slow. For a laboratory or pipeline environment that is a fair trade, because the container removes a genuinely painful class of problem, which is getting wfmash, seqwish, smoothxg, gfaffix, odgi and vg to agree with each other on a hundred transitive dependencies.

For a workstation, the bioconda route in the README is the lighter option, and the guix and Singularity routes cover the environments that prefer them.

Where pggb is the wrong tool

Three cases stand out.

The first is a small input. The defaults, the 5kb segment length, the 90 percent identity threshold, the 19-mer k-mer settings and the partitioning step all exist because the intended scale is many human genomes. Handing the pipeline three bacterial contigs to produce a graph of them is using a sledgehammer, and the tool that fits that job is the underlying toolkit used directly, where you would call the graph operations you actually want rather than a fixed pipeline that also aligns, induces, normalizes, visualizes and calls variants.

The second is the need for control at each stage. pggb fixes the pipeline order and its defaults. If you want a different alignment strategy, a different normalization, or a graph built from an alignment you already have, the value of the orchestration disappears and you are back to calling the tools yourself. The README's own parameter list shows the tension: the pipeline is expressive but the expression is in flags, not in a script you can edit.

The third is a linear reference workflow. If your goal is to call variants against one reference genome, a graph is not required, and the reference-based route gives you a smaller, more conventional data set that the rest of your ecosystem already understands.

The scale constraint deserves one more word, because the README does not state memory or disk requirements anywhere. What it does state is that the tool has been tested at scale in the Human Pangenome Reference Consortium and that you should partition whole-genome assemblies into communities. That recommendation is the signal: plan for a partitioned, parallel run rather than a single monolithic build.

Editorial conclusion

pggb fits a genomics team that already holds multiple haplotype-resolved assemblies and needs a single reference-free graph of them, plus the visual diagnostics to interpret it, without wiring five tools together by hand. It does not fit a project with a handful of contigs, a workflow that needs control of each stage of graph construction, or an environment that cannot host the large dependency stack its Dockerfile installs. Verify first that your FASTA is indexed with samtools faidx and follows the PanSN prefix naming pattern, that you have chosen a -p identity threshold and -s segment length that suit your species, and that the partitions produced by partition-before-pggb correspond to the chromosomes you expect before you run the whole pipeline on a full data set.

Frequently asked questions

Official sources

1. License: MIT
2. pangenome/pggb on GitHub
3. Project website
4. README
5. Releases