archaeopteryx 3.22.0 → 3.24.0

package/forester.js

@@ -20,7 +20,7 @@
  *
  */
 
-// v 3.22.0
+// v 3.24.0
 // 2026-09-17
 //
 // forester.js is a general suite for dealing with phylogenetic trees.
@@ -7245,6 +7245,301 @@
         return bothPicturesHaveDepth(root);
     };
 
+    // ---- the CLOCK PLOT ---------------------------------------------------
+    // Every node as a point, its DATE against its DIVERGENCE from the root,
+    // and a straight line through the tips: the slope is the rate the tips
+    // accumulated divergence at, and where the line comes down to the root's
+    // divergence is the date it puts the root on. TempEst's and TreeTime's
+    // root-to-tip regression, Auspice's clock view. Christian, 2026-10-02:
+    // a panel linked to the tree, named "Clock plot"; JS only until the
+    // design is final.
+    //
+    // THE RULE, designed for two kinds of tree (both built; the second on
+    // Christian's word, 2026-10-03):
+    //
+    // 1. 'divergence' -- a tree with Time and Div (hasTimeAndDivergence): each
+    //    node states a date and a divergence from the root, recorded on it or
+    //    summed from each branch's time x its clock rate. Every node is a
+    //    point; which of the two layouts is on screen does not matter.
+    // 2. 'root-to-tip' -- a tree whose branch lengths are its divergence and
+    //    whose tips are dated, with no date on any ancestor (it is not a time
+    //    tree): a tip's divergence is the sum of the stated lengths from the
+    //    root. Tips only. This is the tree a clock plot is wanted for most --
+    //    is there a signal worth dating? -- and the one whose answer depends
+    //    on its root. TempEst's plot. A tip is dated by what the file STATES
+    //    for it (a phyloXML <date>, a num_date annotation), or else by the
+    //    date its NAME carries, read by the label-date parser both programs
+    //    anchor BEAST heights with (Christian, 2026-10-03: names count, as
+    //    TempEst reads them; a year alone is mid-year). An ancestor is never
+    //    dated by its name. Every tip must be dated and every branch must
+    //    state a length: a tip with either missing has no point, and a plot
+    //    that drops tips silently answers a different question than it was
+    //    asked. A clock-model tree (a rate on every branch) is never this
+    //    kind: its lengths are time.
+    //
+    // In both, the plot is offered when its LINE can be drawn: three tips or
+    // more, and not all of them on one date. A tree sampled at one moment has
+    // no slope to estimate. Asked of the tree, never of the view: in the view
+    // of a clade too small or too uniform for a line the points are drawn and
+    // the line is not.
+    //
+    // The FIT is ordinary least squares over the TIPS alone. A tip's date is
+    // an observation; an ancestor's was inferred, usually with a clock, and
+    // counting it would have the estimate confirm itself. The line is not
+    // forced through the root, so the date it reaches the root's divergence
+    // at can be held against the date the tree states for the root -- where
+    // the tree states one; a root-to-tip tree does not, and there the line's
+    // date is the only estimate.
+    const CLOCK_PLOT_MIN_TIPS = 3;
+
+    // A tip's date on a root-to-tip tree: the one the file states, else the
+    // one its name carries (forester.parseTipLabelDate: the rightmost date in
+    // the label; a year alone is mid-year; an ambiguous numeric date is read
+    // day first). {value, fromName, ambiguous}, or null for no date at all.
+    function rootToTipDate(n) {
+        let d = auspiceNodeDate(n);
+        if (d !== null) {
+            return {value: d, fromName: false, ambiguous: false};
+        }
+        let m = (typeof n.name === 'string' && n.name.length > 0) ? forester.parseTipLabelDate(n.name) : null;
+        return m ? {value: m.decimalYear, fromName: true, ambiguous: m.ambiguous === true} : null;
+    }
+
+    // Kind 2 of THE RULE, before the tips are counted: dated tips (by the
+    // file or by their names), undated ancestors (by the file; a name dates
+    // no ancestor), a length on every branch, no clock rates.
+    function isRootToTipTree(root) {
+        if (!root || root._divergenceFromRates === true || !everyLengthWasStated(root)) {
+            return false;
+        }
+        let ok = true;
+        forester.preOrderTraversalAll(root, function (n) {
+            if (!ok) {
+                return;
+            }
+            ok = (n.children && n.children.length > 0) ? auspiceNodeDate(n) === null : rootToTipDate(n) !== null;
+        });
+        return ok;
+    }
+
+    // Each node's distance from the root along the stated branch lengths:
+    // a root-to-tip tree's divergence.
+    function rootToTipDistances(root) {
+        let dist = new Map();
+        (function walk(n, d) {
+            dist.set(n, d);
+            let children = n.children;
+            if (children) {
+                for (let i = 0; i < children.length; ++i) {
+                    let len = children[i].branch_length;
+                    walk(children[i], d + ((typeof len === 'number' && isFinite(len)) ? len : 0));
+                }
+            }
+        }(root, 0));
+        return dist;
+    }
+
+    /**
+     * Which clock plot the tree has, or null for none (see THE RULE above).
+     *
+     * @param phy the tree
+     * @returns {string|null} 'divergence', 'root-to-tip', or null
+     */
+    forester.clockPlotKind = function (phy) {
+        if (!phy) {
+            return null;
+        }
+        let kind = forester.hasTimeAndDivergence(phy) ? 'divergence'
+            : (isRootToTipTree(forester.getTreeRoot(phy)) ? 'root-to-tip' : null);
+        if (kind === null) {
+            return null;
+        }
+        let dateOf = kind === 'root-to-tip' ? function (n) {
+            return rootToTipDate(n).value;    // every tip has one: the kind says so
+        } : auspiceNodeDate;
+        let tips = 0;
+        let first = null;
+        let differ = false;
+        forester.preOrderTraversalAll(forester.getTreeRoot(phy), function (n) {
+            if (n.children && n.children.length > 0) {
+                return;
+            }
+            ++tips;
+            let d = dateOf(n);
+            if (first === null) {
+                first = d;
+            } else if (d !== first) {
+                differ = true;
+            }
+        });
+        return (tips >= CLOCK_PLOT_MIN_TIPS && differ) ? kind : null;
+    };
+
+    /**
+     * Ordinary least squares of y on x, computed about the means: a date is
+     * near 2020 and its spread a few months, and sums of raw squares would
+     * spend every digit on the 2020.
+     *
+     * @param xs the dates
+     * @param ys the divergences, as many
+     * @returns {{n, slope, intercept, r2, meanX, meanY}|null} null with fewer
+     *          than three points or every x the same; r2 is null where every
+     *          y is the same (no variance to explain)
+     */
+    forester.clockRegression = function (xs, ys) {
+        let n = xs.length;
+        if (n < CLOCK_PLOT_MIN_TIPS || ys.length !== n) {
+            return null;
+        }
+        let mx = 0;
+        let my = 0;
+        for (let i = 0; i < n; ++i) {
+            mx += xs[i];
+            my += ys[i];
+        }
+        mx /= n;
+        my /= n;
+        let sxx = 0;
+        let sxy = 0;
+        let syy = 0;
+        for (let i = 0; i < n; ++i) {
+            let dx = xs[i] - mx;
+            let dy = ys[i] - my;
+            sxx += dx * dx;
+            sxy += dx * dy;
+            syy += dy * dy;
+        }
+        if (!(sxx > 0) || !isFinite(sxx) || !isFinite(sxy) || !isFinite(syy)) {
+            return null;
+        }
+        let slope = sxy / sxx;
+        return {
+            n: n,
+            slope: slope,
+            intercept: my - (slope * mx),
+            r2: syy > 0 ? ((sxy * sxy) / (sxx * syy)) : null,
+            meanX: mx,
+            meanY: my
+        };
+    };
+
+    /**
+     * The clock plot of the tree, or of the clade on view.
+     *
+     * @param phy the tree: the RULE is asked of it
+     * @param view the tree or clade to plot (the tree, a node, or the
+     *        viewer's subtree root); the whole tree where none is given
+     * @returns {object|null} null where the tree has no clock plot; else
+     *   kind      'divergence' or 'root-to-tip'
+     *   forward   whether the dates increase toward the tips (calendar
+     *             dates); false for ages
+     *   unit      the dates' unit as the tree states it, or null
+     *   divUnit   the divergence's unit: 'subs/site' for a tree with Time
+     *             and Div, a root-to-tip tree's stated branch length unit,
+     *             or null
+     *   fromRates whether the divergence is time x clock rate
+     *   calendar  whether the dates are calendar years: their unit says so,
+     *             or they were read off the tips' names
+     *   fromNames how many tips are dated by their names (a root-to-tip
+     *             tree; 0 otherwise)
+     *   ambiguousNames how many of those names carry a day/month-ambiguous
+     *             numeric date, read day first
+     *   points    [{node, date, div, tip}] in preorder; the tips'
+     *             `residual` is their divergence less the line's. On a
+     *             root-to-tip tree the tips only: no ancestor has a date
+     *   root      {node, date, div}: the top of the view; `date` null on a
+     *             root-to-tip tree
+     *   fit       forester.clockRegression over the tips, with
+     *             rate      the slope in the direction time runs: divergence
+     *                       per unit of time (negative where the tips'
+     *                       divergence falls with time)
+     *             rootDate  the date the line reaches the root's divergence
+     *                       at; null unless the rate is positive
+     *             or null where the view has no line
+     */
+    forester.clockPlotData = function (phy, view) {
+        let kind = forester.clockPlotKind(phy);
+        if (kind === null) {
+            return null;
+        }
+        let treeRoot = forester.getTreeRoot(phy);
+        // a node is its own top; the tree, or the viewer's holder of a clade,
+        // is a parentless wrapper around it
+        let top = treeRoot;
+        if (view) {
+            top = (!view.parent && view.children && view.children.length === 1) ? view.children[0] : view;
+        }
+        // a root-to-tip tree's divergence is the path from the TREE's root,
+        // in the view of a clade too: the clade's top then has one as well
+        let rootToTip = kind === 'root-to-tip';
+        let dist = rootToTip ? rootToTipDistances(treeRoot) : null;
+        let divOf = rootToTip ? function (n) {
+            return dist.get(n);
+        } : auspiceNodeDiv;
+        let points = [];
+        let xs = [];
+        let ys = [];
+        let fromNames = 0;
+        let ambiguousNames = 0;
+        forester.preOrderTraversalAll(top, function (n) {
+            let tip = !(n.children && n.children.length > 0);
+            let date = auspiceNodeDate(n);
+            if (rootToTip && tip && date === null) {
+                let named = rootToTipDate(n);    // every tip has one: the kind says so
+                date = named ? named.value : null;
+                if (named && named.fromName) {
+                    ++fromNames;
+                    if (named.ambiguous) {
+                        ++ambiguousNames;
+                    }
+                }
+            }
+            let div = divOf(n);
+            if (date === null || div === null) {
+                return;    // an undated ancestor (root-to-tip), or a guard, not a rule
+            }
+            points.push({node: n, date: date, div: div, tip: tip});
+            if (tip) {
+                xs.push(date);
+                ys.push(div);
+            }
+        });
+        let info = forester.timeAxisInfo(treeRoot);
+        // a root-to-tip tree has no dated pair to read the direction off:
+        // its dates are calendar dates unless their unit says ages
+        let forward = rootToTip ? info.type !== 'geologic' : timeIncreasesTowardTips(treeRoot);
+        // calendar years: the dates' unit says so, or they were read off the
+        // tips' names, which carry no other kind of date
+        let calendar = forward && (info.type === 'calendar' || (rootToTip && info.type === null && fromNames > 0));
+        let root = {node: top, date: auspiceNodeDate(top), div: divOf(top)};
+        let fit = forester.clockRegression(xs, ys);
+        if (fit) {
+            fit.rate = forward ? fit.slope : -fit.slope;
+            fit.rootDate = (fit.rate > 0 && root.div !== null)
+                ? ((root.div - fit.intercept) / fit.slope) : null;
+            for (let i = 0; i < points.length; ++i) {
+                if (points[i].tip) {
+                    points[i].residual = points[i].div - (fit.intercept + (fit.slope * points[i].date));
+                }
+            }
+        }
+        let lengthUnit = (phy !== treeRoot && typeof phy.branch_length_unit === 'string'
+            && phy.branch_length_unit.trim().length > 0) ? phy.branch_length_unit.trim() : null;
+        return {
+            kind: kind,
+            forward: forward,
+            unit: dateUnitOf(treeRoot),
+            divUnit: rootToTip ? lengthUnit : DIVERGENCE_LENGTH_UNIT,
+            fromRates: !rootToTip && treeRoot._divergenceFromRates === true && !recordsDivergence(treeRoot),
+            calendar: calendar,
+            fromNames: fromNames,
+            ambiguousNames: ambiguousNames,
+            points: points,
+            root: root,
+            fit: fit
+        };
+    };
+
     // A number that is not NaN. It used to test only for null, undefined and
     // NaN, and so answered TRUE for "hello", "", {}, [] and true -- which no
     // caller was hurt by, since all of them pass the result of parseFloat, but
@@ -10220,6 +10515,41 @@
         return vals;
     };
 
+    // Month ticks over [from, to] in decimal years, for a span too short for
+    // whole years (an outbreak sampled over some months): the first of every
+    // 1st, 2nd, 3rd, 6th or 12th month, the smallest step leaving six ticks
+    // or fewer; none where even a tick a year is too many. {value, year,
+    // month}; month is 1-12, value the decimal year at which that month
+    // begins.
+    forester.calendarTickMonths = function (from, to) {
+        let span = to - from;
+        if (!(span > 0) || !isFinite(span) || !isFinite(from)) {
+            return [];
+        }
+        let steps = [1, 2, 3, 6, 12];
+        for (let s = 0; s < steps.length; ++s) {
+            let step = steps[s];
+            let ticks = [];
+            let year = Math.floor(from);
+            // month index = year * 12 + (month - 1); ticks where it divides
+            for (let k = year * 12; ticks.length <= 6; ++k) {
+                let y = Math.floor(k / 12);
+                let m = (k - (y * 12)) + 1;
+                let v = y + ((tipDateDayOfYear(y, m, 1) - 1) / tipDateYearLength(y));
+                if (v > to + 1e-9) {
+                    break;
+                }
+                if (v >= from - 1e-9 && (k % step) === 0) {
+                    ticks.push({value: v, year: y, month: m});
+                }
+            }
+            if (ticks.length <= 6) {
+                return ticks;
+            }
+        }
+        return [];
+    };
+
 
     // --------------------------------------------------------------
     // Multiple sequence alignment (the desktop's alignment track)

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "archaeopteryx",
-  "version": "3.22.0",
+  "version": "3.24.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",
@@ -20,7 +20,7 @@
     "LICENSE"
   ],
   "scripts": {
-    "test": "node test/forester_test.js && node test/search_test.js && node test/visualization_test.js && node test/domain_test.js && node test/gene_test.js && node test/metadata_test.js && node test/heatmap_test.js && node test/clustering_test.js",
+    "test": "node test/forester_test.js && node test/search_test.js && node test/visualization_test.js && node test/domain_test.js && node test/gene_test.js && node test/clock_test.js && node test/metadata_test.js && node test/heatmap_test.js && node test/clustering_test.js",
     "lint": "eslint .",
     "lint:fix": "eslint . --fix",
     "format": "prettier --write .",