FAQ

FAQ

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).

Examples:

• A virus-encoded psbA or soxY is an AMG because they encode proteins with functions in host photosynthesis and sulfide oxidation.
• A virus-encoded VasG type VI secretion system protein or HicA toxin is an APG because they are involved in host physiology.
• A LuxR transcriptional regulator or an AsiA anti-sigma factor protein is an AReG because they are likely involved in the regulation of host gene expression.

Despite the name "CheckAMG", this tool predicts APGs and AReGs as well as AMGs, differing only by functional annotation criteria.

How does CheckAMG predict AVGs overall?

CheckAMG offers two independent approaches:

• annotate (annotation-based): profile HMM searches assign functional annotations, curated reference lists and filters classify candidates as AMG/APG/AReG, and viral genome context assigns a viral-origin confidence.
• de-novo (annotation-independent): the PST genome language model embeds query proteins and a nearest-neighbor search against a labeled reference predicts whether each protein is virus-encoded and auxiliary, without using annotations.

The two can be combined with aggregate or run together via end-to-end. de-novo is more sensitive and can recover AVGs that annotate cannot detect, while annotate provides functional classification and curation. See the Home page for guidance on which to run.

How does annotate classify and curate its predictions?

annotate applies a multi-stage process:

1. Use curated profile HMMs that represent metabolic, physiological, and regulatory genes to produce initial AVG candidates.
2. Filter metabolic gene predictions by their AMG weight (see below) and, optionally, curated extra keyword/substring filters to remove unlikely AMGs, APGs, and AReGs, controlled by --filter-presets).
3. Use viral genome context to assign a viral-origin confidence and, optionally, to filter predictions outside strict viral regions or within AVG arrays (see below).

Unclassified genes are those with annotations that don't meet thresholds for confident AVG classification, not necessarily unannotated genes.

What is the AMG weight?

The AMG weight (--min-amg-weight, default 0.6) is a continuous score of 0.0-1.0 assigned to each metabolic annotation. It is a capped geometric mean of two components:

1. The ratio of auxiliary-like to non-auxiliary-like metabolic annotations for that function.
2. The function's rarity in viral genomes (its VL-score).

Higher (more conservative) weights indicate functions that are predominantly associated with metabolic pathways and are uncommon in viral genomes broadly. Lower (more permissive) weights indicate functions that are either very common in viral genomes (suggesting a non-auxiliary role), predominantly associated with non-metabolic or essential pathways, or both. A candidate AMG is retained only if its annotation's AMG weight is at least --min-amg-weight. Lowering the threshold is more permissive but increases the need for manual curation.

The AMG weight is applied alongside, and independently of, the --filter-presets keyword filters.

How do the --filter-presets work?

The presets control keyword-based filtering of functional annotations, separate from the AMG weight. The default enables four allow_* categories (allow_glucan, allow_nucleotide, allow_methyl, allow_lipid), meaning glycosyl, nucleotide, methyl, and lipid annotations are kept and CheckAMG relies on the AMG weight plus essential-function filters to remove unlikely AVGs.

• all_filters: apply filtering in all four categories (strict; cannot be combined with other presets).
• no_filter: disable all filtering, including essential viral annotation filters (not recommended).

Use the default for most cases. Switch to all_filters to be stricter, or pass a custom comma-separated subset (e.g. allow_glucan,allow_nucleotide) to keep only specific categories. If you deviate from the default or lower --min-amg-weight, additional manual curation is recommended. See annotate for the full list.

Why does one AVG have multiple function categories?

CheckAMG reports multi-level functional categories (category_L1, category_L2, category_L3) for classified AVGs, and a single AVG, particularly an AMG, can be assigned to more than one category. This is expected and reflects how the reference data are built, not a claim about the gene's actual activity.

The reference metabolic protein families that CheckAMG matches against have been described in the literature as participating in multiple metabolic pathways. When a query protein matches such a family, CheckAMG reports all of the pathways that family has been associated with, because, with sequence data alone and no host context, there is no way to determine which one (if any) the protein actually functions in.

Crucially, multiple reported categories do not mean the AVG is involved in all of those pathways. The gene may function in only one of them, or in none of them. The categories are a list of potential pathways the protein might be involved in, given only its sequence-based annotation. Confirming a genuine functional role requires evidence beyond what CheckAMG provides, such as host genomic context, expression data, or biochemical validation. See Downstream analyses for suggested follow-up steps.

What do the viral-origin confidence assignments mean?

TL;DR They reflect the likelihood that a gene is virus-encoded (vs host/MGE).

Applies to annotate only. Viral-origin confidence, its high/medium/low levels, strict viral regions, and AVG arrays are all features of the annotation- and V/VL-score-based annotate module, which uses human-readable contextual information. They are not used by de-novo, which derives its own separate confidence levels from PST embeddings and nearest-neighbor voting (see de-novo).

AVGs often resemble host genes and can result from contamination. annotate uses local genome context to assign high, medium, or low viral-origin confidence based on:

1. Proximity to virus-like or viral hallmark genes.
2. Proximity to transposases or other non-viral mobilization genes.
3. Local viral gene content, determined using V- and VL-scores (Zhou et al., 2025).

A LightGBM model, trained on real and simulated viral/non-viral data, makes these assignments. Confidence levels refer to viral origin, not the functional annotation.

de-novo reports its own separate confidence levels (very high, high, medium, low) for AVG-like, viral, and combined Final AVG probabilities, derived from PST nearest-neighbor voting rather than the LightGBM context model. See de-novo.

Which confidence levels should I use?

TL;DR When in doubt, use high, but medium can be included if your input is virus-enriched.

The precision and recall of each confidence level depend on the input dataset.

• High-confidence: high-confidence predictions can almost always be trusted (false-discovery rate < 0.05 in most cases). They are conservative to maintain integrity even when viral proteins are rare. Recommended when viral proteins are relatively rare (mixed-community metagenomes) or the input composition is unknown.
• Medium-confidence: significantly increases recovery of truly viral proteins. Maintains FDR < 0.1 in datasets with at least ~33% viral proteins, but FDR rises as inputs become increasingly non-viral. Recommended together with high-confidence when roughly one-half or more of your input sequences are viral (e.g. outputs from most virus prediction tools, or viromes).
• Low-confidence: not filtered at all. Only use when you are certain all input sequences are free of non-viral contamination (complete or isolate viral genomes), or for testing.

What are strict viral regions?

Applies to annotate only (not de-novo).

A strict viral region is a stretch of a contig where CheckAMG annotate is extra confident that it's genuinely viral. Strict viral regions are identified from window-average VL-scores (--min-window-avg-vlscore) and then refined using per-gene V-scores (--min-flank-vscore), or viral hallmark genes if --use-hallmark is enabled (stricter, lower recall).

Every gene's membership is reported in the final_results.tsv "Protein in Strict Viral Region" column. The --filter-ambig-regions option (off by default) excludes any prediction that does not overlap a strict viral region. It is disabled by default because strict-region calls can be too conservative when the annotation rate is low but other viral-origin signals are strong; enable it to be extra conservative.

What are AVG arrays and why are they filtered?

Applies to annotate only (not de-novo).

An AVG array is a contiguous run of predicted AVGs on a contig. Long runs of adjacent AVGs typically indicate a non-auxiliary function (e.g. a core viral operon or a misannotated region) rather than genuine individual auxiliary genes. By default (--filter-avg-arrays, on), CheckAMG excludes runs of --avg-array-limit (default 3) or more AVGs in a row. Disable with --no-filter-avg-arrays, or change the run-length cutoff with --avg-array-limit.

How does CheckAMG assign functions to proteins?

TL;DR Profile HMM searches with adaptive adjustment of database-provided thresholds.

1. Homology searching: CheckAMG uses pyhmmer for fast, reproducible HMM searches of user proteins against profile HMMs.

2. Databases: searches run against

   • KEGG Orthology (KO) (Kanehisa et al., 2016)
   • FOAM (Prestat et al., 2014)
   • Pfam-A (Mistry et al., 2021)
   • PHROGs (Terzian et al., 2021)
   • dbCAN CAZyme HMMs (Zheng et al., 2023)
   • METABOLIC HMMs (Zhou et al., 2022)
   • CAMPER (McGivern et al., 2024)

3. Initial E-value: a permissive E-value cutoff of 0.01 is applied during hmmsearch to minimize hits missed due to chunking/memory differences when parallelizing, which preserves reproducibility.

4. Coverage filter: after hits are collected, CheckAMG enforces a minimum HMM-profile coverage and a minimum query-sequence coverage (default 0.4 for both, via --cov-fraction), so functional inferences are not drawn from tiny partial alignments.

5. Database-specific thresholds:

   • Pfam: sequence-level gathering threshold (GA); hits below GA are excluded.
   • FOAM, KEGG, METABOLIC, CAMPER: use database-defined bit score thresholds with a relaxed fallback heuristic (below). METABOLIC now uses database-derived bitscore cutoffs.

6. Fallback heuristic (FOAM, KEGG, METABOLIC, CAMPER): KEGG-derived thresholds can be overly strict for environmental viruses. Inspired by Anvi'o's anvi-run-kegg-kofams, a hit below the database-provided threshold is still retained if all four hold: bit score >= --bitscore-fraction-heuristic (default 0.5) of the threshold; E-value < 1e-5; query coverage >= 0.4; HMM coverage >= 0.4. A similar heuristic improves recovery without compromising too much on precision (Kananen et al., 2025).

7. Fallback filtering for databases without defined cutoffs (dbCAN, PHROGs): minimum query coverage 0.4, minimum HMM coverage 0.4, minimum bit score 60 (--bitscore), maximum E-value 1e-5 (--evalue).

8. Consolidation and best-hit reporting: each protein is searched against every database. Results feed two independent paths:

   • Annotation path (strict): only hits passing all quality filters are kept. The single best hit per protein per database is reported (lowest E-value, then highest bitscore), plus one cross-database top-hit summary per protein (top_hit_hmm_id, top_hit_description, top_hit_db).
   • Scoring path (relaxed): all hits at E-value <= 1e-5 are retained regardless of annotation quality, best per protein-database pair. Used exclusively for V/VL-score assignment for genomic context scoring, not for functional annotation.

   Full, unfiltered hmmsearch output is always generated internally and can be copied to the output with --keep-full-hmm-results (use --save-to-parquet for large inputs).

These defaults balance accuracy and recall and are based on benchmarking and community best practices. Thresholds are configurable via --bitscore, --bitscore-fraction-heuristic, --evalue, and --cov-fraction, but changing them is generally not recommended.

Snakemake

CheckAMG modules are executed as Snakemake pipelines. If a run is interrupted, it can resume from the last complete step as long as intermediate files exist.