Enhance documentation and examples for PlotNado

.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

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`).

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.

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).

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")
 ```

docs/figure_workflows.md

@@ -3,39 +3,35 @@
 ## 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.
 
 ## 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:
-
-![Advanced workflow figure](images/examples/advanced_features.png)

docs/index.md

@@ -1,78 +1,37 @@
 # PlotNado
 
-PlotNado is a Python package for making clean, publication-ready genome browser plots with a fast, chainable API.
+![PlotNado logo](assets/plotnado-logo.svg)
+
+PlotNado is a Python library for clean, publication-ready genome browser figures with a fast, chainable API.
 
 ## Install
 
 ```bash
 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:
 
-![Quickstart plot](images/examples/quickstart_first_plot.png)
+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:
-
-![Basic figure](images/examples/basic_figure.png)
-![Advanced features](images/examples/advanced_features.png)
-
-## 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)