Annotation strategies

Annotation strategies chain homology searches from fast to sensitive. Which one to choose, and why the .env variants are now the recommended default

After assembly, LazypipeX annotates contigs by searching them against reference databases. An annotation strategy is a named preset that fixes which search engines run, against which databases, and in what order. Strategies are selected with --anns <key>:

lazypipe.pl -p main --hostgen Homo_sapiens --anns vi.chain3.env -1 reads_R1.fastq.gz -s mysample -r results -v

--anns overrides any --ann1 or --ann2 given on the same command line. The presets are defined in the ann.strategies section of config.yaml; to compose a chain yourself instead, see the --ann1 / --ann2 syntax in lazypipe.pl -h.

Recommended: The .Env Variants

This supersedes the earlier recommendation in the Lazypipe3 user guide , which presented the .env strategies as a special case for environmental and faecal samples. We now recommend the .env variants as the default for all sample types.

A strategy without .env searches the archaea–bacteria–virus (ABV) subset of the reference database in its first round. A contig of eukaryotic origin — most often host mRNA — cannot be recognised as eukaryotic against such a subset, and is instead assigned to whichever archaeal, bacterial or viral sequence it resembles most. That is the main source of false positives in the reported virus list.

The .env variants search the complete, unsubsetted database in the first round. Eukaryotic contigs are then binned as eukaryotic, and the virus list is correspondingly cleaner. The cost is execution time: in our published benchmarks .env chain ran roughly seven times longer than its subsetted equivalent.

On Roihu that penalty is largely offset, for three reasons:

  1. The medium and large partitions allocate — and bill — a whole node, so a run gets far more cores than the 30 used in the benchmarks at no extra cost.
     
  2. Those partitions also provide 600 GiB of fast node-local disk for working files, which is what makes large libraries practical at all.
     
  3. The complete database an .env chain searches on Roihu is core_nt, NCBI's curated replacement for nt: roughly 320 volumes against 1,444 for the full nt, or about a quarter of the size. What it leaves out is largely environmental and whole-genome-shotgun bulk rather than the reference sequences a virus search depends on, so the search covers much the same ground at a fraction of the cost.
     

In practice, large libraries run with vi.chain3.env finish in a normal working day: in our reference run on Roihu, 47 libraries of 4–8 GB gzipped reads each completed in 4 h 34 m to 6 h 34 m per sample (mean 5 h 20 m) on 64 cores. See .

Note that .env and background filtering are not alternatives. The published benchmark ran vi.chain3.env without --hostgen, but the two combine freely, and the reference run above used --anns vi.chain3.env together with --hostgen naming both the host genome and human. Filtering the background first reduces the number of contigs entering annotation and therefore shortens the run; searching the complete database then keeps whatever eukaryotic material survived filtering out of the virus list. Use both.

Choose a non-.env strategy when CPU time is the binding constraint — a quick preliminary screen, a very large sample set, or a small allocation.

Strategy Reference

Key Chain Use for
vi.chain3.env Minimap2 (complete core_nt) → DIAMOND blastp (UniRef100ABV) recommended default: virus discovery, all sample types
vi.chain1.env Minimap2 (complete core_nt) → BLASTN (core_ntABV) → BLASTP (UniRef100ABV) maximum sensitivity, smaller datasets or a large allocation
vi.chain2.env Minimap2 (complete core_nt) → BLASTP (UniRef100ABV) as vi.chain1.env, without the intermediate BLASTN
vi.chain3 Minimap2 (core_ntABV) → DIAMOND blastp (UniRef100ABV) virus discovery when CPU time is the binding constraint
vi.chain1 Minimap2 (core_ntABV) → BLASTN (core_ntABV) → BLASTP (UniRef100ABV) as vi.chain3, slower and more sensitive
corent.vi.env Minimap2 (core_ntVi) → BLASTN (complete core_nt) two-round virus identification, including retroviruses
corent.vi Minimap2 (core_ntVi) → BLASTN (core_ntABV) two-round virus identification, excluding retroviruses
corent.abv.env Minimap2 (core_ntABV) → BLASTN (complete core_nt) for viral and bacterial bins archaea and bacteria as well as viruses
corent.vi.fast Minimap2 (core_ntVi) only the quickest useful run
refseq.vi Minimap2 (RefSeqVi) → BLASTN (RefSeqABV) fast preliminary screen; RefSeq is far smaller than core_nt

 

Run lazypipe.pl --databases on Roihu for the databases actually installed, and check config.yaml for the full list of strategy keys in your deployment.

Accuracy And Speed, As Published

Benchmarked against a Vi.chain0 baseline (BLASTN against NTABV → BLASTP against UniRef100ABV) on 90 Ochlerotatus mosquito libraries:

Strategy Precision Recall Speedup vs. baseline
vi.chain1 ~100% ~100% 5×
vi.chain2 ~100% ~99% 6×
vi.chain3 ~100% ~99% 20×
vi.chain3.env ~100% ~98% 20×

 

All strategies reached ≥99.7% precision. Average runtimes for these libraries fell from 20 hours under the BLASTN/BLASTP baseline to as little as 1 hour — savings of up to 95%.

The slightly lower recall of vi.chain3.env in this table is an artefact of how the benchmark was scored: the baseline searched a background-filtered ABV subset, so contigs with close eukaryotic homologs were absent from it and count as false negatives for the .env run that did find them. Those are exactly the contigs the .env variants are meant to resolve correctly.

Source: Weinstein, Vapalahti, Kant and Smura, npj Viruses (2026), accepted; .