phylustrator 0.2.17__tar.gz → 0.3.0__tar.gz

{phylustrator-0.2.17/src/phylustrator.egg-info → phylustrator-0.3.0}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: phylustrator
-Version: 0.2.17
+Version: 0.3.0
 Summary: A composable plotter for evolutionary figures: phylogenetic trees, genomes, synteny and alignments
 Author-email: "Adrian A. Davin" <aaredav@gmail.com>
 License: MIT
@@ -75,6 +75,8 @@ That is the whole idea: `plot(tree)` starts a figure and each `+ layer` adds one
 - **Layers** — `color_branches`, `color_history`, `tip_labels`, `node_labels`, `tip_track`,
   `branch_events`, `colorbar`, `legend`, `time_axis`, `time_marker`, `scale_bar`, `note`,
   `highlight_clade`.
+- **Panels** — `node_points`, placed under a rectangular tree with `ph.below(tree, panel)`. The panel
+  shares the tree's time axis, so a value measured at a node sits directly under that node.
 
 ## Genomes
 

{phylustrator-0.2.17 → phylustrator-0.3.0}/README.md

@@ -36,6 +36,8 @@ That is the whole idea: `plot(tree)` starts a figure and each `+ layer` adds one
 - **Layers** — `color_branches`, `color_history`, `tip_labels`, `node_labels`, `tip_track`,
   `branch_events`, `colorbar`, `legend`, `time_axis`, `time_marker`, `scale_bar`, `note`,
   `highlight_clade`.
+- **Panels** — `node_points`, placed under a rectangular tree with `ph.below(tree, panel)`. The panel
+  shares the tree's time axis, so a value measured at a node sits directly under that node.
 
 ## Genomes
 

{phylustrator-0.2.17 → phylustrator-0.3.0}/pyproject.toml

@@ -4,7 +4,7 @@ build-backend = "setuptools.build_meta"
 
 [project]
 name = "phylustrator"
-version = "0.2.17"
+version = "0.3.0"
 description = "A composable plotter for evolutionary figures: phylogenetic trees, genomes, synteny and alignments"
 readme = "README.md"
 requires-python = ">=3.10"

{phylustrator-0.2.17 → phylustrator-0.3.0}/src/phylustrator/__init__.py

@@ -12,8 +12,9 @@ Two domains, one grammar (``plot(x) + layer + …``), one shared drawing backend
     G = ph.zombi.read_genomes("run")
     (ph.genomes.plot(G["n12"], layout="circular") + ph.genomes.genes(by="family")).save("ring.png")
 
-    # bridge: a matrix beside a tree
+    # bridge: a matrix beside a tree, or a per-node value below it on the same time axis
     ph.beside(ph.trees.plot(tree) + ph.trees.tip_labels(), ph.genomes.heatmap(ph.zombi.read_profiles("run")))
+    ph.below(ph.trees.plot(tree), ph.trees.node_points({"C": 1.5, "R": -0.5}))
 
 ``ph.zombi`` is the only ZOMBI2-format-aware module; ``trees`` / ``genomes`` are general.
 """
@@ -24,7 +25,7 @@ from importlib.metadata import PackageNotFoundError
 from importlib.metadata import version as _pkg_version
 
 from . import genomes, trees, zombi
-from .compose import Composite, beside
+from .compose import Composite, below, beside
 from .style import Style
 
 try:  # single source of truth is pyproject.toml; read it from the installed metadata
@@ -32,4 +33,4 @@ try:  # single source of truth is pyproject.toml; read it from the installed met
 except PackageNotFoundError:  # a source tree that hasn't been installed
     __version__ = "0.0.0+unknown"
 
-__all__ = ["trees", "genomes", "zombi", "beside", "Composite", "Style", "__version__"]
+__all__ = ["trees", "genomes", "zombi", "beside", "below", "Composite", "Style", "__version__"]

phylustrator-0.3.0/src/phylustrator/compose.py

@@ -0,0 +1,121 @@
+"""Composition — put a panel beside a Phylustrator tree, rows lined up with the tips, or below it,
+lined up with the time axis.
+
+``beside(tree, panel)`` takes a **Phylustrator** figure (the phylogeny — Phylustrator draws it, we do
+not redraw it) and a panel (``heatmap`` / ``alignment``). It asks the tree for its tip pixel positions
+(``Figure.geometry``), renders the tree into the left column, and draws the panel to the right with
+each row at its tip's ``y`` — so a genome's row sits exactly on its leaf.
+
+``below(tree, panel)`` is its x-axis twin: the panel (``trees.node_points``) sits under the tree and
+places each value at its node's pixel ``x``.
+"""
+
+from __future__ import annotations
+
+from dataclasses import replace
+
+from .render import Canvas
+from .style import Style
+from .trees.layers.guides import draw_time_axis
+
+
+class Composite:
+    """The rendered composite; save like any figure."""
+
+    def __init__(self, canvas: Canvas) -> None:
+        self._canvas = canvas
+
+    def as_svg(self) -> str:
+        return self._canvas.as_svg()
+
+    def save(self, path):
+        return self._canvas.save(path)
+
+
+def beside(tree, panel, *, width: float = 1100.0, height: float | None = None,
+           tree_fraction: float = 0.4, gap: float = 18.0, pad: float = 34.0,
+           footer: float = 0.0, background: str = "white") -> Composite:
+    """Render Phylustrator ``tree`` on the left and ``panel`` on the right, rows aligned to the tips.
+
+    ``tree_fraction`` is the share of the width given to the tree column (the rest, minus ``gap`` and
+    ``pad``, holds the panel). ``footer`` reserves blank height below the rows (for a panel's colour
+    key). Rows are matched to tips by label and drawn in the tree's tip order. Needs ``cairosvg``."""
+    try:
+        import cairosvg
+    except ImportError as exc:                       # pragma: no cover
+        raise RuntimeError("genustrator.beside needs cairosvg (pip install genustrator[export]) "
+                           "to place the tree into the composite") from exc
+
+    n_tips = len(tree.tree.leaves)
+    # per-tip row height eases from ~44px (few tips) down to ~24px (many), so 25-40 rows stay sane
+    row_px = max(24.0, 46.0 - 0.55 * n_tips)
+    H = height if height is not None else max(260.0, 70.0 + row_px * n_tips) + footer
+    tree_w = round(width * tree_fraction)
+    tree_h = H - footer                              # tips fill the area above the footer
+
+    sized = tree.with_size(tree_w, tree_h)
+    geom = sized.geometry()
+    png = cairosvg.svg2png(bytestring=sized.as_svg().encode(),
+                           output_width=int(tree_w * 2), output_height=int(tree_h * 2))
+
+    canvas = Canvas(Style(width=width, height=H, margin=0, background=background), (0.0, 1.0), (0.0, 1.0))
+    canvas.embed_png(png, 0, 0, tree_w, tree_h)
+
+    # A panel that wants **every** tip row says so, and gets them all — including tips it has no
+    # value for. `Bars` does: its axis sits under the last row it is handed, and filtering the rows
+    # down to the ones it has values for put that axis under the last *valued* tip instead of under
+    # the tree, so a tree with extinct tips below the last bar drew its two axes at different heights.
+    wanted = set(panel.rows)
+    rows = [(t.name, t.y) for t in geom.tips
+            if getattr(panel, "all_rows", False) or t.name in wanted]
+    if rows:
+        panel.draw(canvas, tree_w + gap, width - pad, rows, canvas.style)
+    return Composite(canvas)
+
+
+def below(tree, panel, *, panel_height: float = 200.0, gap: float = 18.0, axis: str | None = "Time",
+          ticks: int = 5) -> Composite:
+    """Render Phylustrator ``tree`` with ``panel`` underneath, both on the tree's x axis.
+
+    The x-axis twin of :func:`beside`: a value at a node sits directly under that node (see
+    :func:`~phylustrator.trees.node_points`). The tree keeps its own style — width, height, margins —
+    and every node lands on the pixel it has in the tree alone. The page grows by ``gap`` plus
+    ``panel_height``, and the panel spans the tree's left and right pixel edges.
+
+    ``axis`` labels a time axis under the panel; ``None`` draws none. Leave ``time_axis`` off the
+    tree itself: anything a tree layer puts in its bottom margin (``time_axis``, ``scale_bar``, a
+    bottom-left ``colorbar``) lands in the panel. The panel's y axis sits in the tree's left margin,
+    so widen ``margin_left`` in the tree's ``Style`` for long tick labels or a y label.
+
+    Rectangular trees only, since that is the layout where x is time. The composite is drawn as
+    vectors on one canvas, so it needs no cairosvg (unlike :func:`beside`)."""
+    if tree.layout != "rectangular":
+        raise ValueError(f"below() needs a rectangular tree, where x is time; got layout={tree.layout!r}")
+    if not hasattr(panel, "draw_below"):
+        raise TypeError(f"below() takes a panel lined up with the tree's x axis, such as trees.node_points; "
+                        f"{type(panel).__name__} is not one (a row panel goes in beside())")
+    style = tree.style
+    ts, ls = style.font_size * 0.85, style.font_size
+    plot_bottom = style.height - style.margin_at("bottom")      # where the lowest tip sits in the tree alone
+    top = plot_bottom + gap
+    bottom = top + panel_height
+    # Under the panel: the tree's bottom margin, or more when the axis needs it. The axis label is
+    # centred 14 + ts + ls + 4 below the panel, so a 40px margin cut the label in half.
+    if axis is None:
+        axis_room = 0.0
+    elif axis:
+        axis_room = 14 + ts + ls + 4 + ls / 2 + 6
+    else:                                                       # ticks, no label
+        axis_room = 14 + ts + 3 + ts / 2 + 6
+    height = bottom + max(style.margin_at("bottom"), axis_room)
+    # The same tree on a taller page, with all the extra height given to its bottom margin: the
+    # nodes keep their pixels, and the panel is drawn into that margin on the same canvas.
+    sized = tree.with_style(replace(style, height=height, margin_bottom=height - plot_bottom))
+    geom = sized.geometry()
+    canvas = sized._build()
+    panel.draw_below(canvas, geom, top, bottom, style)
+    if axis is not None:
+        # +14 below the panel, the offset trees.time_axis leaves below a tree
+        draw_time_axis(canvas, geom.px, geom.xlim[1], bottom + 14, axis, ticks=ticks,
+                       tick_size=ts, label_size=ls)
+    return Composite(canvas)

{phylustrator-0.2.17 → phylustrator-0.3.0}/src/phylustrator/genomes/figure.py

@@ -173,14 +173,13 @@ class GridFigure(Figure):
     def _build(self) -> Canvas:
         from ..color import colormap, to_hex
 
-        m = self.style.margin
         canvas = Canvas(self.style, (0.0, 1.0), (0.0, 1.0))
         nrow, ncol = len(self.matrix.rows), len(self.matrix.cols)
         if not nrow or not ncol:
             return canvas
-        x0, y0 = m, m
-        w = self.style.width - 2 * m
-        h = self.style.height - 2 * m
+        x0, y0 = self.style.margin_at("left"), self.style.margin_at("top")
+        w = self.style.width - x0 - self.style.margin_at("right")
+        h = self.style.height - y0 - self.style.margin_at("bottom")
         cw, ch = w / ncol, h / nrow
 
         sample = colormap(self.cmap)

{phylustrator-0.2.17 → phylustrator-0.3.0}/src/phylustrator/genomes/layers/guides.py

@@ -25,9 +25,8 @@ def position_axis(label: str = "position", *, ticks: int = 6):
 
 def _linear(canvas, layout, style, label, ticks) -> None:
     _, height = canvas.size
-    m = style.margin
     x0, x1 = layout.xlim
-    y = height - m * 0.62
+    y = height - style.margin_at("bottom") * 0.62
     canvas.raw_line(canvas.px(x0), y, canvas.px(x1), y, "#333333", 1.2)
     small = style.font_size * 0.85
     for i in range(ticks):

{phylustrator-0.2.17 → phylustrator-0.3.0}/src/phylustrator/render.py

@@ -10,6 +10,7 @@ through cairosvg, falling back to ``.svg`` (with a note) when it is absent.
 from __future__ import annotations
 
 import math
+from collections.abc import Collection
 from pathlib import Path
 
 import drawsvg as draw
@@ -25,22 +26,29 @@ class Canvas:
                  *, equal_aspect: bool = False) -> None:
         self.style = style
         self.scale = None  # set by a colouring layer; read by colorbar()/legend()
+        # node names whose branch is dashed; set by the tree figure, read by a colouring layer
+        self.dashed: Collection[str] | None = None
         self._d = draw.Drawing(style.width, style.height, origin=(0, 0))
         if style.background:
             self._d.append(draw.Rectangle(0, 0, style.width, style.height, fill=style.background))
         self._x0, self._x1 = xlim
         self._y0, self._y1 = ylim
-        self._m = style.margin
-        self._top = style.margin + getattr(style, "headroom", 0.0)
+        self._left = style.margin_at("left")
+        self._right = style.margin_at("right")
+        self._bottom = style.margin_at("bottom")
+        self._top = style.margin_at("top") + getattr(style, "headroom", 0.0)
         # equal_aspect keeps circles round (radial/unrooted): one scale for x and y, centred.
         self._equal = None
         if equal_aspect:
             xspan = (self._x1 - self._x0) or 1.0
             yspan = (self._y1 - self._y0) or 1.0
-            s = min((style.width - 2 * self._m) / xspan,
-                    (style.height - self._m - self._top) / yspan)
-            self._equal = (s, style.width / 2 - s * (self._x0 + self._x1) / 2,
-                           style.height / 2 - s * (self._y0 + self._y1) / 2)
+            s = min((style.width - self._left - self._right) / xspan,
+                    (style.height - self._bottom - self._top) / yspan)
+            # centred between the margins; headroom shrinks the scale but does not shift the centre
+            cx = (self._left + style.width - self._right) / 2
+            cy = (style.margin_at("top") + style.height - self._bottom) / 2
+            self._equal = (s, cx - s * (self._x0 + self._x1) / 2,
+                           cy - s * (self._y0 + self._y1) / 2)
 
     # --- data-space (transformed through the layout extent) ---------------
 
@@ -49,14 +57,14 @@ class Canvas:
             s, ox, _ = self._equal
             return ox + s * x
         span = (self._x1 - self._x0) or 1.0
-        return self._m + (x - self._x0) / span * (self.style.width - 2 * self._m)
+        return self._left + (x - self._x0) / span * (self.style.width - self._left - self._right)
 
     def py(self, y: float) -> float:
         if self._equal:
             s, _, oy = self._equal
             return oy + s * y
         span = (self._y1 - self._y0) or 1.0
-        return self._top + (y - self._y0) / span * (self.style.height - self._m - self._top)
+        return self._top + (y - self._y0) / span * (self.style.height - self._bottom - self._top)
 
     def line(self, x1, y1, x2, y2, color: str, width: float, *, dash: bool = False) -> None:
         extra = {"stroke_dasharray": "5,4"} if dash else {}

{phylustrator-0.2.17 → phylustrator-0.3.0}/src/phylustrator/style.py

@@ -14,6 +14,13 @@ class Style:
     width: float = 800.0
     height: float = 600.0
     margin: float = 50.0
+    #: one side's margin, when it should differ from ``margin``; ``None`` takes ``margin``. A
+    #: composite reserves room on one side — a y axis on the left, a panel underneath — without
+    #: moving the other three. Read a side through :meth:`margin_at`, never the field itself.
+    margin_left: float | None = None
+    margin_right: float | None = None
+    margin_top: float | None = None
+    margin_bottom: float | None = None
     #: extra space above the plot, on top of ``margin``. A colorbar or legend is drawn inside
     #: the plotting area, so on a tree whose first branch reaches the top corner the two share
     #: a row; this pushes the tree down instead of moving the key somewhere worse.
@@ -34,3 +41,14 @@ class Style:
     font_size: float = 12.0
     label_color: str = "#222222"
     background: str | None = "white"
+
+    def margin_at(self, side: str) -> float:
+        """The margin on ``side`` (``"left"`` / ``"right"`` / ``"top"`` / ``"bottom"``): that side's
+        own value if set, else ``margin``.
+
+        Resolved on every read, not once in ``__post_init__``: ``replace(style, margin=10)`` copies
+        the side fields as they are, so a side filled in from the old ``margin`` would keep it."""
+        if side not in ("left", "right", "top", "bottom"):
+            raise ValueError(f"side must be 'left', 'right', 'top' or 'bottom', got {side!r}")
+        own = getattr(self, f"margin_{side}")
+        return self.margin if own is None else own

{phylustrator-0.2.17 → phylustrator-0.3.0}/src/phylustrator/trees/__init__.py

@@ -7,7 +7,7 @@
 
 from __future__ import annotations
 
-from .figure import Figure, Geometry, TipPos, plot
+from .figure import Figure, Geometry, NodePos, TipPos, plot
 from .io import dumps, loads, read, write
 from .layers import (
                      branch_events,
@@ -27,13 +27,15 @@ from .layers import (
                      tip_labels,
                      tip_track,
 )
+from .panels import NodePoints, node_points
 from .tree import Node, Tree
 
 __all__ = [
     "Node", "Tree", "read", "loads", "write", "dumps",
-    "plot", "Figure", "Geometry", "TipPos",
+    "plot", "Figure", "Geometry", "NodePos", "TipPos",
     "color_branches", "color_history", "color_lanes", "tip_labels", "node_labels", "tip_track", "ring",
     "rubberband",
     "branch_events", "colorbar", "legend", "note", "time_axis", "time_marker", "scale_bar",
     "highlight_clade",
+    "node_points", "NodePoints",
 ]

{phylustrator-0.2.17 → phylustrator-0.3.0}/src/phylustrator/trees/figure.py

@@ -12,7 +12,7 @@ contract, so new decorations never touch the figure.
 
 from __future__ import annotations
 
-from dataclasses import dataclass, replace
+from dataclasses import dataclass, field, replace
 from typing import Callable
 
 from ..render import Canvas
@@ -35,15 +35,39 @@ class TipPos:
     y: float
 
 
+@dataclass
+class NodePos:
+    """Where any node — a tip or an internal node — lands on the rendered page, in pixels."""
+
+    name: str
+    x: float
+    y: float
+    is_leaf: bool
+
+
 @dataclass
 class Geometry:
     """The rendered figure's pixel geometry — enough to align something else (a heatmap, an
     alignment) to the tree's tips without redrawing the tree. ``tips`` are in top-to-bottom order;
-    ``tip_x`` is the pixel x where the tips end (where a companion panel can begin)."""
+    ``tip_x`` is the pixel x where the tips end (where a companion panel can begin).
+
+    The x axis too: ``nodes`` holds every node, internal ones included, in preorder, and :meth:`px`
+    turns a layout x (a time, under the rectangular layout) into a pixel x. ``xlim`` is the layout's
+    x range and ``x_pixels`` its two ends on the page — where a panel under the tree starts and stops
+    (see :func:`~phylustrator.compose.below`)."""
 
     size: tuple[float, float]
     tips: list[TipPos]
     tip_x: float
+    nodes: list[NodePos] = field(default_factory=list)
+    xlim: tuple[float, float] = (0.0, 1.0)
+    x_pixels: tuple[float, float] = (0.0, 1.0)
+
+    def px(self, x: float) -> float:
+        """The pixel x of layout x ``x``. The canvas maps x linearly in every layout, so two points
+        fix it."""
+        (x0, x1), (p0, p1) = self.xlim, self.x_pixels
+        return p0 + (x - x0) / ((x1 - x0) or 1.0) * (p1 - p0)
 
 
 class Figure:
@@ -73,20 +97,26 @@ class Figure:
     def with_size(self, width: float, height: float) -> "Figure":
         """A copy of this figure rendered at a given pixel size (same tree, layers, style otherwise).
         Used to fit the tree into a column beside a companion panel."""
-        return Figure(self.tree, layout=self.layout, stem=self.stem,
-                      style=replace(self.style, width=width, height=height),
+        return self.with_style(replace(self.style, width=width, height=height))
+
+    def with_style(self, style: Style) -> "Figure":
+        """A copy of this figure drawn with ``style`` (same tree, layers and options otherwise)."""
+        return Figure(self.tree, layout=self.layout, stem=self.stem, style=style,
                       dashed=self.dashed, skeleton=self.skeleton, layers=self.layers)
 
     def geometry(self) -> Geometry:
-        """The pixel positions of the tips for this figure's current style — so a companion panel can
-        line its rows up with the tree without redrawing it."""
+        """The pixel positions of the tips and of every node for this figure's current style, and
+        the x-to-pixel mapping — so a companion panel can line up with the tree without redrawing it."""
         layout = _LAYOUTS[self.layout](self.tree, stem=self.stem)
         canvas = Canvas(self.style, layout.xlim, layout.ylim,
                         equal_aspect=(self.layout != "rectangular"))
         tips = [TipPos(leaf.name or "", canvas.px(layout.x(leaf)), canvas.py(layout.y(leaf)))
                 for leaf in self.tree.leaves]
         tip_x = max((t.x for t in tips), default=canvas.size[0])
-        return Geometry(canvas.size, tips, tip_x)
+        nodes = [NodePos(node.name or "", canvas.px(layout.x(node)), canvas.py(layout.y(node)), node.is_leaf)
+                 for node in self.tree.walk()]
+        x_pixels = (canvas.px(layout.xlim[0]), canvas.px(layout.xlim[1]))
+        return Geometry(canvas.size, tips, tip_x, nodes, layout.xlim, x_pixels)
 
     def _build(self) -> Canvas:
         layout = _LAYOUTS[self.layout](self.tree, stem=self.stem)

{phylustrator-0.2.17 → phylustrator-0.3.0}/src/phylustrator/trees/layers/events.py

@@ -116,15 +116,14 @@ def branch_events(events, *, styles: dict | None = None, size: float = 5.5,
 
 def _draw_legend(canvas, style, used, title, marker, loc, fsize) -> None:
     width, height = canvas.size
-    m = style.margin
     fs = fsize if fsize is not None else style.font_size
     ms = marker * (fs / style.font_size)                            # glyphs scale with the legend text
     row_h = fs * 1.7
     labels = ([title] if title else []) + list(used)
     box_w = ms * 2 + 14 + max(len(s) for s in labels) * fs * 0.62
     n_rows = len(used) + (1 if title else 0)
-    x = (m + ms + 6) if "left" in loc else (width - m - box_w)
-    y = (m * 0.6 + fs) if "top" in loc else (height - m - row_h * n_rows)
+    x = (style.margin_at("left") + ms + 6) if "left" in loc else (width - style.margin_at("right") - box_w)
+    y = (style.margin_at("top") * 0.6 + fs) if "top" in loc else (height - style.margin_at("bottom") - row_h * n_rows)
     if title:
         canvas.raw_text(x, y, title, anchor="start", weight="bold", size=fs)
         y += fs * 1.8

{phylustrator-0.2.17 → phylustrator-0.3.0}/src/phylustrator/trees/layers/guides.py

@@ -41,14 +41,15 @@ def colorbar(title: str = "", *, loc: str = "top-left", width: float = 130.0, he
         if not scale or scale.get("kind") != "continuous":
             return
         _, h = canvas.size
-        m = inset if inset is not None else style.margin
+        left, top, bottom = ((inset, inset, inset) if inset is not None else
+                             (style.margin_at("left"), style.margin_at("top"), style.margin_at("bottom")))
         fs = size if size is not None else style.font_size
-        x = m
+        x = left
         if "bottom" in loc:
-            y = h - m * 0.5 - height - fs * 0.9        # bar top, leaving room for the min/max labels
+            y = h - bottom * 0.5 - height - fs * 0.9   # bar top, leaving room for the min/max labels
             title_y = y - fs * 0.6 - 2
         else:
-            y, title_y = m + fs, m - 2
+            y, title_y = top + fs, top - 2
         lo, hi = labels if labels else (f"{scale['vmin']:.2f}", f"{scale['vmax']:.2f}")
         top = min(title_y - fs, y) if title else y
         bottom = y + height + fs * 1.1
@@ -78,10 +79,10 @@ def legend(title: str = "", *, swatch: float | None = None, size: float | None =
             if not scale or scale.get("kind") != "categorical":
                 return
             palette = scale["palette"]
-        m = inset if inset is not None else style.margin
         fs = size if size is not None else style.font_size
         sw = swatch if swatch is not None else fs * 0.95
-        x, y = m, m + dy
+        x = inset if inset is not None else style.margin_at("left")
+        y = (inset if inset is not None else style.margin_at("top")) + dy
         rows = len(palette) + (1 if title else 0)
         widest = max([_text_width(str(k), fs) for k in palette] +
                      [_text_width(title, fs) if title else 0.0])
@@ -127,10 +128,9 @@ def note(text: str, *, loc: str = "top-left", size: float | None = None,
 
     def layer(canvas, tree, layout, style):
         w, h = canvas.size
-        m = style.margin
         fs = size if size is not None else style.font_size
-        x = m if "left" in loc else w - m
-        y = (m * 0.6 + fs) if "top" in loc else (h - m * 0.5)
+        x = style.margin_at("left") if "left" in loc else w - style.margin_at("right")
+        y = (style.margin_at("top") * 0.6 + fs) if "top" in loc else (h - style.margin_at("bottom") * 0.5)
         y += dy
         anchor = "start" if "left" in loc else "end"
         canvas.raw_text(x, y, text, anchor=anchor, size=fs,
@@ -145,11 +145,10 @@ def scale_bar(length: float | None = None, label: str | None = None):
 
     def layer(canvas, tree, layout, style):
         width, height = canvas.size
-        m = style.margin
         span = layout.xlim[1] - layout.xlim[0]
         L = length if length is not None else _round_nice(span / 5 or 1.0)
         px_len = abs(canvas.px(L) - canvas.px(0.0))
-        x1, y = width - m, height - m * 0.5
+        x1, y = width - style.margin_at("right"), height - style.margin_at("bottom") * 0.5
         x0 = x1 - px_len
         canvas.raw_line(x0, y, x1, y, "#333333", 1.6)
         canvas.raw_text((x0 + x1) / 2, y - 8, label or f"{L:.2g}",
@@ -173,18 +172,23 @@ def _round_ticks(span: float, target: int) -> list[float]:
     """About ``target`` tick positions from 0 to at most ``span``, at multiples of a
     round step (1, 2, 2.5 or 5 times a power of ten). The last tick may stop short
     of the axis end; a round number short of the edge beats an exact ugly one."""
-    import math
     if span <= 0:
         return [0.0]
+    step = _round_step(span, target)
+    n = int(span / step + 1e-9)
+    return [round(i * step, 10) for i in range(n + 1)]
+
+
+def _round_step(span: float, target: int) -> float:
+    """The round step (1, 2, 2.5 or 5 times a power of ten) that cuts ``span`` into at most
+    ``target - 1`` intervals. ``span`` must be positive."""
+    import math
     raw = span / max(target - 1, 1)
-    mag = 10 ** math.floor(math.log10(raw))
-    step = 10 * mag
+    mag = 10.0 ** math.floor(math.log10(raw))
     for mult in (1, 2, 2.5, 5, 10):
         if span / (mult * mag) <= target - 1 + 1e-9:
-            step = mult * mag
-            break
-    n = int(span / step + 1e-9)
-    return [round(i * step, 10) for i in range(n + 1)]
+            return mult * mag
+    return 10 * mag
 
 
 def time_axis(label: str = "Time", *, ticks: int = 5, tick_size: float | None = None,
@@ -192,30 +196,37 @@ def time_axis(label: str = "Time", *, ticks: int = 5, tick_size: float | None =
     """A horizontal scale along the bottom, in the layout's distance units (0 at the origin).
     Rectangular only (distance maps to x); use ``scale_bar`` for radial/unrooted. ``tick_size`` /
     ``label_size`` set the tick-number and axis-label font sizes (default: the style's font size);
-    the vertical spacing follows the font, so give the figure enough bottom ``margin`` for big text.
+    the vertical spacing follows the font, so give the figure enough bottom margin for big text.
     ``bold`` sets the label weight (default: bold only when a ``label_size`` is given)."""
 
     def layer(canvas, tree, layout, style):
         if layout.kind != "rectangular":
             return
         _, height = canvas.size
-        m = style.margin
-        x0, x1 = 0.0, layout.xlim[1]
         ts = tick_size if tick_size is not None else style.font_size * 0.85
         ls = label_size if label_size is not None else style.font_size
-        y = height - m + 14  # just below the tree area, inside the bottom margin
-        canvas.raw_line(canvas.px(x0), y, canvas.px(x1), y, "#333333", 1.2)
-        # ticks at round numbers (a 1 / 2 / 2.5 / 5 step), not at even fractions of the
-        # height: dividing a height of 3.96 into quarters gave "0, 0.99, 2, 3, 4",
-        # where the "2" was really 1.98 — ugly and, worse, slightly wrong
-        for t in _round_ticks(x1 - x0, ticks):
-            tx = canvas.px(x0 + t)
-            canvas.raw_line(tx, y, tx, y + 5, "#333333", 1.2)
-            canvas.raw_text(tx, y + ts + 3, f"{t:g}", anchor="middle", size=ts)
-        if label:
-            mid = (canvas.px(x0) + canvas.px(x1)) / 2
-            is_bold = (label_size is not None) if bold is None else bold
-            weight = "bold" if is_bold else "normal"
-            canvas.raw_text(mid, y + ts + ls + 4, label, anchor="middle", size=ls, weight=weight)
+        is_bold = (label_size is not None) if bold is None else bold
+        y = height - style.margin_at("bottom") + 14  # just below the tree area, inside the bottom margin
+        draw_time_axis(canvas, canvas.px, layout.xlim[1], y, label, ticks=ticks, tick_size=ts,
+                       label_size=ls, weight="bold" if is_bold else "normal")
 
     return layer
+
+
+def draw_time_axis(canvas, px, x_end: float, y: float, label: str | None, *, ticks: int = 5,
+                   tick_size: float, label_size: float, weight: str = "normal") -> None:
+    """Draw a time axis from 0 to ``x_end`` at pixel height ``y``, with ``px`` mapping a time to a
+    pixel x. Shared by :func:`time_axis` and :func:`~phylustrator.compose.below`, so an axis under a
+    panel is the same axis a tree draws under itself."""
+    canvas.raw_line(px(0.0), y, px(x_end), y, "#333333", 1.2)
+    # ticks at round numbers (a 1 / 2 / 2.5 / 5 step), not at even fractions of the
+    # height: dividing a height of 3.96 into quarters gave "0, 0.99, 2, 3, 4",
+    # where the "2" was really 1.98 — ugly and, worse, slightly wrong
+    for t in _round_ticks(x_end, ticks):
+        tx = px(t)
+        canvas.raw_line(tx, y, tx, y + 5, "#333333", 1.2)
+        canvas.raw_text(tx, y + tick_size + 3, f"{t:g}", anchor="middle", size=tick_size)
+    if label:
+        mid = (px(0.0) + px(x_end)) / 2
+        canvas.raw_text(mid, y + tick_size + label_size + 4, label, anchor="middle", size=label_size,
+                        weight=weight)

phylustrator-0.3.0/src/phylustrator/trees/panels.py

@@ -0,0 +1,109 @@
+"""Panels that line up with a tree's **x** axis, drawn under a rectangular tree by
+:func:`~phylustrator.compose.below`.
+
+A row panel (``genomes.heatmap``, ``genomes.bars``) is handed one pixel ``y`` per tip and sits beside
+the tree. These go the other way: a panel is handed the tree's :class:`~phylustrator.trees.Geometry`
+and a pixel band ``[top, bottom]``, and places each value at its node's pixel x — so a quantity
+measured at a node sits directly under that node.
+"""
+
+from __future__ import annotations
+
+import math
+
+from .layers.guides import _round_step, _text_width
+
+
+class NodePoints:
+    """One point per named node, at the node's x and at a height set by its value.
+
+    ``values`` is ``{node name: number}``. Internal nodes count, so they need names (a ZOMBI2 tree
+    names every node). A name the tree does not have raises an error rather than dropping the point:
+    a typo would otherwise read as a missing measurement.
+
+    ``colors`` tints points per node, else the flat ``color``. ``line`` joins the points left to
+    right. ``zero`` draws a light line at 0 when the range crosses it — the reference a difference is
+    read against. ``vmin`` / ``vmax`` fix the y range; by default it is the values' range, widened
+    to round numbers. ``label`` names the y axis.
+    """
+
+    def __init__(self, values: dict, *, color: str = "#3a6ea5", colors: dict | None = None,
+                 shape: str = "circle", size: float = 4.5, line: bool = False,
+                 line_color: str | None = None, zero: bool = True, vmin: float | None = None,
+                 vmax: float | None = None, label: str = "", ticks: int = 5) -> None:
+        if not values:
+            raise ValueError("node_points() needs at least one value")
+        self.values = {str(k): float(v) for k, v in values.items()}
+        self.color = color
+        self.colors = {str(k): v for k, v in colors.items()} if colors else {}
+        self.shape = shape
+        self.size = size
+        self.line = line
+        self.line_color = line_color
+        self.zero = zero
+        self.vmin = vmin
+        self.vmax = vmax
+        self.label = label
+        self.ticks = ticks
+
+    def _range(self) -> tuple[float, float, float]:
+        """The y range and its tick step. An end the caller did not fix is pushed out to the next
+        round tick, so the axis starts and stops on a labelled number."""
+        lo = min(self.values.values()) if self.vmin is None else self.vmin
+        hi = max(self.values.values()) if self.vmax is None else self.vmax
+        if hi <= lo:                              # one value, or all equal: give it a band to sit in
+            lo, hi = lo - 1.0, hi + 1.0
+        step = _round_step(hi - lo, self.ticks)
+        if self.vmin is None:
+            lo = math.floor(lo / step + 1e-9) * step
+        if self.vmax is None:
+            hi = math.ceil(hi / step - 1e-9) * step
+        return lo, hi, step
+
+    def draw_below(self, canvas, geometry, top: float, bottom: float, style) -> None:
+        at: dict[str, float] = {}
+        for node in geometry.nodes:
+            if node.name:
+                at.setdefault(node.name, node.x)          # the first in preorder, as Tree.find
+        missing = sorted(set(self.values) - set(at))
+        if missing:
+            shown = ", ".join(missing[:5]) + (", …" if len(missing) > 5 else "")
+            raise ValueError(f"node_points: {len(missing)} name(s) not in the tree: {shown}")
+
+        lo, hi, step = self._range()
+
+        def py(v: float) -> float:
+            return bottom - (v - lo) / (hi - lo) * (bottom - top)
+
+        x0, x1 = geometry.x_pixels
+        ts, ls = style.font_size * 0.85, style.font_size
+        # the y axis stands a little left of time 0, so a point at the crown is not drawn on it
+        ax = x0 - 10
+        canvas.raw_line(ax, top, ax, bottom, "#333333", 1.2)
+        widest = 0.0
+        k = math.ceil(lo / step - 1e-9)
+        while k * step <= hi + step * 1e-9:
+            v = round(k * step, 10) + 0.0                 # + 0.0 turns a -0.0 into 0
+            text = f"{v:g}"
+            canvas.raw_line(ax - 5, py(v), ax, py(v), "#333333", 1.2)
+            canvas.raw_text(ax - 8, py(v), text, anchor="end", size=ts)
+            widest = max(widest, _text_width(text, ts))
+            k += 1
+        if self.label:
+            canvas.raw_text(ax - 8 - widest - ls * 0.8, (top + bottom) / 2, self.label,
+                            anchor="middle", size=ls, rotate=-90)
+        if self.zero and lo < 0.0 < hi:
+            canvas.raw_line(x0, py(0.0), x1, py(0.0), "#b8bec3", 1.0)
+
+        points = sorted((at[name], py(v), name) for name, v in self.values.items())
+        if self.line:
+            for (xa, ya, _), (xb, yb, _) in zip(points, points[1:]):
+                canvas.raw_line(xa, ya, xb, yb, self.line_color or self.color, 1.4)
+        for x, y, name in points:
+            canvas.raw_marker(x, y, self.shape, self.colors.get(name, self.color), self.size)
+
+
+def node_points(values: dict, **kw) -> NodePoints:
+    """A panel under a tree: one point per named node, placed at the node's time. Pass it to
+    :func:`~phylustrator.compose.below`; see :class:`NodePoints` for the options."""
+    return NodePoints(values, **kw)

{phylustrator-0.2.17 → phylustrator-0.3.0/src/phylustrator.egg-info}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: phylustrator
-Version: 0.2.17
+Version: 0.3.0
 Summary: A composable plotter for evolutionary figures: phylogenetic trees, genomes, synteny and alignments
 Author-email: "Adrian A. Davin" <aaredav@gmail.com>
 License: MIT
@@ -75,6 +75,8 @@ That is the whole idea: `plot(tree)` starts a figure and each `+ layer` adds one
 - **Layers** — `color_branches`, `color_history`, `tip_labels`, `node_labels`, `tip_track`,
   `branch_events`, `colorbar`, `legend`, `time_axis`, `time_marker`, `scale_bar`, `note`,
   `highlight_clade`.
+- **Panels** — `node_points`, placed under a rectangular tree with `ph.below(tree, panel)`. The panel
+  shares the tree's time axis, so a value measured at a node sits directly under that node.
 
 ## Genomes
 

{phylustrator-0.2.17 → phylustrator-0.3.0}/src/phylustrator.egg-info/SOURCES.txt

@@ -32,6 +32,7 @@ src/phylustrator/trees/__init__.py
 src/phylustrator/trees/figure.py
 src/phylustrator/trees/io.py
 src/phylustrator/trees/layout.py
+src/phylustrator/trees/panels.py
 src/phylustrator/trees/skeleton.py
 src/phylustrator/trees/tree.py
 src/phylustrator/trees/layers/__init__.py
@@ -41,6 +42,7 @@ src/phylustrator/trees/layers/events.py
 src/phylustrator/trees/layers/guides.py
 src/phylustrator/trees/layers/labels.py
 src/phylustrator/trees/layers/tracks.py
+tests/test_below.py
 tests/test_cli.py
 tests/test_figure.py
 tests/test_genomes.py

phylustrator-0.3.0/tests/test_below.py

@@ -0,0 +1,137 @@
+"""A panel under a rectangular tree, on the tree's time axis: ``below``, ``node_points``, the node
+positions in ``Figure.geometry`` and the per-side margins that make room for them (issue #7)."""
+
+import re
+from dataclasses import replace
+
+import pytest
+
+from phylustrator import Style, below
+from phylustrator.genomes import bars
+from phylustrator.trees import loads, node_points, plot, tip_labels
+
+# R's stem is 0.5, so under the default stem-aware layout: R 0.5, E 1.5, H 2.0, C 2.5, A 3.5
+NEWICK = "(((A:1,B:1)C:1,D:2)E:1,(F:1.5,G:1.5)H:1.5)R:0.5;"
+
+
+def _circles(svg):
+    return [(float(x), float(y)) for x, y in re.findall(r'<circle cx="([-\d.]+)" cy="([-\d.]+)"', svg)]
+
+
+def _texts(svg):
+    return re.findall(r"<text [^>]*>([^<]*)</text>", svg)
+
+
+# --- geometry -------------------------------------------------------------------------------------
+
+def test_geometry_lists_every_node_and_maps_time_to_pixels():
+    geom = plot(loads(NEWICK)).geometry()
+    by_name = {n.name: n for n in geom.nodes}
+    assert len(geom.nodes) == 9
+    assert {n.name for n in geom.nodes if not n.is_leaf} == {"R", "E", "C", "H"}
+    for tip in geom.tips:                                   # a tip is the same point either way
+        assert (by_name[tip.name].x, by_name[tip.name].y) == pytest.approx((tip.x, tip.y))
+    assert geom.px(2.5) == pytest.approx(by_name["C"].x)
+    assert geom.px(geom.xlim[1]) == pytest.approx(by_name["A"].x)
+    assert geom.x_pixels[0] == pytest.approx(50.0)          # time 0 sits on the left margin
+
+
+# --- margins --------------------------------------------------------------------------------------
+
+def test_side_margins_default_to_margin():
+    tree = loads(NEWICK)
+    sides = dict(margin_left=30, margin_right=30, margin_top=30, margin_bottom=30)
+    assert (plot(tree, style=Style(margin=30)).as_svg()
+            == plot(tree, style=Style(margin=30, **sides)).as_svg())
+
+
+def test_a_side_left_unset_follows_margin_after_replace():
+    """Resolving the sides once, at construction, would freeze them at the old ``margin``."""
+    style = replace(Style(margin=50, margin_left=90), margin=10)
+    assert style.margin_at("left") == 90
+    assert style.margin_at("bottom") == 10
+    with pytest.raises(ValueError):
+        style.margin_at("middle")
+
+
+def test_one_side_margin_moves_only_that_side():
+    tree = loads(NEWICK)
+    base = Style(width=400, height=300, margin=20)
+    plain = plot(tree, style=base).geometry()
+    wide = plot(tree, style=replace(base, margin_left=80)).geometry()
+    assert wide.x_pixels[0] == pytest.approx(80.0)
+    assert wide.x_pixels[1] == pytest.approx(plain.x_pixels[1])
+    assert [t.y for t in wide.tips] == pytest.approx([t.y for t in plain.tips])
+
+
+# --- below ----------------------------------------------------------------------------------------
+
+def test_below_puts_each_point_under_its_node():
+    """The point of the issue: a value measured at a node is drawn at that node's pixel x."""
+    fig = plot(loads(NEWICK), style=Style(margin_left=70)) + tip_labels()
+    values = {"R": -1.0, "E": 2.0, "H": 3.0, "C": 0.5, "A": 1.0}
+    svg = below(fig, node_points(values), axis=None).as_svg()
+    geom = fig.geometry()
+    x_of = {n.name: n.x for n in geom.nodes}
+    circles = sorted(_circles(svg))
+    assert [x for x, _ in circles] == pytest.approx(sorted(x_of[name] for name in values))
+    lowest_tip = max(t.y for t in geom.tips)
+    assert all(y > lowest_tip for _, y in circles)
+    # higher value, higher on the page: sorted by x the nodes are R, E, H, C, A
+    ys = dict(zip(["R", "E", "H", "C", "A"], (y for _, y in circles)))
+    assert ys["H"] < ys["E"] < ys["A"] < ys["C"] < ys["R"]
+
+
+def test_below_leaves_the_tree_where_it_was():
+    fig = plot(loads(NEWICK)) + tip_labels()
+    alone = fig.as_svg()
+    composite = below(fig, node_points({"C": 1.0})).as_svg()
+    branches = re.findall(r"<path [^>]*/>", alone)
+    labels = re.findall(r"<text [^>]*>[^<]*</text>", alone)
+    assert branches and labels
+    assert all(element in composite for element in branches + labels)
+
+
+def test_below_draws_the_time_axis_under_the_panel_and_on_the_page():
+    """A small bottom margin once cut the axis label in half at the page edge."""
+    fig = plot(loads(NEWICK), style=Style(margin=20))
+    svg = below(fig, node_points({"C": 1.0, "H": 2.0}), axis="Time (My)").as_svg()
+    assert "Time (My)" in _texts(svg)
+    axis_y = float(re.search(r'<text x="[\d.]+" y="([\d.]+)"[^>]*>Time \(My\)</text>', svg).group(1))
+    page_height = float(re.search(r'<svg [^>]*height="([\d.]+)"', svg).group(1))
+    assert all(axis_y > y for _, y in _circles(svg))
+    assert axis_y + fig.style.font_size / 2 < page_height
+    assert "Time (My)" not in below(fig, node_points({"C": 1.0}), axis=None).as_svg()
+
+
+def test_below_refuses_a_tree_without_a_time_axis_and_a_row_panel():
+    tree = loads(NEWICK)
+    with pytest.raises(ValueError, match="rectangular"):
+        below(plot(tree, layout="radial"), node_points({"C": 1.0}))
+    with pytest.raises(TypeError, match="beside"):
+        below(plot(tree), bars({"A": 1.0}))
+
+
+# --- node_points ----------------------------------------------------------------------------------
+
+def test_node_points_names_the_nodes_it_cannot_find():
+    with pytest.raises(ValueError, match="Cx"):
+        below(plot(loads(NEWICK)), node_points({"Cx": 1.0, "C": 2.0}))
+
+
+def test_node_points_ticks_stop_on_round_numbers():
+    svg = below(plot(loads(NEWICK)), node_points({"C": -1.3, "H": 2.7}), axis=None).as_svg()
+    assert {"-2", "-1", "0", "1", "2", "3"} <= set(_texts(svg))
+
+
+def test_node_points_zero_line_only_when_the_range_crosses_zero():
+    tree = plot(loads(NEWICK))
+    assert "#b8bec3" in below(tree, node_points({"C": -1.0, "H": 2.0})).as_svg()
+    assert "#b8bec3" not in below(tree, node_points({"C": 1.0, "H": 2.0})).as_svg()
+    assert "#b8bec3" not in below(tree, node_points({"C": -1.0, "H": 2.0}, zero=False)).as_svg()
+
+
+def test_node_points_line_joins_the_points_left_to_right():
+    values = {"R": 0.0, "E": 1.0, "H": 3.0, "C": 2.0}
+    svg = below(plot(loads(NEWICK)), node_points(values, line=True, line_color="#123456")).as_svg()
+    assert svg.count('stroke="#123456"') == 3

phylustrator-0.2.17/src/phylustrator/compose.py

@@ -1,66 +0,0 @@
-"""Composition — put a Genustrator panel beside a Phylustrator tree, rows lined up with the tips.
-
-``beside(tree, panel)`` takes a **Phylustrator** figure (the phylogeny — Phylustrator draws it, we do
-not redraw it) and a panel (``heatmap`` / ``alignment``). It asks the tree for its tip pixel positions
-(``Figure.geometry``), renders the tree into the left column, and draws the panel to the right with
-each row at its tip's ``y`` — so a genome's row sits exactly on its leaf.
-"""
-
-from __future__ import annotations
-
-from .render import Canvas
-from .style import Style
-
-
-class Composite:
-    """The rendered composite; save like any figure."""
-
-    def __init__(self, canvas: Canvas) -> None:
-        self._canvas = canvas
-
-    def as_svg(self) -> str:
-        return self._canvas.as_svg()
-
-    def save(self, path):
-        return self._canvas.save(path)
-
-
-def beside(tree, panel, *, width: float = 1100.0, height: float | None = None,
-           tree_fraction: float = 0.4, gap: float = 18.0, pad: float = 34.0,
-           footer: float = 0.0, background: str = "white") -> Composite:
-    """Render Phylustrator ``tree`` on the left and ``panel`` on the right, rows aligned to the tips.
-
-    ``tree_fraction`` is the share of the width given to the tree column (the rest, minus ``gap`` and
-    ``pad``, holds the panel). ``footer`` reserves blank height below the rows (for a panel's colour
-    key). Rows are matched to tips by label and drawn in the tree's tip order. Needs ``cairosvg``."""
-    try:
-        import cairosvg
-    except ImportError as exc:                       # pragma: no cover
-        raise RuntimeError("genustrator.beside needs cairosvg (pip install genustrator[export]) "
-                           "to place the tree into the composite") from exc
-
-    n_tips = len(tree.tree.leaves)
-    # per-tip row height eases from ~44px (few tips) down to ~24px (many), so 25-40 rows stay sane
-    row_px = max(24.0, 46.0 - 0.55 * n_tips)
-    H = height if height is not None else max(260.0, 70.0 + row_px * n_tips) + footer
-    tree_w = round(width * tree_fraction)
-    tree_h = H - footer                              # tips fill the area above the footer
-
-    sized = tree.with_size(tree_w, tree_h)
-    geom = sized.geometry()
-    png = cairosvg.svg2png(bytestring=sized.as_svg().encode(),
-                           output_width=int(tree_w * 2), output_height=int(tree_h * 2))
-
-    canvas = Canvas(Style(width=width, height=H, margin=0, background=background), (0.0, 1.0), (0.0, 1.0))
-    canvas.embed_png(png, 0, 0, tree_w, tree_h)
-
-    # A panel that wants **every** tip row says so, and gets them all — including tips it has no
-    # value for. `Bars` does: its axis sits under the last row it is handed, and filtering the rows
-    # down to the ones it has values for put that axis under the last *valued* tip instead of under
-    # the tree, so a tree with extinct tips below the last bar drew its two axes at different heights.
-    wanted = set(panel.rows)
-    rows = [(t.name, t.y) for t in geom.tips
-            if getattr(panel, "all_rows", False) or t.name in wanted]
-    if rows:
-        panel.draw(canvas, tree_w + gap, width - pad, rows, canvas.style)
-    return Composite(canvas)