Web App¶

dot-explorer ships with a browser app for comparing two genome assemblies — no installation required. The app is fully client-side: your FASTA files are parsed, aligned, and plotted entirely in your browser (via WebAssembly and Pyodide) and never leave your machine.

Launch the app in a new window →

The app opens in its own window — it needs the full viewport for the interactive dotplot, and running it standalone keeps its memory separate from the docs site.

Capabilities¶

Limits and notes¶

• Memory: the app's Python runtime can grow its WebAssembly heap to 4 GB — measured directly: the heap tops out at 4096 MB, with ~4.0 GB allocatable before a clean MemoryError (a 90 Mb k-mer run peaked at 2.9 GB). The app is best suited to viral, bacterial, and fungal-scale assemblies; for large plant or animal genomes, use dot-explorer locally instead. The sidebar shows the live wasm-heap usage against this cap.
• Input size limits (measured empirically in Chrome with synthetic assembly pairs): the k-mer method completes at 90 Mb combined and crashes the Python runtime at 100 Mb, so beyond ~80 Mb combined the app removes the k-mer method from the selector (and warns above 40 Mb that big runs take minutes). A native memory audit (scripts/mem_profile_index.py) confirms this ceiling comes from the k-mer index's CSR tables (~15 B/bp) plus match-record objects — not from stored alignment sequences — so it is inherent to the method at this heap size — at that scale, use minimap2/nucmer here or run the dot-explorer Python library locally. minimap2 and nucmer run in their own workers: minimap2 completed at 200 MB combined and nucmer at 250 MB; at 300 MB the browser tab itself crashed (both tools), so above ~200 MB the app suggests aligning locally and uploading the precomputed PAF via the Alignment (PAF) input mode, which skips in-browser aligning entirely.
• First load: the app downloads about 26 MB of Python/wasm runtime assets on first visit (52 files, 37 MB uncompressed — measured from a cold load of the deployed export); the browser caches them, so subsequent loads are fast. The biowasm aligner binaries are separate and fetch only when an aligner is selected.
• Why no BLAST? No production WebAssembly build of NCBI BLAST+ exists, so BLAST cannot run in the browser. MUMmer4's nucmer is offered as the closest substitute for sensitive genome-vs-genome alignment.

Run it locally¶

The app is a standard Shiny for Python app: the hosted version above is a Shinylive/WebAssembly export of the same app, which also runs natively on a workstation or HPC node with the installed dot-explorer instead of the wasm wheel.

Install and run¶

The app ships inside the wheel, so no checkout is needed:

pip install "dot-explorer[app]"
dot-explorer-app

That serves the app on http://127.0.0.1:8000 and opens a browser.

Developers building the Rust extension from source use maturin develop --release plus pip install ".[app]" from a checkout, and can also run shiny run --launch-browser python/dot_explorer/app/app.py directly — see the app README for the development and Shinylive-export recipes, or environment.yml for the conda route.

On a remote server / HPC¶

The same command works headless — bind a port and tunnel to it:

dot-explorer-app --host 127.0.0.1 --port 8000 --no-browser   # on the server
ssh -L 8000:localhost:8000 user@server                       # from your laptop
# then open http://localhost:8000

Prefer --host 127.0.0.1 plus the SSH tunnel on shared systems so the app is not exposed to other users on the network.

Where the app writes files¶

Nothing is written next to the installed package, and nothing is written to the directory you launch from. Every file the app creates goes to the system temporary directory:

• Uploads land in a per-session directory Shiny creates with tempfile.mkdtemp(prefix="fileupload-"), and are removed when the session ends.
• The .fai index, the decompressed copy of a .gz upload, and the FASTA reconstructed from a GenBank upload are all written beside the upload, in that same directory.
• HTML reports and figure exports use tempfile.TemporaryDirectory().

The k-mer index itself is held in memory (the Rust heap), not on disk. The largest on-disk artefacts are therefore an uncompressed copy of your assembly plus its index.

On a cluster where /tmp is small or per-node, point the temporary directory somewhere with room before launching:

export TMPDIR=/scratch/$USER/tmp      # Windows: set TEMP=...
mkdir -p "$TMPDIR"
dot-explorer-app --no-browser

Local vs. in-browser differences¶

The k-mer method and PAF import work fully offline locally; only the minimap2/nucmer buttons need a network connection (they fetch the tool binaries from the biowasm CDN into your browser tab, even for a local app). For very large genomes, align outside the app with native minimap2 and use the Alignment (PAF) input mode.