plot-io 0.12.0__py3-none-win_arm64.whl

plot_io/genome/lanes.py

@@ -0,0 +1,191 @@
+"""Lanes: a plot holding interval series is a vertical stack of lanes in its axes
+rectangle.
+
+The *value lane* holds the series with a y scale (signals, ordinary series, the Hi-C
+triangle).  Each interval series (a series with a ``lane`` setting; a signal drawn as a
+heat strip) gets a lane of its own, measured in px (its rows × ``row_height``):
+``lane="below"`` (the default) or ``"above"`` the value lane, each group top to bottom in
+call order, ``lane_gap`` apart; or ``lane="over"``: drawn in the lane of the series called before it (over the value lane, its
+rows span that lane; over an interval lane, the two share rows).
+
+The y axis maps only the value lane: :func:`y_span` gives the px its state leaves at each
+end (``AxisState.span``), which its mapper, ticks, grid and spine follow.  Interval series
+draw through a y mapper of their lane (``call.lane``, see :func:`lane_mapper`): rows from
+the lane's top, no axis padding.  With ``height="auto"`` a track is as high as its lanes
+(:func:`natural_height`); with a fixed height the interval lanes keep their px and the
+value lane takes the rest; without a value lane the lanes are scaled to fill the axes.
+An interval lane's ``name`` is drawn left of the lane, centred on it (:func:`names`).
+"""
+
+from typing import Any
+
+from ..axis import Mapper
+from ..settings import Setting, one_of
+
+__all__ = ["lane_setting", "is_lane", "natural_height", "y_span", "value_height",
+           "lane_mapper", "names", "LANE_GAP"]
+
+#: ``lane_gap`` of a plot without the setting (an ordinary plot), in em.
+LANE_GAP = 0.3
+
+
+def lane_setting() -> Setting:
+    return Setting(one_of("below", "above", "over"),
+                   doc="Where the series is drawn: in a lane of its own `below` or `above` "
+                       "the track's value lane (signals, Hi-C; each group top to bottom "
+                       "in call order), or `over` the lane of the series called before it "
+                       "(over a signal, its rows span the signal's lane; over intervals, "
+                       "the two share rows; over a Hi-C triangle, intervals are drawn as "
+                       "TADs and links as loop marks).")
+
+
+def is_lane(series: Any) -> bool:
+    """Whether a series is drawn in a lane of its own: it has a ``lane`` setting and rows
+    (``lane_rows()``, their count; ``drawn_rows()``, the row range its features cover;
+    ``row_px()``, the height of a row), and ``in_lane()`` when it has one (a signal is a
+    lane as a heat strip only)."""
+    if not (hasattr(series, "lane_rows") and "lane" in series.SETTINGS):
+        return False
+    in_lane = getattr(series, "in_lane", None)
+    return in_lane is None or bool(in_lane())
+
+
+class Lane:
+    """A lane: ``where`` (``"above"``, ``"value"`` or ``"below"``), the interval series
+    drawn in it, its top and height (px from the axes' top, once placed)."""
+
+    __slots__ = ("where", "members", "top", "height")
+
+    def __init__(self, where: str, members: list[Any]) -> None:
+        self.where, self.members = where, members
+        self.top = self.height = 0.0
+
+    def rows(self) -> int:
+        """The rows the members share."""
+        return max((s.lane_rows() for s in self.members), default=1)
+
+    def px(self) -> float:
+        """The lane's own height: its rows × its first member's row height
+        (``row_px()``: ``row_height``, half of it for squished rows), or the height a
+        member asks (``lane_px()``: links), the larger."""
+        rowed = [s for s in self.members if not hasattr(s, "lane_px")]
+        own = [s.lane_px() for s in self.members if hasattr(s, "lane_px")]
+        if rowed:
+            own.append(max(s.lane_rows() for s in rowed) * rowed[0].row_px())
+        return max(own)
+
+
+def _lanes(plot: Any) -> tuple[Lane | None, list[Lane]]:
+    """The value lane (``None``: the plot has no series with a y scale) and every lane, top
+    to bottom."""
+    value = Lane("value", [])
+    has_value = any(t.series for t in getattr(plot, "twins", ()))
+    above: list[Lane] = []
+    below: list[Lane] = []
+    prev: Lane | None = None
+    for s in plot.series:
+        if not is_lane(s):
+            has_value = True
+            prev = value
+            continue
+        where = s.resolve("lane")
+        if where == "over" and prev is not None:
+            prev.members.append(s)
+            continue
+        lane = Lane("above" if where == "above" else "below", [s])
+        (above if where == "above" else below).append(lane)
+        prev = lane
+    if not has_value:
+        return None, above + below
+    return value, above + [value] + below
+
+
+def lane_gap(plot: Any) -> float:
+    if "lane_gap" in plot.SETTINGS:
+        return float(plot.resolve("lane_gap"))
+    return LANE_GAP * float(plot.resolve("font_size"))
+
+
+def natural_height(plot: Any, value_height: float) -> float:
+    """The height of a plot's lanes: the interval lanes', the value lane
+    ``value_height`` high (when the plot has one), and the gaps between them."""
+    value, lanes = _lanes(plot)
+    if not lanes:
+        return value_height
+    total = sum(value_height if la is value else la.px() for la in lanes)
+    return total + lane_gap(plot) * (len(lanes) - 1)
+
+
+def _placed(plot: Any, h: float) -> tuple[Lane | None, list[Lane]]:
+    """The lanes placed in axes ``h`` px high."""
+    value, lanes = _lanes(plot)
+    if not lanes:
+        return value, lanes
+    gaps = lane_gap(plot) * (len(lanes) - 1)
+    own = [la.px() for la in lanes if la is not value]
+    total = sum(own)
+    if value is not None:
+        rest = h - gaps - total
+        k = 1.0 if rest >= 1.0 or not total else max(0.0, h - gaps - 1.0) / total
+        rest = max(rest, min(1.0, h))
+    else:
+        rest = 0.0
+        k = max(0.0, h - gaps) / total if total else 1.0
+    y = 0.0
+    for la in lanes:
+        la.top = y
+        la.height = rest if la is value else la.px() * k
+        y += la.height + lane_gap(plot)
+    return value, lanes
+
+
+def y_span(plot: Any, h: float) -> tuple[float, float]:
+    """The px the y axis leaves below and above the value lane of axes ``h`` px high (0 and
+    0: the plot has no interval lane, or no value lane)."""
+    value, lanes = _placed(plot, h)
+    if value is None or len(lanes) < 2:
+        return 0.0, 0.0
+    return h - value.top - value.height, value.top
+
+
+def value_height(plot: Any, h: float) -> float:
+    """The height of the value lane of axes ``h`` px high (``h``: no interval lane)."""
+    value, lanes = _placed(plot, h)
+    return h if value is None or len(lanes) < 2 else value.height
+
+
+def _lane_of(plot: Any, series: Any, h: float) -> Lane | None:
+    _, lanes = _placed(plot, h)
+    return next((la for la in lanes if any(s is series for s in la.members)), None)
+
+
+def lane_mapper(series: Any) -> Any:
+    """``call.lane`` of an interval series: the y mapper of its rows in its lane, from the
+    plot's drawing context (row 0 at the lane's top)."""
+    def mapper(ctx: Any) -> Mapper:
+        x0, y0, x1, y1 = ctx.rect
+        lane = _lane_of(series.plot, series, y1 - y0)
+        if lane is None:
+            top, height, lo, hi = y0, y1 - y0, 0.0, float(series.lane_rows())
+        elif lane.where == "value":           # the features span the value lane
+            top, height = y0 + lane.top, lane.height
+            lo, hi = series.drawn_rows()
+        else:
+            top, height, lo, hi = y0 + lane.top, lane.height, 0.0, float(lane.rows())
+        return Mapper(None, lo, hi, top, top + height)
+    return mapper
+
+
+def names(plot: Any, h: float) -> list[tuple[Any, float, float]]:
+    """The names of the interval lanes of axes ``h`` px high: ``(name, top, bottom)``, px
+    from the axes' top (a lane's name: its first member's ``name``)."""
+    _, lanes = _placed(plot, h)
+    out = []
+    for la in lanes:
+        if la.where == "value":
+            continue
+        name = next((s.resolve("name") for s in la.members if s.resolve("name") is not None),
+                    None)
+        if name is not None and name != "":
+            out.append((name, la.top, la.top + la.height))
+    return out

plot_io/genome/layout.py

@@ -0,0 +1,184 @@
+"""Genome tracks: a tracks figure (``plt.Tracks(region)``) whose rows are :class:`Track`
+plots over a genome x axis.
+
+``plt.Tracks(region, **settings)`` is a :class:`~plot_io.Figure` with ``layout="tracks"``:
+one column of plots sharing x, each as high as its ``height``; its x axes take the genome
+scale over ``region`` (``figure.x_axis``).  A track is a plot preset: a height from its
+content, space above it, the y axis with at most 4 ticks and its label left of the track
+(``label_position="left"``; a ``band`` label longer than the track is drawn as ``left``),
+axis lines left and bottom (Hi-C: bottom only).  Its interval series are in lanes of their
+own beside the value lane (:mod:`plot_io.genome.lanes`).  Plot types called on the figure
+(``fig.bigwig(…)``) add a track holding them; called on a track, they overlay in it.
+"""
+
+from typing import Any
+
+from .._methods import TrackMixin
+from ..figure import Figure
+from ..plot import Plot
+from ..settings import Setting, either, literal, table
+from ..styles import register_class
+from ..validators import length
+from .contacts import HiC
+from .lanes import is_lane, natural_height
+from .series import GenomeSeries, axes_width
+from .signal import fill_mode
+
+__all__ = ["Track", "Tracks"]
+
+#: Keywords of :func:`Tracks` that go to the genome x axis.
+AXIS_KEYS = ("unit", "unit_in", "tick_format", "origin", "region_widths", "region_gap",
+             "chr_sizes", "scale_bar")
+
+
+def _hangs(track: "Track") -> bool:
+    """A Hi-C triangle hangs from the top (no x axis under it)."""
+    return any(isinstance(s, HiC) and s.resolve("direction") == "down" for s in track.series)
+
+
+def _spines(track: "Track") -> Any:
+    if any(isinstance(s, HiC) and not s.square() for s in track.series):
+        return "none" if _hangs(track) else ["bottom"]
+    return ["left", "bottom"]
+
+
+def check_height(v: Any) -> Any:
+    """A track height: ``"auto"``, a length, or a share ``"2fr"`` (kept as ``("fr", 2.0)``:
+    the figure turns it into a row ratio)."""
+    if isinstance(v, tuple) and len(v) == 2 and v[0] == "fr":
+        return v
+    if isinstance(v, str) and v.strip().lower().endswith("fr"):
+        try:
+            n = float(v.strip()[:-2] or 1.0)
+        except ValueError:
+            raise ValueError(f"expected a share such as '1fr', got {v!r}") from None
+        if not n > 0:
+            raise ValueError(f"expected a positive share, got {v!r}")
+        return ("fr", n)
+    return either(literal("auto"), length(positive=True))(v)
+
+
+def _auto_space(track: "Track") -> float:
+    """``space_above="auto"``: none above the figure's first plot, else
+    ``auto_space_above``."""
+    plots = track.figure.plots
+    if plots and plots[0] is track:
+        return 0.0
+    return float(track.resolve("auto_space_above"))
+
+
+def _auto_height(track: "Track") -> float:
+    """``height="auto"``: the track's lanes, its value lane as high as the largest height
+    a genome series asks (Hi-C from its depth), else ``auto_height``."""
+    width = axes_width(track)
+    asked = [a for a in (s.track_height(width) for s in track.series
+                         if isinstance(s, GenomeSeries) and not is_lane(s)) if a is not None]
+    value = max(asked) if asked else float(track.resolve("auto_height"))
+    return natural_height(track, value)
+
+
+class Track(TrackMixin, Plot):
+    """A row of a tracks figure (:func:`Tracks`): a plot with a height and space above it.
+    Add series with its methods (``bigwig``, ``bed``, ``genes``, ``gtf``, ``hic``, or any
+    plot type).
+
+    A track has axis lines left and bottom (Hi-C: bottom only), at most 4 y ticks and its y
+    ``label`` left of it.  A plot holding interval series is a stack of lanes: the value
+    lane (signals, ordinary series, Hi-C) and one lane per interval series (``bed``,
+    ``genes``, ``gtf``: rows × ``row_height``; ``links``: its arcs), ``lane="below"``
+    (default) or ``"above"`` it, ``lane_gap`` apart; ``lane="over"`` draws a series in the
+    lane of the one before it (over Hi-C: intervals as domains, links as loops).  An
+    interval lane's ``name`` is written left of it.  The y axis maps the value lane only;
+    interval rows are px.  ``height``: a length, a share (``"1fr"``) or ``"auto"`` (the Hi-C
+    triangle's, capped by ``max_height``, or ``auto_height`` for signals, plus the lanes).
+    ``bins`` of ``bigwig`` and ``hic``: a width on the axes (``"0.5px"``: two per px), a size
+    (``"10kb"``, read on the genome-wide grid) or a count.  ``share_y=other_track``, or the
+    figure's ``share_y="bigwig"`` (a plot type's name), puts tracks on one y scale.
+    """
+
+    SETTINGS = table(**{**Plot.SETTINGS, **dict(
+        height=Setting(check_height, auto=_auto_height,
+                       doc="Height of the track's axes: a length, a share of the room the "
+                           "fixed heights leave (`\"1fr\"`, with the figure's height given), "
+                           "or `auto`: the lanes' heights, intervals rows × `row_height`, the "
+                           "value lane from Hi-C's `depth` (square cells), else "
+                           "`auto_height`."),
+        auto_height=Setting(length(positive=True, percent="em"),
+                            doc="Height of the value lane (signals) and of empty tracks with "
+                                "`height=\"auto\"`."),
+        space_above=Setting(either(literal("auto"), length(lo=0, percent="em")),
+                            auto=_auto_space,
+                            doc="Space above the track; `auto`: none for the first track, "
+                                "else `auto_space_above`."),
+        auto_space_above=Setting(length(lo=0, percent="em"),
+                                 doc="The space `space_above=\"auto\"` leaves."),
+        lane_gap=Setting(length(lo=0, percent="em"),
+                         doc="Space between the track's lanes (the value lane and each "
+                             "interval series' lane)."),
+        fill_mode=Setting(fill_mode,
+                          doc="Fill between the track's signals (replacing their `fill_to`): "
+                              "`\"in_between(up)\"` (or `\"in_between\"`), each band between "
+                              "two neighbouring signals in the fill color of the one above; "
+                              "`(down)`, of the one below; `(max)`, one band from the lowest "
+                              "signal to the highest in the color of the top one; `(min)`, of "
+                              "the bottom one. `None`: each signal's `fill_to`."),
+    )})
+    RULES = {"spines": _spines}
+    #: a ``band`` label longer than the track is drawn as ``left`` (:mod:`plot_io.rows`)
+    BAND_FITS = True
+
+    def __init__(self, figure: Any = None, id: Any = None, **settings: Any) -> None:
+        own = {k: settings.pop(k) for k in list(settings)
+               if k in Track.SETTINGS and k not in Plot.SETTINGS}
+        y_axis = settings.pop("y_axis", None)
+        if figure is None:
+            figure = Tracks()
+        super().__init__(figure=figure, id=id, **settings)
+        self.y_axis.set(max_ticks=4, label_position="left", label_pad="0.5em")
+        self.set(**own)
+        if y_axis is not None:
+            self._set_axes({"y_axis": y_axis})
+
+    def __repr__(self) -> str:
+        label = self.y_axis.get("label")
+        return f"Track({label!r})" if label else f"Track({self.id!r})"
+
+
+def Tracks(region: Any = None, **settings: Any) -> Figure:
+    """A figure of genome tracks over ``region`` (``"chr2:143,120,001-143,780,000"``,
+    ``(chr, start, end)`` or a mapping), or over a list of regions drawn side by side in
+    each track (segments of one genome axis: :mod:`plot_io.genome.scale`); a chromosome
+    name (``"chr1"``) is the whole chromosome: ``layout="tracks"``, its x axes on the
+    genome scale over the region (``unit``, ``unit_in``, ``tick_format``, ``origin``,
+    ``region_widths``, ``region_gap``, ``chr_sizes`` and ``scale_bar`` go to
+    ``figure.x_axis`` too); the other
+    settings are the figure's.
+
+    A region is a string, 1-based and inclusive (``"chr2:143,120,001-143,780,000"``;
+    positions may carry a unit: ``"chr1:1.2M-1.5M"``), a ``(chr, start, end)`` tuple
+    (0-based, half-open) or a mapping with ``chr``, ``start``, ``end``; it has no strand.  A
+    chromosome name takes its size from the x axis' ``chr_sizes``, else the readers'.  Data
+    are read when the figure is drawn, for the region drawn: ``save``, ``write``, ``draw`` and
+    ``size`` take ``region=``.
+
+    The x axis: ticks under every track, tick labels and the label (``chr2 (Mb)``) under the
+    bottom one (``label_outer=False``: every track).  ``unit`` (``auto``, ``bp``, ``kb``,
+    ``Mb``) and ``unit_in`` (``"label"``, or ``"ticks"``: ``-500kb 0 500kb``) set the labels;
+    ``tick_format="chr:pos"`` writes positions; in a ``label`` string ``{chr}``, ``{unit}``,
+    ``{start}``, ``{end}`` are filled in.  ``origin`` (a position, ``"center"``, ``"start"``,
+    ``"end"``) is drawn at 0: limits, ticks and decorations are distances from it.
+    ``scale_bar=True`` (or a length) draws a scale bar in place of ticks.  Regions side by
+    side (a list) are segments of one x axis, ``region_widths`` (``"span"`` or ``"equal"``)
+    wide and ``region_gap`` apart, each with its ticks and label; each series reads each
+    region, and a track keeps one y scale across them.
+    """
+    axis = {k: settings.pop(k) for k in AXIS_KEYS if k in settings}
+    fig = Figure(layout="tracks", **settings)
+    if region is not None:
+        axis["region"] = region
+    if axis:
+        fig.x_axis.set(scale="genome", **axis)
+    return fig
+
+
+register_class(Track)