Metadata-Version: 2.4
Name: visuamitra
Version: 1.0.1
Summary: A Tandem Repeats visualization tool for Decomposition of Motifs and Methylation across alleles.
License: MIT
Requires-Python: >=3.8
Description-Content-Type: text/markdown
Requires-Dist: fastapi
Requires-Dist: uvicorn
Requires-Dist: pysam
Requires-Dist: pandas
Requires-Dist: python-multipart
Requires-Dist: bitarray
Requires-Dist: regex

# VisuaMiTRA - a Tandem Repeat Visualizer

<div align="center">
  <img src="./assets/vis_logo1.png" alt="Workflow" width="100">
  <p><i>VisuaMiTRa</i></p>
</div>

**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 files into an accessible and navigable landscape.

# Motivation

The high-resolution genotypes and methylation profiles generated by [**ATaRVa**](https://github.com/SowpatiLab/ATaRVa) require an integrated perspective to be clearly interpreted. VisuaMiTRa is the essential next step, transforming VCF data outputs into an interactive landscape 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](#motivation)
* [Installation](#installation)
* [Usage](#usage)
  * [Workflow](#workflow)
  * [Features](#features)
* [Data Requirements](#data-requirements)
* [Citation](#citation)
* [Contacts](#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)
```python -m venv venv
source venv/bin/activate  # On Windows use: venv\Scripts\activate
```

### Install the package
```
pip install visuamitra
```

# Usage

#### Browser mode
Once installed, to launch the tool and manually select or upload your VCF files via the web interface:
```Bash
visuamitra
```

#### CLI Mode

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

```Bash
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

<div align="center">
  <img src="./assets/vis_flowchart.png" alt="Workflow" width="500">
  <p><i>Fig 1: Workflow of visuamitra</i></p>
</div>

 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.

<div align="center">
  <img src="./assets/vis_overview1.png" alt="Workflow" width="600">
  <p><i>Fig 2: Overview of visuamitra</i></p>
</div>

## ✨ 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 individuals or cohorts.


#### 🧬 Dual View for Motifs & Methylation

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

#### 📍 Effortless Navigation
* Target specific loci using coordinate inputs (Chr, Start, End) or manually browse thousands of records smoothly and an interactive with a track of physical context in Chromosome.

<div align="center">
  <img src="./assets/vis_LocPicker1.png" alt="Workflow" width="600">
  <p><i>Fig 3: Location inputs </i></p>
</div>

<div align="center">
  <img src="./assets/vis_Ideogram.png" alt="Workflow" width="600">
  <p><i>Fig 4: Chromosome context </i></p>
</div>

#### 📏 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.


<div align="center">
  <img src="./assets/vis_decomp.png" alt="Workflow" width="600">
  <p><i>Fig 5: Repeat counts </i></p>
</div>
<div align="center">
  <img src="./assets/vis_meth.png" alt="Workflow" width="600">
  <p><i>Fig 6: Methylation markers </i></p>
</div>


#### 💾 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.

  <div align="center">
  <img src="./assets/vis_download.png" alt="Workflow" width="180" >
  <p><i>Fig 6: Download options </i></p>
</div>


 [↑ Back to Top](#visuamitra---a-tandem-repeat-visualizer)


## 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



