AMAP: Assisted Microbial Annotator Pipeline

Paula Ruiz-Rodriguez¹ and Mireia Coscolla¹
_{1. I²SysBio, University of Valencia-CSIC, FISABIO Joint Research Unit Infection and Public Health, Valencia, Spain}

AMAP annotates assembled bacterial genomes with Bakta, aligns a trusted reference proteome onto them with miniprot, and settles every disagreement between the two: late starts, genes split in two, calls that are not genes, genes Bakta missed. Built for the Mycobacterium tuberculosis complex, where it changes about 30% of the genes, and for any species you have a trusted annotation for (--ref_annotation + --ref_genome).

The website: start here, the tutorial, how it works, step by step, and the documentation.

Quickstart	From an installed Nextflow to an open report
Parameters	Every flag and its default
Outputs	What every file is
The correction algorithm	Every rule and threshold, drawn on real genes
Custom reference	Annotating non-MTBC organisms
Troubleshooting	When a run fails

What AMAP decides

Every Bakta call is compared with where the reference proteins align, on the same strand of the same contig. That puts it in one of four cases, and a reference gene with no call at all is a fifth. These are real genes of M. tuberculosis CDC1551; step through each one on the website.

Does it work?

tests/benchmark runs the correction on seven genomes and scores it against an annotation AMAP did not make: the reference's own genes, carried onto the other genomes by a whole-genome alignment. Every gene a genome carries unchanged is found at exactly its coordinates, under its name; of the genes that changed, 99.8 to 100% still sit where the alignment puts them, under their name.

Genome	Unchanged genes, exact	Changed genes, found
M. tuberculosis H37Rv, against itself	4026 / 4026
H37Rv CP110619, against H37Rv	3986 / 3986	50 / 50
M. tuberculosis CDC1551, against H37Rv	3097 / 3097	860 / 862
M. bovis AF2122/97, against H37Rv	2391 / 2391	1515 / 1515
CDC1551 cut into 40 contigs	3072 / 3072
E. coli K-12, against itself	4286 / 4286
E. coli O157:H7 Sakai, against K-12	220 / 220	3363 / 3367

The pipeline

Stations are the processes of main.nf, in the order its workflow runs them; lines are what travels between them. On the website the map is interactive.

1. Database setup (eggNOG): builds the eggNOG database if it is not already there.
2. MTBC lineage typing (pathotypr): assigns lineages from phylogenetic markers and renames the genomes accordingly. Turned off with --skip_typing.
3. Genome annotation (Bakta): CDS, tRNAs and other features, the baseline that AMAP corrects.
4. Protein alignment (miniprot): the reference proteome aligned onto each genome.
5. CDS case classification: every CDS sorted by how it relates to the reference (novel, perfect match, imperfect match, conflicting coordinates, or a reference gene the annotator missed).
6. Annotation correction: conflicts resolved, coordinates adjusted and every gene translated into a corrected gene set.
7. Functional annotation (eggNOG-mapper): COG, KEGG, GO, EC, PFAM and CAZy assignments, and the corrected GFF3 and GenBank.
8. Gene duplication analysis: duplication families per genome, plus homologous communities across genomes with network metrics.
9. Pangenome analysis (pangene): gene content compared across the whole set.
10. Report: a single self-contained HTML file covering all of the above.

Mycobrowser's functional categories describe tuberculosis genes, so they are skipped on their own when a custom reference is not a Mycobacterium; lineage typing is turned off with --skip_typing.

Quickstart

You need Nextflow 24.04 or newer and a container engine. Nothing else: every tool lives in the AMAP image, and there is no need to clone this repository.

conda create -n nextflow-env
conda activate nextflow-env
conda install -c bioconda nextflow

Check the installation. This annotates the reference genome bundled in the container, so you need no data of your own:

nextflow run PathoGenOmics-Lab/AMAP -profile docker,test

Write a tab-separated sample sheet:

sampleId	fasta
G26689	/data/genomes/G26689.fasta
G26690	/data/genomes/G26690.fasta

And run it:

# Local machine, Docker
nextflow run PathoGenOmics-Lab/AMAP -profile docker --tsv samples.tsv

# HPC cluster, Singularity and SLURM
nextflow run PathoGenOmics-Lab/AMAP -profile singularity,slurm --tsv samples.tsv

# A non-MTBC organism, with your own reference
nextflow run PathoGenOmics-Lab/AMAP -profile docker \
    --tsv samples.tsv \
    --skip_typing --skip_mycobrowser \
    --genus Escherichia --species "Escherichia coli" \
    --ref_annotation my_reference.gbk --ref_genome my_reference.fasta

--validate_only checks every FASTA and database path without running anything, which is worth doing before a long run.

See running AMAP for the full set of profiles and options.

Results

Everything lands under --outdir, results/ by default. The three to open first:

What	Where
The full interactive report	results/final_report.html
Corrected annotation, per sample	results/AMAP/{sampleId}/*-AMAP.gff3
Proteins for downstream tools	results/AMAP/{sampleId}/*-AMAP.clean.faa

Alongside them, results/pipeline_info/ holds software_versions.yml and params.yml, which are what belongs in a methods section. Every directory is documented under outputs.

Development

git clone https://github.com/PathoGenOmics-Lab/AMAP
cd AMAP
pip install -r requirements-test.txt
python -m pytest tests/ -v

The website is plain HTML in docs/. After editing a page's markdown, rebuild the pages and check them against the pipeline:

python3 tools/build_docs.py
python3 tools/check_site.py

See contributing.

Citation

Ruiz-Rodriguez, P., & Coscolla, M. (2026). AMAP (Version 1.0.1) [Computer software]. https://doi.org/10.5281/zenodo.8024446

@software{Ruiz-Rodriguez_AMAP_2026,
  author = {Ruiz-Rodriguez, Paula and Coscolla, Mireia},
  doi = {10.5281/zenodo.8024446},
  license = {GPL-3.0},
  month = apr,
  title = {{AMAP}},
  url = {https://github.com/PathoGenOmics-Lab/AMAP},
  version = {1.0.1},
  year = {2026}}

---

✨ Contributors

AMAP is developed with ❤️ by:

Paula Ruiz-Rodriguez 💻 🔬 🤔 🔣 🎨 🔧

Mireia Coscolla 🔍 🤔 🧑‍🏫 🔬 📓

This project follows the all-contributors specification (emoji key).

---

💻 Software Used

Software	Version	Type	Usage
Pipeline & Orchestration
Nextflow	≥24.04	Workflow	Pipeline orchestration
Docker	≥25.0	Container	Containerization
Singularity	≥3.11	Container	Containerization (HPC)
Bioinformatics Tools
Bakta	1.12.0	Tool	Genome Annotation
miniprot	0.18	Tool	Protein-to-genome Alignment
pangene	1.1	Tool	Pangenome Graph Construction
DIAMOND	2.1.24	Tool	Fast Protein Alignment
eggNOG-mapper	2.1.13	Tool	Functional Annotation
Pathotypr	1.0.0	Tool	MTBC Lineage Typing
gfatools	0.5	Tool	GFA Graph Utilities
Python
Python	3.9	Runtime	Programming Language
pandas	≥2.0	Library	Data Analysis
NumPy	≥1.24	Library	Numerical Computing
Biopython	≥1.83	Library	Sequence Manipulation
matplotlib	≥3.7	Library	Static Visualization
plotly.py	≥5.0	Library	Interactive Visualization
NetworkX	≥3.0	Library	Network Analysis
intervaltree	≥3.1	Library	Overlap Detection
python-louvain	≥0.16	Library	Community Detection
pyvis	0.3.2	Library	Network Visualization
R
R	4.4	Runtime	Statistical Computing
ggplot2	≥3.5	Package	Data Visualization
dplyr	≥1.1	Package	Data Manipulation
tidyr	≥1.3	Package	Data Tidying
plotly (R)	≥4.10	Package	Interactive Plots
ggpubr	≥0.6	Package	Publication-ready Plots
pheatmap	≥1.0	Package	Heatmap Visualization
DT	≥0.30	Package	Interactive Tables
rmarkdown	≥2.25	Package	Report Rendering
ggsimplestats	latest	Package	Statistical Annotations