archaeopteryx 3.13.0 → 3.15.0

package/forester.js

@@ -20,7 +20,7 @@
  *
  */
 
-// v 3.13.0
+// v 3.15.0
 // 2026-09-17
 //
 // forester.js is a general suite for dealing with phylogenetic trees.
@@ -3814,6 +3814,411 @@
     };
 
 
+    // 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.
+    forester.labelOccupancy = function (cell) {
+        let size = Math.max(4, cell);
+        let cells = new Map();
+        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
+                }
+                let c0 = Math.floor(x / size), c1 = Math.floor((x + w) / size);
+                let r0 = Math.floor(y / size), r1 = Math.floor((y + h) / size);
+                for (let c = c0; c <= c1; ++c) {
+                    for (let r = r0; 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;
+                            }
+                        }
+                    }
+                }
+                let box = [x, y, w, h];
+                for (let c = c0; c <= c1; ++c) {
+                    for (let r = r0; r <= r1; ++r) {
+                        let key = c + ':' + r;
+                        let bucket = cells.get(key);
+                        if (!bucket) {
+                            bucket = [];
+                            cells.set(key, bucket);
+                        }
+                        bucket.push(box);
+                    }
+                }
+                return true;
+            }
+        };
+    };
+
+    // 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
+    // useful, min, median, max, n, also type ... also need to include the
+    // properties").
+    //
+    // Side-effect free and DOM-free, so it can be tested in Node -- the whole
+    // reason it lives here rather than in the dialog that renders it, which is
+    // the same split the desktop makes between TreeFacts and
+    // TreePropertiesForm.
+    //
+    // Support values are grouped BY TYPE, because a tree can carry a bootstrap
+    // and a posterior on the same branch and their ranges are not comparable
+    // (0-100 against 0-1); averaging them together would produce a number that
+    // describes neither. MAD values are excluded for the same reason they are
+    // excluded from the Newick support slot: they rate a root position, not a
+    // clade.
+    forester.treeStatistics = function (phyOrNode) {
+        // Callers hand this either a phylogeny wrapper or the root node, and
+        // the difference is one extra internal node, one extra branch and one
+        // more of depth -- small enough to read as plausible. getTreeRoot
+        // normalizes both, as collectBasicTreeProperties does.
+        let root = phyOrNode ? forester.getTreeRoot(phyOrNode) : null;
+        let stats = {
+            tips: 0, internal: 0, nodes: 0, branches: 0,
+            polytomies: 0, maxChildren: 0,
+            depth: 0, height: 0, heightKnown: false,
+            collapsed: 0,
+            branchLengths: null,
+            support: [],
+            ultrametric: false,
+            tipsWithTaxonomy: 0, distinctTaxonomies: 0, tipsWithTaxonomyId: 0,
+            tipsWithSequence: 0, tipsWithMolSeq: 0, tipsWithDomains: 0,
+            nodesWithDate: 0, tipsWithDistribution: 0, namedInternal: 0,
+            duplications: 0, speciations: 0, nodesWithEvents: 0,
+            propertyRefs: []
+        };
+        if (!root) {
+            return stats;
+        }
+        let lengths = [];
+        let zeroLengths = 0;
+        let negativeLengths = 0;
+        let byType = Object.create(null);
+        let taxa = Object.create(null);
+        let refs = Object.create(null);
+        let refOrder = [];
+        let tipDepths = [];
+        let maxDepth = 0;
+
+        (function walk(n, depth, distance) {
+            ++stats.nodes;
+            let kids = n.children || [];
+            if (depth > maxDepth) {
+                maxDepth = depth;
+            }
+            if (n !== root) {
+                ++stats.branches;
+                let b = n.branch_length;
+                if (typeof b === 'number' && isFinite(b)) {
+                    lengths.push(b);
+                    if (b === 0) {
+                        ++zeroLengths;
+                    } else if (b < 0) {
+                        ++negativeLengths;
+                    }
+                    distance += b;
+                }
+            }
+            // support, by type, MAD left out
+            if (n.confidences) {
+                for (let i = 0; i < n.confidences.length; ++i) {
+                    let c = n.confidences[i];
+                    if (c.type === forester.MAD_CONFIDENCE_TYPE) {
+                        continue;
+                    }
+                    if (typeof c.value !== 'number' || !isFinite(c.value)) {
+                        continue;
+                    }
+                    let key = c.type || '';
+                    if (!byType[key]) {
+                        byType[key] = [];
+                        stats.support.push({type: key, values: byType[key]});
+                    }
+                    byType[key].push(c.value);
+                }
+            }
+            if (n.date && typeof n.date.value === 'number' && isFinite(n.date.value)) {
+                ++stats.nodesWithDate;
+            }
+            if (n.properties) {
+                let seen = Object.create(null);
+                for (let i = 0; i < n.properties.length; ++i) {
+                    let ref = n.properties[i] && n.properties[i].ref;
+                    if (!ref || seen[ref]) {
+                        continue;   // a node carrying a ref twice counts once
+                    }
+                    seen[ref] = true;
+                    if (refs[ref] === undefined) {
+                        refs[ref] = 0;
+                        refOrder.push(ref);
+                    }
+                    ++refs[ref];
+                }
+            }
+            if (n.events) {
+                ++stats.nodesWithEvents;
+                if (n.events.duplications > 0) {
+                    stats.duplications += n.events.duplications;
+                }
+                if (n.events.speciations > 0) {
+                    stats.speciations += n.events.speciations;
+                }
+            }
+            if (kids.length > 0) {
+                ++stats.internal;
+                if (kids.length > stats.maxChildren) {
+                    stats.maxChildren = kids.length;
+                }
+                if (kids.length > 2) {
+                    ++stats.polytomies;
+                }
+                if (n !== root && n.name) {
+                    ++stats.namedInternal;
+                }
+                for (let i = 0; i < kids.length; ++i) {
+                    walk(kids[i], depth + 1, distance);
+                }
+                return;
+            }
+            ++stats.tips;
+            tipDepths.push(distance);
+            if (n.taxonomies && n.taxonomies.length > 0) {
+                ++stats.tipsWithTaxonomy;
+                let t = n.taxonomies[0];
+                let label = t.scientific_name || t.code || t.common_name || '';
+                if (label) {
+                    taxa[label] = true;
+                }
+                if (t.id && t.id.value) {
+                    ++stats.tipsWithTaxonomyId;
+                }
+            }
+            if (n.sequences && n.sequences.length > 0) {
+                ++stats.tipsWithSequence;
+                let q = n.sequences[0];
+                if (q.mol_seq && q.mol_seq.value) {
+                    ++stats.tipsWithMolSeq;
+                }
+                if (forester.domainArchitectureOf(n)) {
+                    ++stats.tipsWithDomains;
+                }
+            }
+            if (n.distributions && n.distributions.length > 0) {
+                ++stats.tipsWithDistribution;
+            }
+        })(root, 0, 0);
+
+        stats.depth = maxDepth;
+        stats.distinctTaxonomies = Object.keys(taxa).length;
+        stats.propertyRefs = refOrder.map(function (r) {
+            return {ref: r, nodes: refs[r]};
+        });
+        stats.branchLengths = forester.describeValues(lengths);
+        if (stats.branchLengths) {
+            stats.branchLengths.zero = zeroLengths;
+            stats.branchLengths.negative = negativeLengths;
+        }
+        stats.support = stats.support.map(function (g) {
+            let d = forester.describeValues(g.values);
+            d.type = g.type;
+            return d;
+        }).filter(function (d) {
+            return d.n > 0;
+        });
+        if (tipDepths.length > 0) {
+            // running, not Math.min.apply: the spread of 150k tip depths
+            // overflows the call stack, as timeAxisInfo found before this
+            let lo = Infinity;
+            let hi = -Infinity;
+            for (let i = 0; i < tipDepths.length; ++i) {
+                if (tipDepths[i] < lo) {
+                    lo = tipDepths[i];
+                }
+                if (tipDepths[i] > hi) {
+                    hi = tipDepths[i];
+                }
+            }
+            stats.height = hi;
+            stats.heightKnown = lengths.length > 0;
+            // ultrametric: every tip the same distance from the root, to a
+            // tolerance scaled to the tree, since branch lengths are floats
+            stats.ultrametric = stats.heightKnown && (hi - lo) <= (Math.max(hi, 1e-12) * 1e-6);
+        }
+        return stats;
+    };
+
+    // n, minimum, median, maximum, mean and sum of a list of numbers, or null
+    // when there are none. The median is the middle value of the sorted list,
+    // or the mean of the two middle ones -- taken on a COPY, because sorting
+    // the caller's array would reorder data it still owns.
+    forester.describeValues = function (values) {
+        if (!values || values.length === 0) {
+            return null;
+        }
+        let v = values.slice().sort(function (a, b) {
+            return a - b;
+        });
+        let n = v.length;
+        let sum = 0;
+        for (let i = 0; i < n; ++i) {
+            sum += v[i];
+        }
+        let mid = Math.floor(n / 2);
+        return {
+            n: n,
+            min: v[0],
+            max: v[n - 1],
+            median: (n % 2 === 1) ? v[mid] : ((v[mid - 1] + v[mid]) / 2),
+            mean: sum / n,
+            sum: sum
+        };
+    };
+
     forester.calcMaxBranchLength = function (node) {
         let max = 0;
         forester.preOrderTraversalAll(node, function (n) {
@@ -6709,7 +7114,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;
@@ -6811,7 +7222,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.13.0",
+  "version": "3.15.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",