|
iVar
|
| Command | Description |
|---|---|
| trim | Trim reads in aligned BAM |
| variants | Call variants from aligned BAM file |
| filtervariants | Filter variants across replicates |
| consensus | Call consensus from aligned BAM file |
| getmasked | Detect primer mismatches and get primer indices for the amplicon to be masked |
| removereads | Remove reads from trimmed BAM file |
| version | Show version information |
| trimadapter | (EXPERIMENTAL) Trim adapter sequences from reads |
To view detailed usage for each command type ivar <command> Note : Commands maked (EXPERIMENTAL) are still under active development.
iVar uses primer positions supplied in a BED file to soft clip primer sequences from an aligned and sorted BAM file. Following this, the reads are trimmed based on a quality threshold(Default: 20). To do the quality trimming, iVar uses a sliding window approach(Default: 4). The windows slides from the 5' end to the 3' end and if at any point the average base quality in the window falls below the threshold, the remaining read is soft clipped. If after trimming, the length of the read is greater than the minimum length specified(Default: 30), the read is written to the new trimmed BAM file.
To sort and index an aligned BAM file, the following command can be used,
Note: All the trimming in iVar is done by soft-clipping reads in an aligned BAM file. This information is lost if reads are extracted in fastq or fasta format from the trimmed BAM file.
Command:
Example Usage:
The command above will produce a trimmed BAM file test.trimmed.bam after trimming the aligned reads in test.bam using the primer positions specified in test_primers.bed and a minimum quality threshold of 15, minimum read length of 50 and a sliding window of 4.
Example BED file
iVar uses the output of the samtools mpileup command to call variants - single nucleotide variants(SNVs) and indels. In order to call variants correctly, the samtools mpileup command must be run with the reference fasta supplied using the options(–reference or -f). The output of samtools pileup is then piped into ivar variants to generate a .tsv file with the following fields,
There are two parameters that can be set for variant calling using iVar - minimum quality(Default: 20) and minimum frequency(Default: 0.03). Minimum quality is the minimum quality for a base to be used in frequency calculations at a given position. Minimum frequency is the minimum frequency required for a SNV or indel to be reported.
Command:
Example Usage:
The command above will generate a test.tsv file.
Example of output .tsv file.
Description
| Field | Description |
|---|---|
| REGION | Region from BAM file |
| POS | Position on reference sequence |
| REF | Reference base |
| ALT | Alternate Base |
| REF_DP | Depth of reference base |
| REF_RV | Depth of reference base on reverse reads |
| REF_QUAL | Mean quality of reference base |
| ALT_DP | Depth of alternate base |
| ALT_RV | Deapth of alternate base on reverse reads |
| ALT_QUAL | Mean quality of alternate base |
| ALT_FREQ | Frequency of alternate base |
| TOTAL_DP | Total depth at position |
| PVAL | p-value of fisher's exact test |
| PASS | Result of p-value <= 0.05 |
Note: Please use the -B options with samtools mpileup to call variants and generate consensus. When a reference sequence is supplied, the quality of the reference base is reduced to 0 (ASCII: !) in the mpileup output. Disabling BAQ with -B seems to fix this. This was tested in samtools 1.7 and 1.8.
Under the hood, iVar calls an Awk script to get an intersection of variants(in .tsv files) called from any number of replicates. This intersection will filter out any SNVs that do not pass the filters(in the variant calling step) in all the replicates. Fields that are different across replicates(fields apart from REGION, POS, REF, ALT) will have the filename added as a suffix.
Command:
Example Usage:
The command above will prodoce an output .tsv file test.filtered.tsv.
Example output of filtered .tsv file from two files test_rep1.tsv and test_rep2.tsv
Description of fields
| No | Field | Description |
|---|---|---|
| 1 | REGION | Common region across all replicate variant tsv files |
| 2 | POS | Common position across all variant tsv files |
| 3 | REF | Common reference base across all variant tsv files |
| 4 | ALT | Common alternate base across all variant tsv files |
| 5 | REF_DP_<rep1-tsv-file-name> | Depth of reference base in replicate 1 |
| 6 | REF_RV_<rep1-tsv-file-name> | Depth of reference base on reverse reads in replicate 1 |
| 7 | REF_QUAL_<rep1-tsv-file-name> | Mean quality of reference base in replicate 1 |
| 8 | ALT_DP_<rep1-tsv-file-name> | Depth of alternate base in replicate 1 |
| 9 | ALT_RV_<rep1-tsv-file-name> | Deapth of alternate base on reverse reads in replicate 1 |
| 10 | ALT_QUAL_<rep1-tsv-file-name> | Mean quality of alternate base in replicate 1 |
| 11 | ALT_FREQ_<rep1-tsv-file-name> | Frequency of alternate base in replicate 1 |
| 12 | TOTAL_DP_<rep1-tsv-file-name> | Total depth at position in replicate 1 |
| 13 | PVAL_<rep1-tsv-file-name> | p-value of fisher's exact test in replicate 1 |
| 14 | PASS_<rep1-tsv-file-name> | Result of p-value <= 0.05 in replicate 1 |
| 15 | Continue rows 5 - 14 for every replicate provided |
To generate a consensus sequence iVar uses the output of samtools mpileup command. The mpileup output must be piped into ivar consensus. There are five parameters that can be set - minimum quality(Default: 20), minimum frequency threshold(Default: 0), minimum depth to call a consensus(Default: 1), a flag to exclude nucleotides from regions with depth less than the minimum depth and a character to call in regions with coverage lower than the speicifed minimum depth(Default: '-'). Minimum quality is the minimum quality of a base to be considered in calculations of variant frequencies at a given position. Minimum frequency threshold is the minimum frequency that a base must match to be called as the consensus base at a position. If one base is not enough to match a given frequency, then an ambigious nucleotide is called at that position. Minimum depth is the minimum required depth to call a consensus. If '-k' flag is set then these regions are not included in the consensus sequence. If '-k' is not set then by default, a '-' is called in these regions. You can also specfy which character you want to add to the consensus to cover regions with depth less than the minimum depth. This can be done using -n options. It takes onr of two values: '-' or 'N'.
As an example, consider a position with 6As, 3Ts and 1C. The table below shows the consensus nucleotide called at different frequencies.
| Minimum frequency threshold | Consensus |
|---|---|
| 0 | A |
| 0.5 | A |
| 0.6 | A |
| 0.7 | W(A or T) |
| 0.9 | W (A or T) |
| 1 | H (A or T or C) |
If there are two nucleotides at the same frequency, both nucleotides are used to call an ambigious base as the consensus. As an example, consider a position wiht 6 Ts, 2As and 2 Gs. The table below shows the consensus nucleotide called at different frequencies.
| Minimum frequency threshold | Consensus |
|---|---|
| 0 | T |
| 0.5 | T |
| 0.6 | T |
| 0.7 | D(A or T or G) |
| 0.9 | D(A or T or G) |
| 1 | D(A or T or G) |
The output of the command is a fasta file with the consensus sequence and a .txt file with the average quality of every base used to generate the consensus at each position. For insertions, the quality is set to be the minimum quality threshold since mpileup doesn't give the quality of bases in insertions.
Command:
Example Usage:
The command above will produce a test.fa fasta file with the consensus sequence and a test.qual.txt with the average quality of each base in the consensus sequence.
iVar uses a .tsv file with variants to get the zero based indices(based on the BED file) of mismatched primers. This command requires another .tsv file with each line containing the left and right primer names separated by a tab. This is used to get both the primers for an amplicon with a single mismatched primer. The output is a text file with the zero based primer indices delimited by a space. The output is written to a a text file using the prefix provided.
Command:
Example BED file
Example primer pair information file
Example Usage:
The command above produces an output file - test.masked.txt.
Example Output:
This command accepts an aligned and sorted BAM file trimmed using ivar trim and removes the reads corresponding to the supplied primer indices, which is the output of ivar getmasked command. Under the hood, ivar trim adds the zero based primer index(based on the BED file) to the BAM auxillary data for every read. Hence, ivar removereads will only work on BAM files that have been trimmed using ivar trim.
Command:
Example Usage:
The ivar trim command above trims test.bam and produced test.trimmed.bam with the primer indice data added. The ivar removereads command produces an output file - test.trimmed.masked.bam after removing all the reads corresponding to primer indices - 1,2,7 and 8.
Note: This feature is under active development and not completely validated yet.
trimadapter in iVar can be used to trim adapter sequences from fastq files using a supplied fasta file.
1.8.14