BiNgo Genome Viewer

PyPI version Python License

A lightweight, browser-based genome viewer for visualising reference genomes, coverage tracks, read alignments, variant calls, and feature annotations. The frontend is a React single-page application; the backend is a FastAPI server that streams binned data on demand. Designed for fast interactive work on bacterial-scale genomes from a laptop, with no external services or compiled C dependencies.

Highlights

  • Single-command install. python -m pip install BiNgoViewer && bingo launches the viewer in your default browser. The compiled frontend ships with the wheel — Node.js is not required at install time.
  • Pure-Python readers for every supported format (no pysam, no pyBigWig C extensions). Works on Windows, macOS, and Linux without build tools.
  • Auto-cancelled fetches. Pan/zoom requests are cancelled when superseded; transient backend failures retry silently with backoff; in-flight reads are serialised per-track to keep non-thread-safe file handles consistent.
  • Session export / restore. Workspace state — viewport, track order, colours, scale, feature-type filters, strand visibility — round-trips through a single JSON file or auto-restores from localStorage.
  • Overlay coverage tracks. Stack two or more BigWig/WIG/bedGraph tracks in a single row on a shared Y axis, with per-track transparency and stacking order, for direct signal comparison.
  • SVG and PNG export with grouped vector layers suitable for figure preparation.
  • Five built-in themes (Dark, Light, Colorblind Friendly, Soft, High Contrast) plus a custom theme editor.

Supported file formats

Type Formats Notes
Reference genome FASTA (.fa, .fasta), GenBank (.gb, .gbk, .genbank) GenBank files contribute both reference sequence and a built-in annotation track. Multiple genome files can be merged with Add chromosomes.
Coverage / signal BigWig (.bw, .bigwig), WIG (.wig, .wig.gz), BedGraph (.bedgraph, .bedgraph.gz, .bdg, .bdg.gz) Compressed .gz variants are decompressed on the fly. WIG dialects (fixedStep, variableStep, headerless, 3-column forward/reverse) are auto-detected. BigWig parsing is pure-Python via R-tree traversal.
Read alignments BAM (.bam + .bai index) Index file required. Coverage is shown when zoomed out; individual reads with CIGAR-aware match / deletion / intron / insertion / soft-clip rendering appear within 50 kbp views. CRAM is not supported.
Variants VCF (.vcf, .vcf.gz), BCF (.bcf) Plain and gzip-compressed VCF; up to 10 000 variants per region returned.
Feature annotations BED (.bed), GTF (.gtf), GFF2 (.gff2), GFF3 (.gff3), GenBank (.gb) The ambiguous .gff extension is auto-detected as GFF2/GTF or GFF3 by inspecting ##gff-version and the column-9 attribute style.

Installation

Requires Python 3.10 or newer. Get it from python.org if needed.

pip (recommended)

python -m pip install BiNgoViewer
bingo

python -m pip (in preference to a bare pip) binds the install to the interpreter you just invoked, including any active virtual environment. On systems where only python3 / pip3 is on PATH, substitute python3 -m pip install BiNgoViewer.

Windows one-click

Double-click Install_Windows.bat. It creates a local virtual environment, installs the package, and launches the viewer.

macOS / Linux one-click

Double-click Install_macOS.command (or run it from a terminal). The first time, you may need to mark it executable:

chmod +x Install_macOS.command

Docker

cd app
docker compose up --build

Then open http://localhost:8000. The Dockerfile builds the frontend in a Node stage and copies the bundle into a slim Python runtime.

Command-line options

bingo                    Launch on default port 8000 and open the browser
bingo --port 9000        Use a different port
bingo --host 0.0.0.0     Bind to a different host (default: 127.0.0.1)
bingo --no-browser       Start the server without launching a browser
bingo --install          Create a desktop shortcut for the current user
bingo --update           Check PyPI and install a newer version if available
bingo --no-update        Skip the automatic update check at launch
bingo --close-window     Close the launching terminal when the server exits
                         (Windows cmd / PowerShell only)
bingo --version          Print the installed version and exit

The server auto-shuts down shortly after the last browser tab closes (typically within ~20 seconds; longer if the closing browser can't send its shutdown beacon). You can also stop it with Ctrl+C.

Using the viewer

  1. Load files. Use the file picker, drop files anywhere in the window, or paste a local path (recommended for BAMs over 50 MB — the server reads directly from disk instead of uploading through the browser).
  2. Navigate. Left-click drag to pan; scroll to zoom (anchored at the cursor). Use the chromosome scrubber along the top to jump anywhere on the current sequence. Shift+scroll scrolls vertically inside read pile-ups.
  3. Select a region. Right-click drag to mark a region; a tooltip shows the selection length and per-track stats (mean coverage, variant count, feature count, read count). Click the highlighted band to dismiss; right-click it to recolour the underlying region.
  4. Zoom to a feature. Double-click any annotation to centre it in the view with ~15 % flanking context.
  5. Tune tracks. Open Track Settings to adjust height, colour, linear/log Y-axis, fixed Y range, auto-fit-to-visible-region scaling, bar width, peak outline tracing, strand visibility (BAM), strand colours, arrow style, nucleotide display, and per-feature-type visibility (GenBank/GFF). Multi-select to apply changes to several tracks at once; mixed values render as indeterminate checkboxes.
  6. Overlay coverage tracks. Multi-select two or more coverage tracks in Track Settings and click Overlay to stack them in one shared-axis row. The merged row's legend controls each track's colour, transparency, and draw order; Separate overlay undoes it.
  7. Reorder. Drag the grip handle on a track label.
  8. Export. Save the current view as SVG (grouped layers, ready for vector editing) or PNG.
  9. Save / restore session. Export the workspace to JSON, or rely on the autosave to localStorage for an exit-and-resume workflow.

Performance characteristics

The viewer is built around a binned-coverage data model with overscan caching and zoom-aware refetching, so it remains responsive on bacterial genomes (single chromosome, ~1–10 Mbp) with several large coverage tracks and BAMs loaded simultaneously. Indicative timings on a recent laptop:

Workload Time
GenBank parse (1.8 MB) ~200 ms
WIG parse (11 MB, point data) ~340 ms
WIG parse (3 MB gzipped) ~410 ms
Coverage query (full chromosome, 1000 bins, 11 MB WIG) ~140 ms
Annotation query (full chromosome GFF3) <1 ms

These numbers reflect cold reads. The frontend keeps an in-memory overscan cache of fetched regions, so panning within — or returning to — an already-loaded area is served instantly without a new backend request; the backend parses on demand and does not itself cache.

Troubleshooting

Problem Solution
python not found Install Python 3.10+ and tick Add to PATH during setup. On macOS/Linux, try python3 instead of python.
pip not found / wrong Python Use python -m pip install BiNgoViewer (or python3 -m pip ...). This binds to the interpreter you invoked, including the active venv, even when no pip shim exists on PATH.
Installed but bingo is not on PATH Your Python's Scripts/ (Windows) or bin/ (Unix) directory is not exported. Activate your venv first, or run python -m bingoviewer directly.
"No matching distribution" Your Python is older than 3.10. Check with python --version.
pip install still fails Try python -m pip install --user BiNgoViewer, or create a clean venv: python -m venv .venv && .venv/bin/pip install BiNgoViewer (Windows: .venv\Scripts\pip).
Port 8000 in use bingo --port 9000 (any free port).
Browser doesn't open Visit http://localhost:8000 manually; the server will keep running.
Server won't stop It auto-exits shortly (~20 s) after the last tab closes; Ctrl+C from the launching terminal also works.
BAM rejected Ensure a .bai index sits alongside the BAM (named reads.bam.bai or reads.bai). CRAM is not supported.
Cloud-synced file errors OneDrive / Dropbox files marked "online only" cannot be read. Pin them locally before loading.

API

When the server is running, FastAPI serves auto-generated OpenAPI documentation:

The frontend talks to the same API; nothing in the UI is privileged.

Project layout

.
├── README.md
├── CHANGELOG.md
├── CONTRIBUTING.md
├── pyproject.toml              # pip package definition
├── Install_Windows.bat         # One-click Windows installer
├── Install_macOS.command       # One-click macOS / Linux installer
├── bingoviewer/                # Installable Python package
│   ├── __init__.py             # __version__
│   ├── cli.py                  # `bingo` entry point
│   ├── server/                 # FastAPI backend (mirror of app/backend)
│   └── frontend_dist/          # Pre-built React bundle
└── app/
    ├── Dockerfile              # Container build
    ├── docker-compose.yml
    ├── backend/                # Backend source (FastAPI + readers)
    └── frontend/               # Frontend source (React + Vite)

bingoviewer/server/ and app/backend/ are kept byte-identical so a single change set can serve both the development workflow and the packaged release. See CONTRIBUTING.md for the sync workflow.

Citation

If you use this software in published research, please cite:

Ngo, B. M. (2026). BiNgo Genome Viewer (v2.12) [Software]. https://github.com/billy-ngo/bingo-genome-viewer

Acknowledgements

Software libraries

Backend. FastAPI (Ramírez, 2018); Uvicorn; BioPython (Cock et al., Bioinformatics 25(11), 2009); pyfaidx (Shirley et al., PeerJ PrePrints, 2015); bamnostic (Sherman & Mills, 2019).

Frontend. React; Vite; Axios.

File-format specifications

  • SAM/BAM — Li et al., Bioinformatics 25(16), 2009.
  • VCF — Danecek et al., Bioinformatics 27(15), 2011.
  • BigWig / WIG — Kent et al., Bioinformatics 26(17), 2010.
  • BED — UCSC Genome Browser.
  • GFF3 — Sequence Ontology Project.
  • GTF — Ensembl.
  • GenBank — Benson et al., Nucleic Acids Research 41(D1), 2013.

Inspiration

  • IGV — Robinson et al., Nature Biotechnology 29(1), 2011.

Pre-release testing

Amanda Antoch · Isaac Poarch · Otto Chipashvili · Jake Colautti.

License

Proprietary. All rights reserved. Contact the author for licensing inquiries.

Project links

Data verified by PyPI on Jul 29, 2026
Data provided by the project maintainers, verified at the time the release was uploaded to PyPI.

Key dates

PyPI data
Data sourced directly from PyPI's database.
  • Released:
Latest release

1 maintainer

PyPI data
Data sourced directly from PyPI's database.
Avatar for billyngo from gravatar.com billyngo

Credits

Author: Billy M Ngo

GitHub Statistics

Data verified by PyPI on Jul 29, 2026
The GitHub source repository was provided by the project maintainers and verified by PyPI at the time of upload. Stars, forks, and open issues/PRs are derived from that repository and have not been independently verified.

License

Proprietary

Requires

Python >=3.10

Tags

genomics genome viewer browser bioinformatics igv

Classifiers

Report project as malware

Download files

Download the file for your platform. If you're not sure which to choose, learn more about installing packages.

Source Distribution

bingoviewer-2.13.0.tar.gz (172.6 kB view details)

Uploaded Source

Built Distribution

If you're not sure about the file name format, learn more about wheel file names.

bingoviewer-2.13.0-py3-none-any.whl (181.7 kB view details)

Uploaded Python 3

File details

Details for the file bingoviewer-2.13.0.tar.gz.

File metadata

  • Download URL: bingoviewer-2.13.0.tar.gz
  • Upload date:
  • Size: 172.6 kB
  • Tags: Source
  • Uploaded using Trusted Publishing? Yes
  • Uploaded via: twine/6.1.0 CPython/3.13.14

File hashes

Hashes for bingoviewer-2.13.0.tar.gz
Algorithm Hash digest
SHA256 fc708a330f081c80ad77149e0897276c267c86a996b4fcdf6ba7f86d8daa00d0
MD5 5919825b1c2a1d988bc2346035166dac
BLAKE2b-256 efb2314c3abf40a92f466442307b5e84f52c8a9b80977182d26c4c965a20efba

See more details on using hashes here.

Provenance

The following attestation bundles were made for bingoviewer-2.13.0.tar.gz:

Publisher: publish.yml on billy-ngo/bingo-genome-viewer

Attestations: Values shown here reflect the state when the release was signed and may no longer be current.

File details

Details for the file bingoviewer-2.13.0-py3-none-any.whl.

File metadata

  • Download URL: bingoviewer-2.13.0-py3-none-any.whl
  • Upload date:
  • Size: 181.7 kB
  • Tags: Python 3
  • Uploaded using Trusted Publishing? Yes
  • Uploaded via: twine/6.1.0 CPython/3.13.14

File hashes

Hashes for bingoviewer-2.13.0-py3-none-any.whl
Algorithm Hash digest
SHA256 e73bfb19ed4006b49c7d08db70660d2227dc97b466603734f5d27d461b2c30f6
MD5 f5516728c9254aebc12322a80310fb67
BLAKE2b-256 42bf4ac9e96a1e60020852213d1bdadd893171617d459861d4c7d906c3632174

See more details on using hashes here.

Provenance

The following attestation bundles were made for bingoviewer-2.13.0-py3-none-any.whl:

Publisher: publish.yml on billy-ngo/bingo-genome-viewer

Attestations: Values shown here reflect the state when the release was signed and may no longer be current.

Release history Release notifications | RSS feed

This release

2.13.0 This release

2 files

2.12.1

2 files

2.12.0

2 files

2.11.3

2 files

2.11.2

2 files

2.11.1

2 files

2.11.0

2 files

2.10.3

2 files

2.10.2

2 files

2.10.1

2 files

2.10.0

2 files

2.9.11

2 files

2.9.10

2 files

2.9.9

2 files

2.9.8

2 files

2.9.7

2 files

2.9.6

2 files

2.9.5

2 files

2.9.4

2 files

2.9.3

2 files

2.9.2

2 files

2.9.1

2 files

2.9.0

2 files

2.8.0

2 files

2.7.5

2 files

2.7.4

2 files

2.7.3

2 files

2.7.2

2 files

2.7.1

2 files

2.7.0

2 files

2.6.1

2 files

2.6.0

2 files

2.5.4

2 files

2.5.3

2 files

2.5.2

2 files

2.5.1

2 files

2.5.0

2 files

2.4.1

2 files

2.4.0

2 files

2.3.5

2 files

2.3.4

2 files

2.3.3

2 files

2.3.2

2 files

2.3.1

2 files

2.3.0

2 files

2.2.9

2 files

2.2.8

2 files

2.2.7

2 files

2.2.6

2 files

2.2.5

2 files

2.2.4

2 files

2.2.3

2 files

2.2.2

2 files

2.2.1

2 files

2.2.0

2 files

2.1.2

2 files

2.1.1

2 files

2.1.0

2 files

2.0.9

2 files

2.0.8

2 files

2.0.7

2 files

2.0.6

2 files

2.0.5

2 files

2.0.4

2 files

2.0.3

2 files

2.0.2

2 files

2.0.1

2 files

2.0.0

2 files

1.9.4

2 files

1.9.3

2 files

1.9.2

2 files

1.9.1

2 files

1.9.0

2 files

1.8.3

2 files

1.8.2

2 files

1.8.1

2 files

1.8.0

2 files

1.7.6

2 files

1.7.5

2 files

1.7.4

2 files

1.7.3

2 files

1.7.2

2 files

1.7.1

2 files

1.7.0

2 files

1.6.3

2 files

1.6.2

2 files

1.6.1

2 files

1.6.0

2 files

1.5.6

2 files

1.5.5

2 files

1.5.4

2 files

1.5.3

2 files

1.5.2

2 files

1.5.1

2 files

1.5.0

2 files

1.4.7

2 files

1.4.6

2 files

1.4.5

2 files

1.4.4

2 files

1.4.3

2 files

1.4.2

2 files

1.4.1

2 files

1.4.0

2 files

1.3.6

2 files

1.3.5

2 files

1.3.4

2 files

1.3.3

2 files

1.3.2

2 files

1.3.1

2 files

1.3.0

2 files

1.0.0

2 files

Anthropic, PBC Visionary sponsor Bloomberg Visionary sponsor Hudson River Trading Visionary sponsor Meta Visionary sponsor NVIDIA Visionary sponsor Microsoft Sustainability sponsor Depot Continuous Integration AWS Cloud computing and Security Sponsor Datadog Monitoring Fastly CDN Google Download Analytics Sentry Error logging StatusPage Status page