TITLE: MultiQuas (Multiple reference quasispecies reconstruction protocol)
AUTHORS: Marco  Cacciabue

[DESCRIPTION]
<div class = "text-blocks"><div class = "text-block">The following protocol summarizes the major steps to run the MultiQuas pipeline to evaluate viral variability and reconstruct the viral quasispecies from NGS data (particularly Miseq reads). It is based on the assumption that 1 o more known references are available. These references could be obtained using other haplotype reconstruction softwares. Nonetheless, it is recommended that only a few trusted references are used. </div><br/><br/></div>

[STEPS]
?. [Brief pipeline description]
Reads are trimmed and filtered using
?. [Brief pipeline description]
Filtered and trimmed reads are aligned to a set of user-defined references (multifasta format) with
?. [Brief pipeline description]
Reads are then split into different classes (one for each reference and one for the unmapped reads) using
?. [Brief pipeline description]
For each class,  reads are merged usingand then haplotypes are reconstructed withImportant note: If the time limit is reached this step is repeated with a subset of the reads in order to reduce computation time and resources required by QuRe. Steps include 0.99, 0.9, 0.8, 0.7, 0.6 and 0.5 proportions of the toal reads for each class in that order.
?. [Brief pipeline description]
Next, the proportions of each haplotype class (predicted by QuRe) are adjusted to reflect the number of reads of the corresponding class.
?. [Brief pipeline description]
All reconstructed haplotypes are aligned to the first reference in the multifasta file using
?. [Brief pipeline description]
Additionally, reads are then aligned to the first reference in the multifasta file. Single Nucleotide Variants (SNVs) are called using
?. [Brief pipeline description]
Finally, concordance between the SNVs (expected minor allele frequency) from the predicted quasispecies and the Lofreq variants using an in-house R script. Higher value of R-squared indicates a better quasispecies reconstruction. Important: this step does not meant as a validation of the obtained results, but it allows the user to choose between different haplotypes reconstructions.
?. [Installing docker]
In order to run the pipeline, a wrapper file is available (bash) which automatically perfoms all the above numbered steps. A docker image is available that includes all the necessary dependencies. If you do not yet have docker installed, do so at this time, and ensure that is in your PATH. For more information please visit https://www.docker.com/get-started
?. [Installing docker]
The docker image ("multiquas") is available at Docker hub To pull the image, use the command below:This will download and install the corresponding docker image. Only has to be run the first time (it may take several minutes depending on your internet connection)
?. [Installing docker]
Alternatively, If you don't want to use Docker, you can install all dependencies by yourself (only for linux users). The dependencies are:BCFtools v1.8 (or later version) http://www.htslib.org/download/Samtools v1.8 (or later version) http://www.htslib.org/download/Bowtie2 v2.2.4 http://bowtie-bio.sourceforge.net/bowtie2/index.shtmlPEAR https://cme.h-its.org/exelixis/web/software/pear/doc.htmlseqtk https://github.com/lh3/seqtkbbmap https://jgi.doe.gov/data-and-tools/bbtools/bb-tools-user-guide/bbduk-guide/Lofreq v2 https://csb5.github.io/lofreq/mafft https://mafft.cbrc.jp/alignment/software/R v4.1 (or later version) https://www.r-project.org/R package seqinr https://cran.r-project.org/web/packages/seqinr/index.htmlR package ape https://cran.r-project.org/web/packages/ape/R package VariantAnnotation https://bioconductor.org/packages/release/bioc/html/VariantAnnotation.htmlR package Biostrings https://bioconductor.org/packages/release/bioc/html/Biostrings.htmlR package ggplot2 https://ggplot2.tidyverse.org/R package ggrepel https://cran.r-project.org/web/packages/ggrepel/vignettes/ggrepel.htmland contact the author for the most up-to-date wrapper scripts.
?. [Preparing analysis]
Depending on your operating system follow these steps
?. [Preparing analysis]
On windows: open a windows terminal (WIN + R), type "cmd" and press enter. A Windows terminal should be up and running.
?. [Preparing analysis]
Create a folder to work with and navigate to the location for your new folder. For example:
?. [Preparing analysis]
Copy the fastq files and the reference file (1 or more sequences to use as references in multifasta format) to the test_dir folder.
?. [Preparing analysis]
On linux the steps are similar.
?. [Preparing analysis]
Open a terminal (ctrl + alt + T), A bash terminal should be up and running.
?. [Preparing analysis]
Create a folder to work with and navigate to the location for your new folder. For example:
?. [Preparing analysis]
Copy the fastq files and the reference file (1 or more sequences to use as references in multifasta format) to the test_dir folder.
?. [Running MultiQuas workflow]
The following command will create a docker container, mount the test_dir folder into the container and perform all the necessary step of the MultiQuas workflow.
Backups files of the fastq reads and reference should be made and store in a different location before running the following command in order to prevent loss of data.
?. [Running MultiQuas workflow]
For Windows:The user should replace each of the following: OUTPUT_FOLDER: folder name inside test_dir to automatically save all files.R1.fq and R2.fq: corresponding names of the paired-end reads (use the correct extension in case you have .fastq)REFERENCE.fasta: name of the fasta file to use.Optional paramenters can be set:-l: use to indicate a specific label (default: SAMPLE)-p/--proc: Number of threads to use (default=2)-m/--mem: ram memmory available to use by the java machine (default=4).--min_quality: Phred value cutoff for filtering the reads (default=25)--timeout: seconds (per reference) before shutting down QuRe in case it freezes (default=600). Each time, the reads are downsampled and the step is repeated (6 times per reference)Optional paramenters can be set:-l: use to indicate a specific label (default: SAMPLE)-p/--proc: Number of threads to use (default=2)-m/--mem: ram memmory available to use by the java machine (default=4).--min_quality: Phred value cutoff for filtering the reads (default=25)--timeout: seconds (per reference) before shutting down QuRe in case it freezes (default=600). Each time, the reads are downsampled and the step is repeated (6 times per reference)
?. [Running MultiQuas workflow]
For linux:The user should replace each of the following: OUTPUT_FOLDER: folder name inside test_dir to automatically save all files.R1.fq and R2.fq: corresponding names of the paired-end reads.REFERENCE.fasta: name of the fasta file to use.Optional paramenters can be set:-l: use to indicate a specific label (default: SAMPLE)-p/--proc: Number of threads to use (default=2)-m/--mem: ram memmory available to use by the java machine (default=4).--min_quality: Phred value cutoff for filtering the reads (default=25)--timeout: seconds (per reference) before shutting down QuRe in case it freezes (default=600). Each time, the reads are downsampled and the step is repeated (6 times per reference)Optional paramenters can be set:-l: use to indicate a specific label (default: SAMPLE)-p/--proc: Number of threads to use (default=2)-m/--mem: ram memmory available to use by the java machine (default=4).--min_quality: Phred value cutoff for filtering the reads (default=25)--timeout: seconds (per reference) before shutting down QuRe in case it freezes (default=600). Each time, the reads are downsampled and the step is repeated (6 times per reference)
?. [Output files]
Regardless of the operating system a set of folders should be created:Filtering: Filtered and trimmed reads are stored here.Multiple_Aligning: Alignment files are stored here.unmapped: reads extracted from the alignment are stored here.Additionally, for each reference a corresponding folder will be created.lofreq: the alignment to the first reference is store here. Also you will find the variant.vcf file here.A set of output files will also be saved in test_dir/OUTPUT_FOLDER. Most relevant are:SAMPLE_haplotypes.fasta (and SAMPLE_haplotypes_aligned.fasta): the reconstructed haplotypes (first sequence is always the first sequence in the REFERENCE.fasta file and should NOT be considered an haplotype).SAMPLE_adjusted_proportions.txt: proportions of each reconstructed haplotype.SAMPLE_graphs.png: Concordance graph between lofreq and the reconstructed haplotypes. It should include a linear regression equation (the higher R-squared the better)A set of output files will also be saved in test_dir/OUTPUT_FOLDER. Most relevant are:SAMPLE_haplotypes.fasta (and SAMPLE_haplotypes_aligned.fasta): the reconstructed haplotypes (first sequence is always the first sequence in the REFERENCE.fasta file and should NOT be considered an haplotype).SAMPLE_adjusted_proportions.txt: proportions of each reconstructed haplotype.SAMPLE_graphs.png: Concordance graph between lofreq and the reconstructed haplotypes. It should include a linear regression equation (the higher R-squared the better)