Module de novo

Module: de-novo

The annotation-independent module. It predicts auxiliary viral genes with a protein-based genome language model, the Protein Set Transformer (PST), instead of relying on functional annotations. Query proteins are embedded with PST (via ESM2), then compared against a labeled reference of pre-trained embeddings using a nearest-neighbor search. For each query protein this yields two marginal probabilities, an AVG-like probability and a viral probability, plus a combined Final AVG probability.

Because it does not depend on annotations, de-novo is more sensitive than annotate and can recover AVGs with no informative annotation. It does not yet assign specific functions or classify predictions as metabolic, physiological, or regulatory. To combine de-novo predictions with the functional classifications from annotate, use aggregate or run end-to-end.

de-novo runs on CPU or GPU, but benefits substantially from a GPU.

Inputs

de-novo accepts FASTA inputs (which it embeds) or precomputed embeddings (faster, skips embedding).

FASTA inputs

Argument	Description
-c, --query-contigs	Input nucleotide contigs FASTA (.fna/.fasta, gzipped allowed).
-C, --query-bins	Folder of binned contig FASTAs (vMAGs), one per bin.
-p, --query-proteins	Amino-acid FASTA from translated contigs (Prodigal headers).
-P, --query-bin-proteins	Folder of amino-acid FASTAs from translated bins, one per bin.

Embedding inputs (optional, faster)

Argument	Description
-i, --query-file	PST-embedded query proteins (field ctx_ptn). Skips both ESM2 and PST embedding.
-e, --query-file-esm2	Precomputed graph-formatted ESM2 embeddings; PST embeddings are computed from these before nearest-neighbor label propagation.
-f, --fasta-file	The FASTA used to generate -i/-e, so sequence names can be written alongside predictions. If omitted, predictions are written in embedding order with generic identifiers.

Providing precomputed ESM2 or PST embeddings from a previous run on the same input saves time.

Parameters

Inference settings

Argument	Default	Description
-b, --batch-size	16	Batch size in number of scaffolds when PST embeddings must be computed.
--nn-batch-size	4096	Batch size in number of proteins for kNN searches.
--num-index-cells	auto	If a search index must be built from the training data, the number of cells to partition it into for inverted lookup. Smaller values build faster but search slower. Automatic by default; very large datasets (>10M proteins) can take a long time to index.
--num-probe-cells	1	Number of index cells to visit when searching for nearest neighbors. Higher can improve accuracy with large queries/indexes at the cost of speed.
-k, --knn	20	Number of nearest neighbors for distance-weighted class-label voting.

Reference training data

Provide either the packaged de-novo database (-d) or a custom reference (e.g. from train).

Argument	Description
-d, --db-dir	Path to the CheckAMG de-novo database (from checkamg download, separate from the annotate database) containing pre-trained model inputs. If omitted, a custom reference must be provided.
-td, --train-data-file	Graph-formatted .h5 training data. Embedded with the trained PST model, then used to build the search index.
-te, --train-embed-file	Train protein PST embeddings with labels in an H5 file (embeddings under ctx_ptn, labels under label). Used directly to build the search index.
-tx, --train-index-file	Precomputed FAISS index (faiss.write_index) of the training protein PST embeddings.
-tl, --train-labels-file	Train protein labels stored in an H5 file under label.
-mc, --model-ckpt	Trained CheckAMG-PST model checkpoint (.ckpt).
-ec, --esm2-ckpt-dir	Directory with pre-downloaded ESM2 checkpoints (esm2_t30_150M_UR50D.pt and its contact-regression file). If omitted, they are downloaded to ~/.cache/torch/hub/checkpoints on first run.

When not using --db-dir, provide --train-data-file OR --train-embed-file OR (--train-index-file AND --train-labels-file), together with --model-ckpt.

Outputs

Argument	Description
-o, --output	Output directory for results, intermediate files, and logs (required).

Resources

Argument	Default	Description
-a, --accelerator	auto	cpu, gpu, or auto.
-x, --devices	1	Number of devices. On CPU this is cores/threads; multi-GPU is not supported (only the first GPU is used).
-m, --mem	80% of available	Memory limit in GB.

Other

Argument	Default	Description
--seed	111	Random seed.
--debug / --no-debug	off	Enable debug-level logging.

Outputs

The main output is predictions.tsv, with one row per query protein and the following columns:

• Genome, Contig, Protein: identifiers.
• AVG-like prob, AVG-like confidence: probability and confidence that the protein's function is auxiliary-like. "AVG-like" refers to the function only and is independent of whether the protein is predicted to be viral, so a protein can be AVG-like without being viral (and vice versa).
• Viral prob, Viral confidence: probability and confidence that the protein is virus-encoded.
• Final AVG prob, Final AVG confidence: the combined AVG-and-viral call (auxiliary-like function AND virus-encoded). The probability is the product of the two marginal probabilities; the confidence uses dedicated AND-gate thresholds.

Each confidence column is one of very high, high, medium, or low. A confidence is not a separate score but a bin (a range of probabilities). The cutoffs defining each bin are pre-determined from evaluation results, chosen to maximize recall while keeping precision at or above 90%. Intermediate files (filtered FASTA, ESM2/PST embeddings, FAISS index, labels) are also written to the output directory and can be reused to speed up subsequent runs.