archaeopteryx 3.9.0 → 3.11.0

package/forester.js

@@ -20,7 +20,7 @@
  *
  */
 
-// v 3.9.0
+// v 3.11.0
 // 2026-09-17
 //
 // forester.js is a general suite for dealing with phylogenetic trees.
@@ -2775,6 +2775,780 @@
         return candidates;
     };
 
+    /**
+     * The HEAT-MAP columns of a tree: every per-tip NUMERIC property ref, and the
+     * one shared scale their values are drawn on.
+     *
+     * Candidacy is not decided here. A column is a ref that
+     * `forester.visualizationCandidates` already calls a numeric property, so the
+     * heat map offers exactly what Color-by offers and inherits the refusal rules
+     * with it -- a ref carried twice by one node, a ref no tip has, an internal
+     * `aptx:` ref. Two features disagreeing about what counts as a numeric field
+     * would be worse than either rule.
+     *
+     * The ORDER is this function's own, and it is not first-appearance. The
+     * candidate list is sorted by the selection ranking, which is right for a menu
+     * and wrong for a matrix: a producer writes the columns in the order it means
+     * them to be read -- gene classes together, say -- and that grouping is
+     * information a matrix should keep.
+     *
+     * But a tip may be MISSING a column, and first-appearance then breaks on the
+     * very thing it is for. Measured on the pan-genome demo: 7 of its 100 tips
+     * carry no `dnaK`, the first tip is one of them, and first-appearance put a
+     * core gene at column 40 of 40, splitting the core block it belongs to. So each
+     * column sits at its MEAN position among the tips that do carry it -- every
+     * tip's own property order is intact, and averaging merges those orders without
+     * one gap being able to move a column. `dnaK` is at index 2 in the tips that
+     * have it, `recA` at 2.93 across tips with and without, so the core block
+     * survives. First appearance breaks a tie, so the result is deterministic.
+     *
+     * ONE scale spans every column, so a value means the same thing across the
+     * matrix: a 4 in one gene is the colour a 4 is in every other. Per-column
+     * scaling would make each column use the whole range and a colour mean
+     * something different in each.
+     *
+     * Returns `{ refs: [{ref, label}], min, max }`, or refs: [] when the tree has
+     * no numeric per-tip property. `min`/`max` are over every value of every
+     * column and are `null` when there is nothing to scale.
+     */
+    forester.heatmapColumns = function (tree) {
+        let numeric = Object.create(null);
+        let label = Object.create(null);
+        forester.visualizationCandidates(tree).forEach(function (c) {
+            if (c && c.kind === 'property' && c.numeric === true && c.ref) {
+                numeric[c.ref] = true;
+                label[c.ref] = c.label || c.ref;
+            }
+        });
+        let seen = Object.create(null);    // ref -> its label, for the refs any tip carries
+        let sequences = [];                // one per tip: the columns IT lists, in ITS order
+        let min = null;
+        let max = null;
+        forester.preOrderTraversalAll(tree, function (n) {
+            if (n.children && n.children.length > 0) {
+                return;                      // per-TIP columns: an internal node has no row
+            }
+            let seq = [];
+            (n.properties || []).forEach(function (p) {
+                if (!p || !numeric[p.ref]) {
+                    return;
+                }
+                seen[p.ref] = label[p.ref];
+                seq.push(p.ref);
+                let v = forester.heatmapValue(n, p.ref);
+                if (v !== null) {
+                    min = (min === null || v < min) ? v : min;
+                    max = (max === null || v > max) ? v : max;
+                }
+            });
+            if (seq.length > 0) {
+                sequences.push(seq);
+            }
+        });
+        // The consensus of what the tips actually said (see
+        // heatmapConsensusOrder). Nothing here depends on the order the tips
+        // were REACHED in, and that matters: the traversal follows the tree's
+        // current child order, which ladderizing rewrites -- measured, the same
+        // file once gave "B A" ladderized and "A B" not. A column order is a
+        // fact about the values.
+        let refs = forester.heatmapConsensusOrder(sequences, Object.keys(seen));
+        return {
+            refs: refs.map(function (ref) {
+                return {ref: ref, label: seen[ref]};
+            }),
+            min: min,
+            max: max
+        };
+    };
+
+    /**
+     * The number in `node`'s heat-map cell for `ref`, or `null` when there is none.
+     *
+     * `null` is NOT zero and must never be drawn as one: a missing property is a
+     * cell nobody filled in -- absence of evidence -- and on a presence/absence
+     * matrix reading it as 0 would state the opposite of what the file says. An
+     * empty, blank or non-numeric value is the same case. Only the FIRST value of
+     * a repeated ref can be shown, there being one cell to show it in; such refs
+     * are refused upstream as candidates, so this is a backstop, not the path.
+     */
+    forester.heatmapValue = function (node, ref) {
+        let ps = (node && node.properties) || [];
+        for (let i = 0; i < ps.length; i++) {
+            if (ps[i] && ps[i].ref === ref) {
+                let v = ps[i].value;
+                if (v === null || v === undefined || String(v).trim() === '') {
+                    return null;
+                }
+                let n = Number(String(v).trim());
+                return isFinite(n) ? n : null;
+            }
+        }
+        return null;
+    };
+
+    // ---- heat-map column ORDER -------------------------------------------
+    //
+    // The desktop's View > Order Matrix Columns, minus its Manual mode (which
+    // needs a drag-to-reorder dialog we have not got). Every data-driven mode
+    // starts from the columns in DOCUMENT order, so a result never depends on
+    // the order they happened to be in: switching Alphabetical -> Clustered
+    // and Document -> Clustered must give the same clustering.
+    //
+    // A cell that is not assessed never counts as 0, in any mode: blank is
+    // absence of evidence, not evidence of absence.
+
+    forester.HEATMAP_ORDER_MODES = ['document', 'clustered', 'clustered-presence', 'alphabetical',
+        'frequency', 'manual'];
+
+    /**
+     * The value of every column at every tip, [column][tip], null where the
+     * tip has no value -- the same number the cell is drawn from. EVERY tip
+     * counts, collapsed or not, as the shared colour scale does: an order that
+     * changed when a clade is collapsed would make the columns jump under the
+     * reader.
+     */
+    forester.heatmapValueMatrix = function (tree, refs) {
+        let tips = forester.getAllExternalNodes(tree);
+        return refs.map(function (ref) {
+            return tips.map(function (t) {
+                return forester.heatmapValue(t, ref);
+            });
+        });
+    };
+
+    /**
+     * Euclidean distance between every two columns, R's dist(method =
+     * "euclidean") convention for missing values: only the tips where BOTH
+     * columns have a value are used, and the squared sum is scaled up by
+     * tips / used, so a pair assessed on fewer tips is not made to look closer
+     * for it. A pair that shares no assessed tip at all has no distance; it is
+     * +Infinity here (R returns NA and its hclust then refuses), so it joins
+     * last.
+     */
+    forester.heatmapEuclideanDistances = function (v) {
+        let n = v.length;
+        let d = v.map(function () {
+            return new Array(n).fill(0);
+        });
+        for (let a = 0; a < n; ++a) {
+            for (let b = a + 1; b < n; ++b) {
+                let sum = 0;
+                let used = 0;
+                let tips = v[a].length;
+                for (let t = 0; t < tips; ++t) {
+                    if (v[a][t] !== null && v[b][t] !== null) {
+                        let dev = v[a][t] - v[b][t];
+                        sum += dev * dev;
+                        ++used;
+                    }
+                }
+                let dist = (used === 0) ? Infinity
+                    : Math.sqrt((used === tips) ? sum : (sum / (used / tips)));
+                d[a][b] = dist;
+                d[b][a] = dist;
+            }
+        }
+        return d;
+    };
+
+    /**
+     * Bray-Curtis dissimilarity between every two columns: sum|x - y| /
+     * sum(x + y) over the tips where BOTH have a value (pairwise deletion, R
+     * vegan's vegdist(method = "bray", na.rm = TRUE)). Being a ratio it
+     * normalizes itself, so -- unlike Euclidean -- it needs no scale-up for
+     * the tips it dropped.
+     *
+     * A tip where both columns are 0 adds nothing to either sum, so it drops
+     * out: the DOUBLE ZERO, which Euclidean reads as agreement, is simply not
+     * evidence here. Two genes that are each rare and never in the same tip
+     * are maximally distant (1) rather than nearly identical. On 0/1 data this
+     * is exactly the Sorensen-Dice dissimilarity 1 - 2|A and B| / (|A| + |B|).
+     *
+     * Two divergences from vegdist, both forced: a pair sharing no assessed
+     * tip is +Infinity (vegdist gives NA, and hclust then refuses), and a pair
+     * that is 0 at every tip it shares -- the undefined 0/0 -- is 0, because
+     * those columns are identical wherever they can be compared (vegdist gives
+     * NaN). The same rule covers the only other way the denominator can fail,
+     * negative values cancelling: a pair that cannot be told apart is 0, one
+     * that differs over a non-positive total is +Infinity rather than a
+     * negative or NaN distance. Bray-Curtis is meant for values 0 or more.
+     *
+     * The result is a DISSIMILARITY, not a metric -- it does not obey the
+     * triangle inequality, which complete linkage does not require.
+     */
+    forester.heatmapBrayCurtisDistances = function (v) {
+        let n = v.length;
+        let d = v.map(function () {
+            return new Array(n).fill(0);
+        });
+        for (let a = 0; a < n; ++a) {
+            for (let b = a + 1; b < n; ++b) {
+                let num = 0;
+                let den = 0;
+                let used = 0;
+                let tips = v[a].length;
+                for (let t = 0; t < tips; ++t) {
+                    if (v[a][t] !== null && v[b][t] !== null) {
+                        num += Math.abs(v[a][t] - v[b][t]);
+                        den += v[a][t] + v[b][t];
+                        ++used;
+                    }
+                }
+                let dist;
+                if (used === 0) {
+                    dist = Infinity;
+                } else if (den <= 0) {
+                    dist = (num === 0) ? 0 : Infinity;
+                } else {
+                    dist = num / den;
+                }
+                d[a][b] = dist;
+                d[b][a] = dist;
+            }
+        }
+        return d;
+    };
+
+    /**
+     * The complete-linkage dendrogram of a symmetric distance matrix, the same
+     * structure R's hclust returns, so it can be pinned against R wholesale:
+     *
+     *   left / right  one merge per stage, in R's $merge node-id convention --
+     *                 a NEGATIVE value is the singleton of that index
+     *                 (-1 = column 0), a POSITIVE value the cluster formed at
+     *                 that earlier stage. Oriented by R's hcass2 rule
+     *                 (singleton before cluster, lower index between
+     *                 singletons, earlier stage between clusters), which is
+     *                 what makes the leaf order reproducible.
+     *   height        the distance each merge happened AT ($height) -- what a
+     *                 drawn dendrogram's bar heights are. It can be +Infinity
+     *                 for a pair sharing no assessed tip, so anything drawing
+     *                 it has to decide what to do with a merge that has no
+     *                 finite height.
+     *   order         the leaves as $order reads them out, which is the column
+     *                 order itself.
+     *
+     * Each step merges the closest two clusters; a cluster is labelled by its
+     * lowest member index and a tie goes to the first pair the (i, j) scan
+     * finds, which is what R's nearest-neighbour scan does. The merged
+     * cluster's distance to every other is the LARGER of the two (complete
+     * linkage, the Lance-Williams update R uses).
+     */
+    forester.heatmapCompleteLinkage = function (d) {
+        let n = d.length;
+        if (n === 0) {
+            return {left: [], right: [], height: [], order: []};
+        }
+        if (n === 1) {
+            return {left: [], right: [], height: [], order: [0]};
+        }
+        let dist = d.map(function (row) {
+            return row.slice();
+        });
+        let active = new Array(n).fill(true);
+        // node id of the cluster currently labelled i: -(i+1) for a singleton,
+        // (stage+1) for a merged cluster
+        let node = new Array(n);
+        for (let i = 0; i < n; ++i) {
+            node[i] = -(i + 1);
+        }
+        let left = new Array(n - 1);
+        let right = new Array(n - 1);
+        let height = new Array(n - 1);
+        for (let stage = 0; stage < (n - 1); ++stage) {
+            let bi = -1;
+            let bj = -1;
+            let best = NaN;
+            for (let i = 0; i < n; ++i) {
+                if (!active[i]) {
+                    continue;
+                }
+                for (let j = i + 1; j < n; ++j) {
+                    if (!active[j]) {
+                        continue;
+                    }
+                    // strictly smaller only: the FIRST pair in (i, j) order
+                    // wins a tie, as in R's scan
+                    if ((bi < 0) || (dist[i][j] < best)) {
+                        best = dist[i][j];
+                        bi = i;
+                        bj = j;
+                    }
+                }
+            }
+            // hcass2's orientation, as one rule: singletons are negative,
+            // clusters positive by stage
+            let a = node[bi];
+            let b = node[bj];
+            let l;
+            let r;
+            if ((a < 0) && (b < 0)) {
+                l = (-a < -b) ? a : b;
+                r = (-a < -b) ? b : a;
+            } else if ((a < 0) || (b < 0)) {
+                l = (a < 0) ? a : b;
+                r = (a < 0) ? b : a;
+            } else {
+                l = Math.min(a, b);
+                r = Math.max(a, b);
+            }
+            left[stage] = l;
+            right[stage] = r;
+            height[stage] = best;
+            // complete linkage: the merged cluster (kept under the lower
+            // label, bi) is as far as its farther half
+            for (let k = 0; k < n; ++k) {
+                if (active[k] && (k !== bi) && (k !== bj)) {
+                    let m = Math.max(dist[bi][k], dist[bj][k]);
+                    dist[bi][k] = m;
+                    dist[k][bi] = m;
+                }
+            }
+            active[bj] = false;
+            node[bi] = stage + 1;
+        }
+        // expand from the root, in place, left child before right -- hcass2's IORDER
+        let order = [left[n - 2], right[n - 2]];
+        for (let stage = n - 2; stage >= 1; --stage) {
+            let pos = order.indexOf(stage);   // the cluster formed at this stage (1-based node id)
+            if (pos >= 0) {
+                order[pos] = left[stage - 1];
+                order.splice(pos + 1, 0, right[stage - 1]);
+            }
+        }
+        return {
+            left: left, right: right, height: height,
+            order: order.map(function (v) {
+                return -v - 1;
+            })
+        };
+    };
+
+    /**
+     * `columns` (the {ref, label} objects forester.heatmapColumns returned, in
+     * DOCUMENT order) re-ordered for `mode`, with the dendrogram behind that
+     * order when there is one.
+     *
+     * The dendrogram is returned only for a clustered mode with at least three
+     * columns -- fewer than three have one order up to a flip and are left
+     * alone, so there is no clustering behind them -- and only when its leaves
+     * ARE the order being returned. A dendrogram drawn over a matrix it does
+     * not describe would have connectors that cross: a picture asserting a
+     * grouping the columns do not have. Checking the answer beats enumerating
+     * the ways to get there.
+     */
+    /**
+     * `columns` put back into DOCUMENT order -- the consensus of what this
+     * tree's tips actually said, read by heatmapConsensusOrder over exactly the
+     * columns GIVEN. A column no tip carries casts no votes and cannot be
+     * placed by them; it must not be dropped for that, so it lands at the end,
+     * by ref.
+     *
+     * Every data-driven mode normalises through here precisely so a result
+     * cannot depend on the order the columns happened to be in -- the previous
+     * mode's, say. Going through heatmapColumns instead would drag in its
+     * CANDIDACY rules (a constant column is refused as a visualization), and an
+     * order must not move for a reason that has nothing to do with ordering.
+     */
+    forester.heatmapInDocumentOrder = function (tree, columns) {
+        let cols = (columns || []).slice();
+        let want = Object.create(null);
+        cols.forEach(function (c) {
+            want[c.ref] = c;
+        });
+        let sequences = [];
+        forester.preOrderTraversalAll(tree, function (n) {
+            if (n.children && n.children.length > 0) {
+                return;
+            }
+            let seq = [];
+            (n.properties || []).forEach(function (p) {
+                if (p && want[p.ref]) {
+                    seq.push(p.ref);
+                }
+            });
+            if (seq.length > 0) {
+                sequences.push(seq);
+            }
+        });
+        // The same consensus forester.heatmapColumns reads, over exactly the
+        // columns GIVEN, so it cannot be moved by a candidacy rule that has
+        // nothing to do with ordering. A column no tip carries casts no votes
+        // and has no position; it lands last, by ref, so the result depends
+        // only on its inputs as a SET.
+        return forester.heatmapConsensusOrder(sequences, cols.map(function (c) {
+            return c.ref;
+        })).map(function (ref) {
+            return want[ref];
+        });
+    };
+
+    /**
+     * The order a heat map opens in when nobody said: a CLUSTERED one, with the
+     * distance picked from the data.
+     *
+     * Bray-Curtis is the better read on presence/absence and abundance data --
+     * it is what the double-zero problem calls for -- but it is meant for
+     * values 0 or more, and these columns are every numeric field the tree
+     * happens to carry rather than a hand-picked matrix. Measured: on a
+     * latitude/longitude matrix 2 of 6 pairs come out with no distance at all
+     * (+Infinity, so they join last arbitrarily), and a year column among small
+     * ones sits at 0.9995 from every one of them -- maximally distant for being
+     * LARGE rather than for any pattern. Within a block of comparable magnitude
+     * it is exactly right; across magnitudes it measures magnitude.
+     *
+     * So: Bray-Curtis where there are zeros to ignore and nothing negative,
+     * Euclidean otherwise. A zero is precisely the precondition for a double
+     * zero to exist -- without one there is nothing for Bray-Curtis to drop,
+     * and a matrix of years or coordinates is the safer read on Euclidean.
+     */
+    /**
+     * How far the INPUT agrees with itself about the column order: {tips,
+     * conflicting}, where a tip conflicts when its own property list is not in
+     * the order `columns` gives (gaps are fine -- a tip that simply lacks a
+     * column is not a disagreement).
+     *
+     * This is what lets the "As in the input" control say whether that order is
+     * the file's or only a consensus. phyloXML gives every node its OWN
+     * property list, unlike a table, so tips CAN list the same columns in
+     * different orders, and a reader has no way of knowing without being told.
+     * Measured on the shipped demos: 0 of 50 and 0 of 100 tips conflict, while
+     * influenza.xml has 2 of 6.
+     */
+
+    /**
+     * ONE column order out of many tips that each list their own columns in
+     * their own order. `sequences` is one array of refs per tip -- that tip's
+     * own order, gaps and all -- and `refs` is the set to place.
+     *
+     * Averaging each column's position was the obvious rule and it fails on a
+     * shape that is not at all exotic: two groups of columns that no tip ever
+     * carries TOGETHER. Tips holding A,B and tips holding X,Y put A and X both
+     * at position 0, so the average interleaves them into X A Y B instead of
+     * leaving the two blocks whole. No tie-break can mend that -- the average
+     * itself is what is wrong, because it compares positions measured on tips
+     * that share no frame of reference.
+     *
+     * So the order is read off a PRECEDENCE GRAPH instead. Each tip votes on
+     * the pairs it actually lists next to each other, the majority direction
+     * of each pair becomes an edge, and the columns come out of a topological
+     * sort of that graph. Two blocks with no tip in common cast no votes about
+     * each other, so nothing forces them apart, and the sort emits one and then
+     * the other.
+     *
+     * Only ADJACENT pairs are looked at -- both the votes and the neighbour
+     * sets the block rule reads -- which keeps this linear in the data. Every
+     * pair would be quadratic in the column count, and a wide matrix is exactly
+     * where that hurts: measured at 42 seconds on 2000 columns across 200 tips,
+     * against 0.2 for adjacency. Transitivity comes from the sort rather than
+     * from the votes, and a block stays whole through its chain of neighbours. The cost is that adjacency can manufacture a cycle where all
+     * pairs would not -- tips A,B,C and C,A give A->B->C->A -- so cycles are
+     * broken rather than assumed away.
+     *
+     * Where the graph says nothing, the old rule decides, so every case it
+     * already got right is unchanged: mean position, then the better-attested
+     * column, then the ref. What is new is that a column is preferred while it
+     * still shares a tip with the one just placed, which is what keeps a block
+     * together once it has been started.
+     */
+    forester.heatmapConsensusOrder = function (sequences, refs) {
+        let all = (refs || []).slice();
+        let n = all.length;
+        if (n < 2) {
+            return all;
+        }
+        let idx = Object.create(null);
+        all.forEach(function (r, i) {
+            idx[r] = i;
+        });
+        let sum = new Array(n).fill(0);
+        let tips = new Array(n).fill(0);
+        let votes = new Map();          // i*n + j -> tips putting i just before j
+        let near = [];                  // i -> Set of columns some tip lists NEXT to i
+        for (let i = 0; i < n; ++i) {
+            near.push(new Set());
+        }
+        (sequences || []).forEach(function (seq) {
+            let at = 0;
+            let prev = -1;
+            for (let k = 0; k < seq.length; ++k) {
+                let j = idx[seq[k]];
+                if (j === undefined) {
+                    continue;
+                }
+                sum[j] += at;
+                tips[j]++;
+                at++;
+                if (prev >= 0 && prev !== j) {
+                    let key = (prev * n) + j;
+                    votes.set(key, (votes.get(key) || 0) + 1);
+                    // neighbours, for the block rule below. Adjacency again,
+                    // not every pair on the tip: every pair is quadratic in the
+                    // column count, and measured, it was 42 SECONDS on 2000
+                    // columns across 200 tips. A block stays whole through its
+                    // chain of neighbours, so adjacency is all it needs.
+                    near[prev].add(j);
+                    near[j].add(prev);
+                }
+                prev = j;
+            }
+        });
+        let mean = new Array(n);
+        for (let i = 0; i < n; ++i) {
+            mean[i] = (tips[i] > 0) ? (sum[i] / tips[i]) : Infinity;
+        }
+        // the majority direction of each voted pair becomes an edge; a pair its
+        // tips split evenly says nothing and gets none
+        let out = [];
+        let indeg = new Array(n).fill(0);
+        for (let i = 0; i < n; ++i) {
+            out.push([]);
+        }
+        votes.forEach(function (count, key) {
+            let i = Math.floor(key / n);
+            let j = key % n;
+            if (count > (votes.get((j * n) + i) || 0)) {
+                out[i].push(j);
+                indeg[j]++;
+            }
+        });
+        // the static key, used wherever the graph is silent: the rule this
+        // replaced, so nothing it already ordered correctly moves
+        function better(a, b, last) {
+            if (last >= 0) {
+                let na = near[last].has(a);
+                let nb = near[last].has(b);
+                if (na !== nb) {
+                    return na;   // keep the block that is already open
+                }
+            }
+            if (mean[a] !== mean[b]) {
+                return mean[a] < mean[b];
+            }
+            if (tips[a] !== tips[b]) {
+                return tips[a] > tips[b];
+            }
+            return all[a] < all[b];
+        }
+        let placed = new Array(n).fill(false);
+        let order = [];
+        let last = -1;
+        for (let step = 0; step < n; ++step) {
+            let pick = -1;
+            for (let i = 0; i < n; ++i) {
+                if (placed[i] || indeg[i] > 0) {
+                    continue;
+                }
+                if (pick < 0 || better(i, pick, last)) {
+                    pick = i;
+                }
+            }
+            if (pick < 0) {
+                // a cycle: no column is free. Break it at the column the fewest
+                // others are waiting on, then by the same static key -- never
+                // leave a column undrawn because its votes disagreed.
+                for (let i = 0; i < n; ++i) {
+                    if (placed[i]) {
+                        continue;
+                    }
+                    if (pick < 0 || indeg[i] < indeg[pick]
+                        || (indeg[i] === indeg[pick] && better(i, pick, last))) {
+                        pick = i;
+                    }
+                }
+            }
+            placed[pick] = true;
+            indeg[pick] = 0;
+            order.push(all[pick]);
+            out[pick].forEach(function (j) {
+                if (!placed[j] && indeg[j] > 0) {
+                    indeg[j]--;
+                }
+            });
+            last = pick;
+        }
+        return order;
+    };
+
+    forester.heatmapInputOrderAgreement = function (tree, columns) {
+        let out = {tips: 0, conflicting: 0};
+        if (!tree || !columns || columns.length < 1) {
+            return out;
+        }
+        let rank = Object.create(null);
+        columns.forEach(function (c, i) {
+            rank[c.ref] = i;
+        });
+        forester.preOrderTraversalAll(tree, function (n) {
+            if (n.children && n.children.length > 0) {
+                return;
+            }
+            let highest = -1;
+            let ordered = true;
+            let carries = false;
+            (n.properties || []).forEach(function (p) {
+                if (!p || !(p.ref in rank)) {
+                    return;
+                }
+                carries = true;
+                let r = rank[p.ref];
+                if (r < highest) {
+                    ordered = false;
+                } else {
+                    highest = r;
+                }
+            });
+            if (!carries) {
+                return;
+            }
+            out.tips++;
+            if (!ordered) {
+                out.conflicting++;
+            }
+        });
+        return out;
+    };
+
+    forester.heatmapDefaultOrder = function (tree, columns) {
+        if (!tree || !columns || columns.length < 1) {
+            return 'document';
+        }
+        let v = forester.heatmapValueMatrix(tree, columns.map(function (c) {
+            return c.ref;
+        }));
+        let any = false;
+        let zero = false;
+        let negative = false;
+        v.forEach(function (row) {
+            row.forEach(function (x) {
+                if (x === null) {
+                    return;
+                }
+                any = true;
+                if (x === 0) {
+                    zero = true;
+                } else if (x < 0) {
+                    negative = true;
+                }
+            });
+        });
+        if (!any) {
+            return 'document';   // nothing to cluster on
+        }
+        return (zero && !negative) ? 'clustered-presence' : 'clustered';
+    };
+
+    /**
+     * `columns` in the order `wanted` names them, which is a reader's own
+     * arrangement and is never second-guessed.
+     *
+     * A column `wanted` does not name is NEW to it -- the tree was edited, a
+     * table was joined since, the order came from a shared link made against a
+     * different file. It cannot be placed by a list that has never heard of it,
+     * so it goes after the ones that can, in the order the tips themselves give
+     * (heatmapInDocumentOrder). A name for a column that is gone is ignored
+     * rather than treated as an error: an order outliving one of its columns is
+     * ordinary, not a fault.
+     */
+    forester.heatmapManualOrder = function (tree, columns, wanted) {
+        let cols = (columns || []).slice();
+        let by = Object.create(null);
+        cols.forEach(function (c) {
+            by[c.ref] = c;
+        });
+        let taken = Object.create(null);
+        let out = [];
+        (wanted || []).forEach(function (ref) {
+            if (by[ref] && !taken[ref]) {
+                taken[ref] = true;
+                out.push(by[ref]);
+            }
+        });
+        let rest = cols.filter(function (c) {
+            return !taken[c.ref];
+        });
+        return (rest.length > 0) ? out.concat(forester.heatmapInDocumentOrder(tree, rest)) : out;
+    };
+
+    forester.heatmapOrder = function (tree, columns, mode, wanted) {
+        let out = {columns: (columns || []).slice(), dendrogram: null};
+        if (!tree || out.columns.length < 1 || !mode || mode === 'document') {
+            return out;
+        }
+        if (mode === 'manual') {
+            // a reader's own order: nothing re-sorts it, and nothing clustered
+            // it, so there is no tree behind it to draw
+            out.columns = forester.heatmapManualOrder(tree, out.columns, wanted);
+            return out;
+        }
+        // Every data-driven mode starts from document order, so switching
+        // Alphabetical -> Clustered and Document -> Clustered must give the
+        // same clustering. Measured: without this the 6x6 linkage fixture fed
+        // in reverse clustered to h6,h5,h3,h4,h2,h1 instead of R's
+        // h6,h3,h5,h4,h1,h2 -- the index order drives the tie-break and the
+        // hcass2 leaf order, so the incoming order really does leak through.
+        let cols = forester.heatmapInDocumentOrder(tree, out.columns);
+        out.columns = cols;
+        if (mode === 'alphabetical') {
+            out.columns = cols.slice().sort(function (a, b) {
+                let la = String(a.label || a.ref).toLowerCase();
+                let lb = String(b.label || b.ref).toLowerCase();
+                // the raw ref breaks a tie, as the desktop's chooser sorts
+                return (la < lb) ? -1 : ((la > lb) ? 1
+                    : ((a.ref < b.ref) ? -1 : ((a.ref > b.ref) ? 1 : 0)));
+            });
+            return out;
+        }
+        let v = forester.heatmapValueMatrix(tree, cols.map(function (c) {
+            return c.ref;
+        }));
+        if (mode === 'frequency') {
+            // by the mean over the tips that HAVE a value, highest first -- on
+            // 0/1 data exactly the fraction of tips carrying it. A blank is
+            // left out, never averaged in as 0; a column with no value at all
+            // goes last; ties keep document order (the sort is stable).
+            let mean = v.map(function (row) {
+                let sum = 0;
+                let n = 0;
+                row.forEach(function (x) {
+                    if (x !== null) {
+                        sum += x;
+                        ++n;
+                    }
+                });
+                return (n > 0) ? (sum / n) : -Infinity;
+            });
+            out.columns = cols.map(function (c, i) {
+                return {c: c, i: i};
+            }).sort(function (a, b) {
+                return (mean[b.i] - mean[a.i]) || (a.i - b.i);
+            }).map(function (e) {
+                return e.c;
+            });
+            return out;
+        }
+        if (mode !== 'clustered' && mode !== 'clustered-presence') {
+            return out;
+        }
+        if (cols.length < 3) {
+            return out;   // one order up to a flip, and R puts index 1 first
+        }
+        let d = (mode === 'clustered')
+            ? forester.heatmapEuclideanDistances(v)
+            : forester.heatmapBrayCurtisDistances(v);
+        let dendro = forester.heatmapCompleteLinkage(d);
+        let ordered = dendro.order.map(function (g) {
+            return cols[g];
+        });
+        out.columns = ordered;
+        // the self-check: the picture is offered only if it describes the order
+        if (dendro.order.length === cols.length) {
+            out.dendrogram = dendro;
+        }
+        return out;
+    };
+
+
     forester.collectBasicTreeProperties = function (tree) {
         let properties = {};
         properties.internalNodeData = false;
@@ -4988,6 +5762,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 +5776,8 @@
                 }
             }
         }
-        return null;
+        return (typeof node._divergence === 'number' && isFinite(node._divergence))
+            ? node._divergence : null;
     }
 
     function auspiceHasAnyDate(node) {
@@ -5051,12 +5831,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
@@ -5669,12 +6637,18 @@
     // so the two programs write the same table: name (always), the first
     // taxonomy's scientific name, common name, code, id and rank, the first
     // sequence's name, gene name, symbol, accession and type, the branch
-    // length, then one column per property ref, sorted, holding its first
-    // value. A column no tip has a value for is left out. When the tip names
-    // cannot key the rows (one blank or repeated), a node_id column comes
-    // first, from idOf(tip, index) or the row number. Tabs and line breaks
-    // inside a value become spaces. A property keeps its ref as the header,
-    // so the table joins back onto a tree with joinMetadataTable.
+    // length, then one column per property ref, sorted, holding its value and
+    // joining repeats of that ref with '; '. A column no tip has a value for
+    // is left out. When the tip names cannot key the rows (one blank or
+    // repeated), a node_id column comes first, from idOf(tip, index) or the
+    // row number. Tabs and line breaks inside a value become spaces. A
+    // property keeps its ref as the header, so the table joins back onto a
+    // tree with joinMetadataTable. One KNOWN divergence as of 2026-09-17: a
+    // ref REPEATED on one node. We join every value with '; ' in document
+    // order; the desktop's NodeDataExporter.propertyValue takes ps.get(0) and
+    // drops the rest. Both programs wrote that bug independently, so the shape
+    // of the API invited it rather than either side being careless. They mean
+    // to follow us here (Christian deciding), so this is us ahead, not adrift.
     forester.externalNodeDataTable = function (tips, idOf) {
         tips = tips || [];
         if (tips.length === 0) {
@@ -5731,8 +6705,17 @@
         });
         Array.from(refs).sort().forEach(function (ref) {
             add(ref, function (n) {
-                let p = (n.properties || []).filter(function (q) { return q.ref === ref; })[0];
-                return p ? p.value : '';
+                // Every value, not just the first: phyloXML lets a ref repeat
+                // on a node, and until 2026-09-17 this kept only [0], so a tip
+                // carrying meta:zeta twice exported one of them and lost the
+                // other with nothing to show it had happened. Joined in
+                // document order, which is the order the reader and the writer
+                // both preserve.
+                return (n.properties || []).filter(function (q) {
+                    return q.ref === ref;
+                }).map(function (q) {
+                    return q.value;
+                }).join('; ');
             });
         });
         return {
@@ -7104,11 +8087,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 +8107,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};
     };