plot-io 0.12.0__py3-none-win_amd64.whl

plot_io/genome/sites.py

@@ -0,0 +1,782 @@
+"""Site matrices: a signal read in windows around sites (peaks, TSSs), one row per site.
+
+:class:`SiteHeatmap` draws the rows as a heat map (``plot.site_heatmap``),
+:class:`SiteProfile` their column mean (``plot.site_profile``), :func:`SignalMatrix` a
+figure of both for each of several signals.
+
+A window is ``flank`` around the site's ``anchor``, read as ``bins`` bins in one
+``read_values`` call per signal (no strand passed to the reader); a ``-`` site's row
+(from a ``strand`` column) is reversed, so rows run 5′ to 3′.  Bins wholly past a
+chromosome end (the reader's ``chr_sizes``) are NaN.  The read and the row order are kept
+by the figure: a heat map and a profile of the same signal, sites and window share them.
+"""
+
+import math
+import operator
+import os
+from array import array
+from collections.abc import Mapping
+from typing import TYPE_CHECKING, Any, Self, Unpack
+
+from .. import kernels
+from ..color.values import color
+from ..layers import add_layer
+from ..layers.base import Series, common
+from ..layers.core import Call, Layer, Table
+from ..layers.grammar import entry
+from ..layers.paint import Paint, role
+from ..layers.geoms import GEOMS
+from ..mapped import color_axis_of, trained
+from ..presets._util import gradient_entry, memo
+from ..settings import Setting, number, one_of, table
+from ..validators import length
+from ..spec import auto_colors, current
+from . import readers, sources
+from .regions import parse_bp
+
+if TYPE_CHECKING:
+    from ..figure import Figure
+    from ..types import SiteHeatmapSettings, SiteProfileSettings
+
+__all__ = ["SiteHeatmap", "SiteProfile", "SignalMatrix"]
+
+#: The reductions a bin of a window takes.
+_MODES = ("mean", "min", "max", "sum", "count")
+#: The share of the rows a gap between groups takes.
+_GAP = 0.02
+
+
+def _flank(v: Any) -> tuple[int, int]:
+    """One length on both sides, or ``(upstream, downstream)``."""
+    if isinstance(v, (tuple, list)):
+        if len(v) != 2:
+            raise ValueError(f"expected a length or (upstream, downstream), got {v!r}")
+        up, down = (parse_bp(x, "flank") for x in v)
+    else:
+        up = down = parse_bp(v, "flank")
+    if up < 0 or down < 0 or up + down <= 0:
+        raise ValueError(f"the flanks must be non-negative and not both 0, got {v!r}")
+    return int(up), int(down)
+
+
+def _sort(v: Any) -> Any:
+    if v is False:
+        return False
+    return one_of("mean", "max")(v)
+
+
+def _row_bins(v: Any) -> Any:
+    if v is False or v == "auto":
+        return v
+    return number(positive=True, integer=True)(v)
+
+
+def _stat(v: Any) -> Any:
+    return one_of("mean", "median")(v)
+
+
+def _band(v: Any) -> Any:
+    if v is False:
+        return False
+    return one_of("sem", "sd")(v)
+
+
+def _window_settings() -> dict[str, Setting]:
+    return dict(
+        flank=Setting(_flank, doc="The window around each site's anchor: a length on both "
+                                  "sides (`\"5kb\"`) or `(upstream, downstream)`."),
+        bins=Setting(number(positive=True, integer=True), doc="Bins per window."),
+        anchor=Setting(one_of("center", "start", "end", "summit"),
+                       doc="The position the window is centred on: the site's `center`, "
+                           "`start` or `end` (5′ and 3′ ends on a `-` site), or its "
+                           "`summit` column (absolute, or a narrowPeak `peak` offset)."),
+        bin_mode=Setting(one_of(*_MODES),
+                         doc="Reduction per bin: `mean`, `min`, `max`, `sum` or `count`."),
+    )
+
+
+# ---------------------------------------------------------------------------
+# Sites
+# ---------------------------------------------------------------------------
+
+def _columns(value: Any, what: str, owner: Any) -> dict[str, list[Any]]:
+    """The columns of a sites table: a mapping of columns, a DataFrame, rows (mappings,
+    or tuples in BED order), an interval reader or a path (every entry)."""
+    if hasattr(value, "to_dict") and hasattr(value, "columns"):          # a DataFrame
+        return {str(c): list(value[c]) for c in value.columns}
+    if isinstance(value, Mapping):
+        return {str(k): list(v.tolist() if hasattr(v, "tolist") else v)
+                for k, v in value.items()}
+    if isinstance(value, (str, bytes)) or hasattr(value, "__fspath__") \
+            or sources.kind_of(value) is not None:
+        reader = readers.adapt(value, "intervals", what, owner=owner)
+        sizes = getattr(reader, "chr_sizes", None)
+        if not isinstance(sizes, Mapping) or not sizes:
+            raise ValueError(f"{what}: an interval reader as sites needs its chr_sizes "
+                             f"(to read every entry); pass a table")
+        got = reader.read_entries([(str(c), 0, int(n)) for c, n in sizes.items()])
+        return _columns(dict(got.items()), what, owner)
+    rows = list(value)
+    if rows and isinstance(rows[0], Mapping):
+        return {str(k): [r[k] for r in rows] for k in rows[0]}
+    names = ("chr", "start", "end", "name", "score", "strand")
+    return {n: [r[i] if i < len(r) else None for r in rows]
+            for i, n in enumerate(names) if any(len(r) > i for r in rows)}
+
+
+def _find(cols: Mapping[str, list[Any]], *names: str) -> list[Any] | None:
+    low = {k.lower(): v for k, v in cols.items()}
+    for n in names:
+        if n in low:
+            return low[n]
+    return None
+
+
+class Sites:
+    """The sites of a site matrix: ``chr``, ``start``, ``end``, and when given
+    ``strand``, ``summit`` (absolute; or ``start`` plus a narrowPeak ``peak`` offset) and
+    one group label per site."""
+
+    def __init__(self, value: Any, group: Any, what: str, owner: Any = None) -> None:
+        cols = _columns(value, what, owner)
+        chrs = _find(cols, "chr", "chrom", "chromosome", "seqname")
+        starts = _find(cols, "start", "chromstart")
+        ends = _find(cols, "end", "chromend")
+        if chrs is None or starts is None or ends is None:
+            raise ValueError(f"{what}: sites need chr, start and end columns")
+        n = len(chrs)
+        self.chr = [str(c) for c in chrs]
+        self.start = [sources._position(s, i, "start") for i, s in enumerate(starts)]
+        self.end = [sources._position(e, i, "end") for i, e in enumerate(ends)]
+        if len(self.start) != n or len(self.end) != n:
+            raise ValueError(f"{what}: the site columns have different lengths")
+        strand = _find(cols, "strand")
+        #: ``True`` per ``-`` site (``None``: no strand column)
+        self.minus = None if strand is None else [s == "-" for s in strand]
+        summit = _find(cols, "summit")
+        peak = _find(cols, "peak")
+        if summit is not None:
+            self.summit: list[int] | None = [int(s) for s in summit]
+        elif peak is not None:
+            self.summit = [s + int(p) if p is not None and int(p) >= 0 else (s + e) // 2
+                           for s, e, p in zip(self.start, self.end, peak)]
+        else:
+            self.summit = None
+        self.groups: list[Any] | None = None
+        if group is not None:
+            labels = cols.get(group) if isinstance(group, str) else group
+            if labels is None:
+                raise ValueError(f"{what}: no column {group!r} in the sites")
+            labels = list(labels.tolist() if hasattr(labels, "tolist") else labels)
+            if len(labels) != n:
+                raise ValueError(f"{what}: group has {len(labels)} labels for {n} sites")
+            self.groups = labels
+
+    def __len__(self) -> int:
+        return len(self.chr)
+
+    def anchors(self, anchor: str, what: str) -> list[int]:
+        """The anchor position of each site."""
+        s, e, minus = self.start, self.end, self.minus
+        if anchor == "center":
+            return [(a + b) // 2 for a, b in zip(s, e)]
+        if anchor == "summit":
+            if self.summit is None:
+                raise ValueError(f"{what}: anchor=\"summit\" needs a summit (or peak) "
+                                 f"column in the sites")
+            return list(self.summit)
+        first = anchor == "start"
+        if minus is None:
+            return list(s if first else e)
+        return [(b if m else a) if first else (a if m else b)
+                for a, b, m in zip(s, e, minus)]
+
+
+# ---------------------------------------------------------------------------
+# The read and the row order (kept by the figure)
+# ---------------------------------------------------------------------------
+
+def _ident(v: Any) -> Any:
+    if isinstance(v, (str, bytes)) or hasattr(v, "__fspath__"):
+        return os.fsdecode(v)
+    return id(v)
+
+
+class Matrix:
+    """The windows of one signal around the sites: ``n`` rows of ``w`` bins (row-major,
+    5′ to 3′), the bins from ``-up`` to ``down`` bp."""
+
+    __slots__ = ("n", "w", "flat", "up", "down", "_rows")
+
+    def __init__(self, n: int, w: int, flat: array, up: int, down: int) -> None:
+        self.n, self.w, self.flat, self.up, self.down = n, w, flat, up, down
+        self._rows: Any = None
+
+    def rows(self) -> Any:
+        """The rows as an ``(n, w)`` buffer."""
+        if self._rows is None:
+            self._rows = memoryview(self.flat).cast("B").cast("d", (self.n, self.w))
+        return self._rows
+
+    def column(self, c: int, rows: Any) -> array:
+        """Bin ``c`` of ``rows`` (indices)."""
+        return kernels.take(self.flat[c::self.w], rows)
+
+    def edges(self) -> list[float]:
+        bw = (self.up + self.down) / self.w
+        return [-self.up + bw * j for j in range(self.w + 1)]
+
+
+def _read(series: Any) -> Matrix:
+    """The windows of ``series``' signal around its sites (one read)."""
+    sites: Sites = series.sites
+    up, down = series.resolve("flank")
+    w = int(series.resolve("bins"))
+    anchors = sites.anchors(series.resolve("anchor"), series.kind)
+    minus = sites.minus or [False] * len(sites)
+    windows = [(c, a - down, a + up) if m else (c, a - up, a + down)
+               for c, a, m in zip(sites.chr, anchors, minus)]
+    reader = series.reader
+    mode = series.resolve("bin_mode")
+    n = len(windows)
+    if not n:
+        return Matrix(0, w, array("d"), up, down)
+    if callable(reader) and not hasattr(reader, "read_values"):
+        rows = [reader(c, s, e, w) for c, s, e in windows]
+    else:
+        rows = reader.read_values(windows, bin_count=w, bin_mode=mode, def_value=0.0)
+    g = kernels.grid(rows)
+    if g is not None:
+        h, gw, _, flat = g
+    else:
+        rows = [list(r) for r in rows]
+        h, gw = len(rows), len(rows[0]) if rows else 0
+        flat = array("d", [float(v) for r in rows for v in r])
+    if h != n or gw != w:
+        raise ValueError(f"{series.kind}: the reader gave {h} rows of {gw} bins for {n} "
+                         f"windows of {w}")
+    sizes = getattr(reader, "chr_sizes", None)
+    sizes = sizes if isinstance(sizes, Mapping) else {}
+    bw = (up + down) / w
+    nan = math.nan
+    for i, (c, lo, hi) in enumerate(windows):
+        size = sizes.get(c)
+        if lo < 0 or (size is not None and hi > size):
+            for j in range(w):
+                a = lo + j * bw
+                if a + bw <= 0 or (size is not None and a >= size):
+                    flat[i * w + j] = nan
+        if minus[i]:
+            flat[i * w:(i + 1) * w] = flat[i * w:(i + 1) * w][::-1]
+    return Matrix(n, w, flat, up, down)
+
+
+def _row_stat(m: Matrix, how: str) -> array:
+    w, flat = m.w, m.flat
+    out = array("d")
+    for i in range(m.n):
+        row = flat[i * w:(i + 1) * w]
+        s = sum(row)
+        if s != s:
+            row = array("d", [v for v in row if v == v])
+            s = sum(row)
+        if not row:
+            out.append(math.nan)
+        elif how == "mean":
+            out.append(s / len(row))
+        else:
+            out.append(max(row))
+    return out
+
+
+def _cache(series: Any) -> dict[Any, Any]:
+    fig = getattr(series.plot, "figure", None) if series.plot is not None else None
+    return (fig if fig is not None else series).__dict__.setdefault("_site_matrices", {})
+
+
+def _key(series: Any) -> tuple[Any, ...]:
+    return (_ident(series.signal), _ident(series.sites_arg), series.resolve("flank"),
+            series.resolve("bins"), series.resolve("anchor"), series.resolve("bin_mode"))
+
+
+def matrix(series: Any) -> Matrix:
+    """The read of ``series`` (shared by the series of its figure that read the same)."""
+    cache = _cache(series)
+    key = ("read", *_key(series))
+    got = cache.get(key)
+    if got is None:
+        try:
+            got = _read(series)
+        except Exception as e:
+            if series.kind in str(e):
+                raise
+            raise type(e)(f"{series.kind}: {e}") from e
+        cache[key] = got
+        cache[("held", *key)] = (series.signal, series.sites_arg)
+    return got
+
+
+def ordered(series: Any, sort: Any) -> tuple[array, list[tuple[Any, int, int]]]:
+    """``(order, blocks)``: the rows in drawing order (the groups in the order they first
+    appear in the sites, the rows of each by ``sort``, descending, NaN last) and the
+    groups as ``(label, first, end)`` of ``order``."""
+    cache = _cache(series)
+    key = ("order", sort, _ident(series.group), *_key(series))
+    got = cache.get(key)
+    if got is not None:
+        return got
+    m = matrix(series)
+    if not sort:
+        order = array("q", range(m.n))
+    else:
+        order = kernels.argsort(_row_stat(m, sort), descending=True)
+    blocks: list[tuple[Any, int, int]] = []
+    groups = series.sites.groups
+    if groups is None:
+        blocks.append((None, 0, m.n))
+    else:
+        by: dict[Any, list[int]] = {g: [] for g in groups}       # in the sites' order
+        for i in order:
+            by[groups[i]].append(i)
+        order = array("q")
+        for label, idx in by.items():
+            blocks.append((label, len(order), len(order) + len(idx)))
+            order.extend(idx)
+    got = cache[key] = (order, blocks)
+    return got
+
+
+def averaged(m: Matrix, rows: array, k: int) -> array:
+    """``rows`` (indices, in order) averaged to ``k`` rows, each over ``len(rows) / k``
+    consecutive rows (a row on a boundary weighted by its share); NaN left out.
+    Row-major."""
+    n, w = len(rows), m.w
+    if not n:
+        return array("d")
+    if k >= n:
+        return kernels.take(m.rows(), rows)
+    out = array("d", bytes(8 * k * w))
+    step = n / k
+    spans = []                      # whole rows [i0, i1), shares of rows i0 - 1 and i1
+    for j in range(k):
+        a, b = j * step, (float(n) if j == k - 1 else (j + 1) * step)
+        i0, i1 = math.ceil(a), min(n, math.floor(b))
+        spans.append((j * w, i0, i1, i0 - a, b - i1 if i1 < n else 0.0))
+    nan = math.nan
+    for c in range(w):
+        col = m.column(c, rows)
+        for at, i0, i1, fa, fb in spans:
+            part = col[i0:i1]
+            total, weight = sum(part), float(i1 - i0)
+            if total != total:
+                part = array("d", [v for v in part if v == v])
+                total, weight = sum(part), float(len(part))
+            if fa > 0:
+                v = col[i0 - 1]
+                if v == v:
+                    total += fa * v
+                    weight += fa
+            if fb > 0:
+                v = col[i1]
+                if v == v:
+                    total += fb * v
+                    weight += fb
+            out[at + c] = total / weight if weight > 1e-12 else nan
+    return out
+
+
+def _x_ticks(series: Any, up: int, down: int) -> list[tuple[float, Any]]:
+    from .regions import auto_unit
+    from .scale import GenomeFormat
+    from ..numbers import NumberStyle
+    values = [float(-up), 0.0, float(down)] if up and down else \
+        [float(-up), 0.0] if up else [0.0, float(down)]
+    unit = auto_unit(-up, down)
+    labels = GenomeFormat(unit, "ticks").format_all(values, NumberStyle.of(
+        series.plot.x_axis))
+    return list(zip(values, labels))
+
+
+class _SiteSeries(Series):
+    """Base of the site series: the signal, the sites and the group labels."""
+
+    SPLITS_GROUPS = False
+
+    def __init__(self, signal: Any, sites: Any, plot: Any = None, *, group: Any = None,
+                 **settings: Any) -> None:
+        what = type(self).__name__
+        self.signal = signal
+        self.reader = readers.adapt(signal, "signal", what, owner=self)
+        self.sites_arg = sites
+        self.group = group
+        self.sites = Sites(sites, group, what, owner=self)
+        super().__init__(plot=plot, **settings)
+
+
+class SiteHeatmap(_SiteSeries):
+    """A signal around sites, one row per site (a table with ``chr``, ``start``, ``end``
+    and optional ``strand``, ``summit`` columns, or an interval reader), x the distance
+    from the anchor in bp; ``group`` (a column of the sites, or a label per site) makes a
+    block of rows per group.
+
+    ``signal`` is anything a :class:`BigWig` takes (`readers <docs/api.md#readers>`_); ``sites`` is a table (a dict
+    of columns, a DataFrame, rows of dicts, or tuples in BED order) with ``chr``, ``start``,
+    ``end`` and optionally ``strand`` and ``summit`` (absolute; or a narrowPeak ``peak``
+    offset from ``start``), or an interval reader or path (every entry, over its
+    ``chr_sizes``).
+
+    The window is ``flank`` around the site's ``anchor`` (``center``, ``start``, ``end``: the
+    5′ and 3′ ends on a ``-`` site; ``summit``), read as ``bins`` bins in one ``read_values``
+    call per signal (no strand passed to the reader).  A ``-`` site's row is reversed, so
+    rows run 5′ to 3′.  Bins wholly past a chromosome end (the reader's ``chr_sizes``; before
+    0 always) are NaN.  x is labelled in genome units (``-5kb 0 5kb``).  A heat map and a
+    profile of the same signal, sites, ``group`` and window in one figure share the read and
+    the row order; :func:`~plot_io.genome.sites.SignalMatrix` makes the figure of both.
+
+    Rows are ordered by ``sort`` (each row's ``mean`` or ``max``, descending; ``False``: the
+    sites' order).  With ``group``, the blocks are in the order the groups first appear, a
+    gap between blocks, the group names on the y axis (else no y axis).
+    ``row_bins="auto"`` averages consecutive rows (a row on a boundary weighted by its
+    share, NaN left out) so that at most two rows fall in a px; a number draws that many
+    rows; ``False`` every row.  The color axis is trained on the rows drawn.  Use::
+
+        p.site_heatmap("atac.bw", tss, flank=(2000, 5000), anchor="start", group="cluster")
+
+    Example::
+
+        import math
+        rng = random.Random(1)
+        sites = {"chr": ["chr1"] * 40, "start": [10_000 + 20_000 * i for i in range(40)],
+                 "group": ["bound" if i % 3 else "unbound" for i in range(40)]}
+        sites["end"] = [s + 1 for s in sites["start"]]
+        signal = {"chr": [], "start": [], "end": [], "value": []}
+        for s, g in zip(sites["start"], sites["group"]):
+            h = rng.uniform(1, 3) if g == "bound" else rng.uniform(0, 0.5)
+            for x in range(s - 4000, s + 4000, 400):
+                signal["chr"].append("chr1")
+                signal["start"].append(x)
+                signal["end"].append(x + 400)
+                signal["value"].append(0.1 * rng.random() + h * math.exp(-((x - s) / 1000) ** 2))
+        p = plt.Plot(width=240, height=160)
+        p.site_heatmap(signal, sites, group="group", flank="4kb", bins=20, colorbar=True)
+    """
+
+    SETTINGS = table(
+        **_window_settings(),
+        sort=Setting(_sort, doc="Row order: `mean` or `max` of each row, descending (within "
+                                "each group); `False`: the sites' order."),
+        row_bins=Setting(_row_bins,
+                         doc="Rows drawn: `auto` averages consecutive rows so there are at "
+                             "most two per px; a number of rows; `False`: every row."),
+        **common("color_map"),
+        nan_color=Setting(color, doc="Color of missing bins (past a chromosome end); "
+                                     "default: the map's `bad` (transparent)."),
+        **common("name", "opacity", "z", "rasterize"),
+    )
+
+    def __init__(self, signal: Any, sites: Any, plot: Any = None, *, group: Any = None,
+                 **settings: Any) -> None:
+        super().__init__(signal, sites, plot=plot, group=group, **settings)
+
+    def set(self, **settings: "Unpack[SiteHeatmapSettings]") -> Self:  # type: ignore[override]
+        super().set(**settings)
+        if getattr(self, "plot", None) is not None:
+            self._attach_bar()
+        return self
+
+    def _bar_source(self) -> Any:
+        return self
+
+    def blocks(self) -> tuple[array, list[tuple[Any, int, int, float]], float]:
+        """``(order, blocks, height)``: the blocks as ``(label, first, end, y)`` (``y`` the
+        top of the block in rows, gaps between groups included) and the rows' height."""
+        order, blocks = ordered(self, self.resolve("sort"))
+        n = len(order)
+        gap = _GAP * n if len(blocks) > 1 else 0.0
+        out = [(label, a, b, a + i * gap) for i, (label, a, b) in enumerate(blocks)]
+        return order, out, n + gap * (len(blocks) - 1)
+
+    def drawn_rows(self, height: float) -> list[int]:
+        """The rows drawn per block on axes ``height`` px high."""
+        _, blocks, total = self.blocks()
+        rb = self.resolve("row_bins")
+        n = sum(b - a for _, a, b, _ in blocks) or 1
+        out = []
+        for _, a, b, _ in blocks:
+            nb = b - a
+            if rb is False:
+                k = nb
+            elif rb == "auto":
+                k = math.ceil(2 * height * nb / total) if total else nb
+            else:
+                k = round(rb * nb / n)
+            out.append(max(1, min(nb, k)) if nb else 0)
+        return out
+
+    def _drawn(self, rows: list[int]) -> list[array]:
+        """The drawn values of each block, averaged to ``rows``."""
+        order, blocks, _ = self.blocks()
+        m = matrix(self)
+        cache = _cache(self)
+        out = []
+        for (_, a, b, _), k in zip(blocks, rows):
+            key = ("drawn", self.resolve("sort"), _ident(self.group), a, b, k, *_key(self))
+            got = cache.get(key)
+            if got is None:
+                got = cache[key] = averaged(m, order[a:b], k)
+            out.append(got)
+        return out
+
+    def layers(self) -> Call:
+        call = Call(self)
+        m = matrix(self)
+        order, blocks, total = self.blocks()
+        axis = color_axis_of(self)
+        cmap = axis.color_map()
+
+        def height(ctx: Any) -> float:
+            return abs(ctx.rect[3] - ctx.rect[1])
+
+        def placed() -> Any:
+            r = current()
+            return None if r is None or self.plot is None else r.placed.get(id(self.plot))
+
+        def values() -> Any:              # trained once the axes are placed
+            ctx = placed()
+            if ctx is None:
+                return None
+            out = array("d")
+            for v in self._drawn(self.drawn_rows(height(ctx))):
+                out.extend(v)
+            return out
+
+        for k, (label, a, b, y0) in enumerate(blocks):
+            if b <= a or not m.w:
+                continue
+
+            call.layers.append(Layer(GEOMS["cells"], Table(),
+                                     paint=Paint(self, "sites.block", k=k, rows=b - a, y0=y0,
+                                                 m=m, cmap=cmap),
+                                     stat="site_matrix", occupy="all", key=False))
+        name = self.resolve("name")
+        if name is not None:
+            call.entries.append(gradient_entry(self, name, axis.color_map))
+        call.color_sources = [(axis, values)]
+        call.resolution = lambda ctx: tuple(self.drawn_rows(height(ctx)))
+        call.extra = {"x": array("d", [-m.up, m.down]), "y": array("d", [0.0, total])}
+        call.ticks["x"] = _x_ticks(self, m.up, m.down)
+        if len(blocks) > 1:
+            call.ticks["y"] = [(y0 + (b - a) / 2, str(label)) for label, a, b, y0 in blocks]
+        else:
+            call.hide = {"y"}
+        call.invert = {"y"}
+        call.exact = {"x", "y"}
+        return call
+
+
+class SiteProfile(_SiteSeries):
+    """The column mean (or median) of a signal around sites (see :class:`SiteHeatmap`):
+    one line per group, x the distance from the anchor in bp, an optional band.
+
+    Sites, windows and reads as :class:`SiteHeatmap`'s.  Each group is a line in the
+    plot's colors (a legend entry each); ``band="sem"`` or ``"sd"`` draws a band about it.
+
+    Example::
+
+        import math
+        rng = random.Random(1)
+        sites = {"chr": ["chr1"] * 40, "start": [10_000 + 20_000 * i for i in range(40)],
+                 "group": ["bound" if i % 3 else "unbound" for i in range(40)]}
+        sites["end"] = [s + 1 for s in sites["start"]]
+        signal = {"chr": [], "start": [], "end": [], "value": []}
+        for s, g in zip(sites["start"], sites["group"]):
+            h = rng.uniform(1, 3) if g == "bound" else rng.uniform(0, 0.5)
+            for x in range(s - 4000, s + 4000, 400):
+                signal["chr"].append("chr1")
+                signal["start"].append(x)
+                signal["end"].append(x + 400)
+                signal["value"].append(0.1 * rng.random() + h * math.exp(-((x - s) / 1000) ** 2))
+        p = plt.Plot(width=240, height=160)
+        p.site_profile(signal, sites, group="group", flank="4kb", bins=20, band="sem")
+    """
+
+    SETTINGS = table(
+        **_window_settings(),
+        stat=Setting(_stat, doc="The value per bin: the `mean` or `median` of the rows."),
+        band=Setting(_band, doc="A band about the line: `sem` (standard error of the mean), "
+                                "`sd`; `None` or `False`: none."),
+        color=Setting(color, doc="Line color; default: the plot's next color (one per "
+                                 "group)."),
+        line_width=Setting(length(lo=0), inherited=True, doc="Line width."),
+        fill_opacity=Setting(number(lo=0, hi=1), doc="Opacity of the band."),
+        **common("name", "opacity", "z", "rasterize", "simplify"),
+    )
+
+    def set(self, **settings: "Unpack[SiteProfileSettings]") -> Self:  # type: ignore[override]
+        super().set(**settings)
+        return self
+
+    def profiles(self) -> list[tuple[Any, array, array, array | None]]:
+        """``(group label, x, y, band half-width or None)`` per group, x the bin centres."""
+        m = matrix(self)
+        stat, band = self.resolve("stat"), self.resolve("band")
+        key = ("profile", stat, band, _ident(self.group), *_key(self))
+        cache = _cache(self)
+        got = cache.get(key)
+        if got is not None:
+            return got
+        order = array("q", range(m.n))
+        groups = self.sites.groups
+        if groups is not None:
+            by: dict[Any, list[int]] = {}
+            for i, g in enumerate(groups):
+                by.setdefault(g, []).append(i)
+            parts = [(label, array("q", idx)) for label, idx in by.items()]
+        else:
+            parts = [(None, order)]
+        edges = m.edges()
+        xs = array("d", [(a + b) / 2 for a, b in zip(edges, edges[1:])])
+        out = []
+        for label, rows in parts:
+            ys, hw = array("d"), array("d") if band else None
+            for c in range(m.w):
+                col = m.column(c, rows)
+                if sum(col) != sum(col):
+                    col = array("d", [v for v in col if v == v])
+                k = len(col)
+                if not k:
+                    ys.append(math.nan)
+                    if hw is not None:
+                        hw.append(math.nan)
+                    continue
+                mean = sum(col) / k
+                ys.append(mean if stat == "mean" else _median(col))
+                if hw is not None:
+                    var = max(0.0, sum(map(operator.mul, col, col)) / k - mean * mean) * k / (k - 1) \
+                        if k > 1 else 0.0
+                    hw.append(math.sqrt(var / (k if band == "sem" else 1)))
+            out.append((label, xs, ys, hw))
+        cache[key] = out
+        return out
+
+    def profile_colors(self, ctx: Any) -> list[Any]:
+        """The color of each profile."""
+        n = len(self.profiles())
+        c = self.resolve("color")
+        if c is not None:
+            return [ctx.color(c)] * n
+        auto = auto_colors(self) or [None]
+        return [ctx.color(auto[i % len(auto)]) for i in range(n)]
+
+    def layers(self) -> Call:
+        call = Call(self)
+        m = matrix(self)
+        got = self.profiles()
+
+        for i, (label, xs, ys, hw) in enumerate(got):
+            mine = []
+            if hw is not None:
+                lo = array("d", [y - h for y, h in zip(ys, hw)])
+                hi = array("d", [y + h for y, h in zip(ys, hw)])
+
+                mine.append(Layer(GEOMS["band"], Table(x=xs, top=hi, bottom=lo),
+                                  aes={"y1": "top", "y2": "bottom"},
+                                  paint=Paint(self, "band", color="profile_colors()",
+                                              index=i, opacity="fill_opacity"),
+                                  stat="site_profile", occupy=False))
+            mine.append(Layer(GEOMS["path"], Table(x=xs, y=ys),
+                              paint=Paint(self, "stroke", color="profile_colors()", index=i,
+                                          opacity=True),
+                              stat="site_profile"))
+            call.layers += mine
+            name = str(label) if label is not None else self.resolve("name")
+            if name is not None:
+                call.entries.append(entry(self, name, mine, fill="profile_colors()",
+                                          index=i))
+        call.color_count = 0 if self.is_set("color") else len(got)
+        call.ticks["x"] = _x_ticks(self, m.up, m.down)
+        call.extra = {"x": array("d", [-m.up, m.down])}
+        call.exact = {"x"}
+        return call
+
+
+def _median(v: array) -> float:
+    s = sorted(v)
+    k = len(s)
+    return s[k // 2] if k % 2 else (s[k // 2 - 1] + s[k // 2]) / 2
+
+
+#: The settings of :func:`SignalMatrix` that go to both plot types, to the heat maps,
+#: and to the profiles.
+_BOTH = ("flank", "bins", "anchor", "bin_mode", "group")
+
+
+def SignalMatrix(signals: Any, sites: Any, **settings: Any) -> "Figure":
+    """A figure of site matrices: per signal (a mapping of names to signals, or one
+    signal), a column of a :class:`SiteProfile` above a :class:`SiteHeatmap` of the same
+    rows, x shared by column.  ``share_color``: one color axis and one colorbar for all
+    heat maps (else one per column); ``profile_height``: the profiles' share of the
+    height (default ``0.25``).  The settings of both plot types go to them; the others are
+    the figure's.
+
+    Use::
+
+        fig = plt.SignalMatrix({"ATAC": "atac.bw", "H3K27ac": "k27ac.bw"}, "peaks.narrowPeak",
+                               anchor="summit", flank="5kb", width=180, height=600)
+    """
+    from ..figure import Figure
+    named = list(signals.items()) if isinstance(signals, Mapping) else [(None, signals)]
+    share = bool(settings.pop("share_color", False))
+    share_part = float(settings.pop("profile_height", 0.25))
+    both = {k: settings.pop(k) for k in _BOTH if k in settings}
+    heat = {k: settings.pop(k) for k in list(settings)
+            if k in SiteHeatmap.SETTINGS and k not in SiteProfile.SETTINGS}
+    prof = {k: settings.pop(k) for k in list(settings)
+            if k in SiteProfile.SETTINGS and k not in SiteHeatmap.SETTINGS}
+    for k in [k for k in settings if k in SiteHeatmap.SETTINGS]:
+        heat[k] = prof[k] = settings.pop(k)
+    n = len(named)
+    settings.setdefault("heights", [share_part, 1 - share_part])
+    settings.setdefault("share_x", "col")
+    fig = Figure(layout=[[f"p{i}" for i in range(n)], [f"h{i}" for i in range(n)]],
+                 **settings)
+    if share:
+        fig.set(share_color=True)
+    for i, (name, signal) in enumerate(named):
+        top = fig.plot(f"p{i}", title=name) if name is not None else fig.plot(f"p{i}")
+        top.site_profile(signal, sites, **both, **prof)
+        bar = heat.get("colorbar", True) if not share or i == n - 1 else False
+        fig.plot(f"h{i}").site_heatmap(signal, sites, **both, **{**heat, "colorbar": bar})
+    return fig
+
+
+add_layer("site_heatmap", SiteHeatmap)
+add_layer("site_profile", SiteProfile)
+
+
+@role("sites.block")
+def _block_paint(s: Any, ctx: Any, glyph: bool, k: int = 0, rows: int = 0, y0: float = 0.0,
+                 m: Any = None, cmap: Any = None) -> dict[str, Any]:
+    """The cells of block ``k`` (``rows`` sites from ``y0``), averaged to the rows the
+    axes' height draws."""
+    def make() -> dict[str, Any]:
+        drawn = s.drawn_rows(abs(ctx.rect[3] - ctx.rect[1]))
+        vals = s._drawn(drawn)[k]
+        st = trained(color_axis_of(s))
+        assert st.scale is not None
+        fn = st.scale.function
+        f = kernels.scaled(vals, 1.0, 0.0, fn, **st.scale.options) if fn else vals
+        fill, table, _ = cmap.cells(f, st.flo, st.fhi, "image")
+        return {"rows": drawn[k], "fill": fill, "table": table}
+    g = memo(ctx, (id(s), "block", k), make)
+    x0 = ctx.xmap(float(-m.up))
+    xb = (ctx.xmap(float(m.down)) - x0) / m.w
+    ya = ctx.ymap(y0)
+    yb = (ctx.ymap(y0 + rows) - ya) / g["rows"]
+    nan = ctx.color(s.resolve("nan_color"))
+    opacity = s.resolve("opacity")
+    return {"transform": (xb, 0.0, 0.0, yb, x0, ya),
+            "x_edges": range(m.w + 1), "y_edges": range(g["rows"] + 1),
+            "fill": g["fill"], "palette": g["table"],
+            "bad": nan if nan is not None else cmap.bad, "mode": "image",
+            "opacity": 1.0 if opacity is None else opacity}