ATaRVa (pronounced uh-thur-va, IPA: /əθərvə/, Sanskrit: अथर्व) is a technology-agnostic tandem repeat genotyper, specially designed for long read data. The name expands to Analysis of Tandem Repeat Variation, and is derived from the the Sanskrit word Atharva meaning knowledge.
Long-read sequencing propelled comprehensive analysis of tandem repeats (TRs) in genomes. Current long-read TR genotypers are either platform specific or computationally inefficient. ATaRva outperforms existing tools while running an order of magnitude faster. ATaRVa also supports short-read data, multi-threading, haplotyping, and motif decomposition, making it an invaluable tool for population scale TR analyses.
ATaRVa can be directly installed using pip with the package name ATaRVa.
$ pip install ATaRVaAlternatively, it can be installed from the source code:
# Download the git repo
$ git clone https://github.com/SowpatiLab/ATaRVa.git
# Install
$ cd ATaRVa
$ python -m build
$ pip install .Both of the methods add a console command atarva, which can be executed from any directory
ATaRVa can also be installed using the provided Docker image with the following steps:
$ cd ATaRVa
$ docker build --network host -t atarvaThe help message and available options can be accessed using
$ atarva -h
# or
$ atarva --helpwhich gives the following output
usage: atarva [-h] -f <FILE> -b <FILE> [<FILE> ...] -r <FILE> [--format <STR>] [-q <INT>]
[--contigs CONTIGS [CONTIGS ...]] [--min-reads <INT>] [--max-reads <INT>]
[--snp-dist <INT>] [--snp-count <INT>] [--snp-qual <INT>] [--flank <INT>]
[--snp-read <FLOAT>] [--phasing-read <FLOAT>] [-o <FILE>]
[--karyotype KARYOTYPE [KARYOTYPE ...]] [-t <INT>] [--haplotag <STR>]
[--decompose] [-log] [-v]
Required arguments:
-f <FILE>, --fasta <FILE>
input reference fasta file
-b <FILE> [<FILE> ...], --bam <FILE> [<FILE> ...]
samples alignment files. allowed formats: SAM, BAM, CRAM
-r <FILE>, --regions <FILE>
input regions file. the regions file should be strictly in bgzipped
tabix format. If the regions input file is in bed format. First sort it
using bedtools. Compress it using bgzip. Index the bgzipped file with
tabix command from samtools package.
Optional arguments:
--format <STR> format of input alignment file. allowed options: [cram, bam, sam]. default: [bam]
-q <INT>, --map-qual <INT>
minimum mapping quality of the reads to be considered. [default: 5]
--contigs CONTIGS [CONTIGS ...]
contigs to get genotyped [chr1 chr12 chr22 ..]. If not mentioned every
contigs in the region file will be genotyped.
--min-reads <INT> minimum read coverage after quality cutoff at a locus to be genotyped. [default: 10]
--max-reads <INT> maximum number of reads to be used for genotyping a locus. [default: 100]
--snp-dist <INT> maximum distance of the SNP from repeat region to be considered for
phasing. [default: 3000]
--snp-count <INT> number of SNPs to be considered for phasing (minimum value = 1).
[default: 3]
--snp-qual <INT> minimum basecall quality at the SNP position to be considered for
phasing. [default: 13]
--flank <INT> length of the flanking region (in base pairs) to search for insertion
with a repeat in it. [default: 10]
--snp-read <FLOAT> a positive float as the minimum fraction of snp's read contribution to
be used for phasing. [default: 0.25]
--phasing-read <FLOAT>
a positive float as the minimum fraction of total read contribution from
the phased read clusters. [default: 0.4]
-o <FILE>, --vcf <FILE>
name of the output file, output is in vcf format. [default: sys.stdout]
--karyotype KARYOTYPE [KARYOTYPE ...]
karyotype of the samples [XY XX]
-t <INT>, --threads <INT>
number of threads. [default: 1]
--haplotag <STR> use haplotagged information for phasing. eg: [HP]. [default: None]
--decompose write the motif-decomposed sequence to the vcf. [default: False]
-log, --debug_mode write the debug messages to log file. [default: False]
-v, --version show program's version number and exit
The details of each option are given below:
Expects: FILE
Default: None
The -f or --fasta option is used to specify the input FASTA file. The corresponding index file (.fai) should be in the same directory. ATaRVa uses pysam's FastaFile parser to read the input FASTA file.
Expects: FILE
Default: None
The -b or --bam option is used to specify one or more input alignment files in the same format. ATaRVa accepts any of the three alignment formats: SAM, BAM, or CRAM. The alignment file should be sorted by coordinates. The format should be specified using the --format option. The corresponding index file (.bai or .csi) should be located in the same directory. An alignment file can be sorted and indexed using the following commands:
# to sort the alignment file
$ samtools sort -o sorted_output.bam input.bam
# to generate .bai index file
$ samtools index -b sorted_output.bamAn alignment file containing at least one of the following tags is preferred for faster processing: MD tag, CS tag, or a CIGAR string with =/X operations.
- The CS tag is generated using the --cs option when aligning reads with the minimap2 aligner. (
--cs=shortis prefered over--cs=long) - The MD tag can be generated using the --MD option in minimap2.
If the alignment files were generated without any of these tags, you can generate the MD tag by running the following command to
# input: reference genome fasta file & alignment file
# output: an alignment file with MD tag in it
# for generating MD tag
$ samtools calmd -b aln.bam ref.fa > aln_md.bamExpects: FILE
Default: None
The -r or --regions option is used to specify the input TR regions file. ATaRVa requires a sorted, bgzipped BED file of TR repeat regions, along with its corresponding tabix-indexed file. The BED file should contain the following columns:
- Chromosome name where TR is located
- Start position of the TR
- End position of the TR
- Repeat motif
- Motif length
Below is an example of a repeat region BED file. NOTE: The BED file should either have no header or a header that starts with # symbol. The .gz and .tbi files should be in same directory
| #CHROM | START | END | MOTIF | MOTIF_LEN |
|---|---|---|---|---|
| chr1 | 10000 | 10467 | TAACCC | 6 |
| chr1 | 10481 | 10497 | GCCC | 4 |
| chr2 | 10005 | 10173 | CCCACACACCACA | 13 |
| chr2 | 10174 | 10604 | ACCCTA | 6 |
| chr17 | 60483 | 60491 | AGA | 3 |
To sort, bgzip, and index the BED file, use the following commands:
# input: Unsorted bed file
# output: Sorted bed file
# Sorting the BED file using sort
$ sort -k1,1 -k2,2n input.bed > sorted_output.bed
# or using bedtools
$ bedtools sort -i input.bed > sorted_output.bed# input: Sorted bed file
# output: bgzipped bed file
# To keep the original file unchanged and generate separate gz file
$ bgzip -c sorted_output.bed > sorted_output.bed.gz
# or to compress the original file; converts sorted_output.bed to sorted_output.bed.gz
$ bgzip sorted_output.bed# input: bgzipped bed file
# output: tabix indexed file (.tbi)
# install samtools to use tabix
$ tabix -p bed sorted_output.bed.gzExpects: STRING
Default: bam
This option sets the format of the alignment file. The default format is BAM. Specify the input format as sam for SAM files, cram for CRAM files, or bam for BAM files.
Expects: INTEGER
Default: 5
Minimum mapping quality for the reads to be considered. All reads with a mapping quality below the specified value will be excluded during genotyping.
Expects: STRING
Default: None
Specify the chromosome(s) for genotyping; repeat loci on all other chromosomes will be skipped. If no chromosomes are mentioned, repeats on all chromosomes in the BED file will be genotyped. eg: --contigs chr1 chr12 chr22 will genotype only the repeat loci in these mentioned chromosomes in the BED file.
Expects: INTEGER
Default: 10
Minimum number of the supporting reads required to genotype a locus. If the number of reads is less than this value, the locus will be skipped.
Expects: INTEGER
Default: 100
Maximum number of supporting reads allowed for a locus to be genotyped. If the number of reads exceeds this limit, only this specified number of reads will be used for genotyping the locus.
Expects: INTEGER
Default: 3000
Maximum base pair (bp) distance from the flanks of the repeat locus to fetch SNPs from each read considered for phasing.
Expects: INTEGER
Default: 3
Maximum number of SNPs to be used for read clustering and phasing.
Expects: INTEGER
Default: 13
Minimum Q value of the SNPs to be used for phasing.
Expects: INTEGER
Default: 10
The number of base pairs in the flanking regions to be used for realignment.
Expects: FLOAT
Default: 0.2
Minimum fraction of SNPs in the supporting reads of the repeat locus allowed for phasing.
Expects: FLOAT
Default: 0.4
Minimum fraction of reads required in both clusters relative to the total supporting reads for the repeat locus after phasing.
Expects: STRING (to be used as filename)
Default: Input Alignment Filename + .vcf
If this option is not provided, the default output filename will be the same as the input alignment filename, with its extension replaced with '.vcf'. For example, if the input filename is input.bam, the default output filename will be input.vcf. If the input filename does not have any extension, .vcf will be appended to the filename.
Each entry includes the fields specified in the Variant Calling Format (VCF), as described in the table below.
| FIELD | DESCRIPTION |
|---|---|
| CHROM | Chromosome that contains the repeat region |
| POS | Start position of the repeat region |
| ID | Region identifier (set to '.') |
| REF | Reference sequence of the repeat region |
| ALT | Sequence of the repeat alleles in the sample |
| QUAL | Quality score of the genotype (set to '0') |
| FILTER | Filter status (PASS, LESS_READS) |
| INFO | Information about the TR region |
| FORMAT | Data type of the genotype information |
| SAMPLE | Values of the genotype information for the TR region |
The INFO field describes the general structure of the repeat region and includes the following details:
| INFO | DESCRIPTION |
|---|---|
| AC | Total number of respective ALT alleles in called genotypes |
| AN | Total number of alleles in called genotypes |
| MOTIF | Motif of the repeat region |
| END | End position of the repeat region |
The FORMAT fields and their values are provided in the last two columns of the VCF file, containing information about each genotype call. These columns include the following fields:
| FORMAT | DESCRIPTION |
|---|---|
| GT | Genotype of the sample |
| AL | Length of the alleles in base pairs |
| SD | Number of supporting reads for each alleles |
| DP | Number of the supporting reads for the repeat locus |
| SN | Number of SNPs used for phasing |
| SQ | Phred-scale qualities of the SNPs used for phasing |
| DS | Motif decomposed sequence of the alternate alleles |
NOTE: Loci missing in the VCF either have no reads mapped to them, contain reads that do not fully enclose the repeat region, or have reads with low mapping quality (mapQ).
Expects: STRING
Default: XX
Karyotype of the samples eg. XX or XY.
Expects: INTEGER
Default: 1
Number of threads to use for the process.
Expects: STRING
Default: None
Specify the haplotype tag to utilize phased information for genotyping. eg HP
Performs motif-decomposition on ALT sequences.
NOTE: Only applicable for motif length <= 10
Prints the version info of ATaRVa.
The following examples assume the input reference genome is in FASTA format and is named ref.fa, the alignment file is in BAM format and is named input.bam, and the TR regions file is in BED format and is named regions.bed.gz.
To run ATaRVa with default parameters, use the following command:
$ atarva -f ref.fa --bam input.bam -r regions.bed.gzTo run ATaRVa with sex chromosome karyotype, use the following command:
$ atarva -f ref.fa --bam input.bam -r regions.bed.gz --karyotype XYWith multiple bams:
$ atarva -f ref.fa --bam input1.bam input2.bam -r regions.bed.gz --karyotype XY XXTo run ATaRVa on haplotagged alignment file, use the folowing command:
$ atarva -f ref.fa --bam input.bam -r regions.bed.gz --haplotag HPTo run ATaRVa with stringent parameters, use the following command:
$ atarva -q 20 --snp-count 5 --snp-qual 25 --min-reads 20 -t 32 -fi ref.fa --bam input.bam -r regions.bed.gz
# The above command with --snp-count 5 will use a maximum of five heterozygous SNPs to provide accurate genotypes, but only when phasing is based on SNPs and not on length.To genotype TRs from specific chromosomes only, run ATaRVa with the following command:
$ atarva --contigs chr9 chr15 chr17 chrX -t 32 -f ref.fa --bam input.bam -r regions.bed.gz# input cram file
$ atarva --format cram -f ref.fa --bam input.cram -r regions.bed.gz
# input sam file
$ atarva --format sam -f ref.fa --bam input.sam -r regions.bed.gzTo run ATaRVa in docker container, use the following command:
$ docker run -i -t --rm -v /path_of_necessary_files/:/folder_name atarva:latest -f /folder_name/ref.fa --bam /folder_name/input.bam -r /folder_name/regions.bed.gzIn all the above examples, the output of ATaRVa is saved to input.vcf unless -o is specified.
- Added
--haplotagargument to enable the use of haplotag information for genotyping. - Fixed bugs in SNP-based clustering.
- Replaced the use of the mode function with a consensus-based approach for final allele derivation.
- Removed
PCtag from the FORMAT field of the output VCF.
- Modified input arguments.
- Added a Mac OS compatible
.sofile.
- First release.
If you find ATaRVa useful for your research, please cite it as follows:
ATaRVa: Analysis of Tandem Repeat Variation from Long Read Sequencing data
Abishek Kumar Sivakumar, Sriram Sudarsanam, Anukrati Sharma, Akshay Kumar Avvaru, Divya Tej Sowpati
BioRxiv, doi: https://doi.org/10.1101/2025.05.13.653434
For queries or suggestions, please contact:
Divya Tej Sowpati - tej at csirccmb dot org
Abishek Kumar S - abishekks at csirccmb dot org
Akshay Kumar Avvaru - avvaruakshay at gmail dot com