phylustrator 0.1.0__py3-none-any.whl

phylustrator/genomes/layers/synteny.py

@@ -0,0 +1,56 @@
+"""The synteny layer — ribbons linking same-family genes between adjacent stacked genomes.
+
+Runs after ``genes`` when present, so ribbons inherit the family colours the ``genes`` layer chose;
+on its own it falls back to a neutral link colour. Only meaningful on a ``stack``.
+"""
+
+from __future__ import annotations
+
+from ...color import colormap, to_hex
+
+
+def _family_colors(layout, canvas):
+    scale = getattr(canvas, "scale", None)
+    if scale and scale.get("kind") == "genes":
+        return scale["colors"]
+    fams = sorted({str(g.family) for g in layout.genes})
+    sample = colormap("viridis")
+    n = len(fams)
+    return {f: to_hex(sample(i / (n - 1) if n > 1 else 0.5)) for i, f in enumerate(fams)}
+
+
+def synteny(*, by: str = "family", opacity: float = 0.3, color: str | None = None):
+    """Link genes sharing ``by`` between neighbouring tracks with a curved ribbon. ``color`` overrides
+    the per-family colour with a single neutral tone."""
+
+    def layer(canvas, primary, layout, style):
+        tracks = layout.track_order
+        if len(tracks) < 2:
+            return
+        colors = _family_colors(layout, canvas)
+        hh = style.gene_height / 2.0
+        # genes grouped by (track index, key)
+        per_track = [{} for _ in tracks]
+        index = {id(g): t for t, gen in enumerate(tracks)
+                 for g in gen.genes if id(g) in layout.boxes}
+        for g in layout.genes:
+            t = index.get(id(g))
+            if t is None:
+                continue
+            per_track[t].setdefault(str(getattr(g, by)), []).append(g)
+        for t in range(len(tracks) - 1):
+            upper, lower = per_track[t], per_track[t + 1]
+            for key, ups in upper.items():
+                downs = lower.get(key)
+                if not downs:
+                    continue
+                fill = color or colors.get(key, style.default_color)
+                ups = sorted(ups, key=lambda g: layout.box(g)[0])
+                downs = sorted(downs, key=lambda g: layout.box(g)[0])
+                for i, u in enumerate(ups):
+                    d = downs[min(i, len(downs) - 1)]      # pair by copy order
+                    ux0, ux1, uy = layout.box(u)
+                    dx0, dx1, dy = layout.box(d)
+                    canvas.ribbon(ux0, ux1, uy + hh, dx0, dx1, dy - hh, fill=fill, opacity=opacity)
+
+    return layer

phylustrator/genomes/layout.py

@@ -0,0 +1,130 @@
+"""Layouts — place genes in an abstract coordinate space, the renderer maps it to the page.
+
+- ``linear`` — one genome, a horizontal track per chromosome. The **ordered** resolution spaces genes
+  equally by rank; **nucleotide** uses their base coordinates (cladogram vs. phylogram).
+- ``circular`` — the same map wrapped onto a ring, one concentric ring per chromosome (Phylustrator's
+  radial). A ``linear`` plot of a circular genome *is* the linearisation.
+- ``stacked`` — several genomes, one horizontal track each, for synteny comparison.
+
+A :class:`Layout` is **self-describing**: it carries the genes it placed (draw order), each gene's
+owner ``(genome, chromosome)``, the backbones to draw, and the vertical track order — so the drawer and
+every layer read the layout, never the genome, and single/stacked/circular all share one path.
+"""
+
+from __future__ import annotations
+
+import math
+from dataclasses import dataclass, field
+
+
+@dataclass
+class Layout:
+    kind: str
+    boxes: dict                              # linear: id(gene)->(x0,x1,y); circular: id(gene)->(a0,a1,R)
+    xlim: tuple
+    ylim: tuple
+    rows: int = 1
+    genes: list = field(default_factory=list)          # gene objects, draw order
+    owner: dict = field(default_factory=dict)          # id(gene) -> (genome, chromosome)
+    backbones: list = field(default_factory=list)      # [(y, x0, x1)] faint tracks (linear/stacked)
+    track_order: list = field(default_factory=list)    # genomes top->bottom (synteny adjacency)
+    rings: list | None = None                          # circular: centre radius per chromosome
+    ring_hh: float = 0.0                               # circular: gene half-height, radius units
+    equal_aspect: bool = False                         # circular keeps the rings round
+    angle_start: float = 0.0                           # circular: angle (rad) of position 0
+    angle_sweep: float = 0.0                           # circular: angular span (rad) of a chromosome
+    totals: list = field(default_factory=list)         # circular: coordinate span per ring (bp or genes)
+
+    def box(self, gene):
+        return self.boxes[id(gene)]
+
+
+def linear(genome, *, coordinates: str = "ordered", gap: float = 0.16) -> Layout:
+    """Genes on one horizontal track per chromosome."""
+    boxes, owner, backbones, placed = {}, {}, [], []
+    for row, chrom in enumerate(genome.chromosomes):
+        xs = []
+        for gene in chrom.genes:
+            if coordinates == "nucleotide" and gene.start is not None:
+                x0, x1 = float(gene.start), float(gene.end)
+            else:
+                x0, x1 = gene.position + gap / 2, gene.position + 1 - gap / 2
+            boxes[id(gene)] = (x0, x1, float(row))
+            owner[id(gene)] = (genome, chrom)
+            placed.append(gene)
+            xs += [x0, x1]
+        if xs:
+            backbones.append((float(row), min(xs), max(xs)))
+    allx = [v for b in boxes.values() for v in b[:2]] or [0.0, 1.0]
+    rows = len(genome.chromosomes)
+    return Layout("linear", boxes, (min(allx), max(allx)), (-0.5, rows - 0.5), rows=rows,
+                  genes=placed, owner=owner, backbones=backbones, track_order=[genome])
+
+
+def stacked(genomes, *, coordinates: str = "ordered", gap: float = 0.16,
+            chrom_gap: float = 1.0) -> Layout:
+    """Several genomes, one horizontal track each (top genome first). Chromosomes of a genome sit
+    left-to-right on its track separated by ``chrom_gap``. Same-family genes line up by colour, and a
+    ``synteny`` layer links them between adjacent tracks."""
+    boxes, owner, backbones, placed = {}, {}, [], []
+    for row, genome in enumerate(genomes):
+        offset, xs = 0.0, []
+        for chrom in genome.chromosomes:
+            for gene in chrom.genes:
+                if coordinates == "nucleotide" and gene.start is not None:
+                    x0, x1 = offset + float(gene.start), offset + float(gene.end)
+                else:
+                    x0, x1 = offset + gene.position + gap / 2, offset + gene.position + 1 - gap / 2
+                boxes[id(gene)] = (x0, x1, float(row))
+                owner[id(gene)] = (genome, chrom)
+                placed.append(gene)
+                xs += [x0, x1]
+            span = (len(chrom.genes)) if coordinates != "nucleotide" else float(chrom.length or 0.0)
+            offset += span + chrom_gap
+        if xs:
+            backbones.append((float(row), min(xs), max(xs)))
+    allx = [v for b in boxes.values() for v in b[:2]] or [0.0, 1.0]
+    n = len(genomes)
+    return Layout("stacked", boxes, (min(allx), max(allx)), (-0.6, n - 0.4), rows=n,
+                  genes=placed, owner=owner, backbones=backbones, track_order=list(genomes))
+
+
+def circular(genome, *, coordinates: str = "ordered", gap: float = 0.16,
+             start_deg: float = 90.0, break_deg: float = 0.0,
+             band: float = 0.34, ring_gap: float = 0.10, min_deg: float = 2.2) -> Layout:
+    """Genes wrapped onto a ring, one concentric ring per chromosome (chromosome 0 outermost).
+
+    Angles sweep **clockwise** from the top. By default the ring is closed (``break_deg=0``) so genes
+    are evenly spaced all the way round; set ``break_deg`` to leave a wedge marking a linear
+    chromosome's ends. ``coordinates`` chooses equal angular slots by **rank** (``"ordered"``) or
+    base-proportional arcs (``"nucleotide"``)."""
+    start = math.radians(start_deg)
+    sweep = 2.0 * math.pi - math.radians(break_deg)
+    boxes, owner, placed, rings, totals = {}, {}, [], [], []
+    for k, chrom in enumerate(genome.chromosomes):
+        R = 1.0 - band / 2.0 - k * (band + ring_gap)
+        rings.append(R)
+        n = len(chrom.genes)
+        nuc = coordinates == "nucleotide" and n and chrom.genes[0].start is not None
+        total = float(chrom.length or (chrom.genes[-1].end - chrom.genes[0].start) or 1.0) if nuc \
+            else float(n or 1)
+        totals.append(total)
+        # cap the minimum arc so a gene-dense genome (a real GFF) never forces genes to overlap
+        min_arc = min(math.radians(min_deg), 0.9 * sweep / max(n, 1))
+        for rank, gene in enumerate(chrom.genes):        # rank, so "ordered" is even with no holes
+            lo_v, hi_v = (float(gene.start), float(gene.end)) if nuc \
+                else (rank + gap / 2.0, rank + 1.0 - gap / 2.0)
+            a0 = start - (lo_v / total) * sweep          # clockwise: angle decreases with position
+            a1 = start - (hi_v / total) * sweep
+            if abs(a1 - a0) < min_arc:                   # keep tiny (nucleotide) genes visible
+                mid = (a0 + a1) / 2.0
+                a0, a1 = mid + min_arc / 2.0, mid - min_arc / 2.0
+            boxes[id(gene)] = (a0, a1, R)
+            owner[id(gene)] = (genome, chrom)
+            placed.append(gene)
+    hh = band * 0.11                            # thin arrow band so arrowheads read on the ring
+    outer = (rings[0] if rings else 1.0) + hh
+    lim = (-outer, outer)
+    return Layout("circular", boxes, lim, lim, rows=len(genome.chromosomes),
+                  genes=placed, owner=owner, rings=rings, ring_hh=hh, equal_aspect=True,
+                  track_order=[genome], angle_start=start, angle_sweep=sweep, totals=totals)

phylustrator/genomes/matrix.py

@@ -0,0 +1,32 @@
+"""Tabular data to show beside a tree — labelled grids.
+
+A :class:`Matrix` is rows × columns of numbers with labels on both (e.g. a gene-family profile:
+genomes × families). An :class:`Alignment` is rows × sites of residues. Both are consumed by the
+``heatmap`` / ``alignment`` panels and placed by :func:`~phylustrator.compose.beside`. Readers that
+build these from a ZOMBI2 run live in :mod:`phylustrator.zombi`.
+"""
+
+from __future__ import annotations
+
+from dataclasses import dataclass
+
+
+@dataclass
+class Matrix:
+    rows: list          # row labels (e.g. genomes / tree tips)
+    cols: list          # column labels (e.g. families)
+    values: list        # values[i][j] aligned to rows[i], cols[j]
+
+    def row(self, label):
+        return self.values[self.rows.index(label)]
+
+
+@dataclass
+class Alignment:
+    rows: list          # row labels (e.g. genomes / tree tips)
+    seqs: dict          # label -> sequence string
+    kind: str = "nt"    # "nt" | "aa"
+
+    @property
+    def length(self) -> int:
+        return max((len(s) for s in self.seqs.values()), default=0)

phylustrator/genomes/panels.py

@@ -0,0 +1,208 @@
+"""Panels — a matrix or an alignment drawn as a grid, its rows placed by whatever calls it.
+
+A **panel** knows its ``rows`` (labels) and draws itself into a pixel band with :meth:`draw`, given the
+pixel ``y`` of each row it should draw. :func:`~genustrator.compose.beside` supplies those y's from a
+Phylustrator tree's tips, so the grid lines up with the phylogeny; a panel never positions its own
+rows. ``heatmap`` shows a :class:`~genustrator.matrix.Matrix`; ``alignment`` shows residues.
+"""
+
+from __future__ import annotations
+
+from ..color import colormap, colormap_hex, to_hex
+
+# A clean nucleotide palette; unknown residues fall back to a neutral grey.
+NT_COLORS = {"A": "#3a923a", "C": "#3a6ea5", "G": "#e0a327", "T": "#c1443c",
+             "U": "#c1443c", "-": "#e9ecef", "N": "#c8cdd2"}
+
+
+def _row_height(rows) -> float:
+    ys = sorted(y for _, y in rows)
+    gaps = [b - a for a, b in zip(ys, ys[1:])]
+    return (min(gaps) if gaps else 40.0) * 0.82
+
+
+class Heatmap:
+    def __init__(self, matrix, *, cmap="viridis", vmin=None, vmax=None,
+                 col_labels=None, grid="#ffffff", title=None):
+        self.matrix = matrix
+        self.cmap = cmap
+        vals = [v for r in matrix.values for v in r]
+        self.vmin = 0.0 if vmin is None else vmin
+        self.vmax = (max(vals) if vals else 1.0) if vmax is None else vmax
+        # label columns only when there are few enough to read
+        self.col_labels = (len(matrix.cols) <= 26) if col_labels is None else col_labels
+        self.grid = grid
+        self.title = title
+
+    @property
+    def rows(self):
+        return self.matrix.rows
+
+    def draw(self, canvas, x0, x1, rows, style):
+        sample = colormap(self.cmap)
+        span = (self.vmax - self.vmin) or 1.0
+        ncol = len(self.matrix.cols)
+        cw = (x1 - x0) / ncol
+        rh = _row_height(rows)
+        for label, y in rows:
+            values = self.matrix.row(label)
+            for j, v in enumerate(values):
+                t = (v - self.vmin) / span
+                canvas.raw_rect(x0 + j * cw, y - rh / 2, cw, rh,
+                                fill=to_hex(sample(t)), stroke=self.grid, stroke_width=0.6)
+        top = min(y for _, y in rows) - rh / 2
+        if self.col_labels:
+            for j, c in enumerate(self.matrix.cols):
+                cx = x0 + (j + 0.5) * cw
+                canvas.raw_text(cx, top - 6, str(c), anchor="start", baseline="alphabetic",
+                                size=style.font_size * 0.8, rotate=-60)
+        if self.title:
+            canvas.raw_text((x0 + x1) / 2, top - 26, self.title, anchor="middle",
+                            size=style.font_size, weight="bold")
+        self._colorbar(canvas, x0, x1, max(y for _, y in rows) + rh / 2 + 16, style)
+
+    def _colorbar(self, canvas, x0, x1, y, style):
+        w, h = min(200.0, x1 - x0), 12.0
+        canvas.gradient_bar(self.cmap, x0, y, w, h)
+        small = style.font_size * 0.85
+        lo, hi = int(round(self.vmin)), int(round(self.vmax))
+        vals = list(range(lo, hi + 1))
+        if len(vals) > 9:                                  # thin out to ~7 integer ticks
+            step = max(1, round((hi - lo) / 7))
+            vals = list(range(lo, hi + 1, step))
+            if vals[-1] != hi:
+                vals.append(hi)
+        span = (self.vmax - self.vmin) or 1.0
+        for v in vals:
+            tx = x0 + (v - self.vmin) / span * w
+            canvas.raw_line(tx, y + h, tx, y + h + 4, "#555555", 1.0)
+            canvas.raw_text(tx, y + h + 6 + small * 0.7, str(v), anchor="middle", size=small)
+        canvas.raw_text(x0 + w + 12, y + h / 2, "copies", anchor="start", size=small)
+
+
+class Alignment:
+    def __init__(self, alignment, *, palette=None, letters=None, title=None, legend=True):
+        self.alignment = alignment
+        self.palette = palette or NT_COLORS
+        self.letters = letters            # None -> auto (draw letters if cells are wide enough)
+        self.title = title
+        self.legend = legend              # a nucleotide colour key below the alignment
+
+    @property
+    def rows(self):
+        return self.alignment.rows
+
+    def draw(self, canvas, x0, x1, rows, style):
+        L = self.alignment.length
+        if L == 0:
+            return
+        cw = (x1 - x0) / L
+        rh = _row_height(rows)
+        letters = (cw >= 7.0) if self.letters is None else self.letters
+        for label, y in rows:
+            seq = self.alignment.seqs.get(label, "")
+            for s, res in enumerate(seq):
+                cx = x0 + s * cw
+                canvas.raw_rect(cx, y - rh / 2, cw, rh,
+                                fill=self.palette.get(res, "#c8cdd2"),
+                                stroke="#ffffff", stroke_width=0.4)
+                if letters:
+                    canvas.raw_text(cx + cw / 2, y, res, anchor="middle",
+                                    color="#ffffff", size=min(rh, cw) * 0.72, weight="bold")
+        top = min(y for _, y in rows) - rh / 2
+        # a light ruler every 10 sites
+        for s in range(0, L + 1, 10):
+            cx = x0 + s * cw
+            canvas.raw_line(cx, top - 4, cx, top, "#98a2a8", 1.0)
+            canvas.raw_text(cx, top - 7, str(s), anchor="middle", baseline="alphabetic",
+                            size=style.font_size * 0.75)
+        if self.title:
+            canvas.raw_text((x0 + x1) / 2, top - 24, self.title, anchor="middle",
+                            size=style.font_size, weight="bold")
+        if self.legend:
+            self._legend(canvas, x0, max(y for _, y in rows) + rh / 2 + 22, style)
+
+    def _legend(self, canvas, x0, y, style):
+        sw, fs = 20.0, style.font_size * 1.15          # a visible key
+        x = x0
+        for res in ("A", "C", "G", "T"):
+            canvas.raw_rect(x, y, sw, sw, fill=self.palette.get(res, "#c8cdd2"),
+                            stroke="#ffffff", stroke_width=0.8)
+            canvas.raw_text(x + sw + 6, y + sw / 2, res, anchor="start", size=fs, weight="bold")
+            x += sw + 6 + fs * 0.8 + 16
+
+
+class States:
+    """A **categorical** matrix panel — each cell coloured by a value→colour ``palette`` (a discrete
+    sibling of :class:`Heatmap`: no gradient, no numeric scale). For character-state / presence–absence
+    matrices beside a tree — e.g. two binary characters shown as two columns of filled / open cells.
+    ``legend_labels`` maps a value to the text shown for it in the key (``{"1": "present"}``)."""
+
+    def __init__(self, matrix, *, palette=None, col_palettes=None, legend=True, legend_labels=None,
+                 title=None, col_labels=True, grid="#1a1a1a", other="#c8cdd2"):
+        if palette is None and col_palettes is None:
+            raise ValueError("states() needs palette= (one for all columns) or col_palettes= (per column)")
+        self.palette = {str(k): v for k, v in palette.items()} if palette else None
+        # a per-column palette overrides the shared one for that column (e.g. one trait per column)
+        self.col_palettes = ([{str(k): v for k, v in p.items()} for p in col_palettes]
+                             if col_palettes else None)
+        self.matrix = matrix
+        self.legend = legend
+        self.legend_labels = {str(k): v for k, v in (legend_labels or {}).items()}
+        self.title = title
+        self.col_labels = col_labels
+        self.grid = grid
+        self.other = other                 # colour for a value not in the palette
+
+    @property
+    def rows(self):
+        return self.matrix.rows
+
+    def _fill(self, j, v):
+        pal = self.col_palettes[j] if self.col_palettes else self.palette
+        return pal.get(str(v), self.other)
+
+    def draw(self, canvas, x0, x1, rows, style):
+        ncol = len(self.matrix.cols)
+        cw = (x1 - x0) / ncol
+        rh = _row_height(rows)
+        for label, y in rows:
+            for j, v in enumerate(self.matrix.row(label)):
+                canvas.raw_rect(x0 + j * cw, y - rh / 2, cw, rh,
+                                fill=self._fill(j, v),
+                                stroke=self.grid, stroke_width=0.8)
+        top = min(y for _, y in rows) - rh / 2
+        if self.col_labels:
+            for j, c in enumerate(self.matrix.cols):
+                canvas.raw_text(x0 + (j + 0.5) * cw, top - 6, str(c), anchor="middle",
+                                baseline="alphabetic", size=style.font_size, weight="bold")
+        if self.title:
+            canvas.raw_text((x0 + x1) / 2, top - 26, self.title, anchor="middle",
+                            size=style.font_size, weight="bold")
+        if self.legend and self.palette:      # a shared-palette key; per-column panels label elsewhere
+            self._legend(canvas, x0, max(y for _, y in rows) + rh / 2 + 20, style)
+
+    def _legend(self, canvas, x0, y, style):
+        sw, fs = 20.0, style.font_size
+        x = x0
+        for val, color in self.palette.items():
+            canvas.raw_rect(x, y, sw, sw, fill=color, stroke=self.grid, stroke_width=0.9)
+            text = self.legend_labels.get(val, val)
+            canvas.raw_text(x + sw + 6, y + sw / 2, text, anchor="start", size=fs)
+            x += sw + 6 + fs * 0.62 * len(text) + 18
+
+
+def heatmap(matrix, **kw) -> Heatmap:
+    """A heatmap panel for a :class:`~genustrator.matrix.Matrix` (genomes × families)."""
+    return Heatmap(matrix, **kw)
+
+
+def states(matrix, **kw) -> States:
+    """A categorical state matrix panel (rows × discrete characters), colours from a value→colour
+    ``palette`` — for presence–absence or discrete character states beside a tree."""
+    return States(matrix, **kw)
+
+
+def alignment(aln, **kw) -> Alignment:
+    """An alignment panel for an :class:`~genustrator.matrix.Alignment` (genomes × sites)."""
+    return Alignment(aln, **kw)

phylustrator/genomes/track.py

@@ -0,0 +1,59 @@
+"""Gene-arrow drawing — the domain drawer (Phylustrator's ``skeleton``, for genomes).
+
+Both the base map and the ``genes`` colouring layer draw through :func:`draw_genes`, so a gene is
+drawn one way and every layer follows. ``linear`` draws straight arrows; ``circular`` draws the same
+arrow bent along its ring.
+"""
+
+from __future__ import annotations
+
+import math
+
+
+def draw_genes(canvas, layout, color, style) -> None:
+    """Draw each gene the layout placed as an arrow pointing along its strand, filled by
+    ``color(gene)``. Reads ``layout.genes``, so single / stacked / circular all flow through here."""
+    if layout.kind == "circular":
+        _draw_circular(canvas, layout, color, style)
+    else:
+        _draw_linear(canvas, layout, color, style)
+
+
+def _draw_linear(canvas, layout, color, style) -> None:
+    hh = style.gene_height / 2.0            # half-height, in row-spacing units
+    for gene in layout.genes:
+        x0, x1, y = layout.box(gene)
+        tip = 0.4 * (x1 - x0)
+        if gene.strand >= 0:
+            pts = [(x0, y - hh), (x1 - tip, y - hh), (x1, y), (x1 - tip, y + hh), (x0, y + hh)]
+        else:
+            pts = [(x1, y - hh), (x0 + tip, y - hh), (x0, y), (x0 + tip, y + hh), (x1, y + hh)]
+        canvas.polygon(pts, fill=color(gene), stroke=style.gene_stroke,
+                       stroke_width=style.gene_stroke_width)
+
+
+def _polar(a: float, r: float) -> tuple[float, float]:
+    return r * math.cos(a), r * math.sin(a)
+
+
+def _arc(a0: float, a1: float, r: float, step: float = 0.12):
+    """Points along the arc from ``a0`` to ``a1`` at radius ``r`` (data coords)."""
+    n = max(1, int(math.ceil(abs(a1 - a0) / step)))
+    return [_polar(a0 + (a1 - a0) * i / n, r) for i in range(n + 1)]
+
+
+def _draw_circular(canvas, layout, color, style) -> None:
+    hh = layout.ring_hh
+    for gene in layout.genes:
+        a0, a1, R = layout.box(gene)
+        ri, ro = R - hh, R + hh
+        span = a1 - a0
+        tip = 0.4 * span                       # angular length of the arrowhead
+        if gene.strand >= 0:                    # arrow points toward a1
+            base = a1 - tip
+            pts = _arc(a0, base, ro) + [_polar(a1, R)] + _arc(base, a0, ri)
+        else:                                   # arrow points toward a0
+            base = a0 + tip
+            pts = _arc(base, a1, ro) + _arc(a1, base, ri) + [_polar(a0, R)]
+        canvas.polygon(pts, fill=color(gene), stroke=style.gene_stroke,
+                       stroke_width=style.gene_stroke_width)