Home

CheckAMG Wiki

Automated discovery and curation of Auxiliary Metabolic Genes (AMGs), Auxiliary Regulatory Genes (AReGs), and Auxiliary Physiology Genes (APGs) encoded by viral genomes.

CheckAMG identifies and curates high-confidence auxiliary viral genes (AVGs) in viral genomes. It combines an annotation-based approach (curated functional annotations plus viral genome context) with an annotation-independent approach (a protein genome language model, Protein Set Transformer, fined tuned for AVG prediction). Its prediction approach reflects years of community-defined standards for identifying auxiliary genes, validating that they are virus-encoded, and filtering common misannotations.

⚠️ This tool is in active development and has not yet been peer-reviewed.

What is an AVG?

An AVG is an Auxiliary Viral Gene: a virus-encoded gene that is non-essential for viral replication but augments host metabolism (AMGs), physiology (APGs), or regulation (AReGs). Historically many auxiliary genes were referred to broadly as AMGs, but the term AVG has been adopted to include broader host-modulating functions, not just metabolism (see Martin et al. (2025) Nat Microbiol). Despite the name "CheckAMG", this tool predicts AMGs, APGs, and AReGs. See the FAQ for details.

Pages

• Installation - full dependency list, CPU/GPU install recipes, troubleshooting, and conda-pack instructions.
• Modules - detailed descriptions and every parameter:
  • download - fetch the required databases.
  • annotate - annotation-based AVG prediction and curation.
  • de-novo - annotation-independent AVG prediction with PST.
  • aggregate - combine annotate and de-novo results.
  • end-to-end - run annotate, de-novo, and aggregate in tandem.
  • train - finetune a custom CheckAMG-PST model.
• FAQ - confidence levels, AMG weight, strict viral regions, AVG arrays, annotation mechanics, and more.
• Reproducibility - database construction and manuscript notebooks.

Choosing how to run CheckAMG

CheckAMG offers two independent prediction approaches:

• annotate (annotation-based) is conservative and produces curated, trustworthy AVG predictions with functional classification (AMG/APG/AReG) and viral-origin confidence. It can only detect AVGs that can be annotate for functions using CheckAMG's HMMsearches.
• de-novo (annotation-independent) is more sensitive. It predicts whether each protein is virus-encoded and auxiliary using PST embeddings and nearest-neighbor search, so it can recover AVGs with no informative annotation. It does not currently assign specific functions.

Running end-to-end is recommended when feasible, because combining both approaches via aggregate often recovers AVGs that annotate alone cannot. de-novo benefits substantially from a GPU, but GPU access is not required. If a GPU is unavailable or de-novo is impractical at your input scale, running annotate alone is perfectly fine and still produces trustworthy predictions.

Quick start

checkamg download -d /path/to/db/destination

checkamg end-to-end \
  -d /path/to/db/destination \
  -i examples/example_data/single_contig_viruses.fasta \
  -I examples/example_data/multi_contig_vMAGs \
  -o CheckAMG_example_out

Error reporting

To report bugs or request features, please use the GitHub Issues page. To help diagnose issues and debug, please re-run your command that led to the error with the --debug flag, and provide all log files (including module-specific logs within the 01_annotate, 02_denovo, and 03_aggregate if running checkamg end-to-end).