VAMPIRE - VAriation and Motif Patterns In tandem REpeats

Getting Started

# Install
mamba create -n vampire python=3.10 -y
mamba activate vampire
mamba install vampire-tr 

# Annotate TRs on genomes
vampire scan <fasta> <prefix>

# Annotate single TR locus across population
vampire anno <fasta> <prefix>

# Generate simulated TR sequences
vampire generator -m GGC -l 1000 -r 0.01 -p <prefix>
vampire generator -m GGC GGT -l 1000 -r 0.01 -p <prefix>

# Calculate the identity matrix for TR sequences
vampire identity -w 5 <anno_prefix> <identity_prefix>

See Docs for more details.

Table of Contents

• Getting Started
• Introduction
• Why VAMPIRE?
• Installation
• Usage
  • Annotate TRs on genome
  • Annotate single TR locus across population
  • Generate simulated TR sequences
  • Calculate identity matrix
• Getting Help
• Citing VAMPIRE

Introduction

VAMPIRE is a unified framework for de novo tandem repeat (TR) annotation and analysis. It systematically characterizes copy number variation, motif variation and structural variation within TR arrays.

By representing TR arrays as hierarchical motif compositions and quantifying copy-number changes, motif substitutions, and array restructuring across samples, VAMPIRE transforms raw sequence data into standardized, interpretable, and queryable repeat-variation matrices. Through its AnnData-based data model, VAMPIRE enables seamless integration with downstream analysis workflows.

Read the documentation. Open an issue or create a pull request if you would like to contribute.

Why VAMPIRE?

• Beyond Copy Number: VAMPIRE uncovers not only copy number but also internal variation.
• Flexible and Comprehensive: Its customizable parameters support the annotation of a wide range of TRs, from short tandem repeats (STRs) and variable number tandem repeats (VNTRs) to megabase-scale satellite arrays.
• Analysis Ecosytem: VAMPIRE contains vp.anno.pp, vp.anno.pl, vp.anno.tl modules for analysis and plotting.

Installation

# Install by pip 
mamba create -n vampire python=3.10 -y
mamba activate vampire
mamba install vampire-tr 

Usage

VAMPIRE contains several subcommands. Here we list scan, anno, generator and identity.

scan - Annotate TRs on genome

VAMPIRE can scan genome assemblies or long sequences to detect tandem repeat (TR) loci. It uses a multi-scale k-mer smoothness approach to identify candidate regions, followed by banded alignment to annotate period and copy number for each locus.

# Scan a genome with 8 threads
vampire scan -t 8 genome.fa genome_scan

# Output results in BED format
vampire scan --format bed genome.fa genome_scan

anno - Annotate single TR locus across population

One of the primary uses of VAMPIRE is to annotate tandem repeat (TR) sequences from input files in FASTA format. A typical command is as follows:

# de novo annotate TR sequences
vampire anno -t 8 <fasta> <prefix>

where -t sets the number of threads, tests/001-anno_STR.fa is the input sequences, and tests/001-anno_STR is the output prefix. By default, VAMPIRE use the built-in base motif database to refine and label motifs. This database includes pCht/StSat in Pan and human alpha-satellite mononers from the paper:

Altemose N, Logsdon G A, Bzikadze A V, et al. Complete genomic and epigenetic maps of human centromeres[J]. Science, 2022, 376(6588): eabl4178.

For more detailed instructions and examples, refer to the VAMPIRE Docs.

generator - Generate simulated TR sequences

VAMPIRE can generate simulated TR sequences with single or multiple given motif(s), user-defined length and mutation rate. The default random seed is 42. To change the random seed, use the -s option.

# Generate simulated TR sequences
vampire generator -m GGC -l 1000 -r 0.01 -p tests/002-generator_reference
vampire generator -m GGC GGT -l 1000 -r 0.01 -p tests/002-generator_reference

This command will output three files:

• tests/002-generator_reference.fa: the simulated TR sequences in FASTA format.
• tests/002-generator_reference.anno.tsv: the annotation results with mutations.
• tests/002-generator_reference.fa.anno_woMut.tsv: the annotation results without mutations.

identity - Calculate the identity matrix for TR sequences

VAMPIRE uses alignment-based method to calculate the identity matrix for TR sequences.

# Calculate the identity matrix for TR sequences
vampire identity -t 20 -w 30 <anno_prefix> <identity_prefix>

By default, VAMPIRE do not account for insertion and deletion events when generating the identity matrix. To include such events within a specific length range, use the --max-indel and --min-indel options to set the maximum and minimum indel lengths to consider.

After generating the identity matrix, you can visualize the identity heatmap using vp.anno.pl.tracksplot().

Getting Help

For detailed description of options, please see VAMPIRE Docs. If you have further questions, want to report a bug, or suggest a new feature, please raise an issue at the issue page.

Citating VAMPIRE

If you use VAMPIRE in your work, please cite:

To be updated