Mpox virus annotation - NLM-DIR/vadr GitHub Wiki

• Changes from the previous (1.4.2-1) MPXV models

• How to interpret VADR alert and error messages
• Explanation of options used in example annotation

The steps below explain how to use VADR for MPXV validation and annotation. These are only recommendations. Testing of VADR for MPXV is still ongoing and these recommendations are subject to change, possibly significantly. Many 'good' MPXV sequences that do not contain any sequencing or assembly artifacts may 'fail' v-annotate.pl using the steps below.

GenBank is not currently using VADR to automatically process MPXV sequence submissions like it does for SARS-CoV-2. GenBank MPXV sequence submissions are still all manually reviewed, but indexers might use VADR as part of their analysis, using the command-line options listed in step 4 below.

WARNING: VADR is slower for long sequences like MPXV than for shorter viral genomes. In tests on 1415 recent GenBank MPXV genomes with the 1.7-2 models and the options in step 4, annotation took about 11 seconds per genome on average, compared with about 40 seconds per genome with the previous (1.4.2-1) models and options. Some sequences may still take longer.

Steps for using VADR for MPXV annotation:

1. Download and install VADR 1.7.3 (or any later version), following the instructions on this page. The MPXV models in step 2 require VADR 1.7 or later. Alternatively, you can use one of the StaPH-B VADR docker images created by Curtis Kapsak (docker image name: staphb/vadr), available on dockerhub and quay. The README files for the docker images are here. Use an image with VADR 1.7 or later.

   NOTE: the vadr-install.sh script for VADR 1.7.3, and the StaPH-B MPXV docker images (with tags ending in -mpxv), include the older 1.4.2-1 MPXV models. Download the 1.7-2 MPXV models in step 2 even if you used either of these.

2. Download the latest MPXV VADR models (version 1.7-2, gzipped tarball) from here, unpack them (e.g. tar xfz <tarball.gz>). Note the path to the directory name created (<mpxv-models-dir-path>) for step 4.

3. Remove terminal ambiguous nucleotides from your input fasta sequence file using the fasta-trim-terminal-ambigs.pl script in $VADRSCRIPTSDIR/miniscripts/. GenBank processing of viral sequences typically includes removing ambiguous nucleotides from the beginning and ends of sequences, and also removing sequences that are less than 50nt or more than 210,000nt (after trimming).

   WARNING: the fasta-trim-terminal-ambigs.pl script will not exactly reproduce the trimming that the GenBank pipeline does in some rare cases, but should fix the large majority of the discrepancies you might see between local VADR results and GenBank results.

   To remove terminal ambiguous nucleotides from your sequence file <input-fasta-file> and to remove short and long sequences to create a new trimmed file <trimmed-fasta-file>, execute:

$VADRSCRIPTSDIR/miniscripts/fasta-trim-terminal-ambigs.pl --minlen 50 --maxlen 210000 <input-fasta-file> > <trimmed-fasta-file>

4. Run the v-annotate.pl program on an input trimmed fasta file with MPXV sequences using the recommended command and options below (the command is long so you will likely have to scroll to the right to view the entire command).

   NOTE: The following command runs multithreaded on up to 4 CPUs, and so is only recommended if you have at least 4 CPUs and 16Gb RAM available. To run on <n> CPUs instead, replace --cpu 4 with --cpu <n>. To run single threaded on a single CPU remove the --split --cpu 4 options. The --split and --cpu options are incompatible with -p.

v-annotate.pl --nomisc --split --cpu 4 -r --glsearch --minimap2 -s --r_lowsimok --r_lowsimxd 100 --r_lowsimxl 5000 --alt_pass discontn,dupregin --s_overhang 1000 --lowsim5seq 30 --lowsim3seq 30 --xnumali 20 --mkey mpxv --mdir <mpxv-models-dir-path> <fasta-file-to-annotate> <output-directory-to-create>

As of October 2026, the VADR model library for MPXV annotation (vadr-models-mpxv-1.7-2 model file) includes four models, one per MPXV clade:

#CDS is the number of CDS features in the model, including alternative CDS features: NC_063383 has 2 for OPG036 (alternative start codons) and PP601216 has 2 for OPG175 (alternative stop codons). For the three GenBank references, CDS features were added at loci that the GenBank record annotates as a gene and a misc_feature (or does not annotate), where an intact or repaired open reading frame exists. The RELEASE-NOTES.txt file in the model tarball lists each of these changes.

All four models have group MPXV, and the subgroup is the clade (Ia, Ib, IIa or IIb). v-annotate.pl classifies each input sequence to the best-matching model, so the model chosen is effectively the clade call. An INDEFINITE_CLASSIFICATION (indfclas) alert is reported for a sequence whose best and second-best models are from different clades and score closely. This alert does not cause a sequence to fail. Classification between clades is more accurate with a fix for overlapping blastn hits that is expected in a future VADR release.

Each model has an indfstrn_exc exception on the MODEL line of mpxv.minfo for the inverted terminal repeats at the two ends of the genome, so that an indfstrn (INDEFINITE_STRAND) alert is not reported because of the repeated sequence (for example, positions 1..6422 and 190788..197209 of NC_063383).

Some model features have exceptions so that alerts that are expected in normal MPXV sequences do not cause a sequence to fail:

• OPG047 (all four models), OPG174 and OPG176 (NC_063383), and OPG201 (PP601206 and PP601216) are marked misc_not_failure: most alerts that would normally be fatal in these features do not cause a sequence to fail, and the affected CDS is instead annotated as a misc_feature (see here). OPG201 contains a TA dinucleotide repeat whose length varies between sequences and shifts the reading frame.
• Low similarity exceptions (lowsim_exc) cover regions where sequences commonly differ from the reference in repeat length: a Thr-Asp repeat in OPG197 (clade I models), the (TAGAT)n repeat between OPG021 and OPG022 (clade I models), an AT-rich repeat upstream of OPG208 (PV993193, PP601216 and NC_063383), and the tips of the terminal hairpin loop (PV993193).
• In PP601216 (clade Ib), OPG153 has a frameshift exception (fst_exc) over a poly-Asp repeat, and OPG164 has an insertion exception (insertn_exc) over a short repeat where clade Ib assemblies often carry a run of Ns.

The 00README.txt and RELEASE-NOTES.txt files in the model tarball have more details.

The model source files are also available in the vadr-models-mpxv repository (tag vadr-models-mpxv-1.7-2).

The previous MPXV model library (1.4.2-1, July 2022) included a single clade IIb model based on NC_063383, with group Orthopoxvirus and subgroup Monkeypox_virus. The 1.7-x models (October 2026) add models for clades Ia, Ib and IIa, apply the per-gene fixes described above, and change the recommended v-annotate.pl options (adding --minimap2, --s_overhang 1000, --lowsim5seq 30, --lowsim3seq 30 and --xnumali 20).

In tests on 1415 recent GenBank MPXV genomes, the fraction of sequences with less than 3% Ns that passed changed from the 1.4.2-1 models and options to the 1.7-2 models and options as follows:

The mean annotation time per genome went from about 40 seconds to about 11 seconds.

This section shows output from an example v-annotate.pl annotation of three MPXV sequences from GenBank using the above command and options.

The fasta file of those three sequences can be downloaded here.

(A similar example for norovirus sequences, which may contain more details on certain aspects, is here.)

For this example, VADR 1.7.3 is installed in /usr/local/vadr-install-1.7.3, the MPXV model directory is in /usr/local/vadr-models-mpxv-1.7-2 and the pretrim.mpxv.3.fa sequence file is in the current directory. We will create a new file mpxv.3.fa with trimmed sequences in the next step.

As explained above, remove terminal ambiguous nucleotides and sequences that are shorter than 50nt or longer than 210,000nt with the command:

$VADRSCRIPTSDIR/miniscripts/fasta-trim-terminal-ambigs.pl --minlen 50 --maxlen 210000 pretrim.mpxv.3.fa > mpxv.3.fa

Next, to annotate the trimmed sequences using the above v-annotate.pl options for MPXV, run the following command (scroll to the right to see full command), which will create a new directory called my3 into which VADR output files will be written.

v-annotate.pl --nomisc --split --cpu 4 -r --glsearch --minimap2 -s --r_lowsimok --r_lowsimxd 100 --r_lowsimxl 5000 --alt_pass discontn,dupregin --s_overhang 1000 --lowsim5seq 30 --lowsim3seq 30 --xnumali 20 --mkey mpxv --mdir /usr/local/vadr-models-mpxv-1.7-2 mpxv.3.fa my3

The options used are explained further below.

When you execute the above command, you should see output similar to the following block that lists relevant environment variable values, and input arguments and options:

# v-annotate.pl :: classify and annotate sequences using a model library
# VADR 1.7.3 (Sep 2026)
# - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -
# date:              Fri Oct 16 12:32:52 2026
# $VADRBIOEASELDIR:  /usr/local/vadr-install-1.7.3/Bio-Easel
# $VADRBLASTDIR:     /usr/local/vadr-install-1.7.3/ncbi-blast/bin
# $VADREASELDIR:     /usr/local/vadr-install-1.7.3/infernal/binaries
# $VADRFASTADIR:     /usr/local/vadr-install-1.7.3/fasta/bin
# $VADRINFERNALDIR:  /usr/local/vadr-install-1.7.3/infernal/binaries
# $VADRMINIMAP2DIR:  /usr/local/vadr-install-1.7.3/minimap2
# $VADRMODELDIR:     /usr/local/vadr-install-1.7.3/vadr-models-mpxv
# $VADRSCRIPTSDIR:   /usr/local/vadr-install-1.7.3/vadr
#
# sequence file:                                                                    mpxv.3.fa
# output directory:                                                                 my3
# specify that alert codes in <s> do not cause FAILure:                             discontn,dupregin [--alt_pass]
# .cm, .minfo, blastn .fa files in $VADRMODELDIR start with key <s>, not 'vadr':    mpxv [--mkey]
# model files are in directory <s>, not in $VADRMODELDIR:                           /usr/local/vadr-models-mpxv-1.7-2 [--mdir]
# in feature table for failed seqs, never change feature type to misc_feature:      yes [--nomisc]
# lowsim5s/LOW_SIMILARITY_START minimum length is <n>:                              30 [--lowsim5seq]
# lowsim3s/LOW_SIMILARITY_END minimum length is <n>:                                30 [--lowsim3seq]
# align with glsearch from the FASTA package, not to a cm with cmalign:             yes [--glsearch]
# number of alignments to keep in blastx output and consider if --xlongest is <n>:  20 [--xnumali]
# use top-scoring HSP from blastn to seed the alignment:                            yes [-s]
# for -s, set length of nt overhang for subseqs to align to <n>:                    1000 [--s_overhang]
# use minimap2 to derive seed and use it if >= length of blastn seed:               yes [--minimap2]
# replace stretches of Ns with expected nts, where possible:                        yes [-r]
# with -r, do not report lowsim{5,3,i}s within identified N-rich regions:           yes [--r_lowsimok]
# w/--r_lowsimok, maximum length of N-rich region is <n>:                           5000 [--r_lowsimxl]
# w/--r_lowsimok, max diff from expected length for N-rich region is <n>:           100 [--r_lowsimxd]
# split input file into chunks, run each chunk separately:                          yes [--split]
# parallelize across <n> CPU workers (requires --split or --glsearch):              4 [--cpu]
# - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -

Next, v-annotate.pl will output information as it proceeds through different steps of the analysis:

# Validating input                                                                                          ... done. [    0.2 seconds]
# Splitting sequence file into chunks to run independently in parallel on 4 processors                      ... done. [    0.1 seconds]
# Executing 3 scripts in parallel on 4 processors to process 3 partition(s) of all 3 sequence(s)            ... 
#	   2 of    3 jobs finished (0.1 minutes spent waiting)
#	   3 of    3 jobs finished (0.2 minutes spent waiting)
# done. [   50.2 seconds]
# Merging and finalizing output                                                                             ... done. [    0.5 seconds]

With the --split --cpu 4 options, the input fasta script is split up into chunks, in this case placing one sequence per chunk but typically about 2 sequences per chunk for larger files, and runs v-annotate.pl separately on those chunks on 4 different CPUs in parallel. When all sequences are finished processing the main script merges the output together.

The v-annotate.pl output then includes a summary of the classification of sequences, and the alerts reported:

# Summary of classified sequences:
#
#                                  num   num   num
#idx  model      group  subgroup  seqs  pass  fail
#---  ---------  -----  --------  ----  ----  ----
1     NC_063383  MPXV   IIb          3     3     0
#---  ---------  -----  --------  ----  ----  ----
-     *all*      -      -            3     3     0
-     *none*     -      -            0     0     0
#---  ---------  -----  --------  ----  ----  ----
#
# Summary of reported alerts:
#
#     alert     causes   short                            per    num   num  long
#idx  code      failure  description                     type  cases  seqs  description
#---  --------  -------  --------------------------  --------  -----  ----  -----------
1     indfclas  no       INDEFINITE_CLASSIFICATION   sequence      3     3  low score difference between best overall model and second best model (not in best model's subgroup)
2     extrant5  no       EXTRA_SEQUENCE_START        sequence      1     1  extra sequence detected 5' of expected sequence start
3     extrant3  no       EXTRA_SEQUENCE_END          sequence      2     2  extra sequence detected 3' of expected sequence end
4     dupregin  no       DUPLICATE_REGIONS           sequence     73     3  similarity to a model region occurs more than once
5     discontn  no       DISCONTINUOUS_SIMILARITY    sequence      3     3  not all hits are in the same order in the sequence and the homology model
6     ambgntrp  no       N_RICH_REGION_NOT_REPLACED  sequence      4     3  N-rich region of unexpected length not replaced
#---  --------  -------  --------------------------  --------  -----  ----  -----------

And finally a list of the output files created:

# Output printed to screen saved in:                              my3.vadr.log
# List of executed commands saved in:                             my3.vadr.cmd
# List and description of all output files saved in:              my3.vadr.filelist
# esl-seqstat -a output for input fasta file saved in:            my3.vadr.seqstat
# 5 column feature table output for passing sequences saved in:   my3.vadr.pass.tbl
# 5 column feature table output for failing sequences saved in:   my3.vadr.fail.tbl
# list of passing sequences saved in:                             my3.vadr.pass.list
# list of failing sequences saved in:                             my3.vadr.fail.list
# list of alerts in the feature tables saved in:                  my3.vadr.alt.list
# fasta file with passing sequences saved in:                     my3.vadr.pass.fa
# fasta file with failing sequences saved in:                     my3.vadr.fail.fa
# per-sequence tabular classification summary file saved in:      my3.vadr.sqc
# per-model tabular summary file saved in:                        my3.vadr.mdl
# per-sequence tabular annotation summary file saved in:          my3.vadr.sqa
# per-feature tabular summary file saved in:                      my3.vadr.ftr
# per-model-segment tabular summary file saved in:                my3.vadr.sgm
# per-alert tabular summary file saved in:                        my3.vadr.alt
# alert count tabular summary file saved in:                      my3.vadr.alc
# alignment doctoring tabular summary file saved in:              my3.vadr.dcr
# seed alignment summary file (-s) saved in:                      my3.vadr.sda
# replaced stretches of Ns summary file (-r) saved in:            my3.vadr.rpn
#
# All output files created in directory ./my3/
#
# Elapsed time:  00:00:51.20
#                hh:mm:ss
# 
[ok]

Note that all the output files will be in the newly created my3 directory. The Summary of classified sequences listed that all three sequences were classified to the clade IIb model NC_063383 and that all three passed. The file my3.vadr.pass.list, lists the three sequences that passed:

ON803440.1
ON853669.1
ON843168.1

and my3.vadr.fail.list is empty because no sequences failed.

Also, FASTA-formatted sequence files for each the passing and failing sequences are my3.vadr.pass.fa and my3.vadr.fail.fa (here my3.vadr.fail.fa is empty).

The Summary of reported alerts lists six types of alerts, none of which cause a sequence to fail:

• indfclas (INDEFINITE_CLASSIFICATION) was reported for all three sequences, because the score difference between the best model (NC_063383, clade IIb) and the second-best model (PV993193, clade IIa) was about 0.02 bits per nucleotide, below the default threshold of 0.03 (--indefclass).
• extrant5 and extrant3 (EXTRA_SEQUENCE_START and EXTRA_SEQUENCE_END) report 5 or 11 extra nucleotides beyond the ends of the NC_063383 reference sequence.
• dupregin and discontn are expected because of the repeated sequence in MPXV genomes and do not cause failure because of the --alt_pass discontn,dupregin option.
• ambgntrp (N_RICH_REGION_NOT_REPLACED) reports N-rich regions that the -r option did not replace with expected nucleotides.

For the three sequences that passed, the annotation is available in the output my3.vadr.pass.tbl file. Sequences that fail would have their annotation in the my3.vadr.fail.tbl file, followed by a list of the ERRORs that caused them to fail (here my3.vadr.fail.tbl is empty).

Here is the output for the second sequence in the my3.vadr.pass.tbl file: (with the middle of the table removed for brevity)

>Feature ON853669.1
1572	832	gene
			gene	OPG001
1572	832	CDS
			product	Chemokine binding protein
			protein_id	ON853669.1_1
2748	1699	gene
			gene	OPG002
2748	1699	CDS
			product	Crm-B secreted TNF-alpha-receptor-like protein
			protein_id	ON853669.1_2
4604	2838	gene
			gene	OPG003
4604	2838	CDS
			product	Ankyrin repeat protein (25)
			protein_id	ON853669.1_3

...snip...

190988	192301	gene
			gene	OPG015
190988	192301	CDS
			product	Ankyrin repeat protein (39)
			protein_id	ON853669.1_176
192537	194303	gene
			gene	OPG003
192537	194303	CDS
			product	Ankyrin repeat protein (25)
			protein_id	ON853669.1_177
194393	195442	gene
			gene	OPG002
194393	195442	CDS
			product	Crm-B secreted TNF-alpha-receptor-like protein
			protein_id	ON853669.1_178
195569	196309	gene
			gene	OPG001
195569	196309	CDS
			product	Chemokine binding protein
			protein_id	ON853669.1_179

Feature table format is described at https://www.ncbi.nlm.nih.gov/WebSub/html/help/feature-table.html.

In earlier versions of this example, which used VADR 1.5 and the 1.4.2-1 MPXV models, ON803440.1 failed because of an INDEFINITE_ANNOTATION_END (indf3pst) ERROR in the CPXV166 protein CDS (OPG159). With VADR 1.7.3 and the 1.7-2 models it passes. In general, a VADR ERROR doesn't mean that there is a problem with a sequence, just that there is a difference from the reference that might indicate a problem. It also might represent normal sequence divergence in the virus. Many of the VADR ERRORs are meant to highlight potential problems for manual review or regions of interest to the user.

The annotation information is also available in other files with different formats, such as the my3/my3.vadr.ftr file, which may be easier to parse for some applications.

For examples of alerts/errors and more information on how to interpret the VADR output related to those alerts in the output feature tables, .alt.list file and the GenBank submission portal detailed error report .tsv files, see this vadr documentation page.

See the vadr README documentation section for more information on how to interpret VADR results and output, including information on file formats.

You can find information on the VADR 1.0 paper and a published article that describes some of the acceleration strategies that VADR uses for viruses with relatively long genomes (below).

The options used in the above command are the recommended set of options for MPXV annotation. These options are currently used by GenBank indexers when they run VADR for validating and annotating incoming MPXV sequence submissions. (All submissions are currently manually reviewed, no automated processing/approval using VADR is in place for MPXV sequences at this time.) The options are each briefly explained in the table below. More information can be found here.

The -r option is also used for SARS-CoV-2 annotation with VADR, for more information on the option in that context, see this page

The -s option is also used for SARS-CoV-2 annotation with VADR, for more information on the option in that context, see this page

• VADR README
• VADR installation instructions
  • Installation using vadr-install.sh
  • Setting environment variables
  • Verifying successful installation
  • Further information
• v-build.pl example usage and command-line options
  • v-build.pl example usage
  • v-build.pl command-line options
  • Building a VADR model library
  • How the VADR 1.0 model library was constructed
• v-annotate.pl example usage, command-line options and alert information
  • v-annotate.pl example usage
  • v-annotate.pl command-line options
  • Basic Information on v-annotate.pl alerts
  • Additional information on v-annotate.pl alerts
• Explanations and examples of v-annotate.pl detailed alert and error messages
  • Output fields with detailed alert and error messages
  • Explanation of sequence and model coordinate fields in .alt files
  • toy50 toy model used in examples of alert messages
  • Examples of different alert types and corresponding .alt output
  • Posterior probability annotation in VADR output Stockholm alignments
• VADR output file formats
  • VADR output files created by all VADR scripts
  • v-build.pl output files
  • v-annotate.pl output files
  • VADR coords coordinate string format
  • VADR sequence naming conventions
• Using VADR for SARS-CoV-2 annotation

• The recommended citation for using VADR is: Alejandro A Schäffer, Eneida L Hatcher, Linda Yankie, Lara Shonkwiler, J Rodney Brister, Ilene Karsch-Mizrachi, Eric P Nawrocki; VADR: validation and annotation of virus sequence submissions to GenBank. BMC Bioinformatics 21, 211 (2020). https://doi.org/10.1186/s12859-020-3537-3

• The following article describes changes made to VADR for faster SARS-CoV-2 annotation which are also applied to MPXV sequences in the sequences above: Eric P Nawrocki; Faster SARS-CoV-2 sequence validation and annotation for GenBank using VADR. NAR Genom Bioinform. Vol 5, Issue 1 (2023) https://doi.org/10.1093/nargab/lqad002