phylustrator 0.2.3__tar.gz → 0.2.4__tar.gz

{phylustrator-0.2.3/src/phylustrator.egg-info → phylustrator-0.2.4}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: phylustrator
-Version: 0.2.3
+Version: 0.2.4
 Summary: A composable plotter for evolutionary figures: phylogenetic trees, genomes, synteny and alignments
 Author-email: "Adrian A. Davin" <aaredav@gmail.com>
 License: MIT

{phylustrator-0.2.3 → phylustrator-0.2.4}/pyproject.toml

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

{phylustrator-0.2.3 → phylustrator-0.2.4}/src/phylustrator/genomes/figure.py

@@ -57,6 +57,14 @@ class Figure:
             layer(canvas, primary, layout, self.style)
         return canvas
 
+    def extent(self) -> tuple[tuple[float, float], tuple[float, float]]:
+        """The ``(xlim, ylim)`` the canvas fits to, in layout units — the figure's shape before any
+        page size is chosen. Sizing several canvases from this puts their figures on one absolute
+        scale, which is what comparing genomes side by side needs: a genome half the size of another
+        should be drawn half the size, not blown up to fill its own square."""
+        layout = self._make_layout()
+        return layout.xlim, layout.ylim
+
     def as_svg(self) -> str:
         return self._build().as_svg()
 
@@ -106,8 +114,8 @@ def _draw_base(canvas: Canvas, layout: Layout, style: Style) -> None:
         if getattr(style, "ring_backbone", True):
             dash = getattr(style, "gene_style", "arrow") != "wedge"     # arrow: dashed loop; wedge: the classic solid one
             color, width = ("#c9d2ce", 1.2) if dash else ("#d8ddda", 1.4)
-            for R in layout.rings or []:
-                canvas.data_ring(R, color, width, dash=dash)
+            for k, R in enumerate(layout.rings or []):
+                canvas.data_ring(R, color, width, dash=dash, centre=layout.ring_centre(k))
     else:
         for y, x0, x1 in layout.backbones:
             canvas.line(x0, y, x1, y, "#d8ddda", 1.4)

{phylustrator-0.2.3 → phylustrator-0.2.4}/src/phylustrator/genomes/layers/guides.py

@@ -43,16 +43,21 @@ def _linear(canvas, layout, style, label, ticks) -> None:
 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
+    # the axis sits inside the innermost circle — and on *its* centre, which a row of circles moves
+    k = min(range(len(layout.rings)), key=lambda i: layout.rings[i]) if layout.rings else 0
+    R0 = layout.rings[k] if layout.rings else 0.85
+    cx, cy = layout.ring_centre(k)
+    inner = R0 - layout.half_height(R0) - 0.06
+    canvas.data_ring(inner, "#c7d0cc", 1.0, centre=(cx, cy))      # 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.line(cx + inner * math.cos(a), cy + inner * math.sin(a),
+                    cx + (inner - 0.03) * math.cos(a), cy + (inner - 0.03) * math.sin(a),
+                    "#5a6763", 1.1)
+        lx, ly = cx + (inner - 0.10) * math.cos(a), cy + (inner - 0.10) * math.sin(a)
         canvas.text(lx, ly, _fmt_bp(v), anchor="middle", size=small)
         v += step
 

{phylustrator-0.2.3 → phylustrator-0.2.4}/src/phylustrator/genomes/layers/highlight.py

@@ -33,11 +33,12 @@ def highlight(genome, chromosome=None, start: int = 0, end: int = 0, *,
             a_lo = min(min(b[0], b[1]) for b in boxes)
             a_hi = max(max(b[0], b[1]) for b in boxes)
             R = boxes[0][2]
-            hh = layout.ring_hh * 1.9 + pad                 # a halo a touch wider than the genes
-            band = _arc(a_lo, a_hi, R + hh) + _arc(a_hi, a_lo, R - hh)
+            c = layout.centre(sel[0])                       # the circle this chromosome is drawn on
+            hh = layout.half_height(R) * 1.9 + pad          # a halo a touch wider than the genes
+            band = _arc(a_lo, a_hi, R + hh, c=c) + _arc(a_hi, a_lo, R - hh, c=c)
             canvas.polygon(band, fill=color, opacity=0.55, stroke=color, stroke_width=1.2)
             if label:
-                mx, my = _polar((a_lo + a_hi) / 2.0, R + hh + 0.06)
+                mx, my = _polar((a_lo + a_hi) / 2.0, R + hh + 0.06, c)
                 canvas.text(mx, my, label, anchor="middle", color=color, size=style.font_size)
             return
         x0 = min(b[0] for b in boxes)

{phylustrator-0.2.3 → phylustrator-0.2.4}/src/phylustrator/genomes/layout.py

@@ -29,7 +29,10 @@ class Layout:
     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_centres: list = field(default_factory=list)   # circular: (cx, cy) per ring; empty = origin
     ring_hh: float = 0.0                               # circular: gene half-height, radius units
+    ring_hh_rel: float | None = None                   # circular: if set, half-height is this × R
+    centres: dict = field(default_factory=dict)        # circular: id(gene) -> (cx, cy); absent = origin
     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
@@ -38,6 +41,21 @@ class Layout:
     def box(self, gene):
         return self.boxes[id(gene)]
 
+    def centre(self, gene) -> tuple[float, float]:
+        """The circle a gene is drawn on. Concentric rings all sit on the origin; a row of circles
+        gives each chromosome its own centre."""
+        cx, cy = self.centres.get(id(gene), (0.0, 0.0))
+        return float(cx), float(cy)
+
+    def half_height(self, R: float) -> float:
+        """Gene half-thickness at radius ``R``. Concentric rings share one thickness, since they are
+        all much the same size. A row scales it with the circle, so a three-gene chromosome beside a
+        hundred-gene one is drawn as a small circle rather than as a blob."""
+        return self.ring_hh if self.ring_hh_rel is None else self.ring_hh_rel * R
+
+    def ring_centre(self, k: int) -> tuple[float, float]:
+        return self.ring_centres[k] if self.ring_centres else (0.0, 0.0)
+
 
 def linear(genome, *, coordinates: str = "ordered", gap: float = 0.16, style=None) -> Layout:
     """Genes on one horizontal track per chromosome."""
@@ -90,41 +108,78 @@ def stacked(genomes, *, coordinates: str = "ordered", gap: float = 0.16,
 
 
 def circular(genome, *, coordinates: str = "ordered", gap: float = 0.16,
-             start_deg: float = 90.0, break_deg: float = 0.0, scale: str = "each",
-             band: float = 0.34, ring_gap: float = 0.10, min_deg: float = 2.2, style=None) -> Layout:
-    """Genes wrapped onto a ring, one concentric ring per chromosome (chromosome 0 outermost).
+             start_deg: float = 90.0, break_deg: float = 0.0, scale: str | float = "each",
+             arrange: str = "concentric", band: float = 0.34, ring_gap: float = 0.10,
+             row_gap: float = 0.22, min_deg: float = 2.2, style=None) -> Layout:
+    """Genes wrapped onto a ring, one ring per chromosome (chromosome 0 outermost / leftmost).
 
     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"``).
 
-    ``scale`` decides what a ring's angles mean when a genome has several chromosomes:
+    ``arrange`` places the chromosomes of a multi-chromosome genome:
+
+    ``"concentric"`` (default) nests them as rings about one centre — the classic single-genome map.
+    ``"row"`` gives each chromosome its own circle, left to right: a **karyotype**, where the
+    chromosomes are separate objects rather than tracks of one map.
 
-    ``"each"`` (default) gives every chromosome the whole circle, so gene *order* is comparable ring
-    to ring and a chromosome's size is not. ``"shared"`` gives every gene the same angular width,
-    taken from the largest chromosome, so a short chromosome draws a short arc — which is what a
-    **karyotype** needs. Under ``"each"`` a three-gene chromosome is a full circle of three enormous
-    wedges beside a seventy-gene ring, and the picture says they are the same size."""
+    ``scale`` decides what a chromosome's size means. ``"each"`` (default) draws every chromosome the
+    same: a whole circle concentric, or an equal-sized circle in a row — gene *order* is then
+    comparable chromosome to chromosome and size is not. ``"shared"`` draws them to one scale, taken
+    from the largest: in a row the radius follows the gene count, so a gene takes the same arc
+    *length* in every circle; concentric, a short chromosome draws a short arc rather than a full
+    circle of enormous wedges. Pass a **number** instead to fix that reference explicitly — the same
+    value across several figures puts them all on one scale, which is what comparing the karyotypes
+    of different genomes needs."""
     start = math.radians(start_deg)
     sweep = 2.0 * math.pi - math.radians(break_deg)
-    boxes, owner, placed, rings, totals = {}, {}, [], [], []
-    if scale not in ("each", "shared"):
-        raise ValueError(f"unknown scale {scale!r}; choose 'each' or 'shared'")
-    widest = max((len(c.genes) for c in genome.chromosomes), default=1) or 1
+    boxes, owner, placed, rings, totals, centres, ring_centres = {}, {}, [], [], [], {}, []
+    if arrange not in ("concentric", "row"):
+        raise ValueError(f"unknown arrange {arrange!r}; choose 'concentric' or 'row'")
+    sizes = [len(c.genes) for c in genome.chromosomes]
+    if isinstance(scale, str):
+        if scale not in ("each", "shared"):
+            raise ValueError(f"unknown scale {scale!r}; choose 'each', 'shared', or a number")
+        reference = float(max(sizes, default=1) or 1) if scale == "shared" else 0.0
+    else:
+        reference = float(scale)
+        if reference <= 0:
+            raise ValueError(f"scale must be a positive number of genes, not {scale!r}")
+    gstyle = getattr(style, "gene_style", "arrow") if style is not None else "arrow"
+    frac = getattr(style, "ring_gene_frac", None) if style is not None else None
+    if frac is None:                            # chunky "arrow" vs the classic thin "wedge"
+        frac = 0.11 if gstyle == "wedge" else 0.30
+    hh = band * frac                            # gene half-thickness
+    # A row sizes each circle by its own gene count, so the thickness has to follow the circle:
+    # one absolute thickness would swallow the small chromosomes whole.
+    rel = hh / max(1.0 - band / 2.0, 1e-9)      # thickness as a fraction of the circle
+    hh_rel = rel if arrange == "row" else None
+    cursor = 0.0
     for k, chrom in enumerate(genome.chromosomes):
-        R = 1.0 - band / 2.0 - k * (band + ring_gap)
-        rings.append(R)
         n = len(chrom.genes)
+        if arrange == "row":
+            R = (n / reference) if reference else 1.0
+            R = max(R, 1e-3)
+            rings.append(R)
+            cx = cursor + R * (1.0 + rel)
+            cursor = cx + R * (1.0 + rel) + row_gap
+            ring_centres.append((cx, 0.0))
+        else:
+            R = 1.0 - band / 2.0 - k * (band + ring_gap)
+            rings.append(R)
+            cx = 0.0
+            ring_centres.append((0.0, 0.0))
         nuc = coordinates == "nucleotide" and n and chrom.genes[0].start is not None
+        # concentric + a reference: the chromosome takes the fraction of the circle it is worth.
+        # A row already says that with the radius, so its angles always run all the way round.
         total = float(chrom.length or (chrom.genes[-1].end - chrom.genes[0].start) or 1.0) if nuc \
-            else float(widest if scale == "shared" else (n or 1))
+            else float(reference if (reference and arrange == "concentric") else (n or 1))
         totals.append(total)
         # cap the minimum arc so a gene-dense genome (a real GFF) never forces genes to overlap.
         # The cap counts the ring's own slots: under "shared" that is the widest chromosome, so a
         # short ring is never inflated back to the width it would have had on its own.
         min_arc = min(math.radians(min_deg), 0.9 * sweep / max(n if nuc else total, 1.0))
-        _ = style  # (thickness is read from style at draw time via ring_hh below)
         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)
@@ -135,14 +190,15 @@ def circular(genome, *, coordinates: str = "ordered", gap: float = 0.16,
                 a0, a1 = mid + min_arc / 2.0, mid - min_arc / 2.0
             boxes[id(gene)] = (a0, a1, R)
             owner[id(gene)] = (genome, chrom)
+            centres[id(gene)] = (cx, 0.0)
             placed.append(gene)
-    gstyle = getattr(style, "gene_style", "arrow") if style is not None else "arrow"
-    frac = getattr(style, "ring_gene_frac", None) if style is not None else None
-    if frac is None:                            # chunky "arrow" vs the classic thin "wedge"
-        frac = 0.11 if gstyle == "wedge" else 0.30
-    hh = band * frac                            # gene half-thickness
-    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,
+    if arrange == "row":
+        tall = max(((R * (1.0 + rel)) for R in rings), default=1.0)
+        xlim, ylim = (0.0, max(cursor - row_gap, 1e-6)), (-tall, tall)
+    else:
+        outer = (rings[0] if rings else 1.0) + hh
+        xlim = ylim = (-outer, outer)
+    return Layout("circular", boxes, xlim, ylim, rows=len(genome.chromosomes),
+                  genes=placed, owner=owner, rings=rings, ring_centres=ring_centres,
+                  ring_hh=hh, ring_hh_rel=hh_rel, centres=centres, equal_aspect=True,
                   track_order=[genome], angle_start=start, angle_sweep=sweep, totals=totals)

{phylustrator-0.2.3 → phylustrator-0.2.4}/src/phylustrator/genomes/track.py

@@ -32,24 +32,25 @@ def _draw_linear(canvas, layout, color, style) -> None:
                        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 _polar(a: float, r: float, c: tuple[float, float] = (0.0, 0.0)) -> tuple[float, float]:
+    return c[0] + r * math.cos(a), c[1] + r * math.sin(a)
 
 
-def _arc(a0: float, a1: float, r: float, step: float = 0.12):
+def _arc(a0: float, a1: float, r: float, step: float = 0.12, c: tuple[float, float] = (0.0, 0.0)):
     """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)]
+    return [_polar(a0 + (a1 - a0) * i / n, r, c) for i in range(n + 1)]
 
 
 def _draw_circular(canvas, layout, color, style) -> None:
     """Each gene an arrow bent along its ring. ``gene_style="arrow"`` (default) is a chunky body with a
     flared arrowhead (head wider than the body, tapering to a point — the beautiful genome look);
     ``"wedge"`` is the thin, un-flared shape."""
-    hh = layout.ring_hh
     chunky = getattr(style, "gene_style", "arrow") != "wedge"
     for gene in layout.genes:
         a0, a1, R = layout.box(gene)
+        c = layout.centre(gene)                 # a row of circles gives each chromosome its own
+        hh = layout.half_height(R)
         ri, ro = R - hh, R + hh
         span = a1 - a0
         tip = min(0.45 * span, math.radians(11.0))   # arrowhead angular length (capped for long genes)
@@ -58,14 +59,14 @@ def _draw_circular(canvas, layout, color, style) -> None:
         head_hh = max(hh, min(hh * 1.5, R * tip)) if chunky else hh
         if gene.strand >= 0:                    # arrow points toward a1
             base = a1 - tip
-            pts = (_arc(a0, base, ro)
-                   + [_polar(base, R + head_hh), _polar(a1, R), _polar(base, R - head_hh)]
-                   + _arc(base, a0, ri))
+            pts = (_arc(a0, base, ro, c=c)
+                   + [_polar(base, R + head_hh, c), _polar(a1, R, c), _polar(base, R - head_hh, c)]
+                   + _arc(base, a0, ri, c=c))
         else:                                   # arrow points toward a0
             base = a0 + tip
-            pts = ([_polar(a0, R), _polar(base, R + head_hh)]
-                   + _arc(base, a1, ro)
-                   + _arc(a1, base, ri)
-                   + [_polar(base, R - head_hh)])
+            pts = ([_polar(a0, R, c), _polar(base, R + head_hh, c)]
+                   + _arc(base, a1, ro, c=c)
+                   + _arc(a1, base, ri, c=c)
+                   + [_polar(base, R - head_hh, c)])
         canvas.polygon(pts, fill=color(gene), stroke=style.gene_stroke,
                        stroke_width=style.gene_stroke_width)

{phylustrator-0.2.3 → phylustrator-0.2.4}/src/phylustrator/render.py

@@ -148,10 +148,12 @@ class Canvas:
         p.Z()
         self._d.append(p)
 
-    def data_ring(self, r: float, color: str, width: float, *, dash: bool = False) -> None:
-        """A circle of *data* radius ``r`` centred on the data origin (a chromosome backbone / ruler)."""
-        cx, cy = self.px(0.0), self.py(0.0)
-        rpx = self.px(r) - cx
+    def data_ring(self, r: float, color: str, width: float, *, dash: bool = False,
+                  centre: tuple[float, float] = (0.0, 0.0)) -> None:
+        """A circle of *data* radius ``r`` (a chromosome backbone / ruler), on the data origin unless
+        ``centre`` moves it — a karyotype draws each chromosome on its own centre."""
+        cx, cy = self.px(centre[0]), self.py(centre[1])
+        rpx = self.px(centre[0] + r) - cx
         extra = {"stroke_dasharray": "5,4"} if dash else {}
         self._d.append(draw.Circle(cx, cy, abs(rpx), fill="none", stroke=color,
                                    stroke_width=width, **extra))

{phylustrator-0.2.3 → phylustrator-0.2.4/src/phylustrator.egg-info}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: phylustrator
-Version: 0.2.3
+Version: 0.2.4
 Summary: A composable plotter for evolutionary figures: phylogenetic trees, genomes, synteny and alignments
 Author-email: "Adrian A. Davin" <aaredav@gmail.com>
 License: MIT

{phylustrator-0.2.3 → phylustrator-0.2.4}/tests/test_genomes.py

@@ -74,6 +74,46 @@ def test_circular_shared_scale_shortens_the_small_chromosome():
         circular(g, scale="both")
 
 
+def _karyotype():
+    big = _genome("g", list("12345678")).chromosomes[0]
+    small = Chromosome(id="c2", genes=_genome("s", ["9", "10"]).chromosomes[0].genes,
+                       topology="circular", length=200)
+    return Genome(name="k", chromosomes=[big, small]), big, small
+
+
+def test_circular_row_puts_each_chromosome_on_its_own_circle():
+    """A karyotype: ``arrange="row"`` gives every chromosome a centre of its own, left to right."""
+    g, big, small = _karyotype()
+    lay = circular(g, arrange="row")
+    cx = [lay.centre(c.genes[0])[0] for c in (big, small)]
+    assert cx[0] < cx[1]                                  # chromosome 0 leftmost
+    assert len(set(lay.ring_centres)) == 2
+    assert lay.xlim[1] - lay.xlim[0] > lay.ylim[1] - lay.ylim[0]     # a row is wider than it is tall
+    assert (plot(g, layout="circular", arrange="row") + genes(by="family")).as_svg().startswith("<")
+    with pytest.raises(ValueError, match="unknown arrange"):
+        circular(g, arrange="stack")
+
+
+def test_circular_row_scale_shared_sizes_the_circle_by_gene_count():
+    """Under ``scale="shared"`` the radius follows the gene count, so the thickness must follow it
+    too — one absolute thickness would draw the short chromosome as a blob."""
+    g, big, small = _karyotype()
+    each, shared = circular(g, arrange="row"), circular(g, arrange="row", scale="shared")
+    assert each.rings[0] == each.rings[1]                      # every circle the same
+    assert shared.rings[1] == pytest.approx(shared.rings[0] * 2 / 8)
+    assert shared.half_height(shared.rings[1]) < shared.half_height(shared.rings[0])
+    # a number fixes the reference explicitly, so two genomes can be drawn to one scale
+    assert circular(g, arrange="row", scale=16).rings[0] == pytest.approx(0.5)
+    with pytest.raises(ValueError, match="positive number"):
+        circular(g, scale=0)
+
+
+def test_extent_reports_the_layout_the_canvas_fits_to():
+    g, _, _ = _karyotype()
+    fig = plot(g, layout="circular", arrange="row")
+    assert fig.extent() == (circular(g, arrange="row").xlim, circular(g, arrange="row").ylim)
+
+
 def test_heatmap_panel_beside_tree():
     tree = tree_plot(loads("(a:1,b:1)R;"))
     m = Matrix(rows=["a", "b"], cols=["f1", "f2", "f3"], values=[[1, 0, 2], [0, 1, 1]])