proletract 1.1.0
ProleTRact - Tandem Repeat Visualization Tool
Requires Python: >=3.9
Keywords: tandem repeat, VCF, visualization, bioinformatics, genomics

<div align="center">
 <img width="300" alt="grafik" src="assets/ProleTRact_logo.svg">
  </p>
</div>
<br />
<p>This repository contains a <strong>Tandem Repeat Visualization Tool</strong> that serves as the companion tool to <a href="https://github.com/Lionward/TandemTwister"><strong>TandemTwister</strong></a>. 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.</p>

<h2>Why ProleTRact?</h2>
<p>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.</p>

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

<h2>Installation</h2>
<p><strong>Requirements:</strong> Python 3.9, 3.10, 3.11, or 3.12 (Python 3.13+ may require building dependencies from source)</p>
<p>Install from PyPI:</p>
<pre><code>pip install proletract
proletract --install-deps  # launches the web application</code></pre>
<p>The launcher starts both the backend API server (port 8502) and frontend web server (port 3000). The application will open in your browser automatically. On headless machines, access the frontend at <code>http://localhost:3000</code> after starting the application.</p>
<p><strong>Note:</strong> If you encounter build errors (e.g., with Python 3.13+), ensure you're using Python 3.9–3.12, or install system dependencies: <code>liblzma-dev</code> (Ubuntu/Debian) or <code>xz-devel</code> (RHEL/CentOS/Fedora).</p>

<h2>Quickstart</h2>
<ol>
  <li>Launch the app with the command above: <code>proletract</code></li>
  <li>Open the browser tab to <code>http://localhost:3000</code> (the URL will be shown in the terminal if you're running headless).</li>
  <li>Load an individual VCF or cohort folder from the sidebar and start exploring tandem repeats.</li>
</ol>

<h2>Usage</h2>
<h3>Individual mode 👤</h3>
<ol>
  <li>Select <strong>individual sample</strong> in the sidebar.</li>
  <li>Provide the absolute path to a bgzipped and tabix-indexed VCF (<code>.vcf.gz</code> with <code>.tbi</code>):
    <ul>
      <li>Enter the path in the sidebar input, then click <strong>Load VCF</strong>.</li>
      <li>The app will parse records and enable navigation across TR variants.</li>
    </ul>
  </li>
  <li>Use <strong>Previous</strong>/<strong>Next</strong> to step through records or jump to a region like <code>chr1:1000-2000</code>.</li>
  <li>Inspect motif blocks, interruptions, and per-allele differences.</li>
</ol>

<h3>Cohort mode  👥👥</h3>
<h4>Reads-based VCF</h4>
<ol>
  <li>Select <strong>Cohort</strong> in the sidebar and choose <em>Reads-based VCF</em> view.</li>
  <li>Provide the absolute path to a directory containing TandemTwister VCF files.</li>
  <li>Click <strong>Load Cohort</strong> to scan the directory and enable cohort navigation.</li>
  <li>Browse records and compare across samples.</li>
  <li>Use <strong>Previous</strong>/<strong>Next</strong> to step through records or jump to a region like <code>chr1:1000-2000</code>.</li>
  <li>Inspect motif blocks, interruptions, and per-allele differences.</li>
</ol>

<h4>Assembly VCF </h4>
<ol>
  <li>Select <strong>Cohort</strong> in the sidebar and choose <em>Assembly VCF</em> view.</li>
  <li>Provide the absolute path to a directory containing TandemTwister VCF files.</li>
  <li>Click <strong>Load Cohort</strong> to scan the directory and enable cohort navigation.</li>
  <li>Browse records and compare across samples.</li>
  <li>Use <strong>Previous</strong>/<strong>Next</strong> to step through records or jump to a region like <code>chr1:1000-2000</code>.</li>
  <li>Inspect motif blocks, interruptions, and per-allele differences.</li>
</ol>

<h2>Input Requirements</h2>
<ul>
  <li><strong>VCF format:</strong> Standard VCF generated by TandemTwister.</li>
  <li><strong>Cohort directory:</strong> A folder with multiple <code>.vcf.gz</code> files generated by TandemTwister is required for cohort mode.</li>
</ul>


<h2>Demo / Examples</h2>
<p>Example screenshots and short walkthrough GIFs will be added here. For now, you can open <code>example.svg</code> for a preview:</p>
<img src="assets/example.svg" alt="Tandem Repeat Visualization Example" style="max-width: 100%; height: auto; border: 1px solid #ccc; padding: 10px;">
<ul>
  <li><em>Planned:</em> Individual-mode walkthrough </li>
  <li><em>Planned:</em> Cohort-mode walkthrough</li>
</ul>


<h2>Contributing</h2>
<p>Contributions are welcome! Please <a href="https://github.com/Lionward/ProleTRact/issues">open an issue</a> to discuss changes.</p>

<h2>Changelog</h2>
<p>See <a href="CHANGELOG.md">CHANGELOG.md</a> for a list of changes in each version.</p>

<h2>Citation</h2>
<p>If you use TandemTwister/ProleTRact in your research or analysis, please cite our work as follows:</p>

<blockquote>
  <strong>TandemTwister: Scalable genotyping and advanced visualization of tandem repeats</strong><br>
  Al Raei LW, Ghareghani M, Moeinzadeh H, Vingron M<br>
  bioRxiv 2026.01.28.702315; doi: <a href="https://doi.org/10.64898/2026.01.28.702315">https://doi.org/10.64898/2026.01.28.702315</a><br>
  <a href="https://www.biorxiv.org/content/10.64898/2026.01.28.702315v1">Preprint</a> |
  <a href="https://github.com/Lionward/tandemtwister">GitHub Repository</a>
</blockquote>



<h2>License</h2>
<p>This project is licensed under the BSD 3-Clause Non-Commercial License — see <code>LICENSE</code> 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.</p>