variant motif where? variant motif here!

vmwhere (VariantMotifwhere) is a tool for analyzing tandem repeat (microsatellite) regions from long-read sequencing data. It provides three core capabilities:

1. Discovery — identify microsatellite coordinates in a reference genome
2. Genotyping — call allele length, repeath length, and motif-level sequence decomposition at each locus
3. Visualization — generate sequence-resolved allele frequency plots

Installation

VMwhere is available as a Python package:

pip install vmwhere

Requirements

• Python >= 3.12.4

• R (>= 4.0) — required only for the visualize subcommand. Install required R packages:

  Rscript -e "install.packages(readLines('requirements-r.txt'), repos='https://cloud.r-project.org')"
  

Usage

1. Find microsatellites

Scan a reference FASTA for tandem repeat regions matching a given motif.

vmwhere find \
  --motif GGAA \
  --perfect_repeats 4 \
  --max_gap 50 \
  --buffer_size 50 \
  --fasta data/reference.fasta \
  --output_dir output/

This outputs a BED file (microsatellite_coordinates.bed) with columns: chr, start, end, region_id, motif.

Parameters

See examples/run_vmwhere_find.sh for a runnable example.

2. Genotype microsatellites

Extract reads overlapping each locus, decompose sequences into motif and non-motif segments, cluster reads by Levenshtein distance, and call alleles.

vmwhere genotype \
  --sample_id example_sample \
  --bed_file data/T2T_regions.bed \
  --bam_file data/A673_sampled_reads.sorted.bam \
  --fasta data/GCF_009914755.1_T2T-CHM13v2.0_chr6_chr10.fasta \
  --cluster_distance 4 \
  --minor_threshold 0.20 \
  --major_threshold 0.80 \
  --output_dir output/ \
  --num_processes 2

See examples/run_vmwhere_genotype.sh for a runnable example.

Parameters

Required:

Optional:

Output TSV columns

The output follows VCF-style conventions but is written as a TSV for simpler parsing.

3. Visualize alleles at a microsatellite

Generate a PDF showing sequence-resolved allele structures and their frequencies at a given locus.

vmwhere visualize \
  --genotype_tsv output/example_sample_vmwhere_results.tsv \
  --microsatellite_id chr6_region_41 \
  --min_allele_count 0 \
  --output_pdf output/chr6_region_41_visualization.pdf

See examples/run_vmwhere_visualize.sh for a runnable example.