proletract 0.2.0

A user-friendly platform for interactive exploration, visualization, and analysis of tandem repeat findings from TandemTwister outputs

This repository contains a Tandem Repeat Visualization Tool that serves as the companion tool to TandemTwister. The tool processes Variant Call Format (VCF) files generated by TandemTwister and visualize tandem repeats in an intuitive, interactive format. Users can explore motifs, compare alleles to the reference sequence, and gain insights into the structure of tandem repeats, enhancing their ability to interpret genomic variation.

Why ProleTRact?

TRs are complex: alleles can differ by motif composition, length, and interrupted blocks. ProleTRact visulize TR regions with color-coded motifs, highlights interruptions, and provides intuitive navigation across regions and samples, enabling quick insight into potentially pathogenic expansions or atypical structures.

Key Features

• Individual and Cohort modes: Analyze a single VCF or an entire directory of VCFs.
• Dynamic sequence visualization: Color-coded motifs, clear interruption highlighting, and side-by-side allele comparison.
• Pathogenic TR reference overlay: Built-in pathogenic_TRs.bed provides context for known loci (disease, gene, thresholds).
• Fast navigation: Move across TR records with Previous/Next controls or jump to a specific region.

Installation Options

Pick the workflow that fits your environment:

Option A — Install from PyPI (recommended)

pip install proleTRact
proleTRact  # launches the Streamlit app

The launcher opens a browser locally. On headless machines set STREAMLIT_SERVER_HEADLESS=true before invoking proleTRact.

Option B — Clone and run locally (with conda)

git clone [e-mail]:Lionward/ProleTRact.git
cd ProleTRact
conda create -n proletract python=3.9
conda activate proletract
pip install -r requirements.txt
pip install -e .
streamlit run src/proletract/app.py

Quickstart

1. Launch the app with one of the commands above.
2. Open the browser tab (Streamlit prints the URL if you are headless).
3. Load an individual VCF or cohort folder from the sidebar and start exploring tandem repeats.

Usage

Individual mode 👤

1. Select individual sample in the sidebar.
2. Provide the absolute path to a bgzipped and tabix-indexed VCF (.vcf.gz with .tbi):
   • Enter the path in the sidebar input, then click Upload VCF File.
   • The app will parse records and enable navigation across TR variants.
3. Use Previous/Next to step through records or jump to a region like chr1:1000-2000.
4. Inspect motif blocks, interruptions, and per-allele differences.

Cohort mode 👥👥

1. Select Cohort in the sidebar and choose Reads-based VCF or Assembly VCF view.
2. Provide the absolute path to a directory containing TandemTwister VCF files:
3. Click Load Cohort to scan the directory and enable cohort navigation.
4. Browse records and compare across samples.
5. Use Previous/Next to step through records or jump to a region like chr1:1000-2000.
6. Inspect motif blocks, interruptions, and per-allele differences.

Input Requirements

• VCF format: Standard VCF generated by TandemTwister.
• Cohort directory: A folder with multiple .vcf.gz files generated by TandemTwister is required for cohort mode.

Demo / Examples

Example screenshots and short walkthrough GIFs will be added here. For now, you can open example.svg for a preview:

• Planned: Individual-mode walkthrough
• Planned: Cohort-mode walkthrough

Contributing

Contributions are welcome! Please open an issue to discuss changes.

License

This project is licensed under the BSD 3-Clause Non-Commercial License — see LICENSE for details. Commercial use is prohibited. This software is intended for academic research, educational purposes, and personal/private use only. For commercial licensing inquiries, please contact the author.

Citation

If you use ProleTRact in your work, please cite this repository. A formal citation entry will be added once available.