VirStrain

VirStrain is an RNA virus strain-level identification tool for short-read sequencing data.

Overview

VirStrain supports:

• Strain identification from single-end and paired-end short reads
• Strain identification from assembled contigs
• Construction of custom VirStrain databases
• Use of pre-built public databases for common viral species

Contact

• Email: heruiliao2-c@my.cityu.edu.hk
• Recommended version: v1.18
• Legacy note: v1.14 fixed some bugs, but did not include virstrain_contig or virstrain_merge

Changelog

Requirements

Dependencies

• Python >= 3.10
  • Recommended: 3.10.19
  • Should work on python >3.11 as well
• Perl
• Python packages:
  • networkx==3.3
  • numpy==1.26.4
  • pandas==2.3.3
  • biopython==1.84
  • plotly==6.5.0
• Bowtie2
  Required for VirStrain version >= v1.18

If you use Conda, you can install required packages automatically with:

sh install_package.sh

If you install VirStrain via Bioconda or pip, you can ignore manual dependency installation.

Installation

Supported platform: Linux / Ubuntu

Option 1: Install with Bioconda

Once Bioconda is configured:

conda install -c bioconda virstrain
chmod 755 bin/jellyfish-linux

Option 2: Install with pip

pip install virstrain==1.18
chmod 755 bin/jellyfish-linux

Option 3: Manual installation

Make sure all dependencies are installed first.

git clone https://github.com/liaoherui/VirStrain.git
cd VirStrain
chmod 755 bin/jellyfish-linux
rm VirStrain_DB.tar.gz

Command mapping

If you installed VirStrain via Bioconda or pip, use the following command names:

Databases

Download the default reference database

After cloning the repository:

cd VirStrain
sh download.sh

Alternative download method

cd VirStrain
wget -qO- "https://figshare.com/ndownloader/files/34002479" | tar -zx

You may also download the database manually from Google Drive or Figshare and extract it with:

tar -zxvf <downloaded_file>

If all download methods fail, please contact the author by email.

Additional downloadable databases

DNA virus databases

sh download_dna.sh

Includes databases for:

• HBV
• HCMV

Larger SARS-CoV-2 database

sh download_scov2_big.sh

Contig-level database

sh download_contig_db.sh

Pre-built database downloads

If the download scripts fail, pre-built databases are also available via Google Drive.

Usage

If you installed VirStrain via Bioconda or pip, replace script-based commands with the corresponding installed commands shown above.

1) Identify RNA virus strains from short reads

Single-end reads

python VirStrain.py -i Test_Data/MT451123_1.fq -d VirStrain_DB/SCOV2 -o MT451123_SE_Test

Paired-end reads

python VirStrain.py -i Test_Data/MT451123_1.fq -p Test_Data/MT451123_2.fq -d VirStrain_DB/SCOV2 -o MT451123_PE_Test

High-mutation viruses such as HIV

Use the -m option.

Single-end:

python VirStrain.py -i <Read1> -d VirStrain_DB/HIV -o <Output_dir> -m

Paired-end:

python VirStrain.py -i <Read1> -p <Read2> -d VirStrain_DB/HIV -o <Output_dir> -m

2) Identify viral strains from assembled contigs

python VirStrain_contig.py -i <Input_Contig_fasta> -d VirStrain_contig_DB -o VirStrain_Contig_Res

Convert read-based databases into a contig database

python VirStrain_contigDB_merge.py -i VirStrain_DB/SCOV2,VirStrain_DB/H1N1 -o VirStrain_contig_DB_merge

3) Build a custom VirStrain database

Basic usage:

python VirStrain_build.py -i <Input_MSA> -d <Database_Dir>

Important header naming rule

Characters , and | are not allowed in sequence headers in <Input_MSA>.

Examples:

• Not allowed: >Strain_A, 2022
• Not allowed: >Strain_A|2022
• Allowed: >Strain_A_2022

Manual covering for small datasets or large viral genomes

For small strain collections (<1000 strains) or viruses with large genomes such as HCMV, you can use the manual covering function with -s to retain more useful sites.

Example:

python VirStrain_build.py -i <Input_MSA> -d <Database_Dir> -s 0.4

General guidance:

• 0.2–0.6 is usually a reasonable range for -s
• With very few strains (for example, 3 strains), a larger value such as -s 0.8 may also work

Restrict SNV site range

If you only want to use SNV sites from position x to y, use -r.

Example:

python VirStrain_build.py -i <Input_MSA> -d <Database_Dir> -s 0.4 -r 500-1000

Input format note

The input MSA must have the same format as an alignment generated by MAFFT:

https://mafft.cbrc.jp/alignment/software/

Full command-line options

VirStrain - An RNA virus strain-level identification tool for short reads.

Example:
python VirStrain.py -i Test_Data/MT451123_1.fq -p Test_Data/MT451123_2.fq -d VirStrain_DB/SCOV2 -o MT451123_PE_Test

required arguments:
    -i, --input_reads             Input FASTQ data
    -d, --database_dir            Path to VirStrain database

optional arguments:
    -h, --help                    Show help message and exit
    -o, --output_dir              Output directory (default: ./VirStrain_Out)
    -p, --input_reads2            Input FASTQ data for paired-end reads
    -c, --site_filter_cutoff      Site filtering cutoff used when calculating Vscore (default: 0.05)
    -s, --rank_by_sites           If set to 1, sort the most likely strain by site matches (default: 0)
    -f, --turn_off_figures        If set to 1, do not generate figures (default: 0)
    -m, --high_mutation_virus     Use for high mutation rate viruses such as HIV

VirStrain - An RNA virus strain-level identification tool for short reads.

Example:
python VirStrain_build.py -i <Input_MSA> -d <Database_Dir>

required arguments:
    -i, --input_msa               Input MSA file (must match MAFFT output format)

optional arguments:
    -d, --database_dir            Output directory for the constructed database (default: ./VirStrain_DB)
    -c, --dash_cutoff             Dash cutoff for each MSA column (default: 0)
    -s, --sites_cutoff            Cutoff for manual-covering function
                                  (e.g. 1 = all useful sites; 0.8 = 80% of useful sites)
    -r, --sites_rcutoff           Site range cutoff for covering algorithm
                                  (e.g. 3-500 means only SNV sites from positions 3 to 500 are considered)

Output format

VirStrain generates two primary outputs:

1. A text report

   • Contains identified strains, depth, site coverage, and related metrics

2. An interactive HTML report

   • Displays depth and site uniqueness information visually

You can find an example output in the MT451123_Sim_PE folder in this repository.

Example report image:

Report sections

Headers marked with * contain the main identification results.

Report columns

Citation

If you use VirStrain, please cite:

Liao, H., Cai, D. & Sun, Y. VirStrain: a strain identification tool for RNA viruses. Genome Biology 23, 38 (2022). https://doi.org/10.1186/s13059-022-02609-x