Skip to content

Track Construction

This page shows the different ways to add tracks to a GenomicFigure.

1) Preferred chain-helper style

This is concise and works well for interactive analysis.

from plotnado import GenomicFigure

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

gf.bigwig(
    "https://.../THP1H3K4me1_bigWig.bigWig",
    title="THP1 H3K4me1",
    title_color="black",
    color_group="THP1 H3K4me1",
    style="std",
)

gf.axis()
gf.plot_gene("GNAQ")

2) Generic alias entrypoint (add_track)

Best when alias names come from config/TOML/CLI inputs.

gf.add_track("scalebar")
gf.add_track("genes", genome="hg38")
gf.add_track("bigwig", data="signal.bw", title="ChIP", style="std")

3) Explicit track objects

Best when you want strict object construction and reuse track instances.

from plotnado import BigWigTrack

gf.add_track(
    BigWigTrack(
        data="signal.bw",
        title="ChIP",
        style="std",
    )
)
  • Use helper methods for most tracks.
  • Use explicit classes only for custom/advanced tracks.
  • Keep structural tracks first (scalebar, axis, genes) for readability.

Overlay tracks with shared scaling

Use overlay() when several signals should occupy one panel. Treat the overlay as a real track: give the overlay its own title, autoscale_group, and optional min_value / max_value.

gf.overlay(
    [sample_a, sample_b],
    title="Replicate overlay",
    autoscale_group="signal-panels",
    colors=["#2ca02c", "#9467bd"],
    alpha=0.6,
)

Practical rule:

  • Use autoscale_group on the overlay itself when the whole panel should sync with neighboring signal tracks.
  • Use overlay min_value / max_value only when you intentionally want to pin one edge.
  • Use separate panels instead of an overlay when the series need independent y-ranges for interpretation.

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

gf.bigwig(
    "signal.bw",
    title="H3K4me3",
    title_color="black",
    style="std",
    color="#1f77b4",
    alpha=0.8,
)

Equivalent explicit form:

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.

gf = GenomicFigure(theme="publication")
gf.autocolor()
gf.bigwig("sample_a.bw", title="Sample A")
gf.bigwig("sample_b.bw", title="Sample B")

Use color_group when multiple tracks should share the same assigned color.

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

gf.bed("peaks_b.bigBed", title="B peaks", color_group="B")
gf.bigwig("signal_b.bw", title="B signal", color_group="B")

Practical rule:

  • Same biological sample/condition: same color_group.
  • Different sample/condition: different color_group.

Option discovery

from plotnado import GenomicFigure

GenomicFigure.available_track_aliases()
GenomicFigure.track_options("bigwig")
GenomicFigure.track_options("overlay")
GenomicFigure.track_options_markdown("genes")

See Track Aliases for alias notes, Example Coverage for runnable script mapping, and Best Practices for production guidance.