Metadata-Version: 2.4
Name: dot-explorer
Version: 0.2.1
Classifier: Programming Language :: Rust
Classifier: Programming Language :: Python :: Implementation :: CPython
Classifier: Programming Language :: Python :: 3.12
Classifier: Programming Language :: Python :: 3.13
Classifier: Programming Language :: Python :: 3.14
Classifier: Programming Language :: Python :: Free Threading :: 3 - Stable
Classifier: Topic :: Scientific/Engineering :: Bio-Informatics
Requires-Dist: matplotlib>=3.5
Requires-Dist: numpy>=1.21
Requires-Dist: pyfaidx
Requires-Dist: shiny ; extra == 'app'
Requires-Dist: sourmash>=4.8 ; extra == 'cluster'
Requires-Dist: scipy>=1.10 ; extra == 'cluster'
Requires-Dist: isort ; extra == 'dev'
Requires-Dist: maturin>=1.0 ; extra == 'dev'
Requires-Dist: mypy ; extra == 'dev'
Requires-Dist: numpydoc-validation ; extra == 'dev'
Requires-Dist: pre-commit ; extra == 'dev'
Requires-Dist: pydocstyle ; extra == 'dev'
Requires-Dist: ruff ; extra == 'dev'
Requires-Dist: zensical>=0.0.57 ; extra == 'docs'
Requires-Dist: mkdocstrings-python>=2.0 ; extra == 'docs'
Requires-Dist: nbconvert>=7.0 ; extra == 'docs'
Requires-Dist: pytest-codspeed ; extra == 'test'
Requires-Dist: pytest-cov ; extra == 'test'
Requires-Dist: pytest ; extra == 'test'
Requires-Dist: toml ; extra == 'test'
Provides-Extra: app
Provides-Extra: cluster
Provides-Extra: dev
Provides-Extra: docs
Provides-Extra: test
License-File: LICENSE
Summary: A Python library for making fast dot-plot comparisons of DNA sequences powered by Rust.
Keywords: bioinformatics,dotplot,sequence-comparison
Requires-Python: >=3.12, <3.15
Description-Content-Type: text/markdown; charset=UTF-8; variant=GFM
Project-URL: documentation, https://adamtaranto.github.io/dot-explorer/
Project-URL: homepage, https://github.com/adamtaranto/dot-explorer
Project-URL: repository, https://github.com/adamtaranto/dot-explorer

[![License: GPL v3](https://img.shields.io/badge/License-GPLv3-blue.svg)](https://www.gnu.org/licenses/gpl-3.0)

# dot-explorer

A python library with Shiny Web App frontend for fast dot plot comparisons of DNA sequences. Written in Rust with PyO3 python bindings.

## Browser app

[![Web App](https://img.shields.io/badge/Web%20App-live-teal)](https://adamtaranto.github.io/dot-explorer/app/)

Try dot-explorer without installing anything:
**[Launch Dot-Explorer Live](https://adamtaranto.github.io/dot-explorer/app/)**.

The app runs entirely in your browser (WebAssembly + Pyodide) — uploaded
assemblies never leave your machine. Align with the k-mer engine, minimap2,
or nucmer (or import a PAF file), overlay GFF3 annotations, and download SVG/PDF
plots, PAF alignments, and a reordered/reoriented query FASTA.

In-browser computation is memory limited (the wasm heap caps at ~4 GB, so
the k-mer method is gated above ~80 Mb of combined input); larger genomes
should use minimap2 instead of k-mer based plotting. Alternatively, run the
same app locally with no size limits (`pip install "dot-explorer[app]"`, then
`dot-explorer-app`), or generate plots using the Python API locally or on
Google Colab.

See [docs/webapp.md](https://adamtaranto.github.io/dot-explorer/webapp/) for capabilities, limits, and the local/HPC run guide, and
[Python library tutorials](https://adamtaranto.github.io/dot-explorer/tutorials/quickstart/) to run analysis locally.

## Installation

Requires Python >=3.12 <3.15. Binary wheels are published for 3.12, 3.13, 3.14
and 3.14t on Linux, macOS and Windows, so pip never has to compile Rust.

```bash
# Python library
pip install dot-explorer

# Library plus the local browser app
pip install "dot-explorer[app]"

# Optional: similarity metrics, clustering and trees (sourmash + scipy)
pip install "dot-explorer[cluster]"
```

## Run the app locally

```bash
dot-explorer-app
```

Serves the app on <http://127.0.0.1:8000> and opens a browser. Use `--host`,
`--port` and `--no-browser` when running on a remote machine or HPC node — see
the [web app guide](https://adamtaranto.github.io/dot-explorer/webapp/) for the
SSH-tunnel recipe and for where the app writes temporary files.

## Build from source

Only needed to modify the Rust core.

Requirements:

- Rust: See [rust-lang.org](https://rust-lang.org/tools/install/)
- Python >=3.12 <3.15

```bash
# Clone this project repo
git clone https://github.com/Adamtaranto/dot-explorer.git && cd dot-explorer

# Install maturin build tool
pip install maturin

# Build and install the python package
maturin develop --release
```

See the [development guide](https://adamtaranto.github.io/dot-explorer/development/)
for the full contributor setup.

