• VADR output files created by all VADR scripts
  • .log files
  • .cmd files
  • .filelist files
• v-build.pl output files
  • .minfo files
• v-annotate.pl output files
  • basic output files
  • .alc files
  • .alt files
  • .ftr files
  • .mdl files
  • .sgm files
  • .sqa files
  • .sqc files
  • .sda files
  • .rpn files
  • .dcr files
  • .alt.list files
  • extra output files saved with the --keep option
• VADR coords coordinate string format
• VADR sequence naming conventions

All VADR scripts (e.g. v-build.pl and v-annotate.pl) create a common set of three output files. These files are named <outdir>.vadr.<suffix> where <suffix> is either log, cmd or filelist and <outdir> is the command line argument that specifies the name of the output directory to create. These files are the three types of generic files that are supported by the Sequip ofile Perl module.

Each format is explained in more detail below.

The .log files include the same text that is printed to standard output. The documentation on v-annotate.pl and v-build.pl usage go over this output in more detail.

The .cmd files simply list all the commands run by the Perl system function internally by the VADR script, each separated by a newline. The final three lines are special. The third-to-last line lists the date and time just before the script completed execution. The second-to-last line lists system info (output by the uname -a unix command). The final line is either [ok] or [fail], depending on if the script ended successfully (zero return status) or did not (non-zero return status), respectively. If this line is [fail] it will be followed by an error message. An example .cmd output file for the example command v-build.pl -f --group Norovirus --subgroup GI NC_039897 NC_039897 is:

rm -rf NC_039897
mkdir NC_039897
/home/nawrocki/vadr-install-dir/infernal/binaries/esl-reformat --informat afa  stockholm NC_039897/NC_039897.vadr.fa > NC_039897/NC_039897.vadr.stk
/home/nawrocki/vadr-install-dir/infernal/binaries/esl-translate  -M -l 3 --watson NC_039897/NC_039897.vadr.cds.fa > NC_039897/NC_039897.vadr.cds.esl-translate.1.fa
rm NC_039897/NC_039897.vadr.cds.esl-translate.1.fa
rm NC_039897/NC_039897.vadr.cds.esl-translate.2.fa
rm NC_039897/NC_039897.vadr.cds.esl-translate.2.fa.ssi
/home/nawrocki/vadr-install-dir/ncbi-blast/bin/makeblastdb -in NC_039897/NC_039897.vadr.protein.fa -dbtype prot > /dev/null
/home/nawrocki/vadr-install-dir/infernal/binaries/esl-sfetch NC_039897/NC_039897.vadr.protein.fa NC_039897.1/5..5404:+ | /home/nawrocki/vadr-install-dir/hmmer/binaries/hmmbuild -n NC_039897/5..5404:+ --informat afa NC_039897/NC_039897.vadr.1.hmm - > NC_039897/NC_039897.vadr.1.hmmbuild
/home/nawrocki/vadr-install-dir/infernal/binaries/esl-sfetch NC_039897/NC_039897.vadr.protein.fa NC_039897.1/5388..7025:+ | /home/nawrocki/vadr-install-dir/hmmer/binaries/hmmbuild -n NC_039897/5388..7025:+ --informat afa NC_039897/NC_039897.vadr.2.hmm - > NC_039897/NC_039897.vadr.2.hmmbuild
/home/nawrocki/vadr-install-dir/infernal/binaries/esl-sfetch NC_039897/NC_039897.vadr.protein.fa NC_039897.1/7025..7672:+ | /home/nawrocki/vadr-install-dir/hmmer/binaries/hmmbuild -n NC_039897/7025..7672:+ --informat afa NC_039897/NC_039897.vadr.3.hmm - > NC_039897/NC_039897.vadr.3.hmmbuild
cat NC_039897/NC_039897.vadr.1.hmm NC_039897/NC_039897.vadr.2.hmm NC_039897/NC_039897.vadr.3.hmm > NC_039897/NC_039897.vadr.protein.hmm
rm NC_039897/NC_039897.vadr.1.hmm
rm NC_039897/NC_039897.vadr.2.hmm
rm NC_039897/NC_039897.vadr.3.hmm
cat NC_039897/NC_039897.vadr.1.hmmbuild NC_039897/NC_039897.vadr.2.hmmbuild NC_039897/NC_039897.vadr.3.hmmbuild > NC_039897/NC_039897.vadr.protein.hmmbuild
rm NC_039897/NC_039897.vadr.1.hmmbuild
rm NC_039897/NC_039897.vadr.2.hmmbuild
rm NC_039897/NC_039897.vadr.3.hmmbuild
/home/nawrocki/vadr-install-dir/hmmer/binaries/hmmpress NC_039897/NC_039897.vadr.protein.hmm > NC_039897/NC_039897.vadr.hmmpress
/home/nawrocki/vadr-install-dir/infernal/binaries/cmbuild -n NC_039897 --verbose --occfile NC_039897/NC_039897.vadr.cmbuild.occ --cp9occfile NC_039897/NC_039897.vadr.cmbuild.cp9occ --fp7occfile NC_039897/NC_039897.vadr.cmbuild.fp7occ  --noss NC_039897/NC_039897.vadr.cm NC_039897/NC_039897.vadr.stk > NC_039897/NC_039897.vadr.cmbuild
/home/nawrocki/vadr-install-dir/infernal/binaries/cmpress NC_039897/NC_039897.vadr.cm > NC_039897/NC_039897.vadr.cmpress
/home/nawrocki/vadr-install-dir/infernal/binaries/cmfetch NC_039897/NC_039897.vadr.cm NC_039897 | /home/nawrocki/vadr-install-dir/infernal/binaries/cmemit -c - > NC_039897/NC_039897.vadr.nt-cseq.fa
/home/nawrocki/vadr-install-dir/ncbi-blast/bin/makeblastdb -in NC_039897/NC_039897.vadr.nt.fa -dbtype nucl > /dev/null
rm NC_039897/NC_039897.vadr.nt-cseq.fa
# Wed May  6 18:24:56 EDT 2020
# Darwin Erics-MBP.lan 19.0.0 Darwin Kernel Version 19.0.0: Wed Oct 23 18:29:05 PDT 2019; root:xnu-6153.41.3~44/RELEASE_X86_64 x86_64
[ok]

The .filelist files list the output files created by the VADR script. This list will typically include at least those files printed in the file output file list section[log-outputfilelist] of the .log file, and sometimes more. Each line includes a brief description of each file. An example .filelist output file for the example command v-build.pl -f --group Norovirus --subgroup GI NC_039897 NC_039897 is:

# fasta file for NC_039897 saved in:                                               NC_039897.vadr.fa
# feature table format file for NC_039897 saved in:                                NC_039897.vadr.tbl
# feature table format file for YP_009538340.1 saved in:                           NC_039897.vadr.YP_009538340.1.tbl
# feature table format file for YP_009538341.1 saved in:                           NC_039897.vadr.YP_009538341.1.tbl
# feature table format file for YP_009538342.1 saved in:                           NC_039897.vadr.YP_009538342.1.tbl
# Stockholm alignment file for NC_039897 saved in:                                 NC_039897.vadr.stk
# fasta sequence file for CDS from NC_039897 saved in:                             NC_039897.vadr.cds.fa
# fasta sequence file for translated CDS from NC_039897 saved in:                  NC_039897.vadr.protein.fa
# BLAST db .phr file for NC_039897 saved in:                                       NC_039897.vadr.protein.fa.phr
# BLAST db .pin file for NC_039897 saved in:                                       NC_039897.vadr.protein.fa.pin
# BLAST db .psq file for NC_039897 saved in:                                       NC_039897.vadr.protein.fa.psq
# BLAST db .pdb file for NC_039897 saved in:                                       NC_039897.vadr.protein.fa.pdb
# BLAST db .pot file for NC_039897 saved in:                                       NC_039897.vadr.protein.fa.pot
# BLAST db .ptf file for NC_039897 saved in:                                       NC_039897.vadr.protein.fa.ptf
# BLAST db .pto file for NC_039897 saved in:                                       NC_039897.vadr.protein.fa.pto
# esl-sfetch index file for Bio::Easel::SqFile=HASH(0x7fe64f03cca0) saved in:      NC_039897.vadr.protein.fa.ssi
# HMMER model db file for NC_039897 saved in:                                      NC_039897.vadr.protein.hmm
# hmmbuild build output (concatenated) saved in:                                   NC_039897.vadr.protein.hmmbuild
# binary HMM and p7 HMM filter file saved in:                                      NC_039897.vadr.protein.hmm.h3m
# SSI index for binary HMM file saved in:                                          NC_039897.vadr.protein.hmm.h3i
# optimized p7 HMM filters (MSV part) saved in:                                    NC_039897.vadr.protein.hmm.h3f
# optimized p7 HMM filters (remainder) saved in:                                   NC_039897.vadr.protein.hmm.h3p
# hmmpress output file saved in:                                                   NC_039897.vadr.hmmpress
# CM file saved in:                                                                NC_039897.vadr.cm
# cmbuild output file saved in:                                                    NC_039897.vadr.cmbuild
# binary CM and p7 HMM filter file saved in:                                       NC_039897.vadr.cm.i1m
# SSI index for binary CM file saved in:                                           NC_039897.vadr.cm.i1i
# optimized p7 HMM filters (MSV part) saved in:                                    NC_039897.vadr.cm.i1f
# optimized p7 HMM filters (remainder) saved in:                                   NC_039897.vadr.cm.i1p
# cmpress output file saved in:                                                    NC_039897.vadr.cmpress
# fasta sequence file with cmemit consensus sequence for NC_039897 saved in:       NC_039897.vadr.nt.fa
# BLAST db .nhr file for NC_039897 saved in:                                       NC_039897.vadr.nt.fa.nhr
# BLAST db .nin file for NC_039897 saved in:                                       NC_039897.vadr.nt.fa.nin
# BLAST db .nsq file for NC_039897 saved in:                                       NC_039897.vadr.nt.fa.nsq
# BLAST db .ndb file for NC_039897 saved in:                                       NC_039897.vadr.nt.fa.ndb
# BLAST db .not file for NC_039897 saved in:                                       NC_039897.vadr.nt.fa.not
# BLAST db .ntf file for NC_039897 saved in:                                       NC_039897.vadr.nt.fa.ntf
# BLAST db .nto file for NC_039897 saved in:                                       NC_039897.vadr.nt.fa.nto
# VADR 'model info' format file for NC_039897 saved in:                            NC_039897.vadr.minfo

v-build.pl creates many output files. These files are named <outdir>.vadr.<suffix> where <outdir> is the second command line argument given to v-build.pl. The following table lists many of the output files with a brief description and in some cases further references on the file type/format. The .minfo file format is documented further below. Example files were all created with the v-build.pl -f --group Norovirus --subgroup GI NC_039897 NC_039897 command.

VADR .minfo model info files are created by v-build.pl and read by v-annotate.pl. They can also be created manually. An example model info file created by the command: v-build.pl -f --group Norovirus --subgroup GI NC_039897 NC_039897 with VADR 1.0 is:

MODEL NC_039897 blastdb:"NC_039897.vadr.protein.fa" cmfile:"NC_039897.vadr.cm" group:"Norovirus" length:"7745" subgroup:"GI"
FEATURE NC_039897 type:"gene" coords:"5..5404:+" parent_idx_str:"GBNULL" gene:"ORF1"
FEATURE NC_039897 type:"CDS" coords:"5..5404:+" parent_idx_str:"GBNULL" gene:"ORF1" product:"nonstructural polyprotein"
FEATURE NC_039897 type:"gene" coords:"5388..7025:+" parent_idx_str:"GBNULL" gene:"ORF2"
FEATURE NC_039897 type:"CDS" coords:"5388..7025:+" parent_idx_str:"GBNULL" gene:"ORF2" product:"VP1"
FEATURE NC_039897 type:"gene" coords:"7025..7672:+" parent_idx_str:"GBNULL" gene:"ORF3"
FEATURE NC_039897 type:"CDS" coords:"7025..7672:+" parent_idx_str:"GBNULL" gene:"ORF3" product:"VP2"
FEATURE NC_039897 type:"mat_peptide" coords:"5..1219:+" parent_idx_str:"1" product:"p48"
FEATURE NC_039897 type:"mat_peptide" coords:"1220..2308:+" parent_idx_str:"1" product:"NTPase"
FEATURE NC_039897 type:"mat_peptide" coords:"2309..2908:+" parent_idx_str:"1" product:"p22"
FEATURE NC_039897 type:"mat_peptide" coords:"2909..3328:+" parent_idx_str:"1" product:"VPg"
FEATURE NC_039897 type:"mat_peptide" coords:"3329..3871:+" parent_idx_str:"1" product:"Pro"
FEATURE NC_039897 type:"mat_peptide" coords:"3872..5401:+" parent_idx_str:"1" product:"RdRp"

Model info files have two types of lines:

1. Model lines begin with MODEL.
2. Feature lines begin with FEATURE.

(A third type of line is allowed: comment lines prefixed with # are allowed, and ignored.)

MODEL or FEATURE is always followed by one or more whitespace characters and then the model name <modelname> which cannot include whitespace. FEATURE lines for model <modelname> must occur after the MODEL line for <modelname>

After <modelname>, both model and feature lines contain 0 or more <key>:<value> pairs meeting the following criteria:

• <key> must not include any whitespace or : characters
• <value> must start and end with " but include no other " characters,
• <value> may include whitespace characters
• <key>:<value> pairs must be separated by one or more whitespace characters.
• <modelname> and the first <key>:<value> pair must be separated by one or more whitespace characters.

To create multiple qualifier values for the same qualifier (e.g. multiple 'note' qualifier values), separate each qualifier value by the string :GBSEP: in the <value> field. For example:

FEATURE NC_039897 type:"mat_peptide" coords:"3872..5401:+" parent_idx_str:"1" product:"RdRp" note:"this is note 1:GBSEP:this is note 2"

v-annotate.pl will use as many models as exist in the input .minfo file and input .cm files. The default VADR v1.0 set of models is 197 Caliciviridae and Flaviviridae viral genome RefSeq models. This .minfo and .cm files for this library we created by concatenating the individual .minfo and .cm files output from the corresponding 197 v-build.pl commands for each RefSeq. Additionally, all BLAST database files must be in the same directory in order to use a VADR library. Use the v-annotate.pl -m, -i and -b options to specify paths to alternative .minfo files .cm files and BLAST database directories.

v-annotate.pl creates many output files. These files are named <outdir>.vadr.<suffix> where <outdir> is the second command line argument given to v-annotate.pl. The following two tables list many of the output files with a brief description and in some cases further references on the file type/format.

There are also ten types of v-annotate.pl tabular output files with fields separated by one or more spaces, that are designed to be easily parseable with simple unix tools or scripts. These files are listed in the table below

All nine types of tabular output files share the following characteristics:

1. fields are separated by whitespace (with the possible exception of the final field)
2. comment lines begin with #
3. data lines begin with a non-whitespace character other than #
4. all lines are either comment lines or data lines

Each of these nine tabular formats are explained in more detail below. All example files linked to below, except where otherwise stated, were created by the v-annotate.pl example command v-annotate.pl $VADRSCRIPTSDIR/documentation/annotate-files/noro.9.fa va-noro.9.

.alc data lines have 8 or more fields, the names of which appear in the first two comment lines in each file. There is one data line for each alert code that occurs at least once in the input sequence file that v-annotate.pl processed. Example file.

.alt data lines have 14 or more fields, the names of which appear in the first two comment lines in each file. There is one data line for each alert instance that occurs for each input sequence file that v-annotate.pl processed. Example file.

For more information on the seq coords and mdl coords fields, which have different meanings for different alerts, see here.

For examples using a toy model of different types of alerts, see here.

.ftr data lines have 26 fields, the names of which appear in the first two comment lines in each file. There is one data line for each feature that is annotated for each input sequence file that v-annotate.pl processed. The set of possible features for each input sequence depend on its best-matching model, and can be found in the model info file. Example file.

.mdl data lines have 7 fields, the names of which appear in the first two comment lines in each file. There is one data line for each model that is the best-matching model for at least one sequence in the input file, plus 2 additional lines, a line with *all* in the model field reports the summed counts over all models, and a line with *none* in the model field reports the summed counts for all sequences that did not match any models. This information is also included in the .log output file. Example file.

.sgm data lines have 21 fields, the names of which appear in the first two comment lines in each file. There is one data line for each segment of a feature that is annotated for each input sequence file that v-annotate.pl processed. Each feature is composed of 1 or more segments, as defined by the coords field in the model info file. Example file.

.sqa data lines have 14 fields, the names of which appear in the first two comment lines in each file. There is one data line for each sequence in the input sequence file file that v-annotate.pl processed. .sqa files include annotation information for each sequence. .sqc files include classification information for each sequence. Example file.

.sqc data lines have 21 fields, the names of which appear in the first two comment lines in each file. There is one data line for each sequence in the input sequence file file that v-annotate.pl processed. .sqc files include classification information for each sequence. .sqa files include annotation information for each sequence. For more information on bit scores and bias see the Infernal User's Guide (http://eddylab.org/infernal/Userguide.pdf) Example file.

.sda files are only output if the v-annotate.pl -s option is used. .sda data lines have 16 fields, the names of which appear in the first two comment lines in each file. There is one data line for each sequence in the input sequence file file that v-annotate.pl processed. With -s, the alignment from the best-scoring blastn HSP hit is fixed (with some caveats to avoid large gaps and gaps that include start and stop codons) and used as a seed, and only the 5' and 3' regions before and after the seed region are aligned with cmalign or glsearch as described more here. .sda files include information about the seed, 5' and 3' regions. Note that the sequence length fractions in seed fraction, 5'unaln fraction, and 3'unaln fraction will not add up to 1.0 due to overlap between these regions, which is typically 100nt, but can be adjusted with the --s_overhang option to v-annotate.pl. Example file created with the command v-annotate.pl -s $VADRSCRIPTSDIR/documentation/annotate-files/noro.9.fa va-noro-s.9.

.rpn files are only output if the v-annotate.pl -r option is used. .rpn data lines have 16 fields, the names of which appear in the first two comment lines in each file. There is one data line for each sequence in the input sequence file file that v-annotate.pl processed. With -r, sequences are preprocessed with blastn and missing regions between blastn hits are identified and examined for Ns. The Ns in some of these regions are replaced with the expected nucleotides from the model as explained more here. .rpn files include information about these missing regions, referred to as gaps in the .rpn column headers and below. Example file created with the command v-annotate.pl -r $VADRSCRIPTSDIR/documentation/annotate-files/noro.9.r.fa va-noro-r.9.

.dcr data lines have 17 fields, the names of which appear in the first two comment lines in each file. There is one data line for each alignment doctoring that was performed. An alignment doctoring occurs only in rare cases. There are two types of alignment doctorings: insert type and delete types.

An insert type alignment doctoring occurs when the following criteria are met:

1. the initial alignment returned by cmalign or glsearch includes a single nucleotide insertion after the first position of a start codon or a before the final position of a stop codon

2. at least one adjacent nucleotide in the input sequence exists 5' of insert (start codon case) or 3' of insert (stop codon case)

3. the adjacent nucleotide is aligned to a reference position (is not an insertion)

4. making the adjacent nucleotide an insertion instead of the inserted position in the start/stop codon with the will result in a valid start or stop codon aligned to the reference start or stop codon

A delete type alignment doctoring occurs when the following criteria are met:

1. the initial alignment returned by cmalign or glsearch includes a gap at the first position of a start codon of a CDS in the reference model, or at the final position of a stop codon of a CDS

2. at least one adjacent nucleotide in the input sequence exists 5' of gap (start codon case) or 3' of gap (stop codon case)

3. the adjacent nucleotide is aligned to a reference position (is not an insertion)

4. swapping the gapped position in the start/stop codon with the adjacent nucleotide will result in a valid start or stop codon aligned to the reference start or stop codon

For every situation where criteria 1 to 3 above are met for either insert or delete types, a line of information will be output to the .dcr file. If criteria 4 is also met, then field 17 will be yes, otherwise it will be no.

For any doctoring that causes an existing valid start or stop codon in a nearby CDS to become invalid (even more rare), a second doctoring takes place to undo the first, and an additional line for this undoctoring will appear in the .dcr file.

The relevant code is in the parse_stk_and_add_alignment_alerts() and doctoring_check_new_codon_validity() subroutines in v-annotate.pl. The latter subroutine includes simple examples in the comments of its header section.

Example file

.alt.list files begin with a comment line that names the fields, followed by 0 or more lines with 8 tab-delimited fields. Example file.

For more information on the seq coords and mdl coords fields, which have different meanings for different alerts, see here.

For examples using a toy model of different types of alerts, see here.

When run with the --keep option, v-annotate.pl will create additional files, some of these may change based on command-line options, in particular -s and -r: There are additional options that begin with --out_ which specify that a subset of these files be output. For example the --out_stk option specifies that stockholm alignment files be output.

VADR using its own format for specifying coordinates for features and for naming subsequences in some output fasta files.

VADR coordinate strings are made up of one or more tokens with format <d1>..<d2>:<s>, where <d1> is the start position, <d2> is the end position, and <s> is the strand, either + or -, or rarely ? if unknown/uncertain. Tokens are separated by a ,. Each token defines what is referred to as a single segment in VADR code and output.

Here are some examples:

These coords strings appear in .ftr output files and as the <value> in <key>:<value> pairs in v-build.pl output model info (.minfo) files for FEATURE lines.

FASTA format sequence files output by VADR use a specific naming convention for naming sequences.

Specifically, when naming a new subsequence, VADR scripts will append a / character followed by a VADR coordinates string to sequence names to indicate the positions (and strand) of the original sequence the new subsequence derives from. v-annotate.pl will create names in a similar manner, but sometimes will add an additional string that defines the feature being annotated. Here are some examples: