visuamitra 1.0.3

A Tandem Repeats visualization tool for Decomposition of Motifs and Methylation across alleles.

VisuaMiTRA - a Tandem Repeat Visualizer

VisuaMiTRa

VisuaMiTRa (pronounced vi-shu-uh-mee-truh, IPA: /vɪʃuəmiːtrə/, Sanskrit: विश्वमित्र) is a specialized visualization tool for Tandem Repeat alleles, designed for a concise overview of motif decomposition, and corresponding epigenetic methylation signals. The name expands to VISUAlisation of Motifs & Methylation in Tandem Repeat Alleles.

The name is derived from the Sanskrit word Vishvamitra (विश्वमित्र), meaning "Friend of the Universe." In this context, VisuaMiTRa acts as a companion to the researcher, providing a clear comprehensive overview of tandem repeat complexity. By layering structural motifs and methylation data into a single, intuitive interface, it transforms dense genomic variant files into an accessible and navigable landscape.

Motivation

The high-resolution genotypes and methylation profiles generated by ATaRVa (v0.6.0) require an integrated perspective to be clearly interpreted. VisuaMiTRa is the essential next step, transforming VCF data outputs into a visual interface where structural motifs and epigenetic methylation signals align. Providing this overview enables researchers to rapidly validate and navigate ATaRVa's results at scale.

Table of Contents

• Motivation
• Installation
• Usage
  • Workflow
  • Features
• Data Requirements
• Citation
• Contacts

Installation

VisuaMiTRa is available as a Python package that manages both the backend server and the compiled frontend automatically.

Prerequisites: Python 3.9+ and htslib (for Tabix functionality).

Create and activate a python environment (recommended)

source venv/bin/activate  # On Windows use: venv\Scripts\activate

Install the package

pip install visuamitra

Usage

Visuamitra v1.0.1 is compatible with ATaRVa v0.6.0

Browser mode

Once installed, to launch the tool and manually select or upload your VCF files via the web interface:

visuamitra

CLI Mode

Rather than browser upload, passing the vcf file path as argument will launch visuamitra.

visuamitra /path/to/your/file.vcf.gz

Note: The corresponding .tbi index file must reside in the same directory as the target .vcf.gz file, with same name (e.g., file.vcf.gz.tbi).

Access: The application will initialize and host the interface on port 8088. Open your web browser and navigate to http://localhost:8088.

Workflow

Fig 1: Workflow of visuamitra

VisuaMiTRa uses a high-performance backend designed for rapid random access and minimal memory overhead.

Data Ingestion: Users provide a Tabix-indexed VCF file and its .tbi index (generated by ATaRVa).

Validation: FastAPI performs a preflight check using pysam to ensure the requested genomic region exists, preventing empty streams and invalid coordinate errors.

Pagination: To handle large data, the tool uses Base64-encoded cursors which allows to 'bookmark' positions and fetch subsequent pages without re-scanning entire files.

Optimized Streaming: Data is streamed in small chunks and delivered in real-time to ensure the tool remains fast and lightweight, even with very large files.

Reactive Visualization: React parses the TSV stream into an interactive SVG canvas, mapping structural motifs and methylation probabilities in real-time.

Fig 2: Overview of visuamitra

✨ Features

VisuaMiTRa provides a comprehensive and intuitive overview of tandem repeat complexity.

👥 Multi-Sample Comparative Analysis (New in v1.0.0)

VisuaMiTRa now supports the simultaneous visualization of multiple samples from a merged VCF.

• Dynamic Selection: Choose which samples to display using a searchable dropdown menu.

• Synchronized Scaling: All selected samples are rendered on a shared genomic scale, allowing for direct visual comparison of allele lengths, motifs and methylation patterns across cohorts.

🧬 Dual View for Motifs & Methylation

• VisuaMiTRa features independent tabs for motif decomposition & methylation that maintain strict allele-length consistency, enabling precise comparison across multiple samples.

📍 Effortless Navigation

• Target specific loci using coordinate inputs (Chr, Start, End) or manually browse thousands of records smoothly, alongside an indicator with a track of genomic context in Chromosome. (Note: visuamitra v1.0.1 currently supports Hg38 reference only.)

Fig 3: Location inputs

Fig 4: Chromosome context

📏 Interactive Interface

• Magnify in or out of intricate regions to ease data interpretation.

• Hover over motif segments to instantly view repeat counts. Methylation levels markers for clearer visualisation.

• Customize view with professional color palettes, scales & fonts.

Fig 5: Repeat counts

Fig 6: Methylation markers

💾 Download plots (New in v1.0.0)

• Publication-Ready SVGs: Download high-resolution vector graphics of the viewed genomic locations.

• Genomic plots could also be downloaded as PNG/JPGs.

Fig 7: Download options

↑ Back to Top

Contacts

Authors: Siddharth K, Abishek Kumar, Divya Tej Sowpati

Email: Siddharth K - siddharthk at csirccmb dot org

Abishek Kumar S - abishekks at csirccmb dot org

Divya Tej Sowpati - tej at csirccmb dot org