plot-io 0.12.0__py3-none-win_amd64.whl

plot_io/genome/links.py

@@ -0,0 +1,364 @@
+"""Links between two places of the genome (:class:`Links`, BEDPE pairs): arcs in a lane of
+their own, or loop marks on a Hi-C triangle or square (``lane="over"`` after it).
+
+An arc joins the centres of its two anchors; its height is proportional to their distance,
+the tallest of the links with both anchors in view reaching the lane's edge (links with an
+anchor out of view are cut at it).  The lane is as high as that arc at half its anchors'
+distance (a half circle), at most ``max_height``.  Arcs are page polylines, cut at the
+axes' edges.
+"""
+
+import math
+from array import array
+from typing import Any
+
+from .._methods import LinksMixin
+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 add_layer
+from ..layers.base import common
+from ..layers.core import Call, Layer, Table
+from ..layers.geoms import GEOMS
+from ..mapped import color_axis_of, unit_of
+from ..validators import length
+from . import readers, sources
+from .lanes import lane_mapper, lane_setting
+from .series import GenomeSeries, region_setting
+
+__all__ = ["Links"]
+
+_STEPS = 48                     # segments of a whole arc
+
+
+def _link_color(v: Any) -> Any:
+    if isinstance(v, str) and v.strip().lower() == "score":
+        return "score"
+    return color(v)
+
+
+class Links(LinksMixin, GenomeSeries):
+    """Links between pairs of places (BEDPE): an arc from anchor centre to anchor centre
+    in a lane of its own, or, ``lane="over"`` a Hi-C triangle or square, a mark at each
+    pair's contact cell (on a square, and at its mirror).  ``pairs`` is a reader whose ``read_entries`` gives the BEDPE columns, a
+    path gwseq_io reads them from, or plain data (the pairs with an anchor in view are
+    read): a dict of columns, a DataFrame, or rows in BEDPE order (``chr1``,
+    ``start1``, ``end1``, ``chr2``, ``start2``, ``end2``, then optionally ``name``,
+    ``score``).
+
+    Readers: see `readers <docs/api.md#readers>`_.  Strand columns are not drawn.  Each arc's height is
+    proportional to the anchors' distance: the tallest arc of the links with both anchors in
+    view reaches the lane's edge (taller arcs of links with an anchor out of view are cut
+    at it), and the lane is as high as that arc at half the distance (a half circle), at
+    most ``max_height``.  A link with one anchor out of view is drawn to the axes' edge
+    (``outside="clip"``) or left out (``"hide"``); links with both anchors out of view, or
+    an anchor on another chromosome, are not drawn.  Over a Hi-C triangle or square
+    (``lane="over"``), see :class:`HiC`.
+
+    Example::
+
+        fig = plt.Tracks(("chr2", 143_000_000, 144_000_000), width=300)
+        fig.links([("chr2", 143_200_000, 143_210_000, "chr2", 143_500_000, 143_510_000, "L1", 12),
+                   ("chr2", 143_300_000, 143_310_000, "chr2", 143_900_000, 143_910_000, "L2", 4),
+                   ("chr2", 143_600_000, 143_610_000, "chr2", 143_700_000, 143_710_000, "L3", 8)],
+                  color="score")
+    """
+
+    SETTINGS = table(
+        region=region_setting(),
+        lane=lane_setting(),
+        direction=Setting(one_of("up", "down"),
+                          doc="`up`: arcs rise from the lane's bottom; `down`: they hang "
+                              "from its top."),
+        color=Setting(_link_color,
+                      doc="A color, or `\"score\"` (the `score` column through "
+                          "`color_map`)."),
+        max_height=Setting(length(positive=True, percent="em"),
+                           doc="Largest height of the lane: arcs are flattened to fit it."),
+        outside=Setting(one_of("clip", "hide"),
+                        doc="A link with one anchor out of view: `clip` draws it to the "
+                            "axes' edge; `hide` leaves it out."),
+        nan_color=Setting(color, doc="Color of links without a score under "
+                                     "`color=\"score\"`; `None`: the map's `bad` "
+                                     "(transparent)."),
+        **common("color_map", "name", "opacity", "z", "line_width"),
+        **coord_settings(),
+    )
+
+    def __init__(self, pairs: Any, plot: Any = None, **settings: Any) -> None:
+        self.reader = readers.adapt(pairs, "pairs", "Links", owner=self)
+        super().__init__(plot=plot, **settings)
+
+    # -- data ------------------------------------------------------------------------
+
+    def segmented(self) -> bool:
+        """Arcs join regions of an axis over several; loop marks are per Hi-C triangle."""
+        from .contacts import under_hic
+        return under_hic(self) is not None
+
+    def _segments(self) -> Any:
+        """The segments of an axis over several regions the arcs are drawn across, or
+        ``None``."""
+        if self.segment() is not None or self.plot is None:
+            return None
+        from .scale import segments_of
+        return segments_of(self.plot)
+
+    def pairs(self) -> dict[str, list[Any]]:
+        """The BEDPE columns of the pairs read for the region (for each region of an axis
+        over several, each pair once)."""
+        segs = self._segments()
+        regions = tuple(g.region for g in segs) if segs is not None else (self.region(),)
+        if segs is None:
+            from .contacts import under_hic
+            hic = under_hic(self)
+            if hic is not None and hic.square() and hic.region2() != regions[0]:
+                regions += (hic.region2(),)         # the pairs with an anchor on y
+                return self.cached(regions, lambda: self._guard(
+                    lambda: sources.read_pairs(self.reader, regions)), kind="pairs")
+        if len(regions) == 1:
+            return self.cached(regions, lambda: self._guard(
+                lambda: sources.read_pairs(self.reader, regions)), kind="pairs")
+        return self.cached(regions, lambda: self._guard(lambda: _union(
+            [sources.read_pairs(self.reader, regions)])), kind="pairs")
+
+    def anchor_x(self, chr: str, pos: float) -> float | None:
+        """Where position ``pos`` of chromosome ``chr`` is on the x axis (bp; over several
+        regions, drawn units); ``None`` where the axis does not show that chromosome.
+        Over several regions, a position out of every region is placed from the nearest
+        region of its chromosome when that falls past the axis' ends, else ``None``."""
+        segs = self._segments()
+        if segs is None:
+            return float(pos) if chr == self.region().chr else None
+        seg = segs.at(chr, pos)
+        if seg is not None:
+            return seg.u(pos)
+        mine = [g for g in segs if g.region.chr == chr]
+        if not mine:
+            return None
+        near = min(mine, key=lambda g: min(abs(pos - g.region.start), abs(pos - g.region.end)))
+        u = near.u(pos)
+        return u if u < 0 or u > segs.total else None
+
+    def in_view(self, x: float) -> bool:
+        segs = self._segments()
+        if segs is not None:
+            return any(g.u0 <= x <= g.u1 for g in segs)
+        r = self.region()
+        return r.start <= x <= r.end
+
+    def links(self) -> list[tuple[int, float, float]]:
+        """The links drawn: ``(i, x1, x2)``, the pair's row and its anchors' centres on the
+        x axis, ``x1 <= x2``; with ``outside="clip"`` the links with one anchor in view,
+        with ``"hide"`` both."""
+        cols = self.pairs()
+        both = self.resolve("outside") == "hide"
+        out = []
+        for i in range(len(cols["start1"])):
+            a = self.anchor_x(cols["chr1"][i], (cols["start1"][i] + cols["end1"][i]) / 2)
+            b = self.anchor_x(cols["chr2"][i], (cols["start2"][i] + cols["end2"][i]) / 2)
+            if a is None or b is None:
+                continue
+            seen = self.in_view(a) + self.in_view(b)
+            if seen == 2 or (seen == 1 and not both):
+                out.append((i, min(a, b), max(a, b)))
+        return out
+
+    def _visible(self, x1: float, x2: float, lo: float, hi: float) -> tuple[float, float]:
+        """The angles (0 at ``x1``, π at ``x2``) of the part of the half ellipse over
+        ``[x1, x2]`` within ``[lo, hi]``."""
+        c, r = (x1 + x2) / 2, (x2 - x1) / 2
+        if r <= 0:
+            return 0.0, math.pi
+        return (math.acos(min(1.0, max(-1.0, (c - lo) / r))),
+                math.acos(min(1.0, max(-1.0, (c - hi) / r))))
+
+    def _tallest(self, spans: Any, lo: float, hi: float) -> float:
+        """The tallest part within ``[lo, hi]`` of the half circles over ``spans``
+        (``(x1, x2)`` pairs)."""
+        top = 0.0
+        for x1, x2 in spans:
+            t0, t1 = self._visible(x1, x2, lo, hi)
+            s = 1.0 if t0 <= math.pi / 2 <= t1 else max(math.sin(t0), math.sin(t1))
+            top = max(top, (x2 - x1) / 2 * s)
+        return top
+
+    def _scale_spans(self, spans: list[tuple[float, float, bool]]) -> list[tuple[float, float]]:
+        """The ``(x1, x2)`` of ``spans`` (``(x1, x2, both anchors in view)``) that set the
+        arcs' scale: those with both anchors in view, else all."""
+        both = [(a, b) for a, b, inside in spans if inside]
+        return both or [(a, b) for a, b, _ in spans]
+
+    def _inside(self, a: float, b: float) -> bool:
+        return self.in_view(a) and self.in_view(b)
+
+    def lane_px(self) -> float:
+        """The lane's height (px): the tallest arc part in view of the links with both
+        anchors in view, at most ``max_height``."""
+        spans = self._scale_spans([(a, b, self._inside(a, b)) for _, a, b in self.links()])
+        segs = self._segments()
+        lo, hi = (0.0, segs.total) if segs is not None else (self.region().start,
+                                                               self.region().end)
+        tallest = self._tallest(spans, lo, hi) * self.axes_px() / ((hi - lo) or 1.0)
+        return max(1.0, min(tallest, float(self.resolve("max_height"))))
+
+    def lane_rows(self) -> int:
+        return 1
+
+    def drawn_rows(self) -> tuple[float, float]:
+        return 0.0, 1.0
+
+    # -- drawing ---------------------------------------------------------------------
+
+    def _colors(self, ctx: Any) -> list[Any]:
+        cols = self.pairs()
+        n = len(cols["start1"])
+        opacity = self.resolve("opacity")
+        opacity = 1.0 if opacity is None else opacity
+        c = self.resolve("color")
+        if c != "score":
+            return [with_alpha(ctx.color(c), opacity)] * n
+        axis = color_axis_of(self)
+        m, unit = axis.color_map(), unit_of(axis)
+        nan = ctx.color(self.resolve("nan_color"))
+        bad = nan if nan is not None else m.bad
+        out = []
+        for v in cols.get("score") or [None] * n:
+            t = math.nan if v is None else unit(v)
+            out.append(with_alpha(m(min(1.0, max(0.0, t))), opacity) if math.isfinite(t)
+                       else bad)
+        return out
+
+    def layers(self) -> Call:
+        from .contacts import under_hic
+        call = self.genome_call()
+        hic = under_hic(self)
+        lines = Table()
+        lines.lazy["page_lines"] = self._arcs if hic is None \
+            else (lambda ctx: self._marks(ctx, hic))
+        call.layers.append(Layer(GEOMS["path"], lines, paint={}, stat="links",
+                                 occupy=False, key=False))
+        if self.resolve("color") == "score":
+            scores = [v for v in self.pairs().get("score") or () if v is not None]
+            call.color_sources = [(color_axis_of(self), array("d", scores))]
+        if self._segments() is None:
+            r = self.region()
+            call.extra = {"x": array("d", [r.start, r.end])}
+        else:
+            call.region = None
+        call.hide = {"y"}
+        if hic is None:
+            call.lane = lane_mapper(self)
+        call.exact = {"x"}
+        return call
+
+    def _bar_source(self) -> Any:
+        """``color="score"`` maps the scores through the color axis, as numbers do."""
+        return self if self.resolve("color") == "score" else super()._bar_source()
+
+    def _arcs(self, ctx: Any) -> list[Any]:
+        """The arcs (page polylines), the tallest of the links with both anchors in view at
+        the lane's edge, taller ones cut at it."""
+        lo, hi = ctx.rect[0], ctx.rect[2]
+        ym = ctx.ymap
+        top, bottom = ym.position(ym.flo), ym.position(ym.fhi)
+        base, room = (bottom, top - bottom) if self.resolve("direction") == "up" \
+            else (top, bottom - top)
+        links = self.links()
+        xs = [(i, *sorted((ctx.xmap(a), ctx.xmap(b)))) for i, a, b in links]
+        tallest = self._tallest(self._scale_spans([
+            (x1, x2, self._inside(a, b)) for (_, x1, x2), (_, a, b) in zip(xs, links)]),
+            lo, hi)
+        k = room / tallest if tallest > 0 else 0.0
+        cs = self._colors(ctx)
+        lw = self.resolve("line_width")
+        out: list[Any] = []
+        for i, x1, x2 in xs:
+            t0, t1 = self._visible(x1, x2, lo, hi)
+            c, r = (x1 + x2) / 2, (x2 - x1) / 2
+            n = max(2, math.ceil(_STEPS * (t1 - t0) / math.pi))
+            ts = [t0 + (t1 - t0) * j / n for j in range(n + 1)]
+            out.append((array("d", [c - r * math.cos(t) for t in ts]),
+                        array("d", [base + math.copysign(min(abs(k * r * math.sin(t)),
+                                                             abs(room)), room)
+                                    for t in ts]), cs[i], lw))
+        return out
+
+    def _marks(self, ctx: Any, hic: Any) -> list[Any]:
+        """Loop marks: an outlined square at each pair's contact cell of ``hic`` (a
+        diamond in the triangle), one bin wide, at least half an em."""
+        if hic.square():
+            return self._square_marks(ctx, hic)
+        n, _, start, b = hic.data()
+        depth = hic.depth()
+        ppb = abs(ctx.xmap(start + b) - ctx.xmap(start)) / b if b else 0.0
+        side = max(b, 0.5 * float(hic.resolve("font_size")) / ppb) if ppb else b
+        cs = self._colors(ctx)
+        lw = self.resolve("line_width")
+        out: list[Any] = []
+        for i, a, c in self.links():
+            u = start + math.floor((a - start) / b) * b + b / 2      # the cells' centres
+            v = start + math.floor((c - start) / b) * b + b / 2
+            x, d = (u + v) / 2, v - u
+            if d - side / 2 > depth:
+                continue
+            pts = [(x - side / 2, d), (x, d - side), (x + side / 2, d), (x, d + side),
+                   (x - side / 2, d)]
+            out.append((array("d", [ctx.xmap(p) for p, _ in pts]),
+                        array("d", [ctx.ymap(q) for _, q in pts]), cs[i], lw))
+        return out
+
+
+    def _square_marks(self, ctx: Any, hic: Any) -> list[Any]:
+        """Loop marks on a square: an outlined square at each pair's cell (first anchor on
+        x, second on y) and at its mirror, where in view, one bin wide, at least half an
+        em."""
+        _, _, _, start, b, start2, b2 = hic.square_data()
+        r, r2 = hic.region(), hic.region2()
+        em = 0.5 * float(hic.resolve("font_size"))
+        ppx = abs(ctx.xmap(start + b) - ctx.xmap(start)) / b if b else 0.0
+        ppy = abs(ctx.ymap(start2 + b2) - ctx.ymap(start2)) / b2 if b2 else 0.0
+        sx = max(b, em / ppx) if ppx else b
+        sy = max(b2, em / ppy) if ppy else b2
+        cols = self.pairs()
+        cs = self._colors(ctx)
+        lw = self.resolve("line_width")
+        out: list[Any] = []
+        for i in range(len(cols["start1"])):
+            a = (cols["chr1"][i], (cols["start1"][i] + cols["end1"][i]) / 2)
+            c = (cols["chr2"][i], (cols["start2"][i] + cols["end2"][i]) / 2)
+            seen = set()
+            for (cx, px), (cy, py) in ((a, c), (c, a)):
+                if cx != r.chr or cy != r2.chr or not (r.start <= px <= r.end and
+                                                       r2.start <= py <= r2.end):
+                    continue
+                u = start + math.floor((px - start) / b) * b + b / 2     # the cell's centre
+                v = start2 + math.floor((py - start2) / b2) * b2 + b2 / 2
+                if (u, v) in seen:
+                    continue
+                seen.add((u, v))
+                xs = (u - sx / 2, u + sx / 2, u + sx / 2, u - sx / 2, u - sx / 2)
+                ys = (v - sy / 2, v - sy / 2, v + sy / 2, v + sy / 2, v - sy / 2)
+                out.append((array("d", [ctx.xmap(p) for p in xs]),
+                            array("d", [ctx.ymap(q) for q in ys]), cs[i], lw))
+        return out
+
+
+def _union(tables: list[dict[str, list[Any]]]) -> dict[str, list[Any]]:
+    """The rows of BEDPE column tables, each pair once (in the order first read)."""
+    keys = ("chr1", "start1", "end1", "chr2", "start2", "end2")
+    names = list(tables[0]) if tables else []
+    out: dict[str, list[Any]] = {k: [] for k in names}
+    seen = set()
+    for t in tables:
+        for i in range(len(t["start1"])):
+            k = tuple(t[c][i] for c in keys)
+            if k in seen:
+                continue
+            seen.add(k)
+            for c in names:
+                out[c].append(t[c][i] if c in t else None)
+    return out
+
+
+add_layer("links", Links)

plot_io/genome/pack.py

@@ -0,0 +1,27 @@
+"""Packing intervals onto rows (IGV's "expanded" mode)."""
+
+import heapq
+from collections.abc import Sequence
+
+__all__ = ["pack_rows"]
+
+
+def pack_rows(lo: Sequence[float], hi: Sequence[float], gap: float = 0.0) -> list[int]:
+    """The row of each interval ``[lo, hi)``: greedily, by start, the first row whose last
+    interval ends at least ``gap`` before it.  Starts only grow, so a row that has room
+    keeps it: rows are freed from a heap of their ends into a heap of free row numbers."""
+    order = sorted(range(len(lo)), key=lambda i: (lo[i], hi[i]))
+    busy: list[tuple[float, int]] = []        # (end + gap, row)
+    free: list[int] = []
+    rows = [0] * len(lo)
+    count = 0
+    for i in order:
+        while busy and busy[0][0] <= lo[i]:
+            heapq.heappush(free, heapq.heappop(busy)[1])
+        if free:
+            r = heapq.heappop(free)
+        else:
+            r, count = count, count + 1
+        rows[i] = r
+        heapq.heappush(busy, (hi[i] + gap, r))
+    return rows

plot_io/genome/readers.py

@@ -0,0 +1,145 @@
+"""What plot_io asks of a reader, and the one door a series' data come in by.
+
+The protocols name the members plot_io calls, with the arguments it passes
+(:mod:`plot_io.genome.sources` makes the calls).  gwseq_io's readers meet them; any
+object with the same members can be drawn, and :func:`plot_io.genome.testing.check`
+says whether it does.  A reader is recognised by its ``type`` attribute (``"bigwig"``,
+``"bed"``, ``"hic"``, …) or, without it, by its members
+(:func:`~plot_io.genome.sources.kind_of`).
+
+:func:`adapt` turns a series' data argument into a reader: a reader passes through; a
+path is opened with gwseq_io (:func:`~plot_io.genome.adapters.open_path`) at draw, once per
+figure; plain data
+(columns, a DataFrame, rows, a matrix) becomes an in-memory reader
+(:mod:`plot_io.genome.adapters`).
+"""
+
+from collections.abc import Mapping, Sequence
+from typing import Any, Protocol, runtime_checkable
+
+from . import sources
+
+__all__ = ["SignalReader", "IntervalReader", "AnnotationReader", "PairReader",
+           "ContactReader", "Resolving", "Sized", "Region3", "adapt", "WANTS"]
+
+#: A region as plot_io passes it: ``(chr, start, end)``, 0-based, half-open.
+Region3 = tuple[str, int, int]
+
+
+@runtime_checkable
+class SignalReader(Protocol):
+    """Values binned over regions (bigWig; the coverage of bigBed, BED and peaks)."""
+
+    def read_values(self, regions: Sequence[Region3], *, bin_count: int | None = ...,
+                    bin_size: int | None = ..., bin_mode: str = ..., def_value: float = ...,
+                    zoom: Any = ..., snap_to_grid: Any = ..., full_bin: bool = ...) -> Any:
+        """One row per region: ``bin_count`` bins over it, or bins of ``bin_size`` from its
+        start (``snap_to_grid="expand"``: grown to the genome-wide grid of the size;
+        ``full_bin``: a last partial bin kept), each the ``bin_mode`` reduction (``mean``,
+        ``min``, ``max``, ``sum``, …) of its bases, ``def_value`` for bases no record
+        covers.  A 2-D buffer or a sequence of rows."""
+        ...
+
+
+@runtime_checkable
+class IntervalReader(Protocol):
+    """Intervals (bigBed, BED, peaks): the entries overlapping regions."""
+
+    def read_entries(self, regions: Sequence[Region3], **kw: Any) -> Any:
+        """A mapping of columns (``chr``, ``start``, ``end``, then any of the BED columns,
+        by their BED or autoSql names), the entries overlapping the regions.  Called with
+        ``columns=n`` (the first ``n`` columns) when the reader has an ``auto_sql``
+        mapping."""
+        ...
+
+
+@runtime_checkable
+class AnnotationReader(Protocol):
+    """Gene annotation (GTF, GFF3): transcripts and their exons.  ``tss`` only marks the
+    kind."""
+
+    def read_entries(self, regions: Sequence[Region3], *, model: str = ...,
+                     gene_type: Any = ..., transcript_type: Any = ...) -> Any:
+        """With ``model="transcript"``: a table of the transcripts overlapping the regions
+        (``start``, ``end``, ``strand``, ``cds_start``, ``cds_end`` (-1: non-coding),
+        ``gene_id``, ``transcript_id``, optional ``gene_name``, ``transcript_name``),
+        whose ``nested["exons"]`` is a table (``start``, ``end``) with ``groups``:
+        transcript ``i``'s exons are rows ``groups[i]:groups[i + 1]``."""
+        ...
+
+    def tss(self, *args: Any, **kw: Any) -> Any: ...
+
+
+@runtime_checkable
+class PairReader(Protocol):
+    """Pairs of places (BEDPE), for links."""
+
+    def read_entries(self, regions: Sequence[Region3]) -> Any:
+        """A mapping of the BEDPE columns (``chr1``, ``start1``, ``end1``, ``chr2``,
+        ``start2``, ``end2``, optional ``name``, ``score``; the first anchor's may be
+        ``chr``, ``start``, ``end``): the pairs with an anchor overlapping the regions
+        (at least those whose first anchor does)."""
+        ...
+
+
+@runtime_checkable
+class ContactReader(Protocol):
+    """A contact matrix (Hi-C)."""
+
+    bin_sizes: Sequence[int]
+    normalizations: Sequence[str]
+
+    def read_values(self, region1: Region3, region2: Region3 | None = ..., *,
+                    bin_size: int | None = ...,
+                    bin_count: int | tuple[int, int] | None = ...,
+                    snap_to_grid: Any = ..., full_bin: bool = ...,
+                    normalization: str = ..., matrix_type: str = ...,
+                    max_distance: int | None = ...) -> Any:
+        """The matrix of ``region1`` against ``region2`` (default ``region1``): rows of
+        ``region1``'s bins, columns of ``region2``'s, in bins of one of ``bin_sizes`` (on
+        its genome-wide grid with ``snap_to_grid="expand"``) or ``bin_count`` bins (with
+        ``region2``: a ``(rows, columns)`` pair);
+        ``normalization`` ``"none"`` or one of ``normalizations``; ``matrix_type``
+        ``observed``, ``oe`` or ``expected``; cells farther than ``max_distance`` from the
+        diagonal may be left out (NaN or 0)."""
+        ...
+
+
+@runtime_checkable
+class Resolving(Protocol):
+    """Optional: the bounds of a binned read, so its bins are placed exactly."""
+
+    def resolve_regions(self, regions: Any, *more: Any, **kw: Any) -> Any:
+        """With the arguments of the read: the ``start`` and ``end`` columns of the rows it
+        gives (a contact reader: under ``"rows"``, and those of ``region2`` under
+        ``"cols"``)."""
+        ...
+
+
+@runtime_checkable
+class Sized(Protocol):
+    """Optional: chromosome sizes, giving the end of a whole chromosome (``"chr1"``)."""
+
+    chr_sizes: Mapping[str, int]
+
+
+#: The reader kinds each data role takes (:func:`~plot_io.genome.sources.kind_of`).
+WANTS = {"signal": ("signal", "intervals"), "intervals": ("intervals",),
+         "annotation": ("annotation",), "pairs": ("intervals",), "contacts": ("contacts",)}
+
+
+def adapt(value: Any, want: str, what: str, owner: Any = None) -> Any:
+    """``value`` as a reader of role ``want`` (``"signal"``, ``"intervals"``,
+    ``"annotation"``, ``"pairs"``, ``"contacts"``) for series ``what``: a reader of a kind
+    the role takes passes through; a path (``str``, ``os.PathLike``) is opened with
+    gwseq_io when first read, once per figure of ``owner`` (its series), and closed with
+    the figure (:class:`~plot_io.genome.adapters.Deferred`); plain data becomes an in-memory reader
+    (an interval table for ``annotation``: BED12 models)."""
+    from . import adapters
+    if isinstance(value, (str, bytes)) or hasattr(value, "__fspath__"):
+        adapters.check_path(value, what)
+        return adapters.Deferred(value, WANTS[want], what, owner)
+    if sources.kind_of(value) is not None:
+        sources.check_reader(value, WANTS[want], what)
+        return value
+    return adapters.from_data(value, want, what)