annoreport

A command-line tool for summarizing and visualizing gene annotation results from metagenome-assembled genome (MAG) workflows. Supports output from Prokka and Bakta, enriches results via the UniProt REST API, and produces a polished interactive HTML report alongside a TSV summary table.

---

Features

• Auto-detects Prokka or Bakta output from directory contents
• GFF-Only Works with GFF/GFF3 files alone, without requiring full Prokka or Bakta output; compatible with public genome catalogs such as UHGG
• Compressed file support Accepts .gz compressed GFF files directly without manual decompression
• Counts and ranks the top N most common annotated gene products across all bins
• Separates hypothetical proteins from annotated CDS and reports them independently
• UniProt annotation lookup — looks up gene names and one-line function descriptions for each top gene product
• Functional clustering — groups genes into biological categories (DNA Metabolism, Translation, Energy & Metabolism, Stress & Chaperones, etc.) based on UniProt keywords. See FUNCTIONAL_CATEGORIES.md for complete category definitions
• Interactive HTML report with:
  • Summary stat cards (bins, contigs, assembly size, CDS counts, annotation rate, RNA features)
  • Feature type and RNA feature tables
  • Functional cluster cards with per-gene CDS counts
  • Functional category distribution bar chart
  • Searchable top-N gene product table
• TSV output for downstream analysis in R, Python, or Excel
• --no_uniprot flag for offline/fast runs — skips UniProt lookup and omits clustering sections

---

Requirements

• Python 3.9+
• No external dependencies — uses Python standard library only
• Internet access required for UniProt annotation lookup (unless --no_uniprot is used)
• Compressed GFF files (.gz) are supported natively

---

Installation

Bioconda (recommended)

conda install -c bioconda annoreport

PyPI

pip install annoreport

From source

git clone https://github.com/keplerridge/annoreport.git
cd annoreport

Or copy annotation_report.py directly into your project's scripts/ directory.

---

Usage

Basic (auto-detect tool)

python3 annotation_report.py \
    --annotation_dir results/prokka \
    --outdir results/annotation_summary

Bakta output

python3 annotation_report.py \
    --annotation_dir results/bakta \
    --outdir results/annotation_summary

Force tool type

python3 annotation_report.py \
    --annotation_dir results/bakta \
    --outdir results/annotation_summary \
    --tool bakta

Skip UniProt lookup (offline / fast mode)

python3 annotation_report.py \
    --annotation_dir results/prokka \
    --outdir results/annotation_summary \
    --no_uniprot

Change number of top genes reported

python3 annotation_report.py \
    --annotation_dir results/bakta \
    --outdir results/annotation_summary \
    --top_n 50

---

Examples

A small example dataset is provided in the examples/ directory, containing 10 Prokka-annotated MAGs from Antarctic soil metagenomes. Expected outputs are provided both with and without UniProt annotation lookup for independent verification.

Run the example without UniProt lookup (fast, no internet required)

python3 annotation_report.py \
    --annotation_dir examples/prokka_example \
    --outdir examples/my_output \
    --no_uniprot

Run the example with UniProt annotation lookup

python3 annotation_report.py \
    --annotation_dir examples/prokka_example \
    --outdir examples/my_output_uniprot

Expected outputs can be found in examples/expected_output_no_uniprot/ and examples/expected_output_uniprot/ for comparison.

---

Arguments

Argument	Default	Description
--annotation_dir	(required)	Path to Prokka or Bakta output directory
--outdir	annotation_summary	Directory for output files
--top_n	100	Number of top gene products to report
--tool	auto-detect	Force tool type: prokka or bakta
--no_uniprot	off	Skip UniProt lookup; omits clustering and gene/function columns

---

Output

Two files are written to --outdir:

annotation_gene_summary.html

An interactive HTML report containing:

• Summary cards — bins/MAGs, contigs, assembly size, total CDS, annotation rate, RNA features
• Hypothetical protein callout — count and percentage of CDS with no known function
• Feature type summary — counts of CDS, tRNA, rRNA, tmRNA, and other features
• RNA features table — breakdown of non-coding RNA annotations
• Functional clusters (UniProt mode only) — top genes grouped by biological function with CDS counts per gene
• Functional category distribution (UniProt mode only) — bar chart of CDS counts per category
• Top N gene products table — searchable table with gene product name, gene name, UniProt function description, CDS count, and percentage

annotation_gene_summary.tsv

Tab-separated summary with columns:

rank  count  percent_of_total_cds  product  gene_name  function  keywords

Plus a feature type summary appended at the bottom.

---

Supported Annotation Tools

Tool	File Types Used	Notes
Prokka	.tsv, .gff	Reads EC numbers and COG categories if present
Bakta	.tsv, .gff3, .json	Reads database cross-references; auto-skips hypotheticals.tsv and inference.tsv

Tool auto-detection checks for .gff3 or .json files (Bakta) versus .gff or .tsv only (Prokka). GFF-only mode is used when no .tsv files are present.

---

Functional Categories

When UniProt lookup is enabled, genes are assigned to one of the following categories based on UniProt keyword matching (first match wins):

Category	Example keywords
DNA Metabolism	DNA replication, DNA repair, DNA-binding
Transcription	Transcription, RNA-binding, Sigma factor
Translation & Ribosomes	Protein biosynthesis, Ribosomal protein, Elongation factor
Energy & Metabolism	ATP synthesis, Oxidoreductase, TCA cycle, Glycolysis
Transport & Membrane	Transport, Membrane, ABC transporter, Porin
Stress & Chaperones	Chaperone, Heat shock, Oxidative stress, Protease
Cell Division & Structure	Cell division, Peptidoglycan, Cell wall
Signaling & Regulation	Kinase, Two-component regulatory system, Signal transduction
Nucleotide Binding	ATP-binding, GTP-binding, Isomerase, Hydrolase
Other / Unclassified	No matching keywords found

Each gene is assigned to exactly one category. Priority follows the order above. See FUNCTIONAL_CATEGORIES.md for the complete keyword list and assignment rules.

---

Example Workflow

This tool is designed to run after a MAG annotation step in a Snakemake workflow:

rule annotation_report:
    input:
        annotation_dir = 'results/bakta'
    output:
        html = 'results/annotation_summary/annotation_gene_summary.html',
        tsv  = 'results/annotation_summary/annotation_gene_summary.tsv'
    params:
        outdir = 'results/annotation_summary'
    conda:
        'envs/annotation_report.yaml'
    threads: 1
    resources:
        mem_mb=4000,
        runtime=30
    shell:
        """
        python3 scripts/annotation_report.py \
            --annotation_dir {input.annotation_dir} \
            --outdir {params.outdir} \
            --top_n 100
        """

---

Notes

• UniProt queries use the reviewed (Swiss-Prot) database only for high-quality annotations
• A 0.2 second delay is applied between UniProt API calls to respect rate limits
• For 100 gene products, the UniProt annotation lookup phase takes approximately 75–80 seconds for full Prokka or Bakta output and 79 seconds in GFF-only mode
• Without UniProt annotation lookup, report generation takes approximately 12–17 seconds for full output and 17 seconds in GFF-only mode
• Peak memory usage ranges from 25 to 42 MB depending on input mode
• The --no_uniprot flag is recommended for quick runs or environments without internet access
• GFF-only mode is compatible with compressed .gz files and public genome catalogues such as UHGG

---

License

MIT License — see LICENSE for details.

---

Citation

If you use this tool in your research, please cite it as:

Software:

Ridge K, Adams BJ. annoreport: an interactive tool for metagenome annotation. Code Ocean 2026. https://doi.org/10.24433/CO.0062762.v1

Paper: (citation will be updated upon publication)