plot-io 0.12.0__py3-none-win_amd64.whl

plot_io/genome/intervals.py

@@ -0,0 +1,750 @@
+"""Intervals and gene models (:class:`Bed`, :class:`Genes`, :class:`Gtf`): boxes or gene
+models packed on rows, with names, strands and colors from the data, each series in a
+lane of its own (:mod:`plot_io.genome.lanes`)."""
+
+import math
+import warnings
+from array import array
+from typing import Any
+
+
+from .._methods import BedMixin, GenesMixin, GtfMixin
+from .. import groups
+from ..color.values import color, nearest_named, rgba_of, variant_of, with_alpha
+from ..labels import NAME_POSITIONS, row as name_row, spot
+from ..settings import Setting, boolean, number, 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 ..layers.paint import Paint, role
+from ..mapped import color_axis_of, unit_of
+from ..presets._util import memo, placed_text
+from ..spec import warn
+from ..text import document_db, font_of, measure
+from ..validators import length
+from . import readers, sources
+from .lanes import lane_mapper, lane_setting
+from .pack import pack_rows
+from .regions import Region, parse_region
+from .series import GenomeSeries, region_setting
+
+__all__ = ["Bed", "Genes", "Gtf"]
+
+
+_BOX = 8 / 13.2                 # height of boxes and coding exons, in rows: 8 px of 13.2
+
+
+def _label_region(v: Any) -> Region | None:
+    return None if v is None else parse_region(v)
+
+
+def _bed_color(v: Any) -> Any:
+    if isinstance(v, str) and v.strip().lower() in ("item_rgb", "score"):
+        return v.strip().lower()
+    return color(v)
+
+
+def _recolor(v: Any) -> Any:
+    if isinstance(v, bool):
+        return v
+    return number(0, 1)(v)
+
+
+def _lightness(c: Any) -> float:
+    """Oklab lightness of ``c`` composited over white (1 when there is no color)."""
+    rgba = rgba_of(c)
+    if rgba is None:
+        return 1.0
+    a = rgba[3] if len(rgba) > 3 else 1.0
+    lin = [(lambda v: v / 12.92 if v <= 0.04045 else ((v + 0.055) / 1.055) ** 2.4)(
+        a * float(v) + 1.0 - a) for v in rgba[:3]]
+    lms = [sum(k * v for k, v in zip(row, lin)) ** (1 / 3) for row in _LMS]
+    return 0.2104542553 * lms[0] + 0.7936177850 * lms[1] - 0.0040720342 * lms[2]
+
+
+_LMS = ((0.4122214708, 0.5363325363, 0.0514459929), (0.2119034982, 0.6806995451, 0.1073969566),
+        (0.0883024619, 0.2817188376, 0.6299787005))
+
+
+def _bp(v: Any) -> float | None:
+    """A position as a float; ``None`` when missing (``None``, ``"."``, ``""``, NaN)."""
+    if v is None or (isinstance(v, str) and v.strip() in ("", ".")) \
+            or (isinstance(v, float) and math.isnan(v)):
+        return None
+    return float(int(v))
+
+
+def _rgb(v: Any, i: int) -> Any:
+    """A BED ``itemRgb`` (``"r,g,b"``) of interval ``i``, or ``None`` (``"0"``, missing);
+    components outside 0–255 raise."""
+    if v is None:
+        return None
+    if isinstance(v, (tuple, list)) and len(v) == 3:
+        parts: Any = list(v)
+    else:
+        parts = str(v).replace(" ", "").split(",")
+        if len(parts) != 3:
+            return None
+    try:
+        rgb = [int(c) for c in parts]
+    except ValueError:
+        return None
+    if not all(0 <= c <= 255 for c in rgb):
+        raise ValueError(f"itemRgb of interval {i + 1} is {v!r}: components are 0 to 255")
+    return tuple(c / 255 for c in rgb)
+
+
+
+#: Strand chevrons' height, × the feature box's height: inside a box, on an intron.
+_CHEVRON_BOX, _CHEVRON_INTRON = 0.45, 0.55
+
+class Bed(BedMixin, GenomeSeries):
+    """Intervals over the region: boxes or gene models, on one row or packed onto
+    rows.  ``reader`` is an interval reader (bigBed, BED, peaks), a path (opened with
+    gwseq_io) or plain data: a dict of
+    columns, a DataFrame, or rows (``start``, ``end`` and optionally ``name``, ``score``,
+    ``strand``, ``thickStart``, ``thickEnd``, ``itemRgb``, ``blockCount``,
+    ``blockSizes``, ``blockStarts``).
+
+    Paths and readers: see `readers <docs/api.md#readers>`_.  Rows of other chromosomes than the region's are left
+    out (when a ``chr`` column is given).  A score that is not a number (``"."``) is missing
+    (the map's ``bad`` color); an interval ending before it starts, or blocks not matching
+    ``blockCount``, are a ``ValueError``.  ``itemRgb`` is ``reserved`` in bigBeds.
+
+    ``kind="genes"`` draws each BED12 model as a line, thin boxes for UTRs and thick boxes
+    for coding exons, chevrons on introns (``strand``), and its name in italics.  A name goes where ``name_position`` says: ``auto`` tries
+    left of its feature, then right, then inside a feature wide enough; a feature crossing
+    the view's edge is named at that edge, over its visible part when the name leaves some
+    of it uncovered (on a background box over a dark feature).  A name with no room is
+    shortened with an ellipsis; one with no room even shortened is left out, and a warning
+    counts them.  In one row (``rows="collapse"``) longer features keep theirs first
+    (``names=False``: none).
+    ``name_region`` names only the features overlapping it (a locus within a wider view).
+
+    ``rows="expand"`` packs the features with their names; past ``max_rows`` it packs them
+    without names and names those that still fit; past ``max_rows`` again, the features of
+    later rows are left out and a "+n more" mark is drawn at the right of the last row.
+    ``rows="squish"`` packs them on rows half ``row_height`` high, without names, under the
+    same cap.  Packing and drawing read one result: no row is kept for a name that is not
+    drawn.
+
+    Features are outlined in their color (``outline``, ``line_width``) over their ``fill``
+    (``False`` for outlines only) at ``fill_opacity``, the outline inside the feature's
+    extent: a feature narrower than two borders is one line, ``line_width`` wide.
+    ``recolor`` snaps the features' colors (``itemRgb`` ones included) to the named colors
+    (``"blue 0.4"``): ``True`` takes the closest of all shades, a level such as ``0.4`` the
+    closest color's shade at that level, so every feature has the same lightness.
+
+    Over a Hi-C triangle (``lane="over"``) each interval is an outlined triangle (a TAD);
+    over a square, an outlined square on the diagonal (see :class:`HiC`).
+
+    Example::
+
+        fig = plt.Tracks(("chr1", 0, 100_000), width=300)
+        fig.bed({"start": [5_000, 22_000, 40_000, 47_000, 70_000],
+                 "end": [15_000, 30_000, 52_000, 60_000, 92_000],
+                 "name": ["p1", "p2", "p3", "p4", "p5"]}, rows="expand", names=True)
+    """
+
+    SETTINGS = table(
+        region=region_setting(),
+        lane=lane_setting(),
+        kind=Setting(one_of("boxes", "genes"),
+                     doc="`boxes` (intervals, 8/13.2 of a row high: 8 px in the default "
+                         "row) or `genes` (BED12 models: exons as high, UTRs half, "
+                         "introns)."),
+        rows=Setting(one_of("collapse", "expand", "squish"),
+                     doc="`collapse`: one row; `expand`: overlapping features (and their "
+                         "names) packed onto rows; `squish`: packed onto rows half "
+                         "`row_height` high, without names."),
+        max_rows=Setting(number(lo=1, integer=True),
+                         doc="Most rows of `expand` and `squish`: names are given up before "
+                             "rows are added, then features past the last row are left out "
+                             "and a \"+n more\" mark is drawn at the lane's lower right."),
+        min_width=Setting(length(lo=0), doc="Narrowest drawn feature (1-bp sites stay "
+                                            "visible)."),
+        color=Setting(_bed_color,
+                      doc="A color, `\"item_rgb\"` (the `itemRgb` column) or `\"score\"` "
+                          "(the `score` column through `color_map`)."),
+        recolor=Setting(_recolor,
+                        doc="Replace each feature's color by the closest named color "
+                            "(`True`: the closest shade; a level 0–1: the closest color's "
+                            "shade at that level); `False`: as given. Not with "
+                            "`color=\"score\"`."),
+        names=Setting(boolean, doc="Feature names (`name`) beside the features "
+                                   "(`name_position`), shortened or left out (with a "
+                                   "warning) where they collide; "
+                                   "in one row, longer features keep theirs first."),
+        name_position=Setting(one_of(*NAME_POSITIONS),
+                              doc="Where a name goes: `left` or `right` of its feature, or "
+                                  "`inside` a feature wide enough; `auto`: the first of "
+                                  "left, right, inside with room. A feature crossing the "
+                                  "view's edge is named at that edge, over its visible "
+                                  "part when the name leaves some of it uncovered. A "
+                                  "name with no room is shortened with an ellipsis."),
+        name_region=Setting(_label_region,
+                            doc="Only features overlapping this region (as `region` takes "
+                                "it) get names; `None`: all."),
+        strand=Setting(boolean, doc="Strand chevrons on boxes and introns."),
+        outline=Setting(boolean, doc="Outline features in their color (`line_width` wide)."),
+        **groups.FillStyle.embed(docs={"fill": "Fill of the features: `True` (their "
+                                               "color), a color, or `False` (outlines only).",
+                                       "fill_opacity": "Opacity of the fill, times "
+                                                       "`opacity`."}),
+        row_height=Setting(length(positive=True, percent="em"),
+                           doc="Height of a row (half of it with `rows=\"squish\"`): the "
+                               "series' lane is rows × it high (scaled to fill a track "
+                               "without a value lane)."),
+        **groups.TextStyle.embed("name_",
+                                 only=("font_size",),
+                                 docs={"font_size": "Font size of feature names."}),
+        nan_color=Setting(color, doc="Color of features without a score under "
+                                     "`color=\"score\"`; `None`: the map's `bad` "
+                                     "(transparent)."),
+        **common("color_map", "name", "opacity", "z", "line_width", "font_size", "font_family",
+                 "text_color"),
+        **coord_settings(),
+    )
+    READS = "intervals"
+
+    def __init__(self, reader: Any, plot: Any = None, **settings: Any) -> None:
+        self.reader = readers.adapt(reader, self.READS, type(self).__name__, owner=self)
+        super().__init__(plot=plot, **settings)
+
+    # -- data (stat intervals) ---------------------------------------------------------
+
+    def entries(self) -> dict[str, list[Any]]:
+        """The BED columns of the entries overlapping the region (positions in bp)."""
+        region = self.region()
+        return self.cached(region, lambda: self._guard(lambda: self._entries(region)),
+                           kind="entries")
+
+    def _entries(self, region: Region) -> dict[str, list[Any]]:
+        cols = self._read(region)
+        if self.resolve("color") == "item_rgb":
+            for i, v in enumerate(cols.get("itemRgb") or ()):
+                _rgb(v, i)                          # components out of 0–255 raise
+        chrs = cols.get("chr")
+        keep = [i for i, (s, e) in enumerate(zip(cols["start"], cols["end"]))
+                if e > region.start and s < region.end and (chrs is None or chrs[i] == region.chr)]
+        names = getattr(self.reader, "chr_sizes", None) or getattr(self.reader, "chr_names",
+                                                                    None) or ()
+        if not keep and region.chr not in names:
+            other = region.chr[3:] if region.chr.startswith("chr") else "chr" + region.chr
+            if other in names:
+                warnings.warn(f"{self._what()}: no interval on {region.chr!r}; the data name it "
+                              f"{other!r}", stacklevel=2)
+        out = {k: [v[i] for i in keep] for k, v in cols.items()}
+        for k in ("start", "end", "thickStart", "thickEnd"):
+            if k in out:
+                out[k] = [_bp(v) for v in out[k]]
+        return out
+
+    def _read(self, region: Region) -> dict[str, list[Any]]:
+        return sources.read_entries(self.reader, region)
+
+    def _label_font(self) -> Any:
+        return font_of(self, self.resolve("name_font_size"),
+                       style="italic" if self.resolve("kind") == "genes" else "normal",
+                       color=self.resolve("text_color"))
+
+    def _label_text(self, i: int, cols: dict[str, list[Any]], keep: int | None = None) -> Any:
+        """The name of entry ``i`` (``None``: none), its first ``keep`` characters and an
+        ellipsis when ``keep`` is given."""
+        names = cols.get("name")
+        if not names or names[i] is None or str(names[i]) in ("", "."):
+            return None
+        only = self.resolve("name_region")
+        if only is not None:
+            if only.chr != self.region().chr or cols["end"][i] <= only.start \
+                    or cols["start"][i] >= only.end:
+                return None
+        name = str(names[i])
+        if keep is not None:
+            name = name[:keep].rstrip() + "…"
+        return name
+
+    def placed(self) -> "Placed":
+        """The rows and names of the entries, for the axes width: packing and drawing
+        read this one result."""
+        return self.cached((self.region(), self.axes_px()), self._place, kind="rows")
+
+    def layout_rows(self) -> tuple[list[int], int]:
+        """The row of each entry (-1: left out past ``max_rows``) and the number of
+        rows."""
+        p = self.placed()
+        return p.rows, p.count
+
+    def _place(self) -> "Placed":
+        cols = self.entries()
+        n = len(cols["start"])
+        if not n:
+            return Placed([], 1, [], 0, 0)
+        region = self.region()
+        ppb = self.axes_px() / region.span                    # px per bp
+        lo, hi = region.start * ppb, region.end * ppb         # the view, px
+        mw = self.resolve("min_width")
+        spans = []
+        for i in range(n):
+            a, b = cols["start"][i] * ppb, cols["end"][i] * ppb   # px, widened as drawn
+            if b - a < mw:
+                a, b = (a + b - mw) / 2, (a + b + mw) / 2
+            spans.append((a, b))
+        mode = self.resolve("rows")
+        widths: list[float | None] = [None] * n
+        heights = [0.0] * n
+        gap = 0.0
+        font = self._label_font()
+        fonts = document_db()
+        if self.resolve("names") and mode != "squish":
+            gap = 0.3 * font.size
+            for i in range(n):
+                t = self._label_text(i, cols)
+                if t is not None:
+                    w, a, d = measure(fonts, t, font)
+                    widths[i], heights[i] = w, a + d
+        positions = NAME_POSITIONS[self.resolve("name_position")]
+        order = None
+        more = 0
+        if mode == "collapse":
+            rows, count = [0] * n, 1
+            order = [b - a for a, b in spans]                 # longer features first
+        else:
+            cap = int(self.resolve("max_rows"))
+            rows = []
+            if any(w is not None for w in widths):            # features with their names
+                foot = [spans[i] if w is None
+                        else spot(*spans[i], w, lo, hi, gap, positions) or spans[i]
+                        for i, w in enumerate(widths)]
+                rows = pack_rows([f[0] for f in foot], [f[1] for f in foot], gap=2.0)
+                if max(rows) + 1 > cap:
+                    rows = []
+            if not rows:                                      # the features alone
+                rows = pack_rows([a for a, _ in spans], [b for _, b in spans], gap=2.0)
+            count = max(rows) + 1
+            if count > cap:
+                more = sum(r >= cap for r in rows)
+                rows = [r if r < cap else -1 for r in rows]
+                count = cap
+        names: list[Any] = [None] * n
+        if any(w is not None for w in widths):
+            keep = [i for i in range(n) if rows[i] >= 0]
+            taken = None
+            if more:                                          # the mark's room
+                w = measure(document_db(), f"+{more} more", self._more_font())[0]
+                taken = {count - 1: (hi - w - gap, hi)}          # gap: 2 × its pad
+            cut = _Cut(self, cols, keep, font)
+            got = name_row([spans[i] for i in keep], [widths[i] for i in keep],
+                           [rows[i] for i in keep], lo, hi, gap, positions,
+                           None if order is None else [order[i] for i in keep], taken, cut)
+            for j, (i, p) in enumerate(zip(keep, got)):
+                if p is not None:
+                    k = cut.kept.get(j)
+                    drawn = widths[i] if k is None else cut.width(j, k)
+                    names[i] = (p[0] / ppb, p[1], p[2], drawn, heights[i],
+                                None if k is None else cut.text(j, k))
+        unnamed = sum(1 for i in range(n)
+                      if rows[i] >= 0 and widths[i] is not None and names[i] is None)
+        return Placed(rows, count, names, more, unnamed)
+
+    def lane_rows(self) -> int:
+        """The number of rows of the series' lane."""
+        return self.layout_rows()[1]
+
+    def drawn_rows(self) -> tuple[float, float]:
+        """The range of rows its features cover (a box's height in its first and last
+        row)."""
+        return 0.5 - _BOX / 2, self.lane_rows() - 0.5 + _BOX / 2
+
+    # -- drawing ---------------------------------------------------------------------
+
+    def _colors(self, ctx: Any, cols: dict[str, list[Any]]) -> list[Any]:
+        c = self.resolve("color")
+        n = len(cols["start"])
+        black = ctx.color(self.resolve("text_color"))
+        if c == "item_rgb":
+            rgb = cols.get("itemRgb") or [None] * n
+            return self._recolored([_rgb(v, i) or black for i, v in enumerate(rgb)])
+        if c == "score":
+            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:
+                if v is None:
+                    out.append(bad)
+                else:
+                    t = unit(v)
+                    out.append(m(min(1.0, max(0.0, t))) if math.isfinite(t) else bad)
+            return out
+        return self._recolored([ctx.color(c)] * n)
+
+    def _recolored(self, colors: list[Any]) -> list[Any]:
+        r = self.resolve("recolor")
+        if r is False:
+            return colors
+        level = None if r is True else float(r)
+        variant = variant_of(self)
+        return [nearest_named(c, level, variant) for c in colors]
+
+    def layers(self) -> Call:
+        from .contacts import tads, under_hic
+        hic = under_hic(self)
+        if hic is not None:                       # over a Hi-C triangle: TADs
+            return tads(self, hic)
+        call = self.genome_call()
+        cols = self.entries()
+        n = len(cols["start"])
+        key = id(self)
+        placed = self.placed()
+        rows, spots = placed.rows, placed.names
+        if placed.more:                           # left out past max_rows
+            keep = [i for i in range(n) if rows[i] >= 0]
+            cols = {k: [v[i] for i in keep] if isinstance(v, list) and len(v) == n else v
+                    for k, v in cols.items()}
+            rows, spots = [rows[i] for i in keep], [spots[i] for i in keep]
+            n = len(keep)
+
+        def colors(ctx: Any) -> list[Any]:
+            opacity = self.resolve("opacity")
+            opacity = 1.0 if opacity is None else opacity
+            return memo(ctx, (key, "colors"), lambda: [with_alpha(c, opacity)
+                                                       for c in self._colors(ctx, cols)])
+
+        if n:
+            if self.resolve("kind") == "genes":
+                self._genes(call, cols, rows, colors)
+            else:
+                self._boxes(call, cols, rows, colors)
+            if any(p is not None for p in spots):
+                call.layers.append(placed_text(self, key, lambda ctx: self._label_items(
+                    ctx, cols, rows, spots, colors), lambda ctx: self._label_font(),
+                    overlay=False, background=self._background))
+        if placed.unnamed:
+            warn(f"{self._what()}: {placed.unnamed} feature name"
+                 f"{'s' if placed.unnamed > 1 else ''} left out (no room)",
+                 key=(key, "unnamed"))
+        if placed.more:
+            call.layers.append(placed_text(self, (key, "more"), lambda ctx: self._more_item(
+                ctx, placed), lambda ctx: self._more_font(), overlay=False,
+                background=self._background))
+        for la in call.layers:
+            la.occupy = False
+            la.options["bounds"] = False
+            la.key = False
+        if self.resolve("color") == "score":
+            scores = [v for v in self.entries().get("score", []) if v is not None]
+            call.color_sources = [(color_axis_of(self), array("d", scores))]
+        r = self.region()
+        call.extra = {"x": array("d", [r.start, r.end])}
+        call.hide = {"y"}                         # rows, in the series' lane
+        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 _rect_paint(self, ctx: Any, colors: Any) -> dict[str, Any]:
+        """Features filled (``fill``) and outlined (``outline``) in their colors."""
+        cs = colors(ctx)
+        fc, fa = groups.fill_parts(self)
+        lw = self.resolve("line_width")
+        fills = cs if fc is None else [ctx.color(fc)] * len(cs)
+        return {"fill": [with_alpha(c, fa) for c in fills] if fa > 0 else None,
+                "stroke": cs if self.resolve("outline") and lw else None,
+                "line_width": lw}
+
+    def _span(self, ctx: Any, s: float, e: float) -> tuple[float, float]:
+        """Page x and width of ``[s, e)``, at least ``min_width`` wide."""
+        a, b = ctx.xmap(s), ctx.xmap(e)
+        a, b = min(a, b), max(a, b)
+        mw = self.resolve("min_width")
+        if b - a < mw:
+            c = (a + b) / 2
+            a, b = c - mw / 2, c + mw / 2
+        return a, b - a
+
+    def _band(self, ctx: Any, row: int, frac: float) -> tuple[float, float]:
+        """Page y (top) and height of the middle ``frac`` of row ``row``."""
+        top, bot = ctx.ymap(row + 0.5 - frac / 2), ctx.ymap(row + 0.5 + frac / 2)
+        return min(top, bot), abs(bot - top)
+
+    def _boxes(self, call: Call, cols: dict[str, list[Any]], rows: list[int],
+               colors: Any) -> None:
+        t = Table(x0=cols["start"], x1=cols["end"], y0=[r + 0.5 - _BOX / 2 for r in rows],
+                  y1=[r + 0.5 + _BOX / 2 for r in rows])
+        call.layers.append(Layer(GEOMS["rects"], t,
+                                 paint=Paint(self, "intervals.rects", colors=colors),
+                                 stat="intervals", min_width=self.resolve("min_width"),
+                                 inset=bool(self.resolve("outline"))))
+        if self.resolve("strand"):
+            def chevrons(ctx: Any) -> list[Any]:
+                out: list[Any] = []
+                strands = cols.get("strand") or []
+                fills = self._rect_paint(ctx, colors)["fill"]
+                cs = colors(ctx)
+                for i, s in enumerate(strands):
+                    if s in ("+", "-"):
+                        x, w = self._span(ctx, cols["start"][i], cols["end"][i])
+                        y, h = self._band(ctx, rows[i], _BOX)
+                        # white on a dark fill, else the feature's color
+                        ink = cs[i] if fills is None or _lightness(fills[i]) > 0.8 else "white"
+                        self._chevrons(out, x, x + w, y + h / 2, h * _CHEVRON_BOX / 2, s, ink)
+                return out
+            lines = Table()
+            lines.lazy["page_lines"] = chevrons
+            call.layers.append(Layer(GEOMS["path"], lines, paint={}, stat="intervals"))
+
+    def _chevrons(self, out: list[Any], x0: float, x1: float, y: float, size: float,
+                  strand: str, col: Any) -> None:
+        """Strand marks along ``[x0, x1]`` at ``y`` (page units), added to ``out`` as one
+        polyline."""
+        step = max(3 * size, 0.9 * self.resolve("font_size"))
+        if x1 - x0 < 1.5 * step:
+            return
+        k = int((x1 - x0) / step)
+        pad = ((x1 - x0) - (k - 1) * step) / 2
+        d = size if strand == "+" else -size
+        xs, ys = array("d"), array("d")
+        for j in range(k):
+            cx = x0 + pad + j * step
+            xs.extend([cx - d / 2, cx + d / 2, cx - d / 2, math.nan])
+            ys.extend([y - size, y, y + size, math.nan])
+        out.append((xs, ys, col, max(0.5, self.resolve("line_width"))))
+
+    def _genes(self, call: Call, cols: dict[str, list[Any]], rows: list[int],
+               colors: Any) -> None:
+        lw = self.resolve("line_width")
+        strands = cols.get("strand") or [None] * len(rows)
+        counts = cols.get("blockCount")
+        sizes = cols.get("blockSizes")
+        starts = cols.get("blockStarts")
+        t0s = cols.get("thickStart")
+        t1s = cols.get("thickEnd")
+        x0, x1, y0, y1, owner = [], [], [], [], []
+        blocks = []
+        for i in range(len(rows)):
+            s, e = cols["start"][i], cols["end"][i]
+            if counts and sizes and starts and counts[i]:
+                bl = [(s + a, s + a + b) for a, b in zip(sources.ints(starts[i]),
+                                                         sources.ints(sizes[i]))]
+            else:
+                bl = [(s, e)]
+            blocks.append(bl)
+            t0 = t0s[i] if t0s and t0s[i] is not None else s
+            t1 = t1s[i] if t1s and t1s[i] is not None else e
+            if t1 <= t0:                       # non-coding: the whole model is UTR-high
+                t0, t1 = s, s
+            for a, b in bl:                    # coding exons as tall as boxes, UTRs half
+                parts = [(a, min(b, t0), _BOX / 2), (max(a, t0), min(b, t1), _BOX),
+                         (max(a, t1), b, _BOX / 2)]
+                if t0 == t1 == s:
+                    parts = [(a, b, 0.75 * _BOX)]
+                for pa, pb, frac in parts:
+                    if pb <= pa:
+                        continue
+                    x0.append(pa)
+                    x1.append(pb)
+                    y0.append(rows[i] + 0.5 - frac / 2)
+                    y1.append(rows[i] + 0.5 + frac / 2)
+                    owner.append(i)
+
+        def models(ctx: Any) -> list[Any]:
+            """The gene lines and their introns' strand marks (page units), per gene."""
+            cs = colors(ctx)
+            out: list[Any] = []
+            for i in range(len(rows)):
+                c = cs[i]
+                cy = ctx.ymap(rows[i] + 0.5)
+                out.append(([ctx.xmap(cols["start"][i]), ctx.xmap(cols["end"][i])], [cy, cy],
+                            c, lw))
+                if self.resolve("strand") and strands[i] in ("+", "-"):
+                    _, h = self._band(ctx, rows[i], _BOX)
+                    bl = blocks[i]
+                    for (_, b0), (a1, _) in zip(bl, bl[1:]):
+                        self._chevrons(out, ctx.xmap(b0), ctx.xmap(a1), cy, h * _CHEVRON_INTRON / 2,
+                                       strands[i], c)
+            return out
+
+        lines = Table()
+        lines.lazy["page_lines"] = models
+        call.layers.append(Layer(GEOMS["path"], lines, paint={}, stat="intervals"))
+        call.layers.append(Layer(GEOMS["rects"], Table(x0=x0, x1=x1, y0=y0, y1=y1),
+                                 paint=Paint(self, "intervals.rects", colors=colors,
+                                             owner=owner), stat="intervals", min_width=self.resolve("min_width"),
+                                 inset=bool(self.resolve("outline"))))
+
+    def _label_items(self, ctx: Any, cols: dict[str, list[Any]], rows: list[int],
+                     spots: list[Any], colors: Any) -> list[Any]:
+        """Feature names where :meth:`placed` put them; a name over a dark feature on a
+        background box."""
+        font = self._label_font()
+        fills = self._rect_paint(ctx, colors)["fill"]
+        pad = 0.15 * font.size
+        out: list[Any] = []
+        for i, p in enumerate(spots):
+            if p is None:
+                continue
+            x, ha, where, w, h, short = p
+            x, y = ctx.xmap(x), ctx.ymap(rows[i] + 0.5)
+            text_ = self._label_text(i, cols) if short is None else short
+            if where in ("inside", "edge") and fills is not None \
+                    and _lightness(fills[i]) < 0.6:
+                x += w / 2 if ha == "left" else -w / 2 if ha == "right" else 0.0
+                out.append((text_, x, y, font.color, "center", "center", 0.0,
+                            (w, h, pad)))
+            else:
+                out.append((text_, x, y, font.color, ha, "center"))
+        return out
+
+    def _background(self, ctx: Any) -> Any:
+        fig = self.plot.figure
+        return next(c for c in (ctx.color(self.plot.resolve("background")),
+                                ctx.color(fig.resolve("background")), "white")
+                    if c is not None)
+
+    def _more_font(self) -> Any:
+        return font_of(self, self.resolve("name_font_size"), color=self.resolve("text_color"))
+
+    def _more_item(self, ctx: Any, placed: "Placed") -> list[Any]:
+        """The "+n more" mark at the right of the series' last row, on a background
+        box."""
+        font = self._more_font()
+        text_ = f"+{placed.more} more"
+        w, a, d = measure(ctx.canvas, text_, font)
+        pad = 0.15 * font.size
+        return [(text_, ctx.rect[2] - w / 2 - pad, ctx.ymap(placed.count - 0.5), font.color,
+                 "center", "center", 0.0, (w, a + d, pad))]
+
+    def row_px(self) -> float:
+        """The height of one of its rows (px)."""
+        h = float(self.resolve("row_height"))
+        return h / 2 if self.resolve("rows") == "squish" else h
+
+
+class Placed:
+    """The rows of a series' entries (``rows``: -1 for an entry left out past
+    ``max_rows``; ``count`` rows), their names (per entry ``(x, ha, where, w, h, short)``:
+    the anchor in bp, its alignment, its position (:data:`plot_io.labels.Spot`), its size
+    in px and the shortened name drawn (``None``: the whole name); or ``None``), how many
+    entries were left out (``more``) and how many names (``unnamed``)."""
+
+    __slots__ = ("rows", "count", "names", "more", "unnamed")
+
+    def __init__(self, rows: list[int], count: int, names: list[Any], more: int,
+                 unnamed: int) -> None:
+        self.rows, self.count, self.names, self.more = rows, count, names, more
+        self.unnamed = unnamed
+
+
+class _Cut:
+    """Names shortened with an ellipsis (:func:`plot_io.labels.row`'s ``cut``) of the
+    entries ``keep`` of ``cols``: ``k`` characters kept, measured once."""
+
+    def __init__(self, series: Any, cols: dict[str, list[Any]], keep: list[int],
+                 font: Any) -> None:
+        self.series, self.cols, self.keep, self.font = series, cols, keep, font
+        self.kept: dict[int, int] = {}
+        self._widths: dict[tuple[int, int], float] = {}
+
+    def steps(self, j: int) -> int:
+        names = self.cols.get("name") or ()
+        i = self.keep[j]
+        return max(0, len(str(names[i])) - 1) if i < len(names) else 0
+
+    def text(self, j: int, k: int) -> Any:
+        return self.series._label_text(self.keep[j], self.cols, k)
+
+    def width(self, j: int, k: int) -> float:
+        if (j, k) not in self._widths:
+            self._widths[(j, k)] = measure(document_db(), self.text(j, k), self.font)[0]
+        return self._widths[(j, k)]
+
+
+class Genes(GenesMixin, Bed):
+    """Gene models (BED12): ``Bed`` with ``kind="genes"``, rows expanded and names on.
+
+    Filled solid without outlines; the settings are :class:`Bed`'s, its own defaults below.
+
+    Example::
+
+        fig = plt.Tracks(("chr1", 13_550_000, 13_980_000), width=300)
+        fig.genes({"start": [13_600_000], "end": [13_930_000], "name": ["Pcsk2"], "strand": ["+"],
+                   "thickStart": [13_640_000], "thickEnd": [13_920_000], "blockCount": [5],
+                   "blockSizes": ["3000,2000,2500,2000,9000"],
+                   "blockStarts": ["0,90000,170000,240000,321000"]})
+    """
+
+
+def _types(v: Any) -> Any:
+    if v is None or isinstance(v, str):
+        return v
+    if isinstance(v, (list, tuple)) and v and all(isinstance(t, str) for t in v):
+        return list(v)
+    raise ValueError(f"expected a type name, a list of them or None, got {v!r}")
+
+
+class Gtf(GtfMixin, Genes):
+    """Gene models of a GTF or GFF3 reader (``read_entries(model=)``) or path: ``Genes``, one
+    model per gene (its transcripts' exons merged) or per transcript, or plain BED12 data
+    as ``Genes`` takes it.
+
+    A path is a bgzipped, indexed GTF or GFF3 (``"gencode.gtf.gz"``; ``gwseq_io.sort_gtf``
+    makes one from any GTF; `readers <docs/api.md#readers>`_).  The transcripts overlapping the region come whole,
+    with their exons outside it.  With ``model="gene"`` each gene is one model: its
+    transcripts' exons merged, coding from the first CDS start to the last CDS end (the stop
+    codon included), named by ``gene_name``; ``model="transcript"`` draws every transcript,
+    named by ``transcript_name``.  An id names what has no name.  ``gene_type`` and
+    ``transcript_type`` keep those biotypes.  A :class:`Bed` or :class:`Genes` given a GTF
+    reader raises ``TypeError`` pointing here.
+
+    Example::
+
+        fig = plt.Tracks(("chr1", 0, 60_000), width=300)
+        fig.gtf({"start": [4_000, 30_000], "end": [26_000, 55_000], "name": ["Abc1", "Def2"],
+                 "strand": ["+", "-"], "thickStart": [6_000, 32_000], "thickEnd": [24_000, 52_000],
+                 "blockCount": [3, 2], "blockSizes": ["3000,4000,4000", "6000,5000"],
+                 "blockStarts": ["0,8000,18000", "0,20000"]})
+    """
+
+    SETTINGS = table(
+        **Genes.SETTINGS,
+        model=Setting(one_of("gene", "transcript"),
+                      doc="`gene`: one model per gene, its transcripts' exons merged and "
+                          "coding from the first CDS start to the last CDS end, named by "
+                          "`gene_name`; `transcript`: one per transcript, named by "
+                          "`transcript_name` (ids where there is no name)."),
+        gene_type=Setting(_types, doc="Gene biotypes kept (`\"protein_coding\"`, a list); "
+                                      "`None`: all."),
+        transcript_type=Setting(_types, doc="Transcript biotypes kept; `None`: all."),
+    )
+    READS = "annotation"
+
+
+    def _read(self, region: Region) -> dict[str, list[Any]]:
+        if sources.kind_of(self.reader) != "annotation":          # BED12 data
+            return sources.read_entries(self.reader, region)
+        return sources.read_models(self.reader, region, self.resolve("model"),
+                                   self.resolve("gene_type"), self.resolve("transcript_type"))
+
+
+add_layer("bed", Bed)
+add_layer("genes", Genes)
+add_layer("gtf", Gtf)
+
+
+@role("intervals.rects")
+def _rects_paint(s: Any, ctx: Any, glyph: bool, colors: Any = None,
+                 owner: Any = None) -> dict[str, Any]:
+    """Features (``owner``: exons, each in its feature's colors)."""
+    p = s._rect_paint(ctx, colors)
+    if owner is not None:
+        for k in ("fill", "stroke"):
+            if isinstance(p[k], list):
+                p[k] = [p[k][i] for i in owner]
+    return p