AGAT: fixing and standardising messy GTF and GFF annotations

The problem: annotations arrive in every shape

AGAT is a suite of tools to handle gene annotations in any GTF or GFF format, and the name is a play on the Gtf and Gff acronyms, Another Gtf or Gff Analysis Toolkit, from the National Bioinformatics Infrastructure in Sweden.

The premise is that annotation files in the wild are inconsistent. They come from different pipelines, different releases and different conventions, and they carry different levels of completeness. A file might have exons and coding sequences but no gene or messenger RNA records, might have identifiers that clash, might have features for the same transcript scattered in different places, or might contain the same feature twice.

The toolkit's answer is to check, fix and pad the missing information of any kind of GTF or GFF to create complete, sorted and standardised GFF3. The claim in the project notes is that comparing to other methods, AGAT holds up against even the most awkward files, which is a claim about tolerance of malformed input rather than about performance.

Underneath, it is a Perl distribution with a set of command line scripts, and the tools are grouped by a naming convention: scripts with the sp prefix handle single files, scripts with the convert prefix handle conversions.

The standardisation tool does the tedious work

One script, agat_convert_sp_gxf2gxf.pl, is the centre of the toolkit, and the list of what it does is the clearest statement of the problem it solves.

It adds missing parent features, so a file that has only coding sequences and exons ends up with gene and messenger RNA records. It adds missing features, such as exons and untranslated regions where they are implied. It adds missing mandatory attributes, specifically the ID and Parent attributes. It fixes identifiers so they are unique. It fixes feature locations. It removes duplicated features. It groups related features that were spread in different places in the file. It sorts the features, with tabix as an option. And it can merge overlapping loci into a single locus, but only if that option is activated.

Two of those deserve a note. Adding the parents means the output is a proper gene model hierarchy rather than a flat list, which is what makes the result usable by tools that expect GFF3. And the fact that merging overlapping loci is opt-in tells you the default is conservative, which is the right default when the input is a gene model rather than a set of intervals.

Converters for the formats that actually turn up

The conversion scripts cover the formats a genomics group accumulates over the years. From any GTF or GFF you can produce BED, GTF, a tabulated format and ZFF, and you can convert between GTF and GFF in the bioperl flavour with the gxf to gxf tool. There is a BED to GFF3 converter as well, so the conversion works in both directions.

Then there are the source-specific ones, which is where the real experience shows. There is a converter for EMBL format, for the output of genscan, and for the output of mfannot, plus one that takes a BAM file produced by minimap2 and turns it into GFF. Those last three exist because those tools emit formats nothing else reads well, and writing a small converter is faster than arguing with a colleague's pipeline.

The naming is consistent, which matters when you have a directory of scripts: the convert scripts take the sp prefix when they handle a single file, and the plain name when they are the general purpose converters, and every one of them is a standalone Perl script you can call from a shell, a Makefile or a workflow manager.

A long tail of task scripts

Beyond the conversion and the standardisation, the toolkit is a catalogue of specific analyses, and the list is long enough to be worth grouping.

There are reporting scripts, for feature statistics and for functional statistics. There are extraction scripts, for pulling out sequences of any type and for pulling out attributes. There are scripts that reshape the annotation itself: complementing annotations to produce non-overlapping loci, merging annotations, filtering gene models by open reading frame size, keeping only the longest isoform, creating intron features, and fixing coding sequence phases.

There are management scripts for identifiers, untranslated regions, introns and functional annotation. And there are comparison scripts, which are the most interesting of the group: one computes sensitivity and specificity, one compares two annotations with the aim of finding fusion or split events between them, and one compares two sets of BUSCO results to analyse the differences.

The pattern across all of them is that each is a small, single-purpose script that reads a file and writes a file. There is no configuration file, no plugin system and no state, which is a deliberate design for a toolkit that has to run inside other people's pipelines.

Four ways to install it

The project offers four installation routes, which is generous for a Perl distribution and reflects who uses it.

Docker and Singularity are both supported, with images published for both through the BioContainers registry, and the Singularity route is a natural fit for a cluster environment. Bioconda is the third, with an install command, an update command and an uninstall command, and the project links to the recipe for details. The fourth is the old school route: install the prerequisites, run the install step, then update, change to a specific version or uninstall as needed. That last set of operations is handled by a script of the same purpose that sits in the repository root.

The repository also carries a conda environment file, which is the fastest way to get a working environment for development rather than for use, and a devcontainer configuration for the same reason.

None of the install routes is complicated, but none of them is a single command that ends with a working toolchain, and the manual route in particular involves Perl modules that the project lists as prerequisites. The container route is the one to prefer for a reproducible analysis, and the documentation says as much in the way it presents the options.

How the project is laid out

The repository follows the conventions of a Perl distribution. There is a Makefile for the build, a MANIFEST file for packaging, an uninstall script, a lib directory for the modules the scripts share, a bin directory for the executables, a share directory for the data files the tools need, and a t directory for the tests. There is also a third party licence file, which matters for a toolkit that ships code and data from other projects, and a release notes file describing how a release is done.

The documentation is built with mkdocs and published under the project pages, and the project notes point out that the previous documentation, for versions up to 1.4.0, is still on readthedocs. That is a useful detail for anyone following an older tutorial, since the two sets of pages differ and the older ones describe the older tool.

The continuous integration badge and the coverage badge at the top of the project notes are the usual signals for a project with a test suite, and the coverage service is wired to the repository, so the test suite is exercised on every change rather than only at release time.

Citing it, and the version trail

The project has a Zenodo DOI, which is the way to cite a specific version of a tool like this, and it has a publication of its own, so there are two things to cite depending on the context.

The release trail is steady: v1.6.0 in December 2025, v1.6.1 in January 2026 and v1.7.0 in April 2026, with the last push to the repository on 2026-09-07. So the project is being worked on, and the released versions come every few months.

The last thing to know before you start is the shape of the tool. AGAT is a set of command line scripts with a common naming convention and a shared data model, and the parser section in the documentation is where that data model is explained, including how the standardisation step produces files that other tools will accept. If you are going to use more than one of the scripts, that section is the one to read first, because the assumptions of the later scripts are the assumptions the standardisation step creates.

Editorial conclusion

AGAT suits a genomics group that keeps inheriting annotation files from other people, because the standardisation tool handles exactly the defects that appear in real files, from missing parents and duplicate identifiers to features scattered across the file. It is the wrong choice if your annotations already come from a modern pipeline and are clean, since the toolkit earns its value on the problems it repairs, and it is the wrong choice if you want a maintained tool that is not a collection of scripts, because the install and the upgrade are manual operations on a Makefile based Perl distribution. Before you run it on anything important, work on a copy, because the standardisation tool rewrites identifiers and adds features, and read the parser section of the documentation, which is the part of the project that explains the data model the other tools assume. The licence is GPL-3.0, the DOI is on Zenodo, and the current release is v1.7.0 from 2026-04-10.

Frequently asked questions

Official sources

1. Issues
2. License: GPL-3.0
3. NBISweden/AGAT on GitHub
4. README
5. Releases