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
.gzcompressed 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_uniprotflag 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_uniprotis 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_uniprotflag is recommended for quick runs or environments without internet access - GFF-only mode is compatible with compressed
.gzfiles 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)
Metadata
Release files for annoreport 0.1.3
For a detailed explanation of source distributions (sdists) and built distributions (wheels), please see the package formats documentation.
Source distribution (sdist)
| File | Size | Uploaded | Provenance | Actions |
|---|---|---|---|---|
| annoreport-0.1.3.tar.gz | 16.6 kB | Without provenance | Details for annoreport-0.1.3.tar.gz |
Built distribution (wheel)
| File | Interpreter | ABI | Platform | Actions Reset |
|---|---|---|---|---|
| annoreport-0.1.3-py3-none-any.whl | Python 3 | none | any | Details for annoreport-0.1.3-py3-none-any.whl |
Total release size: 33.7 kB
Release files / annoreport-0.1.3.tar.gz
| Download URL | annoreport-0.1.3.tar.gz |
|---|---|
| Size | 16.6 kB |
| Tags | Source |
|
SHA-256 checksum How to use checksums |
e37d55c45381b2453bd189d935dd5baae8729e1e78d45f711a41a2e545628b5e
|
|
BLAKE2b-256 checksum How to use checksums |
d66b75f5c784bc3d3587a85c2a1c694f166e3d533d1e54cd0d39166b60d17f33
|
| Upload date | |
|
Uploaded using Trusted Publishing? What is trusted publishing? |
No |
| Uploaded via |
twine/6.2.0 CPython/3.9.21
|
Release files / annoreport-0.1.3-py3-none-any.whl
| Download URL | annoreport-0.1.3-py3-none-any.whl |
|---|---|
| Size | 17.0 kB |
| Tags | Python 3 |
|
SHA-256 checksum How to use checksums |
66b1186a2b5135d96eb3d304fb98d5d428b3072ccbe115e13add8c135754049f
|
|
BLAKE2b-256 checksum How to use checksums |
0b93597258fd8c31efcc18cd13cba35a7e666926c7650583017f26fcf610d546
|
| Upload date | |
|
Uploaded using Trusted Publishing? What is trusted publishing? |
No |
| Uploaded via |
twine/6.2.0 CPython/3.9.21
|
Security for annoreport 0.1.3
Provenance
Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.
No provenance found
None of the files in this release were uploaded with provenance metadata.
A note on package security
PyPI is a repository for distributing packages, not a service for auditing them. While third-party security researchers and our staff do their best to detect and remove malicious packages, PyPI cannot guarantee the quality, security or suitability of any given package.
To learn more about protecting yourself from malicious actors, visit our package security documentation.