plot-io 0.12.0__py3-none-win_amd64.whl

plot_io/genome/signal.py

@@ -0,0 +1,621 @@
+"""Binned signals (:class:`BigWig`): a step line along the bins, filled to a baseline or,
+by a track's ``fill_mode``, between neighbouring signals; with ``bin_mode="auto"`` the
+mean line over a band from the bins' minimum to their maximum; with ``kind="heat"`` a
+one-row lane of cells colored by value (the heat signals of a track share one color
+axis)."""
+
+import contextlib
+import math
+from array import array
+from typing import TYPE_CHECKING, Any, Self, Unpack
+
+from vec_io.arrays import doubles
+
+from .. import groups, kernels
+from ..color.values import color, with_alpha
+from ..settings import Setting, one_of, table
+from ..transform import settings_both as coord_settings
+from ..layers import positions, add_layer
+from ..layers.base import Series, common
+from ..layers.core import Call, Layer, Table
+from ..layers.geoms import GEOMS, with_crossings
+from ..layers.grammar import entry
+from ..layers.paint import Paint, base_color, role
+from ..mapped import ColorAxis, own_axis, shared_axis, trained
+from ..validators import length, real
+from . import readers, sources
+from .lanes import lane_mapper, lane_setting
+from .series import GenomeSeries, check_bins, in_segment, region_setting
+
+if TYPE_CHECKING:
+    from ..types import BigWigSettings
+
+__all__ = ["BigWig", "fill_mode", "signal_bands"]
+
+
+_REDUCTIONS = ("mean", "sd", "sem", "sum", "count", "min", "max", "l1norm", "l2norm")
+#: The reductions ``bin_mode="auto"`` reads: the line, the band's low and high ends.
+_AUTO = ("mean", "min", "max")
+
+
+def _def_value(v: Any) -> float:
+    x = real(v)
+    if x is None:
+        raise ValueError(f"expected a number (NaN allowed), got {v!r}")
+    return x
+
+
+def _callable(v: Any) -> Any:
+    if not callable(v):
+        raise ValueError(f"expected a function, got {v!r}")
+    return v
+
+
+_FILL_MODES = ("up", "down", "min", "max")
+
+
+def fill_mode(v: Any) -> str | None:
+    """A track's ``fill_mode``: ``None`` or ``"in_between(up|down|min|max)"`` (stored as the
+    word in parentheses; ``"in_between"`` is ``up``)."""
+    if v is None:
+        return None
+    t = str(v).replace(" ", "").lower() if isinstance(v, str) else None
+    if t == "in_between":
+        return "up"
+    if t is not None and t.startswith("in_between(") and t.endswith(")") \
+            and t[11:-1] in _FILL_MODES:
+        return t[11:-1]
+    if t in _FILL_MODES:
+        return t
+    raise ValueError(f"expected None or \"in_between(up|down|min|max)\", got {v!r}")
+
+
+def _fill_to(v: Any) -> Any:
+    if v is False:
+        return False
+    if isinstance(v, Series):
+        return v
+    x = real(v)
+    if x is None or not math.isfinite(x):
+        raise ValueError(f"expected a number, a series or False, got {v!r}")
+    return x
+
+
+class BigWig(GenomeSeries):
+    """A binned signal over the region: a step line along the bins, filled to a baseline.
+    ``reader`` is a signal reader (bigWig; bigBed, BED and peaks give their coverage;
+    :func:`~plot_io.genome.combine.combine` of two), a path (opened with gwseq_io),
+    ``chr``, ``start``, ``end``, ``value`` records (columns, a DataFrame or rows; binned
+    by plot_io), a function ``f(chr, start, end, bins)`` giving values, or ``None`` with
+    ``y`` (values over the region) and optionally ``x`` (bin centres, or n + 1 edges, in
+    bp).
+
+    Records and paths: see `readers <docs/api.md#readers>`_.  The color is black when the series is alone in its
+    track, the plot's colors when overlaid.  ``fill_to=<series>`` fills between two signals,
+    each part in the fill color of the series on top.  For more, the track's ``fill_mode``
+    fills between all its signals, in place of their ``fill_to``: ``"in_between(up)"`` (or
+    ``"in_between"``) fills each band between two neighbouring signals in the color of the
+    one just above, ``"in_between(down)"`` of the one just below; ``"in_between(max)"`` fills
+    from the lowest signal to the highest in the color of the top one, ``"in_between(min)"``
+    of the bottom one.  The colors follow wherever the order changes (lines get points where
+    they cross), and 0 is not kept on the y axis::
+
+        t = fig.track(y_axis={"label": "Lamin A/C"}, fill_mode="in_between(up)")
+        t.bigwig(neo_reader, name="Neo")
+        t.bigwig(pax7_reader, name="Pax7")
+
+    ``bin_mode="auto"`` reads each bin's mean, minimum and maximum: the line is the mean, a
+    band from the minimum to the maximum (in the fill color at ``fill_opacity``) replaces
+    the fill, and the y limits cover the band (narrow peaks stay visible at any zoom; three
+    reads).  ``kind="heat"`` draws the bins as one row of cells colored through
+    ``color_map``, in a lane of its own ``row_height`` high, named on the left (``name``);
+    the heat strips of a track share one color axis (the first one's ``color_*`` settings,
+    one colorbar with ``colorbar=True``), and a track of heat strips alone has no y axis.
+
+    ``plot_io.genome.combine(a, b, op="log2ratio", pseudo_count=0)`` is a signal reader of
+    two (readers, paths or records), read with the same arguments and combined bin by bin:
+    ``"difference"`` (``a − b``), ``"ratio"`` (``(a + p) / (b + p)``), ``"log2ratio"``
+    (``log2((a + p) / (b + p))``) or a function ``op(a, b)`` of two numbers; NaN where
+    either is NaN or the result is undefined::
+
+        t = fig.track()
+        for name, r in readers.items():
+            t.bigwig(r, kind="heat", name=name, colorbar=True)
+        fig.bigwig(plt.genome.combine(treat, control, "log2ratio", pseudo_count=1))
+
+    Example::
+
+        import math
+        fig = plt.Tracks(("chr1", 0, 200_000), width=300)
+        fig.bigwig(y=[0.2 + math.exp(-((i - 60) / 6) ** 2) + 0.6 * math.exp(-((i - 140) / 10) ** 2)
+                      for i in range(200)])
+    """
+
+    SETTINGS = table(
+        region=region_setting(),
+        bins=Setting(check_bins,
+                     doc="A bin count over the region (exactly, not on a grid); a bin size "
+                         "(`\"10kb\"`, `\"5000bp\"`), read on the genome-wide grid of the "
+                         "size (the row grown to it, then cut to the region); or a bin "
+                         "width on the axes (`\"0.5px\"`: two bins per px, read as a "
+                         "count)."),
+        bin_mode=Setting(one_of(*_REDUCTIONS, "auto"),
+                         doc="Reduction per bin: `mean`, `max` (keeps narrow peaks), `min`, "
+                             "`sum`, … (gwseq_io's); `auto`: the mean line over a band from "
+                             "each bin's `min` to its `max` (in the fill color at "
+                             "`fill_opacity`, in place of the fill; three reads)."),
+        def_value=Setting(_def_value,
+                          doc="Value of bases no record covers; NaN breaks the line there."),
+        kind=Setting(one_of("step", "line", "bar", "heat"),
+                     doc="`step` (a step line along the bins), `line` (through the bin "
+                         "centres), `bar` (one rectangle per bin) or `heat` (a lane of one "
+                         "row of cells colored through `color_map`, named on the left; "
+                         "the heat signals of a track share one color axis, set by the "
+                         "first one's `color_*` settings)."),
+        lane=lane_setting(),
+        row_height=Setting(length(positive=True, percent="em"),
+                           doc="`kind=\"heat\"`: the height of the lane."),
+        fill_to=Setting(_fill_to,
+                        doc="Fill between the signal and a value, another series of the "
+                            "track (colored by whichever is above), or `False`."),
+        **groups.FillStyle.embed(docs={"fill": "Fill (to `fill_to`): `True` (the line "
+                                               "color), a color, or `False`.",
+                                       "fill_opacity": "Opacity of the fill, times "
+                                                       "`opacity`."}),
+        color=Setting(color, doc="Line color; default black alone in its track, the next "
+                                 "plot's color when overlaid."),
+        transform=Setting(_callable, doc="A function applied to each value (log, scaling)."),
+        **common("name", "color_map", "opacity", "z", "rasterize", "simplify", "line_width",
+                 "font_size", "font_family", "text_color",
+                 docs={"colorbar": "`kind=\"heat\"`: a colorbar of the track's heat color "
+                                   "axis attached to the track (one per track): `True`, a "
+                                   "place or a dict of colorbar settings."}),
+        **coord_settings(),
+    )
+
+    def __init__(self, reader: Any = None, plot: Any = None, *, x: Any = None, y: Any = None,
+                 **settings: Any) -> None:
+        if reader is None and y is None:
+            raise TypeError("BigWig needs a reader, a function or y values")
+        self.reader = None if reader is None else readers.adapt(reader, "signal", "BigWig",
+                                                                owner=self)
+        self.x_data = None if x is None else doubles(x)
+        self.y_data = None if y is None else doubles(y)
+        if self.x_data is not None and self.y_data is not None and \
+                len(self.x_data) not in (len(self.y_data), len(self.y_data) + 1):
+            raise ValueError(f"x has {len(self.x_data)} values for {len(self.y_data)} bins "
+                             f"(give centres or edges)")
+        super().__init__(plot=plot, **settings)
+
+    def set(self, **settings: "Unpack[BigWigSettings]") -> Self:  # type: ignore[override]
+        super().set(**settings)
+        if getattr(self, "plot", None) is not None:
+            self._attach_bar()
+        return self
+
+    # -- heat signals ----------------------------------------------------------------
+
+    def is_heat(self) -> bool:
+        """Whether it is drawn as a heat strip (``kind="heat"``)."""
+        return self.resolve("kind") == "heat"
+
+    def in_lane(self) -> bool:
+        """Whether it is drawn in a lane of its own (:mod:`plot_io.genome.lanes`): a heat
+        strip."""
+        return self.is_heat()
+
+    def lane_rows(self) -> int:
+        return 1
+
+    def drawn_rows(self) -> tuple[float, float]:
+        return 0.0, 1.0
+
+    def row_px(self) -> float:
+        return float(self.resolve("row_height"))
+
+    def heat_axis(self) -> ColorAxis:
+        """The color axis of a heat strip: the shared one given as ``color_axis=``, else the
+        track's (the own axis of its first heat signal without a shared one)."""
+        axis = shared_axis(self, "color")
+        if axis is not None:
+            return axis
+        plot = self.plot
+        first = next((s for s in (plot.series if plot is not None else ())
+                      if isinstance(s, BigWig) and s.is_heat()
+                      and s.resolve("color_axis") is None), self)
+        return own_axis(first, ColorAxis)
+
+    @property
+    def color_axis(self) -> Any:
+        """The color axis of a heat strip (:meth:`heat_axis`)."""
+        return self.heat_axis()
+
+    def _bar_source(self) -> Any:
+        return self.heat_axis() if self.is_heat() else None
+
+    # -- data ----------------------------------------------------------------------
+
+    def bins(self) -> tuple[int | None, int | None]:
+        """``(bin count, bin size)``: one of them."""
+        b = self.resolve("bins")
+        if b.kind == "count":
+            return int(b.value), None
+        if b.kind == "bp":
+            return None, int(b.value)
+        return max(1, round(self.axes_px() / b.value)), None
+
+    def data(self) -> tuple[array, array]:
+        """``(edges, values)``: n + 1 bin edges (bp) and n values."""
+        edges, vals, _ = self.reads()
+        return edges, vals
+
+    def reads(self) -> tuple[array, array, tuple[array, array] | None]:
+        """``(edges, values, band)``: :meth:`data`, and with ``bin_mode="auto"`` the band
+        ``(low, high)``: each bin's ``min`` and ``max`` (``None`` otherwise, and for plain
+        values and functions).  The reads of one draw are cached as one."""
+        if self.reader is None and self.x_data is not None:
+            key: Any = ("plain",)
+        else:
+            key = (self.region(), self.bins(), self.resolve("bin_mode"),
+                   self.resolve("def_value"))
+        return self.cached(key, lambda: self._guard(self._read), kind="data")
+
+    def _read(self) -> tuple[array, array, tuple[array, array] | None]:
+        band = None
+        if self.reader is None:
+            assert self.y_data is not None
+            vals = array("d", self.y_data)
+            n = len(vals)
+            if not n:
+                edges = array("d")
+            elif self.x_data is None:
+                r = self.region()
+                edges = sources.even_edges(r.start, r.end, n)
+            elif len(self.x_data) == n + 1:
+                edges = array("d", self.x_data)
+            else:
+                c = self.x_data
+                if n == 1:
+                    edges = array("d", [c[0] - 0.5, c[0] + 0.5])
+                else:
+                    mids = [(a + b) / 2 for a, b in zip(c, c[1:])]
+                    edges = array("d", [c[0] - (mids[0] - c[0])] + mids
+                                  + [c[-1] + (c[-1] - mids[-1])])
+        elif sources.kind_of(self.reader) is None:            # a function
+            r = self.region()
+            count, size = self.bins()
+            n = count if count is not None else max(1, math.ceil(r.span / (size or 1)))
+            vals = doubles(self.reader(r.chr, r.start, r.end, n))
+            if len(vals) != n:
+                raise ValueError(f"the function gave {len(vals)} values for {n} bins")
+            edges = sources.even_edges(r.start, r.end, n)
+        else:
+            count, size = self.bins()
+            mode = self.resolve("bin_mode")
+            got = [sources.read_signal(self.reader, self.region(), count, size, m,
+                                       self.resolve("def_value"))
+                   for m in (_AUTO if mode == "auto" else (mode,))]
+            edges, vals = got[0]
+            if len(got) > 1:
+                band = (got[1][1], got[2][1])
+        f = self.resolve("transform")
+        if f is not None:
+            vals = array("d", [float(f(v)) for v in vals])
+            if band is not None:
+                band = (array("d", [float(f(v)) for v in band[0]]),
+                        array("d", [float(f(v)) for v in band[1]]))
+        return edges, vals, band
+
+    def centres_at(self, xs: Any) -> array:
+        """The signal through the bin centres (``kind="line"``) at ``xs``: NaN outside."""
+        return centres_at(*self.data(), xs)
+
+    def values_at(self, edges: Any) -> array:
+        """The values at the centres of the bins ``edges`` (another series' bins)."""
+        return values_at(*self.data(), edges)
+
+    def fill_mode(self) -> str | None:
+        """The track's ``fill_mode`` (``None`` on a plot without one, for bars, heat strips
+        and ``bin_mode="auto"``)."""
+        p = self.plot
+        if p is None or "fill_mode" not in p.SETTINGS or self.resolve("kind") in ("bar", "heat") \
+                or self._banded():
+            return None
+        return p.resolve("fill_mode")
+
+    def _banded(self) -> bool:
+        """Whether it draws a min–max band (``bin_mode="auto"`` on a reader) in place of
+        its fill."""
+        return self.resolve("bin_mode") == "auto" and self.reader is not None \
+            and sources.kind_of(self.reader) is not None
+
+    def _fill_to(self) -> Any:
+        if self.fill_mode() is not None or self._banded():
+            return False
+        return self.resolve("fill_to")
+
+    def _alone(self) -> bool:
+        return not any(isinstance(s, BigWig) and s is not self and not s.is_set("color")
+                       and not s.is_heat() for s in self.plot.series)
+
+    def line_color(self, ctx: Any) -> Any:
+        """The line color: its own, black alone in its track, else the plot's next."""
+        if not self.is_set("color") and self._alone():
+            return ctx.color("black")
+        return base_color(self, ctx)
+
+    def fill_of(self, ctx: Any) -> Any:
+        c = groups.fill_parts(self)[0]
+        return ctx.color(c) if c is not None else self.line_color(ctx)
+
+    def fill_amount(self) -> float:
+        """The opacity of the fill (0 without one)."""
+        return groups.fill_parts(self)[1]
+
+    def _points(self, edges: Any, vals: Any) -> tuple[array, array, str]:
+        style = self.resolve("kind")
+        if style == "line":
+            return (array("d", [(a + b) / 2 for a, b in zip(edges, edges[1:])]),
+                    array("d", vals), "linear")
+        ys = array("d", vals)
+        if len(ys):
+            ys.append(ys[-1])
+        return array("d", edges), ys, "step-post"
+
+    # -- the preset (stat region_signal) ----------------------------------------------
+
+    def layers(self) -> Call:
+        edges, vals, band = self.reads()
+        call = self.genome_call()
+        if self.is_heat():
+            return self._heat(call, edges, vals)
+        opacity = self.resolve("opacity")
+        opacity = 1.0 if opacity is None else opacity
+        to = self._fill_to()
+        style = self.resolve("kind")
+        mode = self.fill_mode()
+        if len(vals):
+            xs, ys, interp = self._points(edges, vals)
+            fill_opacity = self.fill_amount() * opacity
+            if band is not None and fill_opacity > 0:
+                _, lo, _ = self._points(edges, band[0])
+                _, hi, _ = self._points(edges, band[1])
+                call.layers.append(Layer(GEOMS["band"], Table(x=xs, y1=lo, y2=hi),
+                                         paint=Paint(self, "signal.fill",
+                                                     opacity=fill_opacity, interp=interp),
+                                         stat="region_signal", key=False))
+            if style == "bar":
+                base = to if isinstance(to, float) else 0.0
+                t = Table(x0=edges[:-1], x1=edges[1:], y0=base, y1=vals)   # NaN: no bar
+                call.layers.append(Layer(GEOMS["rects"], t,
+                                         paint=Paint(self, "signal.bars", opacity=opacity),
+                                         stat="region_signal", key=False))
+            else:
+                if mode is not None:
+                    t = Table()
+                    t.signal = (self, mode)                        # type: ignore[attr-defined]
+                    call.tables.append(t)
+                    call.layers.append(Layer(GEOMS["band"], t, aes={"x": "band_x",
+                                                                    "y1": "band_y",
+                                                                    "y2": "band_bound"},
+                                             paint=Paint(self, "signal.fill",
+                                                         opacity=fill_opacity,
+                                                         interp=interp),
+                                             stat="region_signal", position="signal_band",
+                                             key=False))
+                elif isinstance(to, float):
+                    call.layers.append(Layer(GEOMS["band"], Table(x=xs, y1=ys, y2=to),
+                                             paint=Paint(self, "signal.fill",
+                                                         opacity=fill_opacity,
+                                                         interp=interp),
+                                             stat="region_signal", key=False))
+                elif isinstance(to, BigWig):
+                    other = to.values_at(edges)
+                    if style == "line":
+                        oy = other
+                    else:
+                        oy = array("d", other)
+                        oy.append(oy[-1])
+                    call.layers.append(Layer(GEOMS["band"], Table(x=xs, y1=ys, y2=oy),
+                                             paint=Paint(self, "signal.fill",
+                                                         opacity=fill_opacity,
+                                                         interp=interp, below=to,
+                                                         below_opacity=to.fill_amount()
+                                                         * opacity),
+                                             stat="region_signal", key=False))
+
+                call.layers.append(Layer(GEOMS["path"], Table(x=xs, y=ys),
+                                         paint=Paint(self, "signal.line", opacity=opacity,
+                                                     interp=interp),
+                                         stat="region_signal", key=False))
+        for la in call.layers:                   # the axes see the signal and its baseline
+            la.options["bounds"] = False
+        name = self.resolve("name")
+        if name is not None:
+            legend = Layer(GEOMS["path"], Table(),
+                           paint=Paint(self, "stroke", color="line_color()"))
+            call.entries.append(entry(self, name, [legend], fill="line_color()"))
+        call.color_count = 0 if (self.is_set("color") or self._alone()) else 1
+        y = array("d", [v for v in vals if math.isfinite(v)])
+        if band is not None:
+            y.extend(v for v in (*band[0], *band[1]) if math.isfinite(v))
+            base = self.resolve("fill_to")
+            to = base if isinstance(base, float) else to       # the baseline stays in view
+        if isinstance(to, float):
+            y.append(to)
+            call.sticky_values["y"] = [to]
+        call.extra = {"x": array("d", [edges[0], edges[-1]]) if len(edges) else edges, "y": y}
+        if mode is None:
+            call.zero = {"y"}
+        call.exact = {"x"}
+        if len(vals):
+            mids = array("d", [(a + b) / 2 for a, b in zip(edges, edges[1:])])
+            call.layers.append(Layer(GEOMS["points"], Table(x=mids, y=vals), paint=None,
+                                     key=False, bounds=False))
+        for la in call.layers:
+            if la.geom is not GEOMS["points"]:
+                la.occupy = False
+        return call
+
+    def _heat(self, call: Call, edges: Any, vals: Any) -> Call:
+        """The call of a heat strip: one row of cells in its lane, colored through the
+        track's heat color axis."""
+        axis = self.heat_axis()
+        cmap = axis.color_map()
+        keep = [i for i in range(len(vals)) if edges[i + 1] > edges[i]]
+        if keep:
+            xs = array("d", [edges[keep[0]]] + [edges[i + 1] for i in keep])
+            vs = array("d", [vals[i] for i in keep])
+
+            call.layers.append(Layer(GEOMS["cells"], Table(),
+                                     paint=Paint(self, "signal.heat", axis=axis, cmap=cmap,
+                                                 xs=xs, vs=vs),
+                                     stat="region_signal", occupy=False, key=False,
+                                     bounds=False))
+        call.color_sources = [(axis, array("d", [v for v in vals if math.isfinite(v)]))]
+        call.color_count = 0
+        r = self.region()
+        call.extra = {"x": array("d", [r.start, r.end])}
+        call.hide = {"y"}                         # one row, in the series' lane
+        call.lane = lane_mapper(self)
+        call.exact = {"x"}
+        return call
+
+
+def centres_at(edges: Any, vals: Any, xs: Any) -> array:
+    """A binned signal through its bin centres at ``xs``: NaN outside."""
+    cs = [(a + b) / 2 for a, b in zip(edges, edges[1:])]
+    out = array("d")
+    j = 0
+    n = len(cs)
+    for x in xs:
+        while j < n - 2 and cs[j + 1] <= x:
+            j += 1
+        if not n or x < cs[0] or x > cs[-1]:
+            out.append(math.nan)
+        elif n == 1 or x == cs[j]:
+            out.append(vals[j])
+        else:
+            t = (x - cs[j]) / (cs[j + 1] - cs[j])
+            out.append(vals[j] + t * (vals[j + 1] - vals[j]))
+    return out
+
+
+def values_at(mine: Any, vals: Any, edges: Any) -> array:
+    """A binned signal's values at the centres of the bins ``edges``."""
+    out = array("d")
+    j = 0
+    n = len(vals)
+    for a, b in zip(edges, edges[1:]):
+        c = (a + b) / 2
+        while j < n - 1 and mine[j + 1] <= c:
+            j += 1
+        out.append(vals[j] if n and mine[0] <= c <= mine[-1] else math.nan)
+    return out
+
+
+def signal_bands(plot: Any, calls: list[Any]) -> None:
+    """Position ``signal_band``: under a track's ``fill_mode``, each signal's band runs to
+    the next signal below (``up``), above (``down``), or to the others where it is the
+    highest (``max``) or lowest (``min``), on the points of all the track's signals (bin
+    edges for steps, the last value repeated; bin centres and their crossings for lines,
+    split where they cross with :func:`~plot_io.layers.geoms.with_crossings`).  Writes
+    ``band_x``, ``band_y`` and ``band_bound``.  On an x axis over several regions, per
+    region."""
+    tables = [t for c in calls for t in c.tables if getattr(t, "signal", None) is not None]
+    by: dict[Any, list[Any]] = {}
+    for t in tables:
+        seg = getattr(t, "segment", None)
+        by.setdefault(None if seg is None else seg.number, []).append(t)
+    for group in by.values():
+        seg = getattr(group[0], "segment", None)
+        with in_segment(group[0].signal[0], seg) if seg is not None \
+                else contextlib.nullcontext():
+            _bands(group)
+
+
+def _bands(tables: list[Any]) -> None:
+    peers = [t.signal[0] for t in tables]
+    for me, t in enumerate(tables):
+        s, mode = t.signal
+        if s.resolve("kind") == "line":
+            xs = sorted({(a + b) / 2 for p in peers
+                         for a, b in zip(p.data()[0], p.data()[0][1:])})
+            curves = [list(p.centres_at(xs)) for p in peers]
+            xs, curves = with_crossings(xs, curves)
+        else:
+            xs = sorted({e for p in peers for e in p.data()[0]})
+            curves = []
+            for p in peers:
+                v = list(p.values_at(xs))
+                curves.append(v + v[-1:])
+        ys = array("d", curves[me])
+        bound = array("d")
+        for k, v in enumerate(ys):
+            if not math.isfinite(v):
+                bound.append(math.nan)
+                continue
+            # ties ordered by series, so equal signals share their band once
+            mine = (v, me)
+            others = [(c[k], j) for j, c in enumerate(curves) if j != me
+                      and math.isfinite(c[k])]
+            if mode == "up":
+                b = max((o for o in others if o < mine), default=mine)[0]
+            elif mode == "down":
+                b = min((o for o in others if o > mine), default=mine)[0]
+            elif mode == "max":
+                b = min(others, default=mine)[0] if all(o < mine for o in others) else v
+            else:
+                b = max(others, default=mine)[0] if all(o > mine for o in others) else v
+            bound.append(b)
+        t["band_x"], t["band_y"], t["band_bound"] = array("d", xs), ys, bound
+
+
+add_layer("bigwig", BigWig)
+positions.register(signal_bands, "signal_band")
+
+
+@role("signal.fill")
+def _fill_paint(s: BigWig, ctx: Any, glyph: bool, opacity: float = 1.0, interp: str = "linear",
+                below: Any = None, below_opacity: float = 1.0) -> dict[str, Any]:
+    """A signal's fill (``below``: the signal it fills to, whose fill shows below it)."""
+    p = {"color": s.fill_of(ctx), "opacity": opacity}
+    if below is not None:
+        p.update(below=below.fill_of(ctx), below_opacity=below_opacity)
+    p["interpolation"] = interp
+    return p
+
+
+@role("signal.bars")
+def _bars_paint(s: BigWig, ctx: Any, glyph: bool, opacity: float = 1.0) -> dict[str, Any]:
+    return {"fill": with_alpha(s.line_color(ctx), opacity)}
+
+
+@role("signal.line")
+def _line_paint(s: BigWig, ctx: Any, glyph: bool, opacity: float = 1.0,
+                interp: str = "linear") -> dict[str, Any]:
+    p = {"color": s.line_color(ctx), "width": s.resolve("line_width")}
+    if not glyph:
+        p.update(opacity=opacity, interpolation=interp, simplify=s.resolve("simplify"))
+    return p
+
+
+@role("signal.heat")
+def _heat_paint(s: BigWig, ctx: Any, glyph: bool, axis: Any = None, cmap: Any = None,
+                xs: Any = None, vs: Any = None) -> dict[str, Any]:
+    """A heat strip's cells through the track's heat color axis."""
+    from ..presets.heatmap import _even
+    st = trained(axis)
+    assert st.scale is not None
+    fn = st.scale.function
+    f = kernels.scaled(vs, 1.0, 0.0, fn, **st.scale.options) if fn else vs
+    xe = [ctx.xmap(x) for x in xs]
+    ye = sorted((ctx.ymap(0.0), ctx.ymap(1.0)))
+    if xe[0] > xe[-1]:
+        xe, f = xe[::-1], array("d", f[::-1])
+    mode = "image" if _even(xe) else "cells"
+    fill, table, bounds = cmap.cells(f, st.flo, st.fhi, mode)
+    opacity = s.resolve("opacity")
+    return {"x_edges": xe, "y_edges": ye, "even": mode == "image", "mode": mode,
+            "fill": fill, "palette": table, "bounds": bounds, "bad": cmap.bad,
+            "opacity": 1.0 if opacity is None else opacity}