Gel Annotate

Gel Annotate is a Python package + GUI tool for automated detection and annotation of gel electrophoresis wells, ladders, and PCR bands.
It was developed for lab workflows to speed up gel image analysis and make the results reproducible and easy to share.

Features

• Automatic detection of sample wells and ladder wells from gel images (TIFF, PNG, JPG, etc.).
• PCR band detection with adjustable thresholds.
• Interactive PyQt5 GUI:
  • View annotated gels with labeled wells/bands.
  • Edit probable wells manually by typing coordinates.
  • Save and reload results (.json).
  • Export results to CSV or JSON.
  • Save annotated PNGs for reports.
• Command-line interface for batch processing.
• Cross-platform (Windows, Linux, macOS).
• Optional desktop/start menu shortcuts for quick access.

Installation

You can install from PyPI:

pip install aer-gel-annotate

On Windows (to allow shortcut creation), install with:

pip install aer-gel-annotate[windows]

Usage

Run the GUI

After installation:

gel-annotate

This opens the GUI application.

Run the CLI

For quick batch analysis:

gel-annotate-cli path/to/gel_image.tif --ladder --detect_bars

GUI Overview

• Top row:

  • Select an image file.
  • Set detection parameters (comb size, combs per row, ladder/band detection).
  • Run detection.

• Left sidebar:

  • Manual overrides (force YES/NO for PCR bands).
  • Detected wells and ladder wells (read-only).
  • Probable wells (editable — add/modify coordinates).
  • Save/export options (PNG, CSV, JSON).
  • Load JSON results.

• Main area:

  • Annotated gel image with labeled wells and bands.

Export & Reload Results

• CSV: table of wells, ladder wells, bands.
• JSON: full structured result (including probable wells, ladder bands, etc.).

You can later reload a JSON file into the GUI, edit probable wells, and re-run detection.

Application Shortcuts

• To create a desktop/start menu shortcut (after installation):

gel-annotate-shortcut

• On Linux, this creates a .desktop entry under ~/.local/share/applications and your Desktop.
• On Windows, it creates Gel Annotate.lnk on Desktop and in the Start Menu.
• On macOS, it creates a Gel Annotate.command launcher on the Desktop.

️ Development

Clone the repository and install in editable mode:

git clone https://github.com/your-org/aer-gel-annotate
cd aer-gel-annotate
pip install -e .[windows]  # add [windows] on Windows

Run the GUI locally:

python -m annotation.gui.gel_gui_wrapper

License

MIT License © 2025 Manan Shah