phylustrator 0.3.0__tar.gz → 0.4.0__tar.gz

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

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: phylustrator
-Version: 0.3.0
+Version: 0.4.0
 Summary: A composable plotter for evolutionary figures: phylogenetic trees, genomes, synteny and alignments
 Author-email: "Adrian A. Davin" <aaredav@gmail.com>
 License: MIT
@@ -74,7 +74,7 @@ That is the whole idea: `plot(tree)` starts a figure and each `+ layer` adds one
 - **Layouts** — `rectangular` (default), `radial`, `unrooted`.
 - **Layers** — `color_branches`, `color_history`, `tip_labels`, `node_labels`, `tip_track`,
   `branch_events`, `colorbar`, `legend`, `time_axis`, `time_marker`, `scale_bar`, `note`,
-  `highlight_clade`.
+  `title`, `highlight_clade`. `legend` and `note` take a corner; `title` is centred over the panel.
 - **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.
 

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

@@ -35,7 +35,7 @@ That is the whole idea: `plot(tree)` starts a figure and each `+ layer` adds one
 - **Layouts** — `rectangular` (default), `radial`, `unrooted`.
 - **Layers** — `color_branches`, `color_history`, `tip_labels`, `node_labels`, `tip_track`,
   `branch_events`, `colorbar`, `legend`, `time_axis`, `time_marker`, `scale_bar`, `note`,
-  `highlight_clade`.
+  `title`, `highlight_clade`. `legend` and `note` take a corner; `title` is centred over the panel.
 - **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.
 

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

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

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

@@ -26,6 +26,7 @@ from .layers import (
                      time_marker,
                      tip_labels,
                      tip_track,
+                     title,
 )
 from .panels import NodePoints, node_points
 from .tree import Node, Tree
@@ -35,7 +36,7 @@ __all__ = [
     "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",
+    "branch_events", "colorbar", "legend", "note", "time_axis", "time_marker", "scale_bar", "title",
     "highlight_clade",
     "node_points", "NodePoints",
 ]

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

@@ -8,7 +8,7 @@ Each layer is a callable ``(canvas, tree, layout, style) -> None``. Import them
 from .clades import highlight_clade
 from .coloring import color_branches, color_history, color_lanes
 from .events import branch_events
-from .guides import colorbar, legend, note, scale_bar, time_axis, time_marker
+from .guides import colorbar, legend, note, scale_bar, time_axis, time_marker, title
 from .labels import node_labels, tip_labels
 from .tracks import ring, rubberband, tip_track
 
@@ -28,5 +28,6 @@ __all__ = [
     "time_axis",
     "time_marker",
     "scale_bar",
+    "title",
     "highlight_clade",
 ]

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

@@ -18,6 +18,20 @@ def _clear_behind(canvas, x, y, w, h, pad: float = 6.0) -> None:
                     fill=_KEY_BACKDROP, stroke="none", stroke_width=0.0)
 
 
+#: The corners a pinned layer may sit in — the four ``branch_events`` has always taken.
+_CORNERS = ("top-left", "top-right", "bottom-left", "bottom-right")
+
+
+def _corner(loc: str, who: str) -> str:
+    """Check a corner name at the point it is written. ``"top-centre"`` used to fall through the
+    ``"left" in loc`` test and print as though it had been asked for on the right, which is worse
+    than an error."""
+    if loc not in _CORNERS:
+        centred = " (a centred title is `title()`)" if "cent" in loc.lower() else ""
+        raise ValueError(f"{who}: loc must be one of {', '.join(_CORNERS)}, not {loc!r}{centred}")
+    return loc
+
+
 def _text_width(text: str, size: float) -> float:
     """A serviceable width for a string at this font size — the canvas has no font metrics, and this
     only has to be close enough to clear the tree behind it."""
@@ -64,13 +78,20 @@ def colorbar(title: str = "", *, loc: str = "top-left", width: float = 130.0, he
     return layer
 
 
-def legend(title: str = "", *, swatch: float | None = None, size: float | None = None,
-           entries: dict | None = None, dy: float = 0.0, inset: float | None = None):
-    """A category swatch list, top-left. ``size`` sets the label font (default the style's) and the
-    swatch scales with it. Reads the recorded categorical scale, or ``entries``
-    (``{label: colour}``) to draw an explicit list — a figure whose scale slot is taken by a
-    continuous ring still gets its categorical legend that way. ``dy`` shifts the list down, so it
-    can sit below a ``colorbar`` on the same corner. No-op without a source of entries."""
+def legend(title: str = "", *, loc: str = "top-left", swatch: float | None = None,
+           size: float | None = None, entries: dict | None = None, dy: float = 0.0,
+           inset: float | None = None):
+    """A category swatch list pinned to a corner — ``"top-left"`` by default, or any of the four
+    ``branch_events`` takes. A rectangular tree fills the upper left of its panel, so the top left
+    is often the one corner a legend cannot share; a right corner right-aligns the block on the
+    right margin, and a bottom corner ends it on the bottom margin.
+
+    ``size`` sets the label font (default the style's) and the swatch scales with it. Reads the
+    recorded categorical scale, or ``entries`` (``{label: colour}``) to draw an explicit list — a
+    figure whose scale slot is taken by a continuous ring still gets its categorical legend that
+    way. ``dy`` shifts the list down, so it can sit below a ``colorbar`` in the same corner. No-op
+    without a source of entries."""
+    _corner(loc, "legend")
 
     def layer(canvas, tree, layout, style):
         palette = entries
@@ -79,14 +100,22 @@ def legend(title: str = "", *, swatch: float | None = None, size: float | None =
             if not scale or scale.get("kind") != "categorical":
                 return
             palette = scale["palette"]
+        w, h = canvas.size
         fs = size if size is not None else style.font_size
         sw = swatch if swatch is not None else fs * 0.95
-        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])
-        _clear_behind(canvas, x, y - fs, sw + 8 + widest, rows * fs * 1.65)
+        box_w = sw + 8 + widest
+
+        def side(name):
+            return inset if inset is not None else style.margin_at(name)
+
+        # the drop from the first row's baseline to the last one's; a title row is the taller one
+        drop = (fs * 1.7 if title else 0.0) + max(len(palette) - 1, 0) * fs * 1.6
+        x = side("left") if "left" in loc else w - side("right") - box_w
+        y = (side("top") if "top" in loc else h - side("bottom") - drop - fs * 0.5) + dy
+        _clear_behind(canvas, x, y - fs, box_w, rows * fs * 1.65)
         if title:
             canvas.raw_text(x, y, title, anchor="start", weight="bold", size=fs)
             y += fs * 1.7
@@ -100,15 +129,35 @@ def legend(title: str = "", *, swatch: float | None = None, size: float | None =
 
 def time_marker(*times, color: str = "#444444", width: float = 1.5, dash: bool = True,
                 label: str | None = None, label_size: float | None = None):
-    """Vertical reference line(s) crossing the tree at the given distance/time value(s) — e.g. to mark
-    a mass-extinction moment or a rate shift. Rectangular only (distance maps to x). ``label`` (if
-    given) is written above the first line."""
+    """Reference marker(s) at the given distance/time value(s) — e.g. a mass-extinction moment or a
+    rate shift. Rectangular: a vertical line crossing the tree. Radial: a circle at that distance
+    from the centre, which is what a depth threshold looks like on a tree too big to read as a
+    rectangle. The unrooted layout places branches by angle and has no distance-from-origin axis, so
+    it raises rather than drawing nothing. ``label`` (if given) is written above the first marker.
+
+    Times come on the stem-inclusive scale of the rectangular layout, the same scale
+    ``branch_events`` takes. The radial layout starts at the crown, so the stem comes off there."""
 
     def layer(canvas, tree, layout, style):
-        if layout.kind != "rectangular":
+        ls = label_size if label_size is not None else style.font_size
+        if layout.kind == "unrooted":
+            raise ValueError("time_marker needs a layout with a distance axis, and the unrooted "
+                             "layout has none: it places branches by angle, so a distance from the "
+                             "origin is not a place on it. Use rectangular or radial.")
+        if layout.kind == "radial":
+            # the radial layout drops the stem and starts at the crown, so shift the times by it —
+            # branch_events shifts the same way, for the same reason
+            stem = float(tree.root.length or 0.0)
+            for i, t in enumerate(times):
+                r = t - stem
+                if r < 0:
+                    raise ValueError(f"time_marker at {t:g} falls inside the root stem, which the "
+                                     f"radial layout does not draw: its centre is the crown, at {stem:g}")
+                canvas.data_ring(r, color, width, dash=dash)
+                if label and i == 0:
+                    canvas.text(0.0, -r, label, dy=-8, anchor="middle", color=color, size=ls)
             return
         y0, y1 = layout.ylim
-        ls = label_size if label_size is not None else style.font_size
         for i, t in enumerate(times):
             canvas.line(t, y0, t, y1, color, width, dash=dash)
             if label and i == 0:
@@ -124,7 +173,8 @@ def note(text: str, *, loc: str = "top-left", size: float | None = None,
 
     ``dy`` nudges it in pixels, negative up. The corner is fixed to the margin, which is the right
     place for a note *about* the figure; a note read as a **title** wants a little more air between
-    it and the tree than a margin the tree also uses can give."""
+    it and the tree than a margin the tree also uses can give, so a centred title is :func:`title`."""
+    _corner(loc, "note")
 
     def layer(canvas, tree, layout, style):
         w, h = canvas.size
@@ -139,6 +189,26 @@ def note(text: str, *, loc: str = "top-left", size: float | None = None,
     return layer
 
 
+def title(text: str, *, size: float | None = None, dy: float = 0.0, color: str | None = None,
+          weight: str = "bold"):
+    """A title centred over the panel, in the top margin above the tree.
+
+    ``note`` pins text to a corner, which is where something *about* a figure belongs; a title
+    belongs over the middle of it. ``size`` defaults to half again the style's font, ``dy`` nudges
+    it in pixels (negative up), and the title stays on the page even on a thin top margin. Give the
+    figure a larger ``margin_top`` when the title sits too close to the tree."""
+
+    def layer(canvas, tree, layout, style):
+        w, _ = canvas.size
+        fs = size if size is not None else style.font_size * 1.4
+        # halfway up the top margin, but never so high that the page edge cuts it
+        y = max(style.margin_at("top") * 0.5, fs * 0.75) + dy
+        canvas.raw_text(w / 2, y, text, anchor="middle", size=fs,
+                        color=color or style.label_color, weight=weight)
+
+    return layer
+
+
 def scale_bar(length: float | None = None, label: str | None = None):
     """A short bar of a fixed distance, bottom-right — the branch-length key for any layout. Defaults
     to a round fraction of the tree's extent. Returns a layer."""

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

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: phylustrator
-Version: 0.3.0
+Version: 0.4.0
 Summary: A composable plotter for evolutionary figures: phylogenetic trees, genomes, synteny and alignments
 Author-email: "Adrian A. Davin" <aaredav@gmail.com>
 License: MIT
@@ -74,7 +74,7 @@ That is the whole idea: `plot(tree)` starts a figure and each `+ layer` adds one
 - **Layouts** — `rectangular` (default), `radial`, `unrooted`.
 - **Layers** — `color_branches`, `color_history`, `tip_labels`, `node_labels`, `tip_track`,
   `branch_events`, `colorbar`, `legend`, `time_axis`, `time_marker`, `scale_bar`, `note`,
-  `highlight_clade`.
+  `title`, `highlight_clade`. `legend` and `note` take a corner; `title` is centred over the panel.
 - **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.
 

{phylustrator-0.3.0 → phylustrator-0.4.0}/tests/test_figure.py

@@ -1,9 +1,11 @@
 """Figure: the skeleton renders to SVG, and the stem shows up as one extra branch."""
 
+import math
 import re
 
 import pytest
 
+from phylustrator import Style
 from phylustrator.trees import (
     branch_events,
     color_branches,
@@ -15,6 +17,8 @@ from phylustrator.trees import (
     note,
     plot,
     rubberband,
+    time_marker,
+    title,
 )
 
 
@@ -231,3 +235,147 @@ def test_rubberband_survives_a_lopsided_tree_and_stays_smooth():
                + rubberband(pops, palette=palette, gap=8.0, smooth=smooth)).as_svg()
         assert svg.count("<path") > 0
         assert "#207080" in svg and "#c77bad" in svg
+
+
+# --- time_marker across the layouts (issue #8) ------------------------------------------------
+
+_MARKER_TREE = "((((A:1,B:1)F:1,C:2)G:1,D:3)H:1,E:4)R;"
+
+
+def _circle(svg):
+    """The (cx, cy, r) of the one circle in the figure — the radial marker."""
+    found = re.findall(r'<circle cx="([-\d.]+)" cy="([-\d.]+)" r="([-\d.]+)"', svg)
+    assert len(found) == 1, f"expected one circle, found {len(found)}"
+    return tuple(float(v) for v in found[0])
+
+
+def test_time_marker_draws_in_rectangular_and_radial():
+    """It rendered nothing at all in radial, and said nothing about it."""
+    tree = loads(_MARKER_TREE)
+    for layout in ("rectangular", "radial"):
+        svg = (plot(tree, layout=layout) + time_marker(2.0, color="#D55E00", width=4)).as_svg()
+        assert "#D55E00" in svg, f"the marker is missing from the {layout} layout"
+
+
+def test_the_radial_marker_is_a_circle_through_the_nodes_at_that_distance():
+    tree = loads(_MARKER_TREE)
+    fig = plot(tree, layout="radial") + time_marker(2.0, color="#D55E00")
+    cx, cy, r = _circle(fig.as_svg())
+    at_two = [n for n in fig.geometry().nodes if n.name == "G"][0]      # G sits at distance 2
+    assert math.hypot(at_two.x - cx, at_two.y - cy) == pytest.approx(r)
+    assert r > 0
+
+
+def test_the_radial_marker_takes_the_stem_off_the_time():
+    """The radial layout starts at the crown, as branch_events already assumed for its events."""
+    tree = loads("((((A:1,B:1)F:1,C:2)G:1,D:3)H:1,E:4)R:1.5;")
+    fig = plot(tree, layout="radial") + time_marker(3.5)                # 2.0 past the crown
+    cx, cy, r = _circle(fig.as_svg())
+    at_two = [n for n in fig.geometry().nodes if n.name == "G"][0]
+    assert math.hypot(at_two.x - cx, at_two.y - cy) == pytest.approx(r)
+
+
+def test_the_radial_marker_keeps_its_dash():
+    tree = loads(_MARKER_TREE)
+    assert "stroke-dasharray" in (plot(tree, layout="radial") + time_marker(2.0)).as_svg()
+    assert "stroke-dasharray" not in (plot(tree, layout="radial")
+                                      + time_marker(2.0, dash=False)).as_svg()
+
+
+def test_time_marker_refuses_the_unrooted_layout():
+    """A distance from the origin is not a place on an equal-angle layout. Say so, do not skip."""
+    with pytest.raises(ValueError, match="unrooted"):
+        (plot(loads(_MARKER_TREE), layout="unrooted") + time_marker(2.0)).as_svg()
+
+
+def test_time_marker_refuses_a_time_the_radial_layout_cannot_show():
+    with pytest.raises(ValueError, match="stem"):
+        (plot(loads("((A:1,B:1)F:1,C:2)R:1.5;"), layout="radial") + time_marker(0.5)).as_svg()
+
+
+# --- a centred title, and a legend in any corner (issues #9 and #10) ---------------------------
+
+_PLACED = Style(width=400, height=300, margin=20)
+_ENTRIES = {"a": "#111111", "b": "#222222"}
+_CORNERS = ("top-left", "top-right", "bottom-left", "bottom-right")
+
+
+def _rect(svg, fill):
+    found = re.search(rf'<rect x="([-\d.]+)" y="([-\d.]+)" width="([-\d.]+)" height="([-\d.]+)" '
+                      rf'fill="{fill}"', svg)
+    assert found, f"no rect filled {fill}"
+    return tuple(float(v) for v in found.groups())
+
+
+def _swatches(svg):
+    return [_rect(svg, fill) for fill in _ENTRIES.values()]
+
+
+def _backdrop(svg):
+    """The white patch the legend paints behind itself — the block's own box."""
+    boxes = re.findall(r'<rect x="([-\d.]+)" y="([-\d.]+)" width="([-\d.]+)" height="([-\d.]+)" '
+                       r'fill="#ffffff"', svg)
+    boxes = [tuple(float(v) for v in b) for b in boxes if (float(b[0]), float(b[1])) != (0.0, 0.0)]
+    assert len(boxes) == 1, f"expected one backdrop, found {len(boxes)}"
+    return boxes[0]
+
+
+def _legend_svg(loc):
+    return (plot(loads("((A:1,B:1)C:1,D:2)R;"), style=_PLACED)
+            + legend("state", loc=loc, entries=_ENTRIES)).as_svg()
+
+
+def test_title_sits_centred_over_the_panel():
+    """note pins text to a corner; a title belongs over the middle of the figure."""
+    svg = (plot(loads("((A:1,B:1)C:1,D:2)R;"), style=_PLACED) + title("Primates")).as_svg()
+    found = re.search(r'<text x="([-\d.]+)" y="([-\d.]+)"[^>]*text-anchor="(\w+)"[^>]*>Primates</text>', svg)
+    assert found
+    x, y, anchor = float(found.group(1)), float(found.group(2)), found.group(3)
+    assert x == pytest.approx(_PLACED.width / 2) and anchor == "middle"
+    assert y < _PLACED.margin, "the title should sit in the top margin, above the tree"
+
+
+def test_a_title_stays_on_the_page_when_the_top_margin_is_thin():
+    svg = (plot(loads("(A:1,B:1)R;"), style=Style(width=400, height=300, margin=4))
+           + title("Primates", size=20)).as_svg()
+    y = float(re.search(r'<text x="[-\d.]+" y="([-\d.]+)"[^>]*>Primates</text>', svg).group(1))
+    assert y >= 10.0, "half the title would be cut off by the top edge"
+
+
+def test_note_refuses_a_loc_that_is_not_a_corner():
+    """`loc="top-centre"` used to fall through and print right-aligned instead."""
+    with pytest.raises(ValueError, match="title"):
+        note("Primates", loc="top-centre")
+    with pytest.raises(ValueError, match="top-left"):
+        note("Primates", loc="top")
+
+
+def test_the_legend_default_corner_is_unchanged():
+    assert _legend_svg("top-left") == (plot(loads("((A:1,B:1)C:1,D:2)R;"), style=_PLACED)
+                                       + legend("state", entries=_ENTRIES)).as_svg()
+
+
+def test_the_legend_sits_in_the_corner_it_is_given():
+    """branch_events has always taken the four corners; legend was pinned to the top left."""
+    top_left = _swatches(_legend_svg("top-left"))
+    for loc in _CORNERS:
+        svg = _legend_svg(loc)
+        swatches = _swatches(svg)
+        bx, by, bw, bh = _backdrop(svg)
+        assert bx >= 0 and by >= 0, f"{loc}: the legend runs off the page"
+        assert bx + bw <= _PLACED.width and by + bh <= _PLACED.height, f"{loc}: off the page"
+        if "left" in loc:
+            assert swatches[0][0] == pytest.approx(_PLACED.margin), loc
+        else:
+            # the block is right-aligned on the right margin (the backdrop adds 6px of padding)
+            assert bx + bw - 6 == pytest.approx(_PLACED.width - _PLACED.margin), loc
+        if "top" in loc:
+            assert swatches[0][1] == pytest.approx(top_left[0][1]), loc
+        else:
+            lowest = max(y + h for _, y, _, h in swatches)
+            assert lowest == pytest.approx(_PLACED.height - _PLACED.margin, abs=1.0), loc
+
+
+def test_legend_refuses_a_loc_that_is_not_a_corner():
+    with pytest.raises(ValueError, match="bottom-right"):
+        legend("state", loc="middle", entries=_ENTRIES)