quickstart.qmd

---
jupyter: python3
execute:
  warning: false
  message: false
---

# Quick Start

PlotNado has two entry points:

- Python API for scripts, notebooks, and executable Quarto examples.
- CLI + YAML for file-driven rendering.

Start from source with:

```bash
uv sync --extra dev --extra docs
uv run plotnado --help
```

## Build a figure in Python

This example is fully in-memory, so it renders during the docs build without external files.

```{python}
#| fig-cap: "Scale, axis, signal, and BED-like intervals from deterministic DataFrames."
from plotnado import GenomicFigure
from plotnado.examples import REGION, signal, intervals
# signal() returns a synthetic DataFrame(chrom, start, end, value) — in real use pass a BigWig path/URL or any DataFrame with those columns
# intervals() returns a synthetic DataFrame(chrom, start, end, name) — in real use pass a BED/BigBed path, URL, or DataFrame

fig = GenomicFigure(width=11, track_height=1.25)
fig.scalebar()
fig.bigwig(signal(scale=1.15), title="Synthetic signal", style="fill", color="#1f77b4")
fig.bed(intervals(), title="Intervals", display="expanded", show_labels=True)
fig.axis()
fig.plot(REGION)
```

## Save the same figure

```python
from plotnado import GenomicFigure
from plotnado.examples import REGION, signal, intervals
# signal() → DataFrame(chrom, start, end, value); intervals() → DataFrame(chrom, start, end, name)
# replace with BigWig paths/URLs or real DataFrames

fig = GenomicFigure(width=11, track_height=1.25)
fig.scalebar()
fig.bigwig(signal(scale=1.15), title="Synthetic signal", style="fill", color="#1f77b4")
fig.bed(intervals(), title="Intervals", display="expanded", show_labels=True)
fig.axis()
fig.save("quickstart.png", region=REGION)
```

## Generate and render a template

Use the CLI when you want a human-editable YAML file between data discovery and rendering.

```bash
uv run plotnado init sample1.bw sample2.bw peaks.narrowpeak --auto --output template.yaml
uv run plotnado validate template.yaml
uv run plotnado plot template.yaml --region chr1:1,000,000-1,100,000 --output quickstart-cli.png
```

The generated YAML is intentionally small:

```yaml
genome: hg38
guides:
  genes: true
tracks:
  - path: sample1.bw
    type: bigwig
    title: sample1
  - path: peaks.narrowpeak
    type: narrowpeak
    title: peaks
```

Load a template back into Python when you want to add programmatic logic:

```python
from plotnado import GenomicFigure

fig = GenomicFigure.from_template("template.yaml")
fig.save("quickstart-from-template.png", region="chr1:1,000,000-1,100,000")
```

## Next

- [Track Construction](quickstart_tracks.qmd): helper methods, aliases, and explicit track objects.
- [CLI](cli.qmd): template commands and schema.
- [Aesthetics](aesthetics.qmd): style comparisons and scaling.
- [Track Catalog](track_catalog.qmd): choosing the right track family.