Metadata-Version: 2.4
Name: plotnado
Version: 0.2
Summary: A simple plotting library for making genomic tracks
Author-email: Alastair Smith <alastair.smith@ndcls.ox.ac.uk>
License-Expression: GPL-3.0-or-later
Project-URL: Homepage, https://github.com/alsmith151/plotnado
Project-URL: Repository, https://github.com/alsmith151/plotnado
Project-URL: Bug Tracker, https://github.com/alsmith151/plotnado/issues
Project-URL: Documentation, https://github.com/alsmith151/plotnado
Keywords: genomics,bioinformatics,plotting,genome-browser,tracks
Classifier: Development Status :: 3 - Alpha
Classifier: Intended Audience :: Science/Research
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3 :: Only
Classifier: Programming Language :: Python :: 3.12
Classifier: Topic :: Scientific/Engineering :: Bio-Informatics
Classifier: Topic :: Scientific/Engineering :: Visualization
Requires-Python: >=3.12
Description-Content-Type: text/markdown
License-File: LICENSE
Requires-Dist: matplotlib
Requires-Dist: numpy
Requires-Dist: pandas
Requires-Dist: pydantic>=2.0.0
Requires-Dist: loguru
Requires-Dist: pandera
Requires-Dist: pybigtools
Requires-Dist: pyranges1
Requires-Dist: typer
Requires-Dist: tqdm
Requires-Dist: tomli-w
Provides-Extra: cooler
Requires-Dist: cooler; extra == "cooler"
Requires-Dist: capcruncher; extra == "cooler"
Provides-Extra: quantnado
Requires-Dist: quantnado; extra == "quantnado"
Provides-Extra: toml
Requires-Dist: tomli; python_version < "3.11" and extra == "toml"
Requires-Dist: tomli-w; extra == "toml"
Provides-Extra: dev
Requires-Dist: pytest; extra == "dev"
Requires-Dist: pytest-mock; extra == "dev"
Requires-Dist: pytest-assume; extra == "dev"
Requires-Dist: pre-commit; extra == "dev"
Provides-Extra: docs
Requires-Dist: mkdocs>=1.6.1; extra == "docs"
Requires-Dist: mkdocstrings>=1.0.3; extra == "docs"
Requires-Dist: mkdocs-literate-nav>=0.6.2; extra == "docs"
Requires-Dist: mkdocs-gen-files>=0.6.0; extra == "docs"
Requires-Dist: mkdocs-jupyter>=0.25.1; extra == "docs"
Requires-Dist: mkdocs-click>=0.9.0; extra == "docs"
Requires-Dist: pymdown-extensions>=10.21; extra == "docs"
Requires-Dist: tomli-w; extra == "docs"
Requires-Dist: mkdocstrings[python]>=1.0.3; extra == "docs"
Provides-Extra: all
Requires-Dist: cooler; extra == "all"
Requires-Dist: capcruncher; extra == "all"
Requires-Dist: quantnado; extra == "all"
Requires-Dist: tomli; python_version < "3.11" and extra == "all"
Requires-Dist: tomli-w; extra == "all"
Requires-Dist: pytest; extra == "all"
Requires-Dist: pytest-mock; extra == "all"
Requires-Dist: pytest-assume; extra == "all"
Requires-Dist: pre-commit; extra == "all"
Requires-Dist: mkdocs>=1.6.1; extra == "all"
Requires-Dist: mkdocstrings>=1.0.3; extra == "all"
Requires-Dist: mkdocs-literate-nav>=0.6.2; extra == "all"
Requires-Dist: mkdocs-gen-files>=0.6.0; extra == "all"
Requires-Dist: mkdocs-jupyter>=0.25.1; extra == "all"
Requires-Dist: mkdocs-click>=0.9.0; extra == "all"
Requires-Dist: pymdown-extensions>=10.21; extra == "all"
Requires-Dist: mkdocstrings[python]>=1.0.3; extra == "all"
Dynamic: license-file

# PlotNado

[![Tests](https://github.com/alsmith151/plotnado/actions/workflows/run_tests.yml/badge.svg)](https://github.com/alsmith151/plotnado/actions/workflows/run_tests.yml)

PlotNado is a lightweight Python package for building genome browser-style figures with a modern, chainable API.

> [!NOTE]
> This version of PlotNado is independent and does not require CoolBox.

## Install

```bash
pip install plotnado
```

For development from source:

```bash
git clone https://github.com/alsmith151/plotnado
cd plotnado
pip install -e .[dev,docs]

# required developer setup: run local quality hooks before every commit
pip install pre-commit
pre-commit install
```

## Developer workflow (important)

- Do not edit autogenerated typing surfaces directly:
  - `plotnado/figure.pyi`
  - auto-generated overload blocks in `plotnado/figure.py` (`# BEGIN/END AUTO-GENERATED OVERLOAD`)
- Make API changes in the source Pydantic models first (track models/aesthetics/labels), then regenerate artifacts:

```bash
python scripts/generate_figure_overloads.py
python scripts/generate_figure_stub.py
```

- Always run pre-commit before pushing:

```bash
pre-commit run --all-files
```

## Quick Start

```python
from plotnado import GenomicFigure
import numpy as np
import pandas as pd

bins = np.arange(1_000_000, 1_100_000, 1_000)
signal = pd.DataFrame({
    "chrom": "chr1",
    "start": bins,
    "end": bins + 1_000,
    "value": 5 + 2 * np.sin(np.linspace(0, 6, len(bins))),
})

fig = GenomicFigure()
fig.scalebar()
fig.axis()
fig.genes("hg38")
fig.bigwig(signal, title="Synthetic signal", style="fill", color="#1f77b4")
fig.save("quickstart.png", "chr1:1,010,000-1,080,000")
```

`GenomicFigure()` now uses publication-style defaults automatically. Use `GenomicFigure(theme=None)` to opt out.

## Examples

- Start with `python examples/basic_figure.py`
- Then run `python examples/advanced_features.py`
- Full curated suite: `python examples/run_examples.py`
- Additional focused examples live in:
  - `examples/quickstart/`
  - `examples/tracks/`
  - `examples/recipes/`

All scripts write outputs to `examples/output/`.

## Key Features

- Chainable `GenomicFigure` API for fast composition.
- Alias-based track creation (`fig.add_track("bigwig", ...)`).
- Track option introspection at runtime.
- Built-in themes, autocolor, autoscale, and highlight overlays.
- Broad track support: BigWig, BED, narrowPeak, genes, axis, scalebar, links, `OverlayTrack`, cooler-based matrix tracks.

## Discover Track Options

```python
from plotnado import GenomicFigure, BigWigTrack

GenomicFigure.available_track_aliases()
GenomicFigure.track_options("bigwig")
GenomicFigure.track_options_markdown("bigwig")
BigWigTrack.options_markdown()
```

## Documentation

- Docs home: `docs/index.md`
- Quick start: `docs/quickstart.md`
- Track catalog + options: `docs/track_catalog.md`
- API and generated references: `docs/api_reference.md`

Build docs locally:

```bash
pip install -e .[docs]
mkdocs build --strict
mkdocs serve
```

## CLI

```python
plotnado plot chr1:1,000,000-1,100,000 -o browser_view.png
plotnado track-options bigwig
plotnado track-options --all --output-format json
```
