diff --git a/.gitignore b/.gitignore
index 6246485..2013617 100644
--- a/.gitignore
+++ b/.gitignore
@@ -10,6 +10,7 @@ plotnado_figures/
*.pdf
*.png
*.svg
+!docs/assets/plotnado-logo.svg
template.toml
genes_to_json.ipynb
plot_chipment_and_mcc.ipynb
diff --git a/docs/api_reference.md b/docs/api_reference.md
index 658a21a..86d83c9 100644
--- a/docs/api_reference.md
+++ b/docs/api_reference.md
@@ -25,6 +25,37 @@ Each option payload is split into:
- `aesthetics`: style model fields (`aesthetics={...}` or shorthand kwargs).
- `label`: label controls (`label={...}` or shorthand kwargs).
+## `GenomicFigure` helper methods: automatic kwargs
+
+For helper methods like `gf.bigwig(...)`, kwargs can be provided in shorthand form and PlotNado routes them automatically:
+
+- Track fields: passed directly.
+- Aesthetics fields: routed into `aesthetics`.
+- Label fields: routed into `label`.
+
+```python
+from plotnado import GenomicFigure
+
+gf = GenomicFigure()
+gf.bigwig(
+ "signal.bw",
+ title="Sample A", # label
+ title_color="black", # label
+ style="std", # aesthetics
+ color="#1f77b4", # aesthetics
+ alpha=0.8, # aesthetics
+)
+```
+
+`color_group` is a track-level kwarg and works well with `gf.autocolor()` for consistent sample coloring:
+
+```python
+gf = GenomicFigure(theme="publication")
+gf.autocolor()
+gf.bed("sampleA.bigBed", title="A peaks", color_group="sampleA")
+gf.bigwig("sampleA.bw", title="A signal", color_group="sampleA")
+```
+
## Common entry points
- `plotnado.GenomicFigure`: high-level composition (`add_track`, `plot`, `plot_regions`, `plot_gene`, `to_toml`, `from_toml`).
diff --git a/docs/assets/plotnado-logo.svg b/docs/assets/plotnado-logo.svg
new file mode 100644
index 0000000..80ee9c1
--- /dev/null
+++ b/docs/assets/plotnado-logo.svg
@@ -0,0 +1,34 @@
+
diff --git a/docs/best_practices.md b/docs/best_practices.md
new file mode 100644
index 0000000..c284273
--- /dev/null
+++ b/docs/best_practices.md
@@ -0,0 +1,67 @@
+# Best Practices
+
+Use this checklist when building figures for analysis reports or publications.
+
+## Build figures deterministically
+
+- Pin file paths and genome build explicitly (`genome="hg38"` rather than implicit defaults).
+- Use `fig.to_toml("figure.toml")` to version figure definitions with your analysis code.
+- Rebuild figures from TOML in CI or notebooks to avoid configuration drift.
+
+## Keep track construction readable
+
+- Prefer 4 to 8 tracks per panel for first-pass interpretation.
+- Group structural tracks first (`scalebar`, `axis`, `genes`), then signals, then annotations.
+- Use explicit titles on quantitative tracks so exported figures are self-describing.
+
+## Keep colors semantically consistent
+
+- Call `gf.autocolor()` once near figure setup.
+- Reuse `color_group` across related tracks (for example BED + BigWig for one sample).
+- Avoid manually overriding colors unless you need a specific publication palette.
+
+```python
+gf = GenomicFigure(theme="publication")
+gf.autocolor()
+
+gf.bed("A.bigBed", title="A peaks", color_group="A")
+gf.bigwig("A.bw", title="A signal", color_group="A")
+gf.bed("B.bigBed", title="B peaks", color_group="B")
+gf.bigwig("B.bw", title="B signal", color_group="B")
+```
+
+## Use aliases for speed, models for strictness
+
+- Use alias helpers (`fig.bigwig(...)`, `fig.bed(...)`) for exploratory work.
+- Use explicit track classes when validating inputs/types in larger pipelines.
+- Inspect options at runtime before custom styling:
+
+```python
+from plotnado import GenomicFigure
+
+GenomicFigure.track_options("bigwig")
+GenomicFigure.track_options_markdown("genes")
+```
+
+## Validate input assumptions early
+
+- Confirm chromosome naming is consistent (`chr1` vs `1`).
+- Check region overlap before styling tweaks.
+- Keep coordinate systems and genome versions consistent across all inputs.
+
+## Use themes intentionally
+
+- Start with defaults for publication-ready output.
+- Apply a project-wide theme once (instead of per-track overrides) to reduce style drift.
+- Only disable theme (`theme=None`) when you need full manual control.
+
+## Automate quality checks
+
+- Run tests and docs build before release:
+
+```bash
+pytest tests/ -v
+mkdocs build --strict
+```
+
+- Prefer example scripts in `examples/` as regression fixtures for plotting behavior.
diff --git a/docs/example_coverage.md b/docs/example_coverage.md
new file mode 100644
index 0000000..badab37
--- /dev/null
+++ b/docs/example_coverage.md
@@ -0,0 +1,59 @@
+# Example Coverage
+
+This page maps track types to runnable examples and quick snippets.
+
+## Runnable script coverage
+
+| Track / alias | Coverage level | Example path |
+|---|---|---|
+| `scalebar` | Full runnable | `examples/quickstart/01_first_plot.py` |
+| `axis` | Full runnable | `examples/quickstart/01_first_plot.py` |
+| `genes` | Full runnable | `examples/recipes/03_gene_label_strategies.py` |
+| `bigwig` | Full runnable | `examples/tracks/01_bigwig_styles.py` |
+| `bed` | Full runnable | `examples/tracks/02_bed_and_narrowpeak.py` |
+| `narrowpeak` | Full runnable | `examples/tracks/02_bed_and_narrowpeak.py` |
+| `links` | Full runnable | `examples/tracks/03_links_annotations.py` |
+| `hline` | Full runnable | `examples/tracks/03_links_annotations.py` |
+| `vline` | Full runnable | `examples/tracks/03_links_annotations.py` |
+| `highlight` | Full runnable | `examples/recipes/01_autoscale_overlay_highlight.py` |
+| `overlay` | Full runnable | `examples/recipes/01_autoscale_overlay_highlight.py` |
+
+## Additional documented snippets
+
+These tracks are documented with snippets and option discovery, but do not yet have dedicated runnable scripts in `examples/tracks/`.
+
+### `bigwig_collection` / `bigwig_diff`
+
+```python
+gf.bigwig_collection(files=["a.bw", "b.bw"], title="Replicates")
+gf.bigwig_diff(file_a="treated.bw", file_b="control.bw", title="Treated - Control")
+```
+
+### Matrix tracks
+
+```python
+gf.cooler(file="sample.mcool", resolution=10_000)
+# gf.capcruncher(...)
+# gf.cooler_average(...)
+```
+
+### QuantNado tracks
+
+```python
+gf.quantnado_coverage("sample1", quantnado=qn, title="Coverage")
+gf.quantnado_methylation("sample1", quantnado=qn, title="Methylation")
+```
+
+## Validate option coverage quickly
+
+Use runtime metadata to inspect every field (track, aesthetics, label):
+
+```python
+from plotnado import GenomicFigure
+
+for alias in sorted(GenomicFigure.available_track_aliases()):
+ print(alias)
+ GenomicFigure.track_options(alias)
+```
+
+For full generated tables, see [Aesthetics Reference](aesthetics_reference.md).
diff --git a/docs/faq.md b/docs/faq.md
index f15b61f..9e66ca3 100644
--- a/docs/faq.md
+++ b/docs/faq.md
@@ -2,18 +2,17 @@
## Do I need CoolBox?
-No. PlotNado is independent and does not require CoolBox.
+No. PlotNado is independent.
## Can I use DataFrames instead of files?
-Yes. BigWig-like signals, BED-like intervals, highlights, and links can be created from in-memory DataFrames.
+Yes. Signal and interval-style tracks support in-memory tabular inputs where applicable.
## How do I discover all options for a track?
-Use runtime introspection:
-
```python
from plotnado import GenomicFigure
+
GenomicFigure.track_options("bigwig")
GenomicFigure.track_options_markdown("bigwig")
```
@@ -24,18 +23,13 @@ or CLI:
plotnado track-options bigwig
```
-## How do I apply consistent style to all tracks?
+## What is the recommended coding style?
-`GenomicFigure()` uses publication defaults automatically. Use:
-
-- `GenomicFigure(theme=...)` with `Theme.default()`, `Theme.minimal()`, or `Theme.publication()`.
-- `GenomicFigure(theme=None)` to opt out of themed defaults.
+Use a single `GenomicFigure` instance (`gf`) and chain helper methods. See [Track Construction](quickstart_tracks.md).
## How do I share figure definitions?
-Use TOML:
-
```python
-fig.to_toml("plot.toml")
+gf.to_toml("plot.toml")
loaded = GenomicFigure.from_toml("plot.toml")
```
diff --git a/docs/figure_workflows.md b/docs/figure_workflows.md
index e867e5d..c53eb2d 100644
--- a/docs/figure_workflows.md
+++ b/docs/figure_workflows.md
@@ -3,19 +3,19 @@
## Single region plot
```python
-fig.plot("chr1:1,000,000-1,100,000")
+gf.plot("chr1:1,000,000-1,100,000")
```
## Extend around region
```python
-fig.plot("chr1:1,000,000-1,050,000", extend=0.25)
+gf.plot("chr1:1,000,000-1,050,000", extend=0.25)
```
## Plot many regions
```python
-fig.plot_regions(["chr1:1,000,000-1,050,000", "chr1:1,060,000-1,110,000"], ncols=2)
+gf.plot_regions(["chr1:1,000,000-1,050,000", "chr1:1,060,000-1,110,000"], ncols=2)
```
`plot_regions` also accepts a BED path.
@@ -23,19 +23,15 @@ fig.plot_regions(["chr1:1,000,000-1,050,000", "chr1:1,060,000-1,110,000"], ncols
## Plot by gene symbol
```python
-fig.plot_gene("DDX11L1", extend=0.5)
+gf.plot_gene("GNAQ", extend=0.5)
```
## Save and load figure configs
```python
-fig.to_toml("figure.toml")
+gf.to_toml("figure.toml")
loaded = GenomicFigure.from_toml("figure.toml")
loaded.save("figure.png", "chr1:1,000,000-1,100,000")
```
See `examples/recipes/02_theme_labels_toml.py` for a full round-trip script.
-
-Workflow-style output example:
-
-
diff --git a/docs/index.md b/docs/index.md
index 8ff3480..4e4d220 100644
--- a/docs/index.md
+++ b/docs/index.md
@@ -1,6 +1,8 @@
# PlotNado
-PlotNado is a Python package for making clean, publication-ready genome browser plots with a fast, chainable API.
+
+
+PlotNado is a Python library for clean, publication-ready genome browser figures with a fast, chainable API.
## Install
@@ -8,71 +10,28 @@ PlotNado is a Python package for making clean, publication-ready genome browser
pip install plotnado
```
-## 5-minute quick start
+## Preferred workflow style
```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().axis().genes("hg38")
-fig.bigwig(signal, title="Synthetic signal", style="fill")
-fig.save("quickstart.png", "chr1:1,010,000-1,080,000")
-```
-
-Example output:
-
+gf = GenomicFigure(theme="publication")
+gf.autocolor()
+gf.scalebar()
+gf.genes("hg38", display="expanded", minimum_gene_length=1e5)
-## Learn by task
-
-- New user setup: [Installation](installation.md)
-- First figure quickly: [Quick Start](quickstart.md)
-- Add tracks faster with aliases: [Build Tracks Fast](quickstart_tracks.md)
-- Browse track types and options: [Track Catalog](track_catalog.md)
-- Multi-panel plotting and figure workflows: [Figure Workflows](figure_workflows.md)
-- Practical configurations: [Recipes](recipes.md)
-- Input data formats and requirements: [Data Inputs](data_inputs.md)
-- CLI usage and option discovery: [CLI](cli.md)
-
-## Example scripts
-
-Run these from the repository root:
-
-```bash
-python examples/basic_figure.py
-python examples/advanced_features.py
-python examples/run_examples.py
-```
-
-Focused examples are organized in:
-
-- `examples/quickstart/`
-- `examples/tracks/`
-- `examples/recipes/`
-
-Sample outputs:
-
-
-
-
-## Option discovery
-
-```python
-from plotnado import GenomicFigure
+gf.bigwig("signal_1.bw", title="H3K4me1", color_group="H3K4me1", style="std")
+gf.bigwig("signal_2.bw", title="H3K4me3", color_group="H3K4me3", style="std")
-GenomicFigure.available_track_aliases()
-GenomicFigure.track_options("bigwig")
-GenomicFigure.track_options_markdown("genes")
+gf.axis()
+gf.plot_gene("GNAQ")
```
+## Read by task
+- New environment setup: [Installation](installation.md)
+- First successful figure: [Quick Start](quickstart.md)
+- Ways to add tracks: [Track Construction](quickstart_tracks.md)
+- Production guidance: [Best Practices](best_practices.md)
+- Track families and support matrix: [Track Catalog](track_catalog.md)
+- CLI and runtime option discovery: [CLI](cli.md) and [API Reference](api_reference.md)
diff --git a/docs/installation.md b/docs/installation.md
index 691d085..4a02827 100644
--- a/docs/installation.md
+++ b/docs/installation.md
@@ -1,5 +1,10 @@
# Installation
+## Requirements
+
+- Python 3.12+
+- `pip`
+
## Install from PyPI
```bash
@@ -12,26 +17,9 @@ pip install plotnado
git clone https://github.com/alsmith151/plotnado
cd plotnado
pip install -e .[dev,docs]
-pip install pre-commit
pre-commit install
```
-## Developer notes
-
-- Do not hand-edit autogenerated stubs/overloads in `plotnado/figure.pyi` or auto-generated sections in `plotnado/figure.py`.
-- Update the underlying Pydantic models instead, then regenerate:
-
-```bash
-python scripts/generate_figure_overloads.py
-python scripts/generate_figure_stub.py
-```
-
-- Run hooks before commits:
-
-```bash
-pre-commit run --all-files
-```
-
## Verify installation
```bash
diff --git a/docs/quickstart.md b/docs/quickstart.md
index 11d60cc..7ba2a2a 100644
--- a/docs/quickstart.md
+++ b/docs/quickstart.md
@@ -1,8 +1,8 @@
# Quick Start
-This guide gets you from install to a first figure quickly.
+This guide gets you from installation to a first saved figure quickly.
-## 1) Create a minimal figure
+## 1) Build a minimal figure
```python
from plotnado import GenomicFigure
@@ -10,33 +10,31 @@ 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().axis().genes("hg38")
-fig.bigwig(signal, title="Synthetic signal", style="fill")
-fig.save("quickstart.png", "chr1:1,010,000-1,080,000")
+signal = pd.DataFrame(
+ {
+ "chrom": "chr1",
+ "start": bins,
+ "end": bins + 1_000,
+ "value": 5 + 2 * np.sin(np.linspace(0, 6, len(bins))),
+ }
+)
+
+gf = GenomicFigure(theme="publication")
+gf.scalebar()
+gf.axis()
+gf.genes("hg38")
+gf.bigwig(signal, title="Synthetic signal", style="fill")
+gf.save("quickstart.png", "chr1:1,010,000-1,080,000")
```
-`GenomicFigure()` applies publication-quality styling by default. Pass `theme=None` for unthemed rendering.
-
## 2) Run a ready-made script
```bash
python examples/quickstart/01_first_plot.py
```
-Expected output:
-
-
-
## 3) Next steps
-- Add tracks quickly with aliases: [Build Tracks Fast](quickstart_tracks.md)
+- Learn all track-add patterns: [Track Construction](quickstart_tracks.md)
+- Review practical defaults: [Best Practices](best_practices.md)
- Explore track families: [Track Catalog](track_catalog.md)
-- See practical patterns: [Recipes](recipes.md)
diff --git a/docs/quickstart_tracks.md b/docs/quickstart_tracks.md
index 6330439..f03feca 100644
--- a/docs/quickstart_tracks.md
+++ b/docs/quickstart_tracks.md
@@ -1,75 +1,139 @@
-# Build Tracks Fast
+# Track Construction
-Use aliases with `GenomicFigure.add_track()` or chain helper methods.
+This page shows the different ways to add tracks to a `GenomicFigure`.
-## Alias workflow
+## 1) Preferred chain-helper style
+
+This is concise and works well for interactive analysis.
```python
from plotnado import GenomicFigure
-fig = GenomicFigure()
-fig.add_track("scalebar")
-fig.add_track("axis")
-fig.add_track("genes", genome="hg38")
-fig.add_track("bigwig", data="signal.bw", title="ChIP", color="#1f77b4", alpha=0.7)
-```
+gf = GenomicFigure(theme="publication")
+gf.autocolor()
+gf.scalebar()
+gf.genes("hg38", display="expanded", minimum_gene_length=1e5)
+
+gf.bed(
+ "https://.../THP1H3K4me3_bigBed.bigBed",
+ title="THP1 H3K4me3 peaks",
+ title_color="black",
+ color_group="THP1 H3K4me3",
+ draw_edges=False,
+)
-## Shorthand kwargs
+gf.bigwig(
+ "https://.../THP1H3K4me1_bigWig.bigWig",
+ title="THP1 H3K4me1",
+ title_color="black",
+ color_group="THP1 H3K4me1",
+ style="std",
+)
-You can pass many aesthetics and label options directly:
+gf.axis()
+gf.plot_gene("GNAQ")
+```
-- Aesthetics fields (for example `color`, `alpha`, `style`) are routed to `aesthetics`.
-- Label fields (for example `plot_title`, `title_location`) are routed to `label`.
+## 2) Generic alias entrypoint (`add_track`)
-## Discover aliases and options
+Best when alias names come from config/TOML/CLI inputs.
```python
-from plotnado import GenomicFigure
+gf.add_track("scalebar")
+gf.add_track("genes", genome="hg38")
+gf.add_track("bigwig", data="signal.bw", title="ChIP", style="std")
+```
-GenomicFigure.available_track_aliases()
-GenomicFigure.track_options("bigwig")
-GenomicFigure.track_options_markdown("genes")
+## 3) Explicit track objects
+
+Best when you want strict object construction and reuse track instances.
+
+```python
+from plotnado import BigWigTrack
+
+gf.add_track(
+ BigWigTrack(
+ data="signal.bw",
+ title="ChIP",
+ style="std",
+ )
+)
```
-Or from CLI:
+## 4) Mixed approach (recommended in real projects)
+
+- Use helper methods for most tracks.
+- Use explicit classes only for custom/advanced tracks.
+- Keep structural tracks first (`scalebar`, `axis`, `genes`) for readability.
+
+## Automatic kwarg routing in `GenomicFigure` methods
+
+When you use helper methods like `gf.bigwig(...)`, PlotNado can automatically route kwargs into nested models:
+
+- Track kwargs stay at track level (for example `data`, `autoscale_group`).
+- Aesthetics kwargs are auto-packed into `aesthetics` (for example `style`, `color`, `alpha`).
+- Label kwargs are auto-packed into `label` (for example `title`, `title_color`, `title_location`).
+
+Shorthand (recommended):
-```bash
-plotnado track-options
-plotnado track-options bigwig
-plotnado track-options --all --output-format json
+```python
+gf.bigwig(
+ "signal.bw",
+ title="H3K4me3",
+ title_color="black",
+ style="std",
+ color="#1f77b4",
+ alpha=0.8,
+)
```
-Runnable example: `python examples/quickstart/02_aliases_and_options.py`
+Equivalent explicit form:
-Example output:
+```python
+gf.bigwig(
+ "signal.bw",
+ aesthetics={"style": "std", "color": "#1f77b4", "alpha": 0.8},
+ label={"title": "H3K4me3", "title_color": "black"},
+)
+```
-
+## Color management (`autocolor`, `color_group`)
+Use `autocolor()` to assign colors automatically from the active theme.
-## QuantNado-backed tracks
+```python
+gf = GenomicFigure(theme="publication")
+gf.autocolor()
+gf.bigwig("sample_a.bw", title="Sample A")
+gf.bigwig("sample_b.bw", title="Sample B")
+```
-Object-backed mode (fetch at plot time):
+Use `color_group` when multiple tracks should share the same assigned color.
```python
-from plotnado import GenomicFigure
-from quantnado import QuantNado
+gf = GenomicFigure(theme="publication")
+gf.autocolor()
+
+gf.bed("peaks_a.bigBed", title="A peaks", color_group="A")
+gf.bigwig("signal_a.bw", title="A signal", color_group="A")
-qn = QuantNado.open("dataset.zarr")
-fig = GenomicFigure()
-fig.quantnado_coverage("sample1", quantnado=qn, title="Coverage")
-fig.quantnado_methylation("sample1", quantnado=qn, title="Methylation")
-fig.plot("chr1:100000-110000")
+gf.bed("peaks_b.bigBed", title="B peaks", color_group="B")
+gf.bigwig("signal_b.bw", title="B signal", color_group="B")
```
-Array-backed mode (precomputed xarray-like arrays):
+Practical rule:
+
+- Same biological sample/condition: same `color_group`.
+- Different sample/condition: different `color_group`.
+
+## Option discovery
```python
-fig = GenomicFigure()
-fig.quantnado_variant(
- "sample1",
- allele_depth_ref_data=ref_da,
- allele_depth_alt_data=alt_da,
- title="Variant AF",
-)
-fig.plot("chr1:100000-110000")
+from plotnado import GenomicFigure
+
+GenomicFigure.available_track_aliases()
+GenomicFigure.track_options("bigwig")
+GenomicFigure.track_options_markdown("genes")
```
+
+See [Track Aliases](track_aliases.md) for alias notes, [Example Coverage](example_coverage.md) for runnable script mapping, and [Best Practices](best_practices.md) for production guidance.
diff --git a/docs/recipes.md b/docs/recipes.md
index 6fb6a32..53cbf1c 100644
--- a/docs/recipes.md
+++ b/docs/recipes.md
@@ -4,33 +4,40 @@ Practical combinations of options and track types.
## Autoscale + overlay + highlight
-- Enable global autoscaling with `fig.autoscale(True)`.
-- Overlay multiple signals with `fig.overlay(...)` / `OverlayTrack`.
-- Mark regions with `fig.highlight(...)` and `fig.highlight_style(...)`.
+- Enable global autoscaling with `gf.autoscale(True)`.
+- Overlay multiple signals with `gf.overlay(...)` / `OverlayTrack`.
+- Mark regions with `gf.highlight(...)` and `gf.highlight_style(...)`.
Script: `examples/recipes/01_autoscale_overlay_highlight.py`
-
-
## Theme + labels + TOML round-trip
-- Apply publication defaults with `Theme.publication()`.
-- Control label rendering with shorthand label kwargs.
+- Apply publication defaults with `theme="publication"`.
+- Control labels with shorthand kwargs (`title`, `title_color`, `title_location`).
- Save and reload figure definitions with TOML.
Script: `examples/recipes/02_theme_labels_toml.py`
-
-
+## Autocolor + color groups
+
+- Enable auto palette assignment with `gf.autocolor()`.
+- Use `color_group` so related tracks share one color.
+
+```python
+gf = GenomicFigure(theme="publication")
+gf.autocolor()
+gf.bed("THP1_peaks.bigBed", title="THP1 peaks", color_group="THP1")
+gf.bigwig("THP1_signal.bw", title="THP1 signal", color_group="THP1")
+gf.bed("K562_peaks.bigBed", title="K562 peaks", color_group="K562")
+gf.bigwig("K562_signal.bw", title="K562 signal", color_group="K562")
+```
## Track-style comparisons
-- Compare BigWig styles (`fill`, `fragment`, `scatter`).
+- Compare BigWig styles (`fill`, `fragment`, `scatter`, `std`).
- Compare BED and narrowPeak interval behavior.
Scripts:
- `examples/tracks/01_bigwig_styles.py`
- `examples/tracks/02_bed_and_narrowpeak.py`
-
-
diff --git a/docs/track_aliases.md b/docs/track_aliases.md
index 460533b..5835d55 100644
--- a/docs/track_aliases.md
+++ b/docs/track_aliases.md
@@ -1,65 +1,41 @@
# Track Aliases
-`GenomicFigure.add_track()` accepts either a concrete track instance or a string alias with kwargs.
+`GenomicFigure.add_track()` accepts either a concrete track object or a string alias.
+
+## Alias usage
```python
from plotnado import GenomicFigure
-fig = GenomicFigure()
-fig.add_track("scalebar", position="right")
-fig.add_track("axis")
-fig.add_track("genes", genome="hg38")
-fig.add_track("bigwig", data="signal.bw", color="#1f77b4", alpha=0.7)
+gf = GenomicFigure()
+gf.add_track("scalebar")
+gf.add_track("axis")
+gf.add_track("genes", genome="hg38")
+gf.add_track("bigwig", data="signal.bw", style="fill")
```
-## Shorthand kwargs routing
-
-- Track fields go directly to the track model.
-- Aesthetics fields can be passed directly (auto-packed into `aesthetics`).
-- Label fields can be passed directly (auto-packed into `label`).
-- If both shorthand and nested models are provided, shorthand values win for overlapping keys.
+## How kwargs are routed
-## Complete Alias Reference
+- Track constructor fields: passed directly.
+- Aesthetics fields (for example `color`, `alpha`, `style`): routed to `aesthetics`.
+- Label fields (for example `title`, `title_color`, `title_location`): routed to `label`.
+- If both shorthand and nested objects are supplied, shorthand values win for overlapping keys.
-| Alias | Track Class | Typical kwargs |
-|---|---|---|
-| `scalebar` | `ScaleBar` | `position="left"`, `scale_distance=...` |
-| `scale` | `ScaleBar` | synonym of `scalebar` |
-| `axis` | `GenomicAxis` | `num_ticks=...`, `show_chromosome=True` |
-| `genes` | `Genes` | `genome="hg38"` or `data="genes.gtf.gz"` |
-| `spacer` | `Spacer` | `height=...` |
-| `bigwig` | `BigWigTrack` | `data="signal.bw"`, `style="fill"`, `color=...` |
-| `bed` | `BedTrack` | `data="regions.bed"` or in-memory `DataFrame` |
-| `highlight` | `HighlightsFromFile` | `data="regions.bed"` |
-| `overlay` | `OverlayTrack` | `tracks=[track_a, track_b]` or `tracks=["a.bw", "b.bw"]` |
-| `bigwig_overlay` | `BigwigOverlay` | Backward-compatible alias of `overlay` |
-| `bigwig_collection` | `BigWigCollection` | `files=[...]`, `style="overlay"` |
-| `bigwig_diff` | `BigWigDiff` | `file_a="a.bw"`, `file_b="b.bw"`, `method="subtract"` |
-| `narrowpeak` | `NarrowPeakTrack` | `data="peaks.narrowPeak"` |
-| `links` | `LinksTrack` | `data="loops.bedpe"` |
-| `hline` | `HLineTrack` | `y_value=...` |
-| `vline` | `VLineTrack` | `x_position=...` |
-| `cooler` | `CoolerTrack` | `file="matrix.mcool"`, `resolution=10000` |
-| `capcruncher` | `CapcruncherTrack` | `file=...`, `viewpoint=...`, `normalisation=...` |
-| `cooler_average` | `CoolerAverage` | `files=[... ]`, `resolution=...` |
+## Common aliases
-| `quantnado_coverage` | `QuantNadoCoverageTrack` | `sample="s1"`, `quantnado=qn` or `coverage_data=...` |
-| `quantnado_stranded_coverage` | `QuantNadoStrandedCoverageTrack` | `sample="s1"`, `quantnado=qn` or `coverage_fwd_data=...`, `coverage_rev_data=...` |
-| `quantnado_methylation` | `QuantNadoMethylationTrack` | `sample="s1"`, `quantnado=qn` or `methylation_data=...` |
-| `quantnado_variant` | `QuantNadoVariantTrack` | `sample="s1"`, `quantnado=qn` or `allele_depth_ref_data=...`, `allele_depth_alt_data=...` |
+- Structural: `scalebar`, `axis`, `genes`, `spacer`
+- Signal: `bigwig`, `overlay`, `bigwig_collection`, `bigwig_diff`
+- Interval/annotation: `bed`, `narrowpeak`, `links`, `highlight`, `hline`, `vline`
+- Matrix: `cooler`, `capcruncher`, `cooler_average`
+- QuantNado: `quantnado_coverage`, `quantnado_stranded_coverage`, `quantnado_methylation`, `quantnado_variant`
-## Example
+## Get the full, current alias map
```python
from plotnado import GenomicFigure
-fig = GenomicFigure(width=12)
-fig.axis()
-fig.genes("hg38")
-fig.add_track("bigwig", data="chipseq.bw", title="ChIP", style="fill")
-fig.add_track("vline", x_position=1_050_000)
-
-fig.plot("chr1:1,000,000-1,100,000")
+aliases = GenomicFigure.available_track_aliases()
+print("\n".join(f"{k} -> {v}" for k, v in sorted(aliases.items())))
```
-Use [Track Catalog](track_catalog.md) for track-specific examples and [API Reference](api_reference.md) for full option metadata.
+Use [Track Catalog](track_catalog.md) for track families and [Aesthetics Reference](aesthetics_reference.md) for full field-level options.
diff --git a/docs/track_catalog.md b/docs/track_catalog.md
index 22cceea..716de36 100644
--- a/docs/track_catalog.md
+++ b/docs/track_catalog.md
@@ -1,6 +1,6 @@
# Track Catalog
-This page summarizes major track types and points to runnable scripts.
+This page summarizes major track families and points to runnable scripts.
## Structural tracks
@@ -10,61 +10,63 @@ This page summarizes major track types and points to runnable scripts.
## Signal tracks
-- `bigwig` (`BigWigTrack`): continuous or interval signal (`style`: `fill`, `fragment`, `scatter`).
-- `overlay` (`OverlayTrack`): generic overlay panel for multiple tracks/signals.
-- `bigwig_overlay` (`BigwigOverlay`): backward-compatible alias of `OverlayTrack`.
-- `bigwig_collection` (`BigWigCollection`): collection workflows for multiple BigWigs.
+- `bigwig` (`BigWigTrack`): continuous/interval signal (`style`: `fill`, `fragment`, `scatter`, `std`).
+- `overlay` (`OverlayTrack`): multi-signal overlay panel.
+- `bigwig_overlay` (`BigwigOverlay`): compatibility alias for `overlay`.
+- `bigwig_collection` (`BigWigCollection`): multi-BigWig collection workflows.
- `bigwig_diff` (`BigWigDiff`): subtraction/ratio/log2ratio between two tracks.
-Runnable scripts:
+Scripts:
- `examples/tracks/01_bigwig_styles.py`
- `examples/recipes/01_autoscale_overlay_highlight.py`
-
-
-
## Interval and annotation tracks
- `bed` (`BedTrack`): interval rectangles with optional labels.
-- `narrowpeak` (`NarrowPeakTrack`): peak-specific intervals with summit and score-based colors.
-- `genes` (`Genes`): gene models from bundled genome annotations or custom files.
+- `narrowpeak` (`NarrowPeakTrack`): peak intervals with summit/score support.
+- `genes` (`Genes`): gene models from bundled or custom annotations.
- `links` (`LinksTrack`): arcs for BEDPE-style interactions.
-- `hline` / `vline`: reference lines.
- `highlight` (`HighlightsFromFile`): region overlays.
+- `hline` / `vline`: reference lines.
-Runnable scripts:
+Scripts:
- `examples/tracks/02_bed_and_narrowpeak.py`
- `examples/tracks/03_links_annotations.py`
-
-
-
## Matrix tracks
- `cooler` (`CoolerTrack`)
- `capcruncher` (`CapcruncherTrack`)
- `cooler_average` (`CoolerAverage`)
-These require cooler-compatible input files.
-
+These require cooler-compatible files.
## QuantNado tracks
-- `quantnado_coverage` (`QuantNadoCoverageTrack`): single-sample coverage track.
-- `quantnado_stranded_coverage` (`QuantNadoStrandedCoverageTrack`): mirrored +/− strand coverage.
-- `quantnado_methylation` (`QuantNadoMethylationTrack`): per-CpG methylation scatter.
-- `quantnado_variant` (`QuantNadoVariantTrack`): variant allele-frequency lollipop track.
+- `quantnado_coverage`
+- `quantnado_stranded_coverage`
+- `quantnado_methylation`
+- `quantnado_variant`
+
+These support object-backed and array-backed workflows.
-These tracks accept either:
+## Field-level options
-- a live `quantnado` object (or `dataset_path`) for region-time fetching, or
-- precomputed xarray-like arrays with dims `(sample, position)`.
-## Option reference
+- Runtime introspection: `GenomicFigure.track_options("")`
+- Full generated table: [Aesthetics Reference](aesthetics_reference.md)
+- Script mapping by track: [Example Coverage](example_coverage.md)
-For full per-field options and descriptions:
+## Coverage snapshot
-- [Track Aliases](track_aliases.md)
-- [Aesthetics Reference](aesthetics_reference.md)
-- `GenomicFigure.track_options("")`
+| Track / alias | Coverage | Primary example(s) |
+|---|---|---|
+| `scalebar`, `axis`, `genes` | Runnable script | `examples/quickstart/01_first_plot.py`, `examples/recipes/03_gene_label_strategies.py` |
+| `bigwig` | Runnable script | `examples/tracks/01_bigwig_styles.py`, `examples/basic_figure.py` |
+| `bed`, `narrowpeak` | Runnable script | `examples/tracks/02_bed_and_narrowpeak.py` |
+| `links`, `hline`, `vline` | Runnable script | `examples/tracks/03_links_annotations.py` |
+| `highlight`, `overlay` | Runnable script | `examples/recipes/01_autoscale_overlay_highlight.py` |
+| `bigwig_collection`, `bigwig_diff` | Documented pattern | `docs/recipes.md` |
+| `cooler`, `capcruncher`, `cooler_average` | Documented pattern | `docs/track_catalog.md` |
+| QuantNado aliases | Documented pattern | `docs/quickstart_tracks.md` |
diff --git a/docs/troubleshooting.md b/docs/troubleshooting.md
index 096b78f..ecabbeb 100644
--- a/docs/troubleshooting.md
+++ b/docs/troubleshooting.md
@@ -2,10 +2,9 @@
## `Unknown track alias`
-Check supported aliases:
-
```python
from plotnado import GenomicFigure
+
GenomicFigure.available_track_aliases()
```
@@ -13,27 +12,21 @@ GenomicFigure.available_track_aliases()
- Confirm the region overlaps your data.
- Check chromosome naming consistency (`chr1` vs `1`).
-- Validate DataFrame column names for your track type.
+- Validate required columns for your track input.
-## TOML export/import errors
+## Docs build fails with Python version error
-`to_toml()` requires `tomli-w`.
-
-Install optional docs/dev extras:
+PlotNado requires Python 3.12+.
```bash
-pip install -e .[dev,docs]
+python --version
+mkdocs build --strict
```
-## Matrix tracks fail to load
-
-`cooler`-based tracks require cooler-compatible files and dependencies.
-
-## Docs build issues
+## TOML export/import errors
-Reinstall docs extras and rebuild:
+Install optional dependencies:
```bash
pip install -e .[docs]
-mkdocs build --strict
```
diff --git a/mkdocs.yaml b/mkdocs.yaml
index f81c41f..2dbf980 100644
--- a/mkdocs.yaml
+++ b/mkdocs.yaml
@@ -3,8 +3,10 @@ nav:
- Home: index.md
- Installation: installation.md
- Quick Start: quickstart.md
- - Build Tracks Fast: quickstart_tracks.md
+ - Best Practices: best_practices.md
+ - Track Construction: quickstart_tracks.md
- Track Catalog: track_catalog.md
+ - Example Coverage: example_coverage.md
- Figure Workflows: figure_workflows.md
- Recipes: recipes.md
- Data Inputs: data_inputs.md
@@ -19,6 +21,8 @@ nav:
theme:
name: mkdocs
+ logo: assets/plotnado-logo.svg
+ favicon: assets/plotnado-logo.svg
markdown_extensions:
- toc:
permalink: true
@@ -59,4 +63,4 @@ repo_url: https://github.com/alsmith151/plotnado
validation:
nav:
- omitted_files: ignore
\ No newline at end of file
+ omitted_files: ignore
diff --git a/scripts/gen_ref_pages.py b/scripts/gen_ref_pages.py
index 13d7b54..4bc64ee 100644
--- a/scripts/gen_ref_pages.py
+++ b/scripts/gen_ref_pages.py
@@ -78,6 +78,31 @@ def _generate_aesthetics_reference() -> None:
"This page is auto-generated from runtime model metadata (`Track.options()`).",
"",
"Track styles are configured through nested `aesthetics=...` models.",
+ "When using `GenomicFigure` helper methods (for example `gf.bigwig(...)`),",
+ "aesthetics and label kwargs can also be passed directly and are routed automatically.",
+ "",
+ "Shorthand example:",
+ "",
+ "```python",
+ "gf.bigwig(",
+ " \"signal.bw\",",
+ " title=\"Sample\",",
+ " title_color=\"black\",",
+ " style=\"std\",",
+ " color=\"#1f77b4\",",
+ " alpha=0.8,",
+ ")",
+ "```",
+ "",
+ "Equivalent explicit form:",
+ "",
+ "```python",
+ "gf.bigwig(",
+ " \"signal.bw\",",
+ " aesthetics={\"style\": \"std\", \"color\": \"#1f77b4\", \"alpha\": 0.8},",
+ " label={\"title\": \"Sample\", \"title_color\": \"black\"},",
+ ")",
+ "```",
"",
]