phylustrator 0.1.0__py3-none-any.whl

phylustrator/__init__.py

@@ -0,0 +1,29 @@
+"""Phylustrator — a lean, composable plotter for phylogenetics: **trees** and **genomes**.
+
+Two domains, one grammar (``plot(x) + layer + …``), one shared drawing backend:
+
+    import phylustrator as ph
+
+    # trees
+    tree = ph.trees.loads("((A:1,B:1)C:2,D:3)R;")
+    (ph.trees.plot(tree) + ph.trees.color_branches(vals) + ph.trees.time_axis()).save("tree.pdf")
+
+    # genomes
+    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
+    ph.beside(ph.trees.plot(tree) + ph.trees.tip_labels(), ph.genomes.heatmap(ph.zombi.read_profiles("run")))
+
+``ph.zombi`` is the only ZOMBI2-format-aware module; ``trees`` / ``genomes`` are general.
+"""
+
+from __future__ import annotations
+
+from . import genomes, trees, zombi
+from .compose import Composite, beside
+from .style import Style
+
+__version__ = "0.1.0"
+
+__all__ = ["trees", "genomes", "zombi", "beside", "Composite", "Style", "__version__"]

phylustrator/__main__.py

@@ -0,0 +1,5 @@
+"""``python -m phylustrator`` → the ``phyl`` command-line viewer."""
+
+from .cli import main
+
+raise SystemExit(main())

phylustrator/cli.py

@@ -0,0 +1,85 @@
+"""``phyl`` — a one-shot tree viewer.
+
+    phyl tree.nwk                 # render to a temporary PDF and open it
+    phyl tree.nwk -o fig.svg      # save instead (format from the extension)
+    phyl tree.nwk --radial --no-labels
+
+Deliberately tiny: it reads a Newick file, draws it, and shows or saves it. Anything richer
+(colouring, tracks, custom styles) lives in the Python API.
+"""
+
+from __future__ import annotations
+
+import argparse
+import os
+import subprocess
+import sys
+import tempfile
+from pathlib import Path
+
+from . import __version__
+from .trees import node_labels, plot, read, scale_bar, tip_labels, time_axis
+
+
+def _parser() -> argparse.ArgumentParser:
+    p = argparse.ArgumentParser(prog="phyl", description="Draw a phylogenetic tree from a Newick file.")
+    p.add_argument("tree", help="Newick tree file")
+    p.add_argument("-o", "--output", metavar="FILE",
+                   help="save here (.svg/.pdf/.png); default: a temporary PDF, opened")
+    p.add_argument("--layout", choices=["rectangular", "radial", "unrooted"], default="rectangular")
+    p.add_argument("--radial", action="store_const", const="radial", dest="layout",
+                   help="shortcut for --layout radial")
+    p.add_argument("--unrooted", action="store_const", const="unrooted", dest="layout",
+                   help="shortcut for --layout unrooted")
+    p.add_argument("--no-labels", action="store_true", help="hide tip labels")
+    p.add_argument("--node-labels", action="store_true", help="also label internal nodes")
+    p.add_argument("--no-stem", action="store_true", help="start at the crown (hide the root stem)")
+    p.add_argument("--no-open", action="store_true", help="do not open the temporary file")
+    p.add_argument("-V", "--version", action="version", version=f"phyl {__version__}")
+    return p
+
+
+def _open(path: Path) -> None:
+    try:
+        if sys.platform == "darwin":
+            subprocess.run(["open", str(path)], check=False)
+        elif sys.platform.startswith("win"):
+            os.startfile(str(path))  # type: ignore[attr-defined]  # noqa: S606
+        else:
+            subprocess.run(["xdg-open", str(path)], check=False)
+    except OSError:
+        pass  # opening is a convenience; the path is printed regardless
+
+
+def main(argv: list[str] | None = None) -> int:
+    parser = _parser()
+    args = parser.parse_args(argv)
+
+    try:
+        tree = read(args.tree)
+    except (FileNotFoundError, ValueError) as exc:
+        parser.error(str(exc))
+
+    figure = plot(tree, layout=args.layout, stem=not args.no_stem)
+    if not args.no_labels:
+        figure = figure + tip_labels()
+    if args.node_labels:
+        figure = figure + node_labels()
+    figure = figure + (time_axis() if args.layout == "rectangular" else scale_bar())
+
+    if args.output:
+        out = figure.save(args.output)
+        print(out)
+        return 0
+
+    # No -o: a genuinely throwaway file in the system temp dir.
+    tmp = Path(tempfile.mkdtemp(prefix="phyl_")) / "tree.pdf"
+    out = figure.save(tmp)  # may return a .svg sibling if cairosvg is absent
+    print(out)
+    if not args.no_open:
+        _open(out)
+    return 0
+
+
+if __name__ == "__main__":
+    raise SystemExit(main())

phylustrator/color.py

@@ -0,0 +1,92 @@
+"""Colour — colormaps for continuous values, palettes for categories, and normalisation.
+
+Matplotlib-free: the viridis ramp is a small embedded lookup table sampled by interpolation, and the
+categorical palette is Paul Tol's colour-blind-safe "bright" set.
+"""
+
+from __future__ import annotations
+
+import math
+from typing import Callable, Iterable
+
+# viridis, 16 anchor colours (R, G, B in 0–255), sampled evenly from matplotlib.
+_COLORMAPS: dict[str, list[tuple[int, int, int]]] = {
+    "viridis": [
+        (68, 1, 84), (72, 26, 108), (71, 47, 125), (65, 68, 135),
+        (57, 86, 140), (49, 104, 142), (42, 120, 142), (35, 136, 142),
+        (31, 152, 139), (34, 168, 132), (53, 183, 121), (84, 197, 104),
+        (122, 209, 81), (165, 219, 54), (210, 226, 27), (253, 231, 37),
+    ],
+}
+
+# Paul Tol "bright" — distinct and colour-blind-safe.
+_PALETTE = ["#4477AA", "#EE6677", "#228833", "#CCBB44", "#66CCEE", "#AA3377", "#BBBBBB"]
+
+
+def to_hex(rgb: tuple[float, float, float]) -> str:
+    return "#{:02x}{:02x}{:02x}".format(*(int(max(0, min(255, round(c)))) for c in rgb))
+
+
+def colormap(name: str = "viridis") -> Callable[[float], tuple[int, int, int]]:
+    """Return a sampler ``t in [0, 1] -> (R, G, B)`` that interpolates the named colormap."""
+    anchors = _colormap_anchors(name)
+    n = len(anchors)
+
+    def sample(t: float) -> tuple[int, int, int]:
+        t = max(0.0, min(1.0, float(t)))
+        pos = t * (n - 1)
+        i = int(math.floor(pos))
+        if i >= n - 1:
+            return anchors[-1]
+        frac = pos - i
+        a, b = anchors[i], anchors[i + 1]
+        return tuple(a[k] + (b[k] - a[k]) * frac for k in range(3))
+
+    return sample
+
+
+def colormap_hex(name: str = "viridis") -> list[str]:
+    """The colormap's anchor colours as hex — for a gradient bar."""
+    return [to_hex(rgb) for rgb in _colormap_anchors(name)]
+
+
+def _colormap_anchors(name: str) -> list[tuple[int, int, int]]:
+    anchors = _COLORMAPS.get(name.lower())
+    if anchors is None:
+        raise ValueError(f"unknown colormap {name!r}; available: {sorted(_COLORMAPS)}")
+    return anchors
+
+
+def palette(labels: Iterable) -> dict:
+    """A ``{label: hex colour}`` map over ``labels`` (sorted for stability), from the bright set."""
+    ordered = sorted(set(labels), key=str)
+    return {label: _PALETTE[i % len(_PALETTE)] for i, label in enumerate(ordered)}
+
+
+def normalize(values: Iterable[float]) -> tuple[float, float, Callable[[float], float]]:
+    """Return ``(vmin, vmax, to_unit)`` where ``to_unit(v)`` maps ``[vmin, vmax] -> [0, 1]``."""
+    nums = [float(v) for v in values]
+    vmin, vmax = min(nums), max(nums)
+    span = (vmax - vmin) or 1.0
+    return vmin, vmax, lambda v: (float(v) - vmin) / span
+
+
+def _is_number(v) -> bool:
+    return isinstance(v, (int, float)) and not isinstance(v, bool)
+
+
+def map_values(values: dict, *, cmap: str = "viridis",
+               palette: dict | None = None) -> tuple[dict, dict]:
+    """Turn ``{key: value}`` into ``({key: hex colour}, scale)``, dispatching on the data: numbers get
+    the colormap (and a ``continuous`` scale for a colour bar), labels get a palette (and a
+    ``categorical`` scale for a legend). ``scale`` is ``None`` if there is nothing to colour."""
+    present = {k: v for k, v in values.items() if v is not None}
+    if not present:
+        return {}, None
+    if all(_is_number(v) for v in present.values()):
+        vmin, vmax, to_unit = normalize(present.values())
+        sample = colormap(cmap)
+        colors = {k: to_hex(sample(to_unit(v))) for k, v in present.items()}
+        return colors, {"kind": "continuous", "vmin": vmin, "vmax": vmax, "cmap": cmap}
+    pal = palette or globals()["palette"](present.values())
+    return {k: pal[v] for k, v in present.items()}, {"kind": "categorical", "palette": pal}

phylustrator/compose.py

@@ -0,0 +1,61 @@
+"""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)
+
+    wanted = set(panel.rows)
+    rows = [(t.name, t.y) for t in geom.tips if t.name in wanted]
+    if rows:
+        panel.draw(canvas, tree_w + gap, width - pad, rows, canvas.style)
+    return Composite(canvas)

phylustrator/genomes/__init__.py

@@ -0,0 +1,23 @@
+"""The **genomes** domain — plot genomes, synteny and alignments. Same grammar as ``trees``:
+``phylustrator.genomes.plot(genome) + layer + …``
+
+    import phylustrator as ph
+    G = ph.zombi.read_genomes("run")                 # or ph.genomes.read_gff("genome.gff")
+    (ph.genomes.plot(G["n12"], layout="circular") + ph.genomes.genes(by="family")).save("ring.png")
+"""
+
+from __future__ import annotations
+
+from .figure import Figure, StackFigure, plot, stack
+from .genome import Chromosome, Gene, Genome
+from .io import read_gff
+from .layers import genes, highlight, position_axis, synteny
+from .matrix import Alignment, Matrix
+from .panels import alignment, heatmap, states
+
+__all__ = [
+    "Gene", "Chromosome", "Genome", "read_gff",
+    "plot", "stack", "Figure", "StackFigure",
+    "genes", "synteny", "highlight", "position_axis",
+    "Matrix", "Alignment", "heatmap", "alignment", "states",
+]

phylustrator/genomes/figure.py

@@ -0,0 +1,107 @@
+"""The figure — ``plot(genome)`` + layers, then render. Mirrors Phylustrator's grammar.
+
+    fig = plot(genome, layout="linear") + genes(by="family") + position_axis()
+    fig.save("map.svg")
+
+    fig = stack([g1, g2, g3]) + genes() + synteny()          # several genomes, one per track
+
+A **layer** is a callable ``(canvas, primary, layout, style) -> None`` — the whole extension contract.
+``primary`` is the genome (or the first, for a stack); layers read the self-describing ``layout``.
+"""
+
+from __future__ import annotations
+
+from typing import Callable
+
+from ..render import Canvas
+from ..style import Style
+from .layout import Layout, circular, linear, stacked
+from .track import draw_genes
+
+Layer = Callable[[Canvas, object, Layout, Style], None]
+
+_LAYOUTS = {"linear": linear, "circular": circular}
+
+
+class Figure:
+    def __init__(self, genome, *, layout: str = "linear", coordinates: str = "ordered",
+                 style: Style | None = None, layers: tuple = ()) -> None:
+        if layout not in _LAYOUTS:
+            raise ValueError(f"unknown layout {layout!r}; choose from {sorted(_LAYOUTS)}")
+        self.genome = genome
+        self.layout = layout
+        self.coordinates = coordinates
+        self.style = style or Style()
+        self.layers = tuple(layers)
+
+    def _make_layout(self) -> Layout:
+        return _LAYOUTS[self.layout](self.genome, coordinates=self.coordinates)
+
+    def _clone(self, **kw) -> "Figure":
+        base = dict(layout=self.layout, coordinates=self.coordinates, style=self.style,
+                    layers=self.layers)
+        base.update(kw)
+        return Figure(self.genome, **base)
+
+    def __add__(self, layer: Layer) -> "Figure":
+        return self._clone(layers=self.layers + (layer,))
+
+    def _build(self) -> Canvas:
+        layout = self._make_layout()
+        canvas = Canvas(self.style, layout.xlim, layout.ylim, equal_aspect=layout.equal_aspect)
+        _draw_base(canvas, layout, self.style)
+        primary = layout.track_order[0] if layout.track_order else None
+        for layer in self.layers:
+            layer(canvas, primary, layout, self.style)
+        return canvas
+
+    def as_svg(self) -> str:
+        return self._build().as_svg()
+
+    def save(self, path):
+        return self._build().save(path)
+
+
+class StackFigure(Figure):
+    """A figure over several genomes (one track each). Same grammar; a different layout."""
+
+    def __init__(self, genomes, *, coordinates: str = "ordered", style: Style | None = None,
+                 layers: tuple = ()) -> None:
+        self.genomes = list(genomes)
+        self.layout = "stacked"
+        self.coordinates = coordinates
+        n = len(self.genomes)
+        self.style = style or Style(height=70.0 + 82.0 * n, gene_height=0.4)
+        self.layers = tuple(layers)
+        self.genome = self.genomes[0] if self.genomes else None
+
+    def _make_layout(self) -> Layout:
+        return stacked(self.genomes, coordinates=self.coordinates)
+
+    def _clone(self, **kw) -> "StackFigure":
+        base = dict(coordinates=self.coordinates, style=self.style, layers=self.layers)
+        base.update({k: v for k, v in kw.items() if k in ("coordinates", "style", "layers")})
+        return StackFigure(self.genomes, **base)
+
+
+def plot(genome, *, layout: str = "linear", coordinates: str = "ordered",
+         style: Style | None = None) -> Figure:
+    """Start a figure for one ``genome``. Add layers with ``+``, then :meth:`Figure.save`."""
+    return Figure(genome, layout=layout, coordinates=coordinates, style=style)
+
+
+def stack(genomes, *, coordinates: str = "ordered", style: Style | None = None) -> StackFigure:
+    """Start a figure comparing several ``genomes``, one horizontal track each (top genome first)."""
+    return StackFigure(genomes, coordinates=coordinates, style=style)
+
+
+def _draw_base(canvas: Canvas, layout: Layout, style: Style) -> None:
+    """The base map: a faint backbone per track, and the gene arrows in the default colour (a
+    ``genes`` layer overdraws them coloured)."""
+    if layout.kind == "circular":
+        for R in layout.rings or []:
+            canvas.data_ring(R, "#d8ddda", 1.4)
+    else:
+        for y, x0, x1 in layout.backbones:
+            canvas.line(x0, y, x1, y, "#d8ddda", 1.4)
+    draw_genes(canvas, layout, lambda gene: style.default_color, style)

phylustrator/genomes/genome.py

@@ -0,0 +1,41 @@
+"""The genome data model — :class:`Gene`, :class:`Chromosome`, :class:`Genome`.
+
+Structure only: a genome is chromosomes of ordered genes, and knows nothing about how it is drawn. The
+dataclasses use ``eq=False`` so instances hash by identity (a layout keys its boxes by gene).
+"""
+
+from __future__ import annotations
+
+from dataclasses import dataclass, field
+
+
+@dataclass(eq=False)
+class Gene:
+    """One gene on a chromosome: its ``family`` (shared across genomes — the unit of colour and
+    homology), its ``copy`` name, its ``strand`` (+1 / −1), and its ``position`` (rank order). Optional
+    ``start`` / ``end`` carry nucleotide coordinates for the nucleotide resolution."""
+
+    family: str
+    copy: str = ""
+    strand: int = 1
+    position: int = 0
+    start: float | None = None
+    end: float | None = None
+
+
+@dataclass(eq=False)
+class Chromosome:
+    id: str
+    genes: list = field(default_factory=list)
+    topology: str = "linear"        # "linear" | "circular"
+    length: float | None = None     # nucleotide length, if known
+
+
+@dataclass(eq=False)
+class Genome:
+    name: str
+    chromosomes: list = field(default_factory=list)
+
+    @property
+    def genes(self) -> list:
+        return [g for chrom in self.chromosomes for g in chrom.genes]

phylustrator/genomes/io.py

@@ -0,0 +1,56 @@
+"""General genome input — reading a **GFF3** into :class:`~phylustrator.genomes.genome.Genome`
+objects. Reading a ZOMBI2 *run* (its own file formats) lives in :mod:`phylustrator.zombi`.
+"""
+
+from __future__ import annotations
+
+from pathlib import Path
+
+from .genome import Chromosome, Gene, Genome
+
+__all__ = ["read_gff"]
+
+
+def read_gff(source: str | Path, *, feature: str = "gene", name_attr: str = "locus_tag") -> dict:
+    """Read a **GFF3** into ``{seqid: Genome}`` — real genes at their real base coordinates.
+
+    Genes are the rows whose type is ``feature`` (default ``"gene"``); each gets its ``start`` / ``end``
+    (bp), ``strand``, and a family/name from ``name_attr`` in column 9 (falling back to ``Name`` / ``ID``).
+    A ``##sequence-region`` line or a ``region`` feature sets the replicon length and circularity."""
+    path = Path(source)
+    per: dict[str, dict] = {}
+    for raw in path.read_text().splitlines():
+        if raw.startswith("##sequence-region"):
+            p = raw.split()
+            if len(p) >= 4:
+                per.setdefault(p[1], _blank())["length"] = float(p[3])
+            continue
+        if raw.startswith("#") or not raw.strip():
+            continue
+        c = raw.split("\t")
+        if len(c) < 9:
+            continue
+        seqid, _src, ftype, start, end, _score, strand, _phase, attrs = c[:9]
+        info = per.setdefault(seqid, _blank())
+        if ftype == "region" and "Is_circular=true" in attrs:
+            info["circular"] = True
+        if ftype != feature:
+            continue
+        a = dict(kv.split("=", 1) for kv in attrs.split(";") if "=" in kv)
+        fam = a.get(name_attr) or a.get("Name") or a.get("ID") or ""
+        info["genes"].append(Gene(family=fam, strand=(-1 if strand == "-" else 1),
+                                  start=float(start), end=float(end)))
+        info["length"] = max(info["length"], float(end))
+    genomes = {}
+    for seqid, info in per.items():
+        genes = sorted(info["genes"], key=lambda g: g.start)
+        for rank, g in enumerate(genes):
+            g.position = rank
+        topo = "circular" if info["circular"] else "linear"
+        genomes[seqid] = Genome(name=seqid, chromosomes=[
+            Chromosome(id=seqid, genes=genes, topology=topo, length=info["length"])])
+    return genomes
+
+
+def _blank() -> dict:
+    return {"genes": [], "length": 0.0, "circular": False}

phylustrator/genomes/layers/__init__.py

@@ -0,0 +1,8 @@
+"""Layers — the composable decorations added to a genome figure with ``+``."""
+
+from .genes import genes
+from .guides import position_axis
+from .highlight import highlight
+from .synteny import synteny
+
+__all__ = ["genes", "position_axis", "synteny", "highlight"]

phylustrator/genomes/layers/genes.py

@@ -0,0 +1,35 @@
+"""The gene-colouring layer — paint the arrows by an attribute (default the gene family).
+
+Families get consistent colours across genomes (family "5" is the same colour everywhere), which is
+what makes stacked genomes read as synteny.
+"""
+
+from __future__ import annotations
+
+from ...color import colormap, to_hex
+from ..track import draw_genes
+
+
+def _key(value: str):
+    return (0, int(value)) if str(value).lstrip("-").isdigit() else (1, str(value))
+
+
+def genes(by: str = "family", *, cmap: str = "viridis", palette: dict | None = None):
+    """Colour gene arrows by ``by`` (an attribute of each gene). Returns a layer."""
+
+    def layer(canvas, primary, layout, style):
+        keys = sorted({str(getattr(g, by)) for g in layout.genes}, key=_key)
+        if palette is not None:
+            color_of = dict(palette)
+        else:
+            sample = colormap(cmap)
+            n = len(keys)
+            color_of = {k: to_hex(sample(i / (n - 1) if n > 1 else 0.5)) for i, k in enumerate(keys)}
+        canvas.scale = {"kind": "genes", "colors": color_of, "by": by}
+
+        def color(gene):
+            return color_of.get(str(getattr(gene, by)), style.default_color)
+
+        draw_genes(canvas, layout, color, style)
+
+    return layer

phylustrator/genomes/layers/guides.py

@@ -0,0 +1,78 @@
+"""Guide layers — the chrome that reads the coordinates.
+
+``position_axis`` adapts to the layout: a horizontal ruler for ``linear``, and an inner coordinate
+**ring** (base-position ticks around the circle) for ``circular`` — the standard reference on a
+circular genome map.
+"""
+
+from __future__ import annotations
+
+import math
+
+
+def position_axis(label: str = "position", *, ticks: int = 6):
+    """A coordinate axis in the layout's units: a horizontal ruler (``linear``) or an inner ring of
+    base-position ticks (``circular``)."""
+
+    def layer(canvas, primary, layout, style):
+        if layout.kind == "circular":
+            _circular(canvas, layout, style)
+        else:
+            _linear(canvas, layout, style, label, ticks)
+
+    return layer
+
+
+def _linear(canvas, layout, style, label, ticks) -> None:
+    _, height = canvas.size
+    m = style.margin
+    x0, x1 = layout.xlim
+    y = height - m * 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):
+        t = x0 + (x1 - x0) * i / (ticks - 1)
+        tx = canvas.px(t)
+        canvas.raw_line(tx, y, tx, y + 5, "#333333", 1.2)
+        canvas.raw_text(tx, y + 12, f"{t:.0f}", anchor="middle", size=small)
+    if label:
+        mid = (canvas.px(x0) + canvas.px(x1)) / 2
+        canvas.raw_text(mid, y + 24, label, anchor="middle", size=style.font_size)
+
+
+def _circular(canvas, layout, style) -> None:
+    total = layout.totals[0] if layout.totals else 1.0
+    start, sweep = layout.angle_start, layout.angle_sweep
+    inner = (min(layout.rings) if layout.rings else 0.85) - layout.ring_hh - 0.06
+    canvas.data_ring(inner, "#c7d0cc", 1.0)                       # the coordinate ring
+    step = _nice_step(total, 8)
+    small = style.font_size * 0.9
+    v = 0.0
+    while v < total - step * 1e-6:
+        a = start - (v / total) * sweep
+        canvas.line(inner * math.cos(a), inner * math.sin(a),
+                    (inner - 0.03) * math.cos(a), (inner - 0.03) * math.sin(a), "#5a6763", 1.1)
+        lx, ly = (inner - 0.10) * math.cos(a), (inner - 0.10) * math.sin(a)
+        canvas.text(lx, ly, _fmt_bp(v), anchor="middle", size=small)
+        v += step
+
+
+def _nice_step(span: float, target: int) -> float:
+    raw = span / max(target, 1)
+    if raw <= 0:
+        return 1.0
+    exp = math.floor(math.log10(raw))
+    base = raw / 10 ** exp
+    nice = 1 if base < 1.5 else 2 if base < 3.5 else 5 if base < 7.5 else 10
+    return nice * 10 ** exp
+
+
+def _fmt_bp(v: float) -> str:
+    v = int(round(v))
+    if v == 0:
+        return "0"
+    if v >= 1_000_000:
+        return f"{v // 1_000_000} Mb" if v % 1_000_000 == 0 else f"{v / 1_000_000:.1f} Mb"
+    if v >= 1_000:
+        return f"{v // 1_000} kb" if v % 1_000 == 0 else f"{v / 1_000:.0f} kb"
+    return str(v)

phylustrator/genomes/layers/highlight.py

@@ -0,0 +1,38 @@
+"""The highlight layer — mark a span of a genome (a rearranged segment, a region of interest).
+
+Shades the ranks ``[start, end]`` of one genome's chromosome with a tinted, outlined band that the
+gene arrows read through. Works on a single ``plot`` or on one track of a ``stack``.
+"""
+
+from __future__ import annotations
+
+
+def highlight(genome, chromosome=None, start: int = 0, end: int = 0, *,
+              color: str = "#e8a33d", label: str | None = None, pad: float = 0.12):
+    """Highlight positions ``start``..``end`` (inclusive) on ``genome`` / ``chromosome``.
+
+    ``chromosome`` may be a :class:`Chromosome`, its ``id``, or ``None`` (any chromosome)."""
+
+    def _matches(owner):
+        g, chrom = owner
+        if g is not genome:
+            return False
+        return chromosome is None or chrom is chromosome or chrom.id == chromosome
+
+    def layer(canvas, primary, layout, style):
+        sel = [gene for gene in layout.genes
+               if _matches(layout.owner[id(gene)]) and start <= gene.position <= end]
+        if not sel:
+            return
+        boxes = [layout.box(g) for g in sel]
+        x0 = min(b[0] for b in boxes)
+        x1 = max(b[1] for b in boxes)
+        y = boxes[0][2]
+        hh = style.gene_height / 2.0 + pad
+        canvas.region(x0, y - hh, x1, y + hh, fill=color, opacity=0.2,
+                      stroke=color, stroke_width=1.4, rx=4.0)
+        if label:
+            canvas.text((x0 + x1) / 2.0, y - hh, label, dy=-6, anchor="middle",
+                        color=color, size=style.font_size)
+
+    return layer