archaeopteryx 3.9.0 → 3.10.0

package/archaeopteryx.js

@@ -20,7 +20,7 @@
  *
  */
 
-// v 3.9.0
+// v 3.10.0
 // 2026-09-17
 //
 // Archaeopteryx.js is a software tool for the visualization and
@@ -103,7 +103,7 @@ function (root, d3, forester, phyloXml) {
     // IIFE's own function name -- a plain object says what it is.)
     let archaeopteryx = {};
 
-    const VERSION = '3.9.0';
+    const VERSION = '3.10.0';
     const WEBSITE = 'https://cmzmasek.github.io/archaeopteryx-js/';
     const DESKTOP_WEBSITE = 'https://cmzmasek.github.io/archaeopteryx/';
     const SOURCE_WEBSITE = 'https://github.com/cmzmasek/archaeopteryx-js';
@@ -404,6 +404,9 @@ function (root, d3, forester, phyloXml) {
     const PHYLOGRAM_ALIGNED_BUTTON = 'phya_b';
     const PHYLOGRAM_BUTTON = 'phy_b';
     const PHYLOGRAM_CLADOGRAM_CONTROLGROUP = 'phy_cla_g';
+    const BRANCH_SCALE_CONTROLGROUP = 'branch_scale_g';
+    const BRANCH_SCALE_TIME_BUTTON = 'branch_scale_time_b';
+    const BRANCH_SCALE_DIV_BUTTON = 'branch_scale_div_b';
     const ABOUT_DIALOG = 'aptx_about';
     const PROG_NAME = 'progname';
     const PROGNAMELINK = 'prognamelink';
@@ -577,6 +580,7 @@ function (root, d3, forester, phyloXml) {
     const FOSSIL_BAR_COLOR = 'rgba(150,100,55,0.86)'; // opaque-ish sepia
     let _timeInfo = null;                 // forester.timeAxisInfo, recomputed per render
     let _timeTree = false;                // forester.isTimeTree: never re-rooted
+    let _branchScaleAvailable = false;    // the tree states time AND divergence, so the switch is offered
     let _clusterH = 0;                    // the cluster layout's vertical extent, set per render
     let _docListenersBound = false;       // page-level key/wheel handlers bind once, not per launch
     let _docListeners = [];               // ...and destroy() can take every one of them down again
@@ -5111,6 +5115,12 @@ function (root, d3, forester, phyloXml) {
         // showTimeAxis explicitly.
         _timeInfo = _treeData ? forester.timeAxisInfo(forester.getTreeRoot(_treeData)) : null;
         _timeTree = _treeData ? forester.isTimeTree(_treeData) : false;
+        // Whether this tree says two different things -- when its nodes sit in
+        // time AND its branches measure something else -- and which of the two
+        // it arrived showing. An Auspice build arrives in the time view; a
+        // BEAST or Newick file arrives stating its own branch lengths.
+        _branchScaleAvailable = _treeData ? forester.hasTimeAndDivergence(_treeData) : false;
+        _state.branchScale = _treeData ? forester.branchLengthScale(_treeData) : 'divergence';
         if (_state.showTimeAxis === undefined) {
             _state.showTimeAxis = !!(_timeInfo && _timeInfo.type);
         }
@@ -5651,6 +5661,14 @@ function (root, d3, forester, phyloXml) {
         // and a tree whose dates carry a unit is never touched. The desktop
         // converts at the same point, next to its internal-label policy
         // (their HeightDateConverter, 0.11.151).
+        // Each node's cumulative divergence is recorded from the branch
+        // lengths AS LOADED, before anything rewrites them, so the time <->
+        // divergence switch is reversible rather than one-way. Auspice states
+        // divergence outright (nextstrain:div) and is unaffected; every other
+        // tree states it as its branch lengths, which the time view overwrites.
+        trees.forEach(function (t) {
+            forester.captureDivergence(t);
+        });
         forester.convertLoadedHeightsToDates(trees);
         // the two view keys are checked up here with the other arguments,
         // before anything is touched (and where Node can test it)
@@ -8152,7 +8170,7 @@ function (root, d3, forester, phyloXml) {
         {key: 'e', label: 'E', shift: true, what: 'Expand vertically until the labels fit', run: function () { zoomToExpandY(); }},
         {key: 'l', label: 'L', shift: true, what: 'Next layout: rectangular, circular, unrooted', run: cycleLayout},
         {key: 'd', label: 'D', shift: true, what: 'Next display type: phylogram, aligned, cladogram', run: cycleDisplayType},
-        {key: 'x', label: 'X', shift: true, what: 'Time axis on / off', run: toggleTimeAxis},
+        {key: 'x', label: 'X', shift: true, what: 'Time / divergence scale, or the time axis', run: toggleTimeAxis},
         {key: 'o', label: 'O', shift: true, what: 'Ladderize (order the tree)', run: function () { ladderizeButtonPressed(); }},
         {key: 'u', label: 'U', shift: true, what: 'Uncollapse every clade', run: function () { uncollapseAll(); }},
         {key: 'f', label: 'F', what: 'Go to the search box', run: focusSearch, typing: true},
@@ -8222,9 +8240,45 @@ function (root, d3, forester, phyloXml) {
         }
     }
 
-    // The Time Axis checkbox's toggle; when the distance / time tree switch
-    // arrives it takes over this key.
+    /**
+     * Redraws the tree with its branch lengths taken from the chosen metric:
+     * TIME (the gaps between the nodes' dates) or DIVERGENCE (what the file's
+     * own branch lengths measured, recorded at load). Both metrics stay on the
+     * tree, so this is reversible and lossless -- a round trip restores the
+     * loaded branch lengths exactly.
+     *
+     * @param scale 'time' or 'divergence'
+     */
+    function setBranchScale(scale) {
+        if (!_branchScaleAvailable || !_treeData || _state.branchScale === scale) {
+            return;
+        }
+        _state.branchScale = scale;
+        if (scale === 'time') {
+            forester.applyTimeBranchLengths(_treeData);
+        } else {
+            forester.applyDivergenceBranchLengths(_treeData);
+        }
+        // the branch lengths ARE the layout, so everything measured from them
+        // has to be measured again
+        _basicTreeProperties = forester.collectBasicTreeProperties(_treeData);
+        setCheckboxValue(BRANCH_SCALE_TIME_BUTTON, scale === 'time');
+        setCheckboxValue(BRANCH_SCALE_DIV_BUTTON, scale !== 'time');
+        zoomToFit();
+    }
+
+    function branchScaleButtonClicked() {
+        setBranchScale(getCheckboxValue(BRANCH_SCALE_TIME_BUTTON) ? 'time' : 'divergence');
+    }
+
+    // Shift+X. The switch takes this key over where the tree offers it, as was
+    // always intended; on every other tree it still works the Time Axis
+    // checkbox, so the key never does nothing.
     function toggleTimeAxis() {
+        if (_branchScaleAvailable) {
+            setBranchScale(_state.branchScale === 'time' ? 'divergence' : 'time');
+            return;
+        }
         let cb = byId(TIME_AXIS_CB);
         if (!cb || cb.disabled) {
             return;
@@ -8966,7 +9020,15 @@ function (root, d3, forester, phyloXml) {
         return _state.showTimeAxis === true && !radialDisplay()
             && _state.phylogram === true
             && _timeInfo !== null && _timeInfo.type !== null
-            && _basicTreeProperties.branchLengths === true;
+            && _basicTreeProperties.branchLengths === true
+            // The axis is an overlay calibrated to the tree's own branch scale,
+            // so it must be hidden when the branches are showing DIVERGENCE
+            // and divergence is a different measure -- calendar years against
+            // substitutions reads as a confident lie. Only then: where the two
+            // metrics agree (a BEAST time tree, whose branch lengths ARE time)
+            // there is no switch and the axis is calibrated correctly, which
+            // is what makes a converted BEAST tree show its years at all.
+            && !(_branchScaleAvailable && _state.branchScale === 'divergence');
     }
 
     function timeAxisBottomReserve() {
@@ -12736,6 +12798,8 @@ function (root, d3, forester, phyloXml) {
         on(TIME_GRID_CB, 'click', timeGridCbClicked);
 
         on(LAYOUT_RECT_BUTTON, 'click', layoutButtonClicked);
+        on(BRANCH_SCALE_TIME_BUTTON, 'click', branchScaleButtonClicked);
+        on(BRANCH_SCALE_DIV_BUTTON, 'click', branchScaleButtonClicked);
 
         on(LAYOUT_CIRC_BUTTON, 'click', layoutButtonClicked);
         on(LAYOUT_UNROOTED_BUTTON, 'click', layoutButtonClicked);
@@ -13156,6 +13220,15 @@ function (root, d3, forester, phyloXml) {
             h = h.concat(makeSegment(makeGlyph('aligned_phylogram'), PHYLOGRAM_ALIGNED_BUTTON, radioGroup, 'phylogram display (uses branch length values) with aligned labels'));
             h = h.concat(makeSegment(makeGlyph('cladogram'), CLADOGRAM_BUTTON, radioGroup, ' cladogram display (ignores branch length values)'));
             h = h.concat('</div>');
+            // The branch SCALE, when the tree states two different things: its
+            // nodes' dates, and its branches' divergence. Hidden otherwise,
+            // which is most trees.
+            h = h.concat('<div class="' + BRANCH_SCALE_CONTROLGROUP + ' aptx-segmented">');
+            h = h.concat(makeSegment('Time', BRANCH_SCALE_TIME_BUTTON, 'branch_scale_radio',
+                'branch lengths measure TIME (the nodes\' dates)'));
+            h = h.concat(makeSegment('Div', BRANCH_SCALE_DIV_BUTTON, 'branch_scale_radio',
+                'branch lengths measure DIVERGENCE (substitutions, as the file states them)'));
+            h = h.concat('</div>');
             h = h.concat('</div>');
             h = h.concat('</fieldset>');
             return h;
@@ -13631,6 +13704,14 @@ function (root, d3, forester, phyloXml) {
             disableCheckbox('#' + PHYLOGRAM_BUTTON);
             disableCheckbox('#' + PHYLOGRAM_ALIGNED_BUTTON);
         }
+        setCheckboxValue(BRANCH_SCALE_TIME_BUTTON, _state.branchScale === 'time');
+        setCheckboxValue(BRANCH_SCALE_DIV_BUTTON, _state.branchScale !== 'time');
+        // most trees state only one thing, and a control offering a choice
+        // that does not exist is worse than no control
+        let scaleGroup = document.querySelector('.' + BRANCH_SCALE_CONTROLGROUP);
+        if (scaleGroup) {
+            scaleGroup.style.display = _branchScaleAvailable ? '' : 'none';
+        }
     }
 
 

package/forester.js

@@ -20,7 +20,7 @@
  *
  */
 
-// v 3.9.0
+// v 3.10.0
 // 2026-09-17
 //
 // forester.js is a general suite for dealing with phylogenetic trees.
@@ -4988,6 +4988,11 @@
             ? node.date.value : null;
     }
 
+    // A node's CUMULATIVE divergence from the root. Auspice states it outright
+    // as nextstrain:div; every other tree states it as branch lengths, which
+    // are the same thing in difference form, so it is summed at load and kept
+    // on the node (see forester.captureDivergence). The property wins where it
+    // exists, so an Auspice tree behaves exactly as it always did.
     function auspiceNodeDiv(node) {
         if (node.properties) {
             for (let i = 0; i < node.properties.length; ++i) {
@@ -4997,7 +5002,8 @@
                 }
             }
         }
-        return null;
+        return (typeof node._divergence === 'number' && isFinite(node._divergence))
+            ? node._divergence : null;
     }
 
     function auspiceHasAnyDate(node) {
@@ -5051,12 +5057,200 @@
         setDeltaBranchLengths(forester.getTreeRoot(phy), null, auspiceNodeDiv);
     };
 
-    // True when the tree carries BOTH a time signal (a dated node) AND a
-    // divergence signal (a nextstrain:div property), so the toggle is
-    // meaningful at all.
+    /**
+     * Records each node's cumulative divergence from the root, summed from the
+     * branch lengths AS LOADED, so the divergence view survives the time view
+     * overwriting `branch_length`. Kept in `_divergence`, which is private:
+     * no writer emits it, and a re-read of our own output re-derives it.
+     *
+     * A tree whose branch lengths ARE its dates (an Auspice time tree, say)
+     * gets the snapshot too; it is `hasTimeAndDivergence` that decides whether
+     * the two views differ enough to be worth offering.
+     *
+     * Call once per tree at load, before anything rewrites a branch length.
+     *
+     * @param phy the tree
+     */
+    forester.captureDivergence = function (phy) {
+        let root = forester.getTreeRoot(phy);
+        if (!root) {
+            return;
+        }
+        (function walk(node, cumulative) {
+            node._divergence = cumulative;
+            let children = node.children;
+            if (children) {
+                for (let i = 0; i < children.length; ++i) {
+                    let bl = children[i].branch_length;
+                    let step = (typeof bl === 'number' && isFinite(bl) && bl > 0) ? bl : 0;
+                    walk(children[i], cumulative + step);
+                }
+            }
+        }(root, 0));
+    };
+
+    // How much the tree's SHAPE would change between the two metrics, as a
+    // fraction of its width: each tip's distance from the root under each
+    // metric, normalised by the deepest tip, and the largest disagreement.
+    //
+    // Comparing branch lengths PAIR BY PAIR is the wrong question and gave the
+    // wrong answer: on influenza.tree the branch lengths differ from the date
+    // gaps by a median of 7% per branch, which looks like a separate measure,
+    // but the differences cancel along every path and all 687 tips land within
+    // 0.3% of where the other metric puts them. Its branch lengths ARE time --
+    // a BEAST time tree states time -- so a toggle would redraw one picture
+    // twice. A real Nextstrain build, where divergence is genuinely a
+    // different measurement, moves tips by 24.8% of the tree's width.
+    //
+    // Both metrics are read WITHOUT touching branch_length, so this can be
+    // asked at load without disturbing the tree.
+    function layoutShiftBetweenMetrics(root) {
+        let rootDate = auspiceNodeDate(root);
+        let time = [];
+        let div = [];
+        let ok = true;
+        (function walk(n, t, d) {
+            let nt = auspiceNodeDate(n);
+            let nd = auspiceNodeDiv(n);
+            let tHere = (nt !== null && rootDate !== null) ? Math.abs(nt - rootDate) : t;
+            let dHere = (nd !== null) ? nd : d;
+            if (!n.children || n.children.length === 0) {
+                if (nt === null || nd === null) {
+                    ok = false;
+                }
+                time.push(tHere);
+                div.push(dHere);
+                return;
+            }
+            for (let i = 0; i < n.children.length; ++i) {
+                walk(n.children[i], tHere, dHere);
+            }
+        }(root, 0, 0));
+        if (!ok || time.length === 0) {
+            return 0;
+        }
+        let tMax = Math.max.apply(null, time.length > 50000 ? time.slice(0, 50000) : time);
+        let dMax = Math.max.apply(null, div.length > 50000 ? div.slice(0, 50000) : div);
+        if (!(tMax > 0) || !(dMax > 0)) {
+            return 0;
+        }
+        let worst = 0;
+        for (let i = 0; i < time.length; ++i) {
+            worst = Math.max(worst, Math.abs((time[i] / tMax) - (div[i] / dMax)));
+        }
+        return worst;
+    }
+
+    // Below this the two views are the same picture and the switch is noise.
+    // influenza.tree measures 0.003, nextstrain-ncov.json 0.248.
+    const BRANCH_METRIC_SHIFT_MIN = 0.02;
+
+    function divergenceDiffersFromTime(root) {
+        return layoutShiftBetweenMetrics(root) > BRANCH_METRIC_SHIFT_MIN;
+    }
+
+    // Which metric the CURRENT branch lengths hold -- a different question
+    // from whether the two metrics differ, and it needs the pair-by-pair
+    // comparison: after forester.applyTimeBranchLengths every branch length is
+    // exactly its ends' date gap, and after applyDivergenceBranchLengths it is
+    // not. Asked so a switch starts from what is on screen.
+    function branchLengthsAreTime(root) {
+        let pairs = 0;
+        let same = 0;
+        forester.preOrderTraversalAll(root, function (n) {
+            if (!n.children) {
+                return;
+            }
+            let pv = auspiceNodeDate(n);
+            if (pv === null) {
+                return;
+            }
+            for (let i = 0; i < n.children.length; ++i) {
+                let c = n.children[i];
+                let cv = auspiceNodeDate(c);
+                let bl = c.branch_length;
+                if (cv === null || typeof bl !== 'number' || !isFinite(bl)) {
+                    continue;
+                }
+                ++pairs;
+                let scale = Math.max(Math.abs(bl), Math.abs(cv - pv), 1e-9);
+                if (Math.abs(Math.abs(cv - pv) - bl) <= (scale * 1e-6)) {
+                    ++same;
+                }
+            }
+        });
+        return pairs > 0 && (same * 20) >= (pairs * 19);
+    }
+
+    // Whether the dates run the way the time view needs them to: a CALENDAR
+    // date increases toward the tips, and setDeltaBranchLengths takes
+    // child - parent and clamps at 0. A BEAST height runs the other way -- it
+    // is an age, largest at the root -- so a tree still stating heights would
+    // get a branch length of 0 everywhere and collapse to a point. Measured,
+    // not assumed: forester.convertHeightsToDates turns heights into calendar
+    // dates, and a tree it REFUSED still states ages.
+    function timeIncreasesTowardTips(root) {
+        let up = 0;
+        let pairs = 0;
+        forester.preOrderTraversalAll(root, function (n) {
+            if (!n.children) {
+                return;
+            }
+            let pv = auspiceNodeDate(n);
+            if (pv === null) {
+                return;
+            }
+            for (let i = 0; i < n.children.length; ++i) {
+                let cv = auspiceNodeDate(n.children[i]);
+                if (cv === null || cv === pv) {
+                    continue;
+                }
+                ++pairs;
+                if (cv > pv) {
+                    ++up;
+                }
+            }
+        });
+        return pairs > 0 && (up * 2) > pairs;
+    }
+
+    /**
+     * Which metric the tree's branch lengths currently state. An Auspice build
+     * arrives in the time view (its parser writes date deltas); a BEAST or
+     * Newick file arrives stating whatever it was written with, which is the
+     * divergence view. Asked rather than assumed, so a toggle starts from
+     * what is actually on screen.
+     *
+     * @param phy the tree
+     * @returns {string} 'time' or 'divergence'
+     */
+    forester.branchLengthScale = function (phy) {
+        let root = forester.getTreeRoot(phy);
+        return (root && branchLengthsAreTime(root)) ? 'time' : 'divergence';
+    };
+
+    /**
+     * True when the tree carries BOTH a time signal (dated nodes, running the
+     * calendar way) and a divergence signal that says something different, so
+     * a time <-> divergence toggle is meaningful. Auspice states divergence as
+     * nextstrain:div; a BEAST tree states it as its branch lengths, which on a
+     * real one differ from the dates on nearly every branch (influenza.tree:
+     * 1344 of 1372).
+     *
+     * @param phy the tree
+     * @returns {boolean}
+     */
     forester.hasTimeAndDivergence = function (phy) {
         let root = forester.getTreeRoot(phy);
-        return auspiceHasAnyDate(root) && auspiceHasAnyDiv(root);
+        if (!root || !auspiceHasAnyDate(root) || !timeIncreasesTowardTips(root)) {
+            return false;
+        }
+        // auspiceHasAnyDiv is true for every tree once the divergence has been
+        // captured, so it cannot decide this on its own -- it only says a
+        // divergence measure EXISTS. Whether it says anything different is the
+        // shift test, and that is the question worth asking of both kinds of
+        // tree.
+        return auspiceHasAnyDiv(root) && divergenceDiffersFromTime(root);
     };
 
     // A number that is not NaN. It used to test only for null, undefined and
@@ -7104,11 +7298,17 @@
         let agreeingTips = [];
         let latestStart = -Infinity;
         let earliestEnd = Infinity;
+        // the dates the agreeing tips actually STATE, un-widened: their labels
+        // plus their heights, with no tolerance added
+        let offerLo = -Infinity;
+        let offerHi = Infinity;
         ranges.forEach(function (r) {
             if (heightDateAllows(r, mid)) {
                 agreeingTips.push(r);
                 latestStart = Math.max(latestStart, r[0]);
                 earliestEnd = Math.min(earliestEnd, r[1]);
+                offerLo = Math.max(offerLo, r[0] + r[2]);
+                offerHi = Math.min(offerHi, r[1] + r[2]);
             }
         });
         let agreeing = agreeingTips.length;
@@ -7118,7 +7318,20 @@
         if (latestStart <= earliestEnd) {
             return null; // every agreeing label range overlaps every other
         }
-        let present = Math.max(best[0], Math.min(best[1], heightDatePrecisestMedian(agreeingTips)));
+        // The anchor is clamped into what the agreeing tips actually STATE,
+        // not into the stretch the tolerance opened up. The tolerance decides
+        // AGREEMENT -- how far a tip may miss and still count -- and must not
+        // then place the date: clamping into the widened stretch let the answer
+        // drift by up to the tolerance, about four days. Found by the desktop
+        // on ground truth: three Nextstrain .nwk trees whose .nexus siblings
+        // carry the real dates were out by 4.15, 3.96 and 2.92 days, and land
+        // within half a day after this (2026-09-17).
+        //
+        // Where the agreeing tips overlap only BECAUSE of the tolerance and
+        // state nothing in common, there is nothing to clamp into and the
+        // precise-label median stands.
+        let median = heightDatePrecisestMedian(agreeingTips);
+        let present = (offerLo <= offerHi) ? Math.max(offerLo, Math.min(offerHi, median)) : median;
         return {present: heightDateRound5(present), agreeing: agreeing, compared: compared};
     };
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "archaeopteryx",
-  "version": "3.9.0",
+  "version": "3.10.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",