archaeopteryx 3.23.0 → 3.24.0

package/README.md

@@ -25,7 +25,7 @@ config key live and shows the exact config JSON to copy into your own
 `launch()` call.
 
 * [Auspice / Nextstrain JSON (Time | Div, Clock plot)](https://cmzmasek.github.io/archaeopteryx-js/demo.html?tree=auspice)
-* [Swine H1 HA1 + alignment (Nexus)](https://cmzmasek.github.io/archaeopteryx-js/demo.html?tree=swh1)
+* [Swine H1 HA1 + alignment (Nexus; Clock plot from the years in the names)](https://cmzmasek.github.io/archaeopteryx-js/demo.html?tree=swh1)
 * [BEAST annotations (Nexus)](https://cmzmasek.github.io/archaeopteryx-js/demo.html?tree=beast)
 * [Flavivirus mature peptides (10 trees)](https://cmzmasek.github.io/archaeopteryx-js/demo.html?tree=flavivirus)
 * [SARS-CoV-2 time tree (calendar)](https://cmzmasek.github.io/archaeopteryx-js/demo.html?tree=sarscov2)
@@ -933,11 +933,28 @@ ancestors' points, each at its own date and divergence; the panel opens
 without them, since the line is the tips' and a deep root would crowd them
 into a corner.
 
-The button is offered on a tree that has **Time | Div** and whose line can
-be drawn: three tips or more, not all on one date. A tree sampled at one
-moment has no slope to estimate. (A tree whose branch lengths are divergence
-and whose tips alone are dated — the tree a root-to-tip plot is run on
-*before* dating — has no plot yet.)
+The button is offered on two kinds of tree, whenever the line can be drawn
+(three tips or more, not all on one date; a tree sampled at one moment has
+no slope to estimate):
+
+- a tree that has **Time | Div**: every node is dated and has a divergence,
+  so the ancestors can be shown too;
+- a tree whose **branch lengths are its divergence and whose tips alone are
+  dated** — the tree a root-to-tip plot is run on *before* dating, TempEst's
+  case. A tip's divergence is the sum of the branch lengths from the root;
+  the plot has tips only (**Internal nodes** is not offered, since no
+  ancestor is dated); **Root date, in the tree** says `none`, since the tree
+  states no root date, and **Rate** is in the tree's own branch length unit,
+  where it states one. A tip's date is what the file states for it (a
+  phyloXML `<date>`, a `num_date` annotation) or, failing that, the date in
+  its **name**, as TempEst reads it: the rightmost date the label carries
+  (`A/swine/Iowa/A02524571/2020|1A.3.3.3` is 2020; a year alone is taken as
+  mid-year, 2020.5; a day/month-ambiguous `03/04/2020` is read day first),
+  and the panel's note says how many names it read and how many were
+  ambiguous. An ancestor is never dated by its name. Every tip must be
+  dated, by the file or by its name, and every branch must have a length: a
+  tree with a gap is not offered the plot, rather than plotted with tips
+  missing.
 
 # forester.js
 forester.js is a general suite for dealing with phylogenetic trees.
@@ -2599,15 +2616,25 @@ deliberate difference.)
 ### The clock plot
 
 **Model** (`forester.js`, pure). `forester.clockPlotKind(phy)` answers
-`'divergence'` or `null`: the tree has Time and Div
-(`forester.hasTimeAndDivergence`) and three tips or more, not all on one
-date. It is asked of the **tree**, never of the view. A second kind,
-`'root-to-tip'` — divergence branch lengths, dated tips, no dated ancestors —
-is described beside the function and not built. `forester.clockPlotData(phy,
-view)` returns `{kind, forward, unit, fromRates, points, root, fit}`: a point
+`'divergence'`, `'root-to-tip'` or `null`: `'divergence'` where the tree has
+Time and Div (`forester.hasTimeAndDivergence`); `'root-to-tip'` where every
+tip is dated (by the file, or by the date in its name:
+`forester.parseTipLabelDate`), no ancestor is, every branch states a length
+and no branch states a clock rate (a clock-model tree's lengths are time) — and in
+both cases three tips or more, not all on one date. It is asked of the
+**tree**, never of the view. `forester.clockPlotData(phy, view)` returns
+`{kind, forward, unit, divUnit, fromRates, points, root, fit}`: a point
 `{node, date, div, tip}` per node of the view (a tip also carries its
-`residual`), `forward` false where the dates are ages, `fromRates` true where
-the divergence is time × clock rate, and `fit` =
+`residual`; on a root-to-tip tree the tips only, their `div` the sum of the
+branch lengths from the tree's root), `forward` false where the dates are
+ages (on a root-to-tip tree: where their unit is geologic), `divUnit` the
+divergence's unit (`subs/site` on a Time | Div tree, a root-to-tip tree's
+stated branch length unit, or `null`), `fromRates` true where the divergence
+is time × clock rate, `calendar` true where the dates are calendar years
+(their unit says so, or they were read off the tips' names), `fromNames` and
+`ambiguousNames` how many tips a root-to-tip tree dates by their names and
+how many of those are day/month-ambiguous (read day first), `root.date`
+`null` on a root-to-tip tree, and `fit` =
 `forester.clockRegression(dates, divergences)` over the tips — ordinary least
 squares about the means, `{n, slope, intercept, r2}` — plus `rate` (the slope
 in the direction time runs) and `rootDate` (where the line reaches the view

package/archaeopteryx.js

@@ -20,7 +20,7 @@
  *
  */
 
-// v 3.23.0
+// v 3.24.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.23.0';
+    const VERSION = '3.24.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';
@@ -11171,10 +11171,12 @@ function (root, d3, forester, phyloXml) {
             row.appendChild(input);
             row.appendChild(span);
             options.appendChild(row);
-            return input;
+            return row;
         };
         check('Regression line', 'line', 'to show/hide the least-squares line through the tips');
-        check('Internal nodes', 'internal', 'to show/hide the internal nodes: their dates were inferred,'
+        // on a root-to-tip tree no ancestor is dated: nothing to show, so the
+        // choice is not offered (layClockPlot hides it by the data's kind)
+        let internalRow = check('Internal nodes', 'internal', 'to show/hide the internal nodes: their dates were inferred,'
             + ' and they take no part in the line');
         let deselect = document.createElement('button');
         deselect.type = 'button';
@@ -11197,7 +11199,7 @@ function (root, d3, forester, phyloXml) {
         body.appendChild(note);
 
         _clockPlot = {dialog: shell.dialog, svg: svg, axes: axes, internal: internal, line: line, tips: tips,
-            ring: ring, box: box, stats: stats, note: note, deselect: deselect,
+            ring: ring, box: box, stats: stats, note: note, deselect: deselect, internalRow: internalRow,
             data: null, marks: [], seen: null, hover: null, lays: 0, x: null, y: null};
         // the shell's close control, and anything else that closes the dialog
         let closed = function () {
@@ -11408,7 +11410,9 @@ function (root, d3, forester, phyloXml) {
     }
 
     function layClockPlot(cp, data) {
-        let calendar = data.forward && !!_timeInfo && _timeInfo.type === 'calendar';
+        let calendar = data.calendar;
+        let rootToTip = data.kind === 'root-to-tip';
+        cp.internalRow.style.display = rootToTip ? 'none' : '';
         let shown = data.points.filter(function (p) {
             return p.tip || _clockPlotOptions.internal;
         });
@@ -11464,7 +11468,7 @@ function (root, d3, forester, phyloXml) {
         seg('aptx-clock-frame', left, top, left, bottom);
         let unit = data.unit && !calendar ? ' (' + data.unit + ')' : '';
         text('aptx-clock-title', (data.forward ? 'Date' : 'Age') + unit, (left + right) / 2, CLOCK_PLOT_H - 6, 'middle');
-        let yt = text('aptx-clock-title', 'Divergence (subs/site)', 0, 0, 'middle');
+        let yt = text('aptx-clock-title', 'Divergence' + (data.divUnit ? ' (' + data.divUnit + ')' : ''), 0, 0, 'middle');
         yt.setAttribute('transform', 'translate(12,' + ((top + bottom) / 2) + ') rotate(-90)');
 
         // --- the points: ancestors under the line, tips over it
@@ -11506,12 +11510,13 @@ function (root, d3, forester, phyloXml) {
         let tipCount = data.points.reduce(function (n, p) {
             return n + (p.tip ? 1 : 0);
         }, 0);
-        let per = ' subs/site per ' + (calendar ? 'year' : (data.unit || 'unit of time'));
+        let per = (data.divUnit ? ' ' + data.divUnit : '') + ' per ' + (calendar ? 'year' : (data.unit || 'unit of time'));
         if (fit) {
             treePropRow(cp.stats, 'Rate', clockNumber(fit.rate) + per);
             treePropRow(cp.stats, 'Root date, by the line', fit.rootDate === null
                 ? 'none: divergence does not rise with time' : clockDate(fit.rootDate, calendar));
-            treePropRow(cp.stats, 'Root date, in the tree', clockDate(data.root.date, calendar));
+            treePropRow(cp.stats, 'Root date, in the tree', data.root.date === null
+                ? 'none: only the tips are dated' : clockDate(data.root.date, calendar));
             treePropRow(cp.stats, 'R²', fit.r2 === null ? 'none: every tip has one divergence' : clockNumber(fit.r2));
         } else {
             treePropRow(cp.stats, 'Line', 'none: it takes three tips, not all on one date');
@@ -11520,6 +11525,15 @@ function (root, d3, forester, phyloXml) {
         cp.note.textContent = (data.fromRates
             ? 'Divergence here is each branch’s time × its clock rate: the points show the model’s rates, not a measurement of their own. '
             : '')
+            + (rootToTip
+                ? 'Divergence here is each tip’s distance from the root along the branch lengths the file states; only the tips are dated. '
+                : '')
+            + (data.fromNames > 0
+                ? (data.fromNames === 1 ? 'One tip is dated by its name' : countNumber(data.fromNames) + ' tips are dated by their names')
+                    + ' (a year alone is taken as mid-year'
+                    + (data.ambiguousNames > 0 ? '; ' + countNumber(data.ambiguousNames) + ' with day and month ambiguous, read day first' : '')
+                    + '). '
+                : '')
             + 'The line is fitted to the tips only. Tips share ancestry, so R² describes the fit and is no test.'
             + ' Click a point to select its node; drag to select the tips in a box.';
         // what was laid down, for the browser harness: read here, where it is
@@ -18225,9 +18239,12 @@ function (root, d3, forester, phyloXml) {
         // live. Injecting twice is a no-op.
         injectPanelStyles();
 
+        // REMOVED (2026-10-07): the 2.x class "node_mouseover_tooltip" beside
+        // "aptx-tip". A host's old stylesheet outranked .aptx-tip through it
+        // (div.X beats .Y) and restyled the popup; see CHANGELOG, Unreleased.
         if (!_node_mouseover_div) {
             _node_mouseover_div = d3.select("body").append("div")
-                .attr("class", "node_mouseover_tooltip aptx-tip")
+                .attr("class", "aptx-tip")
                 .style("opacity", 1e-6);
         }
 

package/forester.js

@@ -20,7 +20,7 @@
  *
  */
 
-// v 3.23.0
+// v 3.24.0
 // 2026-09-17
 //
 // forester.js is a general suite for dealing with phylogenetic trees.
@@ -7254,18 +7254,28 @@
     // a panel linked to the tree, named "Clock plot"; JS only until the
     // design is final.
     //
-    // THE RULE, designed for two kinds of tree, the first of them built:
+    // 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' (NOT BUILT) -- a tree whose branch lengths are
-    //    divergence and whose tips are dated, with no dates on its ancestors
-    //    (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.
+    // 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
@@ -7277,19 +7287,76 @@
     // 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.
+    // 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', or null
+     * @returns {string|null} 'divergence', 'root-to-tip', or null
      */
     forester.clockPlotKind = function (phy) {
-        if (!phy || !forester.hasTimeAndDivergence(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;
@@ -7298,14 +7365,14 @@
                 return;
             }
             ++tips;
-            let d = auspiceNodeDate(n);
+            let d = dateOf(n);
             if (first === null) {
                 first = d;
             } else if (d !== first) {
                 differ = true;
             }
         });
-        return (tips >= CLOCK_PLOT_MIN_TIPS && differ) ? 'divergence' : null;
+        return (tips >= CLOCK_PLOT_MIN_TIPS && differ) ? kind : null;
     };
 
     /**
@@ -7363,14 +7430,25 @@
      * @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'
+     *   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
-     *   root      {node, date, div}: the top of the view
+     *             `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'
@@ -7391,24 +7469,49 @@
         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);
-            let div = auspiceNodeDiv(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;    // not on a tree with Time and Div; a guard, not a rule
+                return;    // an undated ancestor (root-to-tip), or a guard, not a rule
             }
-            let tip = !(n.children && n.children.length > 0);
             points.push({node: n, date: date, div: div, tip: tip});
             if (tip) {
                 xs.push(date);
                 ys.push(div);
             }
         });
-        let forward = timeIncreasesTowardTips(treeRoot);
-        let root = {node: top, date: auspiceNodeDate(top), div: auspiceNodeDiv(top)};
+        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;
@@ -7420,11 +7523,17 @@
                 }
             }
         }
+        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),
-            fromRates: treeRoot._divergenceFromRates === true && !recordsDivergence(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

package/package.json

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