archaeopteryx 3.14.0 → 3.16.0

package/forester.js

@@ -20,7 +20,7 @@
  *
  */
 
-// v 3.14.0
+// v 3.16.0
 // 2026-09-17
 //
 // forester.js is a general suite for dealing with phylogenetic trees.
@@ -3814,6 +3814,349 @@
     };
 
 
+    // The nodes of `list` in PREORDER -- root first, then each subtree -- which
+    // is the claim order the crowded-data rule needs and is NOT the order the
+    // layout hands out. d3's descendants() is BREADTH-first (r,a,b,a1,a2,b1),
+    // and the viewer reverses it for drawing, which puts the root LAST. Taking
+    // that order for preorder inverts the whole rule: the leaf-most mark wins
+    // and the one nearer the root is dropped, which is the opposite of what
+    // the desktop does. Measured, after a review caught it: "descendants()
+    // r,a,b,a1,a2,b1" and "reversed b1,a2,a1,b,a,r".
+    //
+    // Derived from the node objects rather than from any layout, so it cannot
+    // drift with one: the root is the member whose parent is not itself in the
+    // list, and children are visited in their own order. A node whose parent
+    // is absent (a subtree view) roots its own walk, and anything unreachable
+    // is appended so no mark is silently skipped.
+    forester.preorderOf = function (list) {
+        let present = new Set(list);
+        let out = [];
+        let seen = new Set();
+        function walk(n) {
+            if (seen.has(n)) {
+                return;
+            }
+            seen.add(n);
+            out.push(n);
+            let kids = n.children;
+            if (kids) {
+                for (let i = 0; i < kids.length; ++i) {
+                    if (present.has(kids[i])) {
+                        walk(kids[i]);
+                    }
+                }
+            }
+        }
+        for (let i = 0; i < list.length; ++i) {
+            let n = list[i];
+            if (!n.parent || !present.has(n.parent)) {
+                walk(n);
+            }
+        }
+        for (let i = 0; i < list.length; ++i) {
+            if (!seen.has(list[i])) {
+                out.push(list[i]);   // a cycle or a detached node: never dropped
+            }
+        }
+        return out;
+    };
+
+    // The box to claim for a mark that RIDES ITS BRANCH -- the circular and
+    // unrooted layouts, where a label is turned to the branch's direction
+    // instead of standing along a row. The axis-aligned bounds of the turned
+    // rectangle, centred on (cx, cy):
+    //
+    //     rot_w = |w*cos(a)| + |h*sin(a)|
+    //     rot_h = |w*sin(a)| + |h*cos(a)|
+    //
+    // The desktop's formula, verbatim (TreePanel.paintBranchDataRadial), and
+    // the second half of the joint rule below. It carries between the two
+    // programs because both measure it in real SCREEN space -- the layout's
+    // own units do not survive the trip, which is why this was parked as a
+    // divergence until forester-71 sent the arithmetic.
+    //
+    // Deliberately conservative: a diagonal label's bounds are wider than its
+    // ink, so a crowded number is dropped rather than overprinted. Exact at
+    // the right angles, worst at 45 degrees. Insensitive to the sign of the
+    // angle and to a half turn, which is what lets the 180-degree flip that
+    // keeps the far half of a fan upright leave the box alone.
+    forester.rotatedLabelBox = function (cx, cy, w, h, angle) {
+        let cos = Math.abs(Math.cos(angle));
+        let sin = Math.abs(Math.sin(angle));
+        let rw = (w * cos) + (h * sin);
+        let rh = (w * sin) + (h * cos);
+        return [cx - (rw / 2), cy - (rh / 2), rw, rh];
+    };
+
+    // The occupancy map behind "auto-hide crowded branch data": a mark is
+    // drawn only when its box overlaps nothing already granted in the same
+    // pass. Ported from the desktop's LabelOccupancy (0.11.161) as a JOINT
+    // rule on Christian's word, 2026-09-25, so neither side retunes it alone.
+    //
+    // Here rather than in the viewer because it is a pure algorithm and the
+    // suite can reach it: the parts that MUST match the desktop -- first claim
+    // wins, a refused claim records nothing, a zero-size box is granted and
+    // not recorded, and boxes that merely touch do not overlap -- are exactly
+    // the parts no screenshot would show going wrong.
+    // A uniform grid rather than all-pairs: a 13,246-tip tree with branch
+    // lengths on offers 18,511 boxes, and 171 million comparisons per redraw
+    // is not a redraw.
+    /**
+     * The same first-come space-keeping as labelOccupancy, but for boxes that
+     * are TURNED: each claim is a quadrilateral, and two of them overlap only
+     * if their own outlines do.
+     *
+     * A turned label cannot use the axis-aligned map. The bounds of a rotated
+     * rectangle grow with its length, so a long name lying near its spoke
+     * reserves several times its own area, and the map refuses neighbours that
+     * a reader can see are clear of it. Measured on a 48-label circular ring:
+     * 28 pairs "overlapping" by the bounds where the outlines gave 0, and a
+     * first-come pass over the same labels in the same order kept 48 by
+     * outline against 32 by bounds -- sixteen names dropped for nothing.
+     *
+     * The grid is still used, on each quad's bounds, to find which claims are
+     * worth testing; only the test itself is exact.
+     *
+     * @param cell - grid size, in the same units as the quads
+     * @returns an object with claim(quad) and occupy(quad); a quad is four
+     *          [x, y] corners in order round the shape
+     */
+    forester.orientedOccupancy = function (cell) {
+        let size = Math.max(4, cell);
+        let cells = new Map();
+        let boundsOf = function (quad) {
+            let x0 = quad[0][0], x1 = quad[0][0], y0 = quad[0][1], y1 = quad[0][1];
+            for (let i = 1; i < quad.length; ++i) {
+                x0 = Math.min(x0, quad[i][0]);
+                x1 = Math.max(x1, quad[i][0]);
+                y0 = Math.min(y0, quad[i][1]);
+                y1 = Math.max(y1, quad[i][1]);
+            }
+            return [x0, y0, x1, y1];
+        };
+        // Separating-axis test. A rectangle's own two edge normals are enough
+        // for itself, but BOTH shapes' normals are needed: with only one
+        // shape's, a box that clears another along the OTHER's axis is
+        // reported as overlapping. Strict, so shapes that merely touch do not
+        // overlap -- as in labelOccupancy.
+        let overlaps = function (P, Q) {
+            for (let s = 0; s < 2; ++s) {
+                let R = s === 0 ? P : Q;
+                for (let k = 0; k < 2; ++k) {
+                    let ax = R[k + 1][1] - R[k][1];
+                    let ay = R[k][0] - R[k + 1][0];
+                    let p0 = Infinity, p1 = -Infinity, q0 = Infinity, q1 = -Infinity;
+                    for (let i = 0; i < P.length; ++i) {
+                        let d = (P[i][0] * ax) + (P[i][1] * ay);
+                        p0 = Math.min(p0, d);
+                        p1 = Math.max(p1, d);
+                    }
+                    for (let i = 0; i < Q.length; ++i) {
+                        let d = (Q[i][0] * ax) + (Q[i][1] * ay);
+                        q0 = Math.min(q0, d);
+                        q1 = Math.max(q1, d);
+                    }
+                    if (p1 <= q0 || q1 <= p0) {
+                        return false;
+                    }
+                }
+            }
+            return true;
+        };
+        let record = function (quad, b) {
+            let c1 = Math.floor(b[2] / size);
+            let r1 = Math.floor(b[3] / size);
+            for (let c = Math.floor(b[0] / size); c <= c1; ++c) {
+                for (let r = Math.floor(b[1] / size); r <= r1; ++r) {
+                    let key = c + ':' + r;
+                    let bucket = cells.get(key);
+                    if (!bucket) {
+                        bucket = [];
+                        cells.set(key, bucket);
+                    }
+                    bucket.push(quad);
+                }
+            }
+        };
+        let free = function (quad, b) {
+            let seen = null;
+            let c1 = Math.floor(b[2] / size);
+            let r1 = Math.floor(b[3] / size);
+            for (let c = Math.floor(b[0] / size); c <= c1; ++c) {
+                for (let r = Math.floor(b[1] / size); r <= r1; ++r) {
+                    let bucket = cells.get(c + ':' + r);
+                    if (!bucket) {
+                        continue;
+                    }
+                    for (let i = 0; i < bucket.length; ++i) {
+                        // a quad spans several cells, so the same one comes up
+                        // more than once; the test is the expensive part
+                        if (seen === null) {
+                            seen = new Set();
+                        }
+                        if (seen.has(bucket[i])) {
+                            continue;
+                        }
+                        seen.add(bucket[i]);
+                        if (overlaps(quad, bucket[i])) {
+                            return false;
+                        }
+                    }
+                }
+            }
+            return true;
+        };
+        let degenerate = function (quad) {
+            if (!quad || quad.length !== 4) {
+                return true;
+            }
+            let b = boundsOf(quad);
+            return !((b[2] - b[0]) > 0) || !((b[3] - b[1]) > 0);
+        };
+        return {
+            claim: function (quad) {
+                if (degenerate(quad)) {
+                    return true;   // reserves nothing, as a zero-size box does
+                }
+                let b = boundsOf(quad);
+                if (!free(quad, b)) {
+                    return false;
+                }
+                record(quad, b);
+                return true;
+            },
+            // record without asking, for what is drawn whatever else is there
+            occupy: function (quad) {
+                if (degenerate(quad)) {
+                    return true;
+                }
+                let b = boundsOf(quad);
+                let clear = free(quad, b);
+                record(quad, b);
+                return clear;
+            }
+        };
+    };
+
+    forester.labelOccupancy = function (cell) {
+        let size = Math.max(4, cell);
+        let cells = new Map();
+        let record = function (x, y, w, h) {
+            let box = [x, y, w, h];
+            let c1 = Math.floor((x + w) / size);
+            let r1 = Math.floor((y + h) / size);
+            for (let c = Math.floor(x / size); c <= c1; ++c) {
+                for (let r = Math.floor(y / size); r <= r1; ++r) {
+                    let key = c + ':' + r;
+                    let bucket = cells.get(key);
+                    if (!bucket) {
+                        bucket = [];
+                        cells.set(key, bucket);
+                    }
+                    bucket.push(box);
+                }
+            }
+        };
+        let free = function (x, y, w, h) {
+            let c1 = Math.floor((x + w) / size);
+            let r1 = Math.floor((y + h) / size);
+            for (let c = Math.floor(x / size); c <= c1; ++c) {
+                for (let r = Math.floor(y / size); r <= r1; ++r) {
+                    let bucket = cells.get(c + ':' + r);
+                    if (!bucket) {
+                        continue;
+                    }
+                    for (let i = 0; i < bucket.length; ++i) {
+                        let b = bucket[i];
+                        // strict: boxes that merely touch do not overlap
+                        if (x < (b[0] + b[2]) && (x + w) > b[0]
+                            && y < (b[1] + b[3]) && (y + h) > b[1]) {
+                            return false;
+                        }
+                    }
+                }
+            }
+            return true;
+        };
+        return {
+            // true when nothing already granted overlaps, and then recorded
+            claim: function (x, y, w, h) {
+                if (!(w > 0) || !(h > 0)) {
+                    return true;   // reserves no space; recording it would only cost comparisons
+                }
+                if (!free(x, y, w, h)) {
+                    return false;
+                }
+                record(x, y, w, h);
+                return true;
+            },
+            // Record without asking, for what is drawn whatever else is there.
+            // A refused CLAIM records nothing, so a label put through claim()
+            // and refused would leave the space open and let a number print
+            // straight through the name it lost to -- the opposite of the
+            // point. Returns whether the space was clear, for measurement;
+            // the box is recorded either way.
+            occupy: function (x, y, w, h) {
+                if (!(w > 0) || !(h > 0)) {
+                    return true;
+                }
+                let clear = free(x, y, w, h);
+                record(x, y, w, h);
+                return clear;
+            }
+        };
+    };
+
+    // Where a protein domain can be read about, as {url, exact} or null.
+    //
+    // An InterPro ENTRY is addressed by ACCESSION and by nothing else --
+    // measured, not assumed: /api/entry/pfam/PF00931/ answers 200 and names
+    // NB-ARC, while /api/entry/pfam/NB-ARC/, /CARD/ and /Death/ are all 404.
+    // phyloXML's <domain id="..."> carries the accession when the annotation
+    // had one, and most files have none (our own apaf.xml names all 166 of its
+    // boxes and gives not one an id), so the fallback is an InterPro text
+    // search.
+    //
+    // The search goes by NAME, never by the id. An id that is not a bare Pfam
+    // accession -- a versioned one from an hmmscan (PF00931.24), or a SMART or
+    // CDD accession -- searches to nothing, while the name is exactly what a
+    // text search is for. A version suffix is stripped for the entry URL
+    // rather than disqualifying it: PF00931.24 IS PF00931.
+    //
+    // Lives here rather than in the viewer so it can be tested: a wrong URL
+    // fails silently in someone else's browser, which is the worst place to
+    // find out.
+    const INTERPRO_ENTRY = 'https://www.ebi.ac.uk/interpro/entry/pfam/';
+    const INTERPRO_SEARCH = 'https://www.ebi.ac.uk/interpro/search/text/';
+
+    forester.domainReference = function (domain) {
+        if (!domain) {
+            return null;
+        }
+        let id = (domain.id || '').trim();
+        let acc = /^(PF\d{5,})(?:\.\d+)?$/i.exec(id);
+        if (acc) {
+            return {url: INTERPRO_ENTRY + acc[1].toUpperCase() + '/', exact: true};
+        }
+        let q = (domain.name || '').trim() || id;
+        return q ? {url: INTERPRO_SEARCH + encodeURIComponent(q) + '/', exact: false} : null;
+    };
+
+    // A domain's E-value for display. It spans many orders of magnitude, so a
+    // small one keeps its exponent; the count of significant digits is the
+    // only thing normalized, because a scan writes 7.2E-117 and 1E-6 and a
+    // readout that mixed those forms would read as two different measures.
+    forester.domainEvalueText = function (e) {
+        if (typeof e !== 'number' || !isFinite(e)) {
+            return null;
+        }
+        if (e === 0) {
+            return '0';
+        }
+        return (Math.abs(e) >= 0.001 && Math.abs(e) < 1e7)
+            ? String(forester.roundNumber(e, 6)) : e.toExponential(2);
+    };
+
     // Everything the Tree Properties dialog reports, gathered in ONE pass:
     // the desktop's TreeFacts.scan, minus its histogram (Christian, 2026-09-23:
     // "we don't need a histogram ... but a more detailed stats would be
@@ -6933,7 +7276,13 @@
                 ignored++;
                 return;
             }
-            domains.push({name: d.name ? String(d.name) : '', from: from, to: to, length: to - from + 1, evalue: e});
+            // `id` is phyloXML's optional domain identifier, which for a Pfam
+            // scan is the accession (PF00931). Carried through because the
+            // hover readout links to the entry with it when it is there, and
+            // has to search by name when it is not -- apaf.xml, our own domain
+            // demo, has names and no ids at all.
+            domains.push({name: d.name ? String(d.name) : '', from: from, to: to,
+                length: to - from + 1, evalue: e, id: d.id ? String(d.id) : ''});
         });
         domains.sort(function (a, b) {
             return a.from - b.from;
@@ -7035,7 +7384,8 @@
             if (!(w > 0) || !isFinite(w)) {
                 return;
             }
-            boxes.push({name: d.name, x: start + ((d.from - 1) * f), w: w, from: d.from, to: d.to, evalue: d.evalue});
+            boxes.push({name: d.name, x: start + ((d.from - 1) * f), w: w, from: d.from, to: d.to,
+                evalue: d.evalue, id: d.id});
         });
         return {backbone: {x: start, w: Number(da.length) * f}, boxes: boxes};
     };

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "archaeopteryx",
-  "version": "3.14.0",
+  "version": "3.16.0",
   "description": "Archaeopteryx.js is a software tool for the visualization and analysis of highly annotated phylogenetic trees.",
   "main": "archaeopteryx.js",
   "types": "archaeopteryx.d.ts",
@@ -25,7 +25,9 @@
     "lint:fix": "eslint . --fix",
     "format": "prettier --write .",
     "format:check": "prettier --check .",
-    "docs:sync": "cp archaeopteryx.js forester.js docs/lib/"
+    "docs:sync": "cp archaeopteryx.js forester.js docs/lib/",
+    "test:browser": "node test/browser/run.js",
+    "test:browser:quick": "node test/browser/run.js --quick"
   },
   "repository": {
     "type": "git",