Module annotate

Module: annotate

The annotation-based module. It predicts and curates auxiliary viral genes from functional annotations (profile HMM searches) and viral genome context. Each prediction is classified as metabolic (AMG), physiological (APG), or regulatory (AReG) and assigned a viral-origin confidence (high/medium/low). This path is conservative and produces curated, trustworthy predictions on its own, but it can only detect AVGs that carry an informative functional annotation. For annotation-independent prediction, see de-novo.

Basic usage

checkamg annotate -i <genomes.fna> -d <db_dir> -o <output_dir>

Basic input arguments:

• -i, --input-contigs: viral genomes/nucleotide sequences in a single FASTA file
• -I, --input-bins: a folder containing multi-contig vMAGs/bins (one FASTA per bin)
• -p, --input-proteins: amino-acid sequences from translated contigs in a single FASTA file
• -P, --input-bin-proteins: a folder containing amino-acid sequences from translated vMAGs/bins
• -d, --db-dir: the CheckAMG database downloaded with checkamg download
• -o, --output: the output folder to be written

Input notes

• At least one of --input-contigs or --input-bins (for --input-type nucl), or one of --input-proteins or --input-bin-proteins (for --input-type prot), must be provided.
• Nucleotide and protein input types cannot be mixed.
• Providing single-contigs versus bins only affects the labeling and organization of results, not the AVG predictions themselves.
• Protein headers must be in prodigal format (e.g. >Contig1_1 # 144 # 635 # 1 or >Contig1_2 # 1535 # 635 # -1). Sequence names must be unique, contain no spaces, and proteins are verified to be in Prodigal format.

Parameters

Required

Argument	Description
-d, --db-dir	Path to the CheckAMG annotate database.
-o, --output	Output directory for all generated files and folders.

Inputs

Argument	Default	Description
-i, --input-contigs	None	Input nucleotide contigs FASTA (.fna/.fasta, gzipped allowed).
-I, --input-bins	None	Folder of binned contig FASTAs (vMAGs with multiple contigs), one per bin.
-p, --input-proteins	None	Amino-acid FASTA from translated contigs (Prodigal headers).
-P, --input-bin-proteins	None	Folder of amino-acid FASTAs from translated bins, one per bin.
--input-type	nucl	nucl for nucleotide sequences, prot for translated amino-acid sequences. With prot, pyrodigal-gv is skipped and all annotation/context analyses use the provided proteins, so all proteins from each contig/bin must be present with correctly formatted headers.

Thresholds and HMMsearch settings

Argument	Default	Description
-l, --min-len	5000	Minimum contig length (bp) to be considered for analysis.
-f, --min-orf	4	Minimum number of ORFs/proteins per contig.
-a, --min-annot	0.20	Minimum fraction (0.0-1.0) of genes per contig that must be annotated for the contig to be considered for contextual analysis.
-c, --cov-fraction	0.4	Minimum covered fraction (0.0-1.0) of the HMM profile and query sequence required to keep a hit.
-e, --evalue	1e-5	Maximum fallback E-value for HMM hits when database-provided cutoffs are unavailable.
-b, --bitscore	60	Minimum fallback bit score for HMM hits when database-provided cutoffs are unavailable.
-bf, --bitscore-fraction-heuristic	0.5	Retain HMM hits scoring at least this fraction (0.0-1.0) of their database-provided threshold during heuristic filtering.

See the FAQ for a detailed explanation of how these thresholds drive functional annotation.

Genomic context settings

Argument	Default	Description
-w, --window-size	5000	Window size (bp) for local average VL-score calculation.
-v, --min-flank-vscore	10.0	Minimum V-score (0.0-10.0) required in flanking regions to verify viral origin and reduce host-contamination artifacts (higher = more viral-like).
-vl, --min-window-avg-vlscore	3.0	Minimum average VL-score within the window around a gene for it to count as a viral region (higher = more viral-like).
-ha, --use-hallmark / --no-use-hallmark	off	Use viral hallmark genes instead of V-scores when evaluating flanks. Enable to be extra conservative.

Filtering settings

Argument	Default	Description
-amg, --min-amg-weight	0.6	Minimum AMG weight (0.0-1.0) for a putative AMG annotation to be kept. AMG weight is a capped geometric mean of (i) the ratio of auxiliary-like to non-auxiliary-like metabolic annotations for a function and (ii) the function's rarity in viral genomes (VL-score). Higher = more conservative. See the FAQ.
--filter-ambig-regions / --no-filter-ambig-regions	off	Exclude predictions that fall outside strict viral regions. Disabled by default because it can be too strict when annotation rate is low but other viral-origin signals are strong. See the FAQ.
--filter-avg-arrays / --no-filter-avg-arrays	on	Exclude AVG predictions that occur in contiguous runs (arrays), which suggests non-auxiliary function. See the FAQ.
--avg-array-limit	3	If --filter-avg-arrays is enabled, exclude runs of AVGs of this length or more.
--filter-presets	allow_glucan,allow_nucleotide,allow_methyl,allow_lipid	Comma-separated preset(s) controlling annotation filtering, independent of AMG weight. See below.

--filter-presets

The presets control keyword-based filtering of functional annotations, independent of the AMG weight. Valid presets:

• allow_glucan: keep glycosyltransferase, glycoside-hydrolase, and related annotations
• allow_nucleotide: keep nucleotide metabolism annotations
• allow_methyl: keep methylase/methyltransferase annotations
• allow_lipid: keep lipopolysaccharide and phospholipid-related annotations
• all_filters: apply filtering in all of the above categories (strict; cannot be combined with other presets)
• no_filter: disable all filtering, including essential viral annotation filters (not recommended)

The default enables all four allow_* categories. This means CheckAMG keeps glycosyl, nucleotide, methyl, and lipid annotations by default and relies on the AMG weight (--min-amg-weight) plus the essential-function filters to remove unlikely AVGs. To be stricter and filter all four categories, use --filter-presets all_filters. Example of a custom combination: --filter-presets allow_glucan,allow_nucleotide.

If you change --filter-presets away from the default or lower --min-amg-weight, additional manual curation of functional annotations is recommended to avoid misclassifying genes as AMGs, APGs, or AReGs.

Output files

Argument	Default	Description
-kf, --keep-full-hmm-results / --no-...	off	Write all HMM search results for every hit in each database. By default only the top hit per protein per database is written. Use with --save-to-parquet for large inputs.
-pq, --save-to-parquet / --no-...	off	Write intermediate and final tables as parquet instead of TSV (smaller, not human-readable without tools). Recommended for large datasets.

Resources

Argument	Default	Description
-t, --threads	25% of available	Maximum number of threads.
-m, --mem	80% of available	Memory limit in GB. The run will crash if usage exceeds this limit.
--debug / --no-debug	off	Enable debug-level logging.

Outputs

The output folder has the following structure:

CheckAMG_annotate_output
|-- CheckAMG_annotate.log
|-- config_annotate.yaml
|-- results/
|   |-- faa_metabolic/
|   |   |-- AMGs_all.faa
|   |   |-- AMGs_high_confidence.faa
|   |   |-- AMGs_medium_confidence.faa
|   |   `-- AMGs_low_confidence.faa
|   |-- faa_physiology/
|   |   `-- APGs_*.faa
|   |-- faa_regulatory/
|   |   `-- AReGs_*.faa
|   |-- final_results.tsv
|   |-- gene_annotations.tsv
|   |-- genes_genomic_context.tsv
|   |-- metabolic_genes_curated.tsv
|   |-- physiology_genes_curated.tsv
|   |-- regulation_genes_curated.tsv
|   |-- metabolic_gene_categories.tsv
|   |-- physiology_gene_categories.tsv
|   `-- regulatory_gene_categories.tsv
|-- snakemake/
`-- wdir/

• CheckAMG_annotate.log: log file for the run.
• config_annotate.yaml: Snakemake pipeline configuration.
• results/:
  • faa_metabolic/, faa_physiology/, faa_regulatory/: predicted AVG amino-acid sequences by type and confidence.
  • final_results.tsv: summary table of AVG predictions. Contains all genes that passed length/CDS filtering (metabolic, physiological, regulatory, and unclassified). Filter on the "Protein Classification" column. Includes the "Protein in Strict Viral Region" column indicating whether a protein falls within a strict viral region (i.e. one that would not be filtered under --filter-ambig-regions).
  • gene_annotations.tsv: all gene annotations.
  • genes_genomic_context.tsv: gene-level genomic context used for confidence assignment.
  • *_genes_curated.tsv: curated lists of metabolic, physiological, and regulatory genes after false-positive filtering.
  • *_gene_categories.tsv: all applicable multi-level functional categories for each reference AMG/APG/AReG. An AVG (especially an AMG) can list multiple categories because its matched reference family has been described in multiple pathways; this does not mean the gene acts in all of them (or any). See Why does one AVG have multiple function categories?.
• snakemake/: Snakemake .done files.
• wdir/: intermediate files.

Examples of these output files are in examples/example_outputs.

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