archaeopteryx 3.0.0 → 3.1.0

package/forester.js

@@ -20,7 +20,7 @@
  *
  */
 
-// v 3.0.0
+// v 3.1.0
 // 2026-09-04
 //
 // forester.js is a general suite for dealing with phylogenetic trees.
@@ -649,6 +649,21 @@
     const VIS_MAX_NUMERIC_UNIQUE_NUM = 9;    // distinct/covered <= 0.9,
     const VIS_MAX_NUMERIC_UNIQUE_DEN = 10;   // integer-exact as well
     const VIS_EXCLUDED_REF_PREFIX = 'style:';
+    // Refs that are never a visualization, however their values distribute.
+    // A taxon identifier repeats like a category and passes every statistical
+    // test above, yet says nothing a colour could carry that the species name
+    // beside it does not -- and reads as "11320" in a legend. Matched on the
+    // ref's local name with case and separators ignored, so vipr:NCBI_Taxon_Id,
+    // ncbi_taxid, taxon_id and taxonomy_id all count.
+    const VIS_EXCLUDED_LOCAL_NAME_RE = /(taxonomy|taxon|tax)id$/;
+
+    function visExcludedRef(ref) {
+        if (ref.indexOf(VIS_EXCLUDED_REF_PREFIX) === 0) {
+            return true;
+        }
+        let local = ref.substring(ref.indexOf(':') + 1).toLowerCase().replace(/[^a-z0-9]/g, '');
+        return VIS_EXCLUDED_LOCAL_NAME_RE.test(local);
+    }
 
     // ---- display normalization --------------------------------------------
     //
@@ -796,6 +811,14 @@
             .join(' ');
     }
 
+    // The display name for a property ref, as the Color-by menu and legends
+    // show it: namespace dropped, then prettified. Exported so the node-data
+    // dialog names a property the same way the rest of the viewer does.
+    forester.propertyDisplayName = function (ref) {
+        let local = ref.indexOf(':') >= 0 ? ref.substring(ref.indexOf(':') + 1) : ref;
+        return prettifyVisLabel(local);
+    };
+
     forester.visualizationCandidates = function (tree) {
         let total = 0;
         let stats = Object.create(null);   // id -> {kind, ref, label, nodes, values:Set, multi}; null-proto: ids embed file refs
@@ -832,8 +855,7 @@
             if (n.properties) {
                 for (let i = 0; i < n.properties.length; ++i) {
                     let p = n.properties[i];
-                    if (p.ref && p.applies_to === 'node'
-                        && p.ref.indexOf(VIS_EXCLUDED_REF_PREFIX) !== 0) {
+                    if (p.ref && p.applies_to === 'node' && !visExcludedRef(p.ref)) {
                         add('prop:' + p.ref, 'property', p.ref, null, p.value);
                     }
                 }
@@ -1302,6 +1324,17 @@
         // Whether a tree is worth drawing to scale is a question about the
         // majority of its branches, not about whether any branch has a length.
         properties.branchesWithPositiveLength = 0;
+        // Branches that carry a length AT ALL -- an explicit zero is a real
+        // measurement, not a missing one, so these are counted separately from
+        // the "positive" tally above. Split internal-vs-all because a missing
+        // length means different things in the two places: an unmeasured TIP
+        // still draws correctly (at its parent), while an unmeasured INTERNAL
+        // branch destroys the scale. All four counts exclude the root, which
+        // has no branch above it.
+        properties.branchCount = 0;
+        properties.branchesWithLength = 0;
+        properties.internalBranchCount = 0;
+        properties.internalBranchesWithLength = 0;
         properties.averageBranchLength = 0;
         let bl_counter = 0;
         let bl_sum = 0;
@@ -1309,8 +1342,23 @@
         // exist -- skewing the branch-length fraction the viewer uses to choose
         // between a phylogram and a cladogram -- and from phyloXML would take
         // the tree's own name for the longest node name.
-        forester.preOrderTraversalAll(realRootOf(tree), function (n) {
+        let rootNode = realRootOf(tree);
+        forester.preOrderTraversalAll(rootNode, function (n) {
             properties.nodeCount += 1;
+            if (n !== rootNode) {
+                let internal = !!(n.children || n._children);
+                let measured = typeof n.branch_length === 'number' && isFinite(n.branch_length);
+                properties.branchCount += 1;
+                if (measured) {
+                    properties.branchesWithLength += 1;
+                }
+                if (internal) {
+                    properties.internalBranchCount += 1;
+                    if (measured) {
+                        properties.internalBranchesWithLength += 1;
+                    }
+                }
+            }
             if (n.name && n.name.length > 0) {
                 properties.nodeNames = true;
                 if (n.name.length > properties.longestNodeName) {
@@ -1916,9 +1964,12 @@
         if (confidenceValuesAsInternalNames === undefined) {
             confidenceValuesAsInternalNames = false;
         }
-        if ((confidenceValuesInBrackets === true) && (confidenceValuesAsInternalNames === true)) {
-            throw ("confidence values cannot be both in brackets and as internal node names");
-        }
+        // The two options used to be mutually exclusive and throwing. They are
+        // not: brackets are consumed by the tokenizer, bare labels are handled
+        // afterwards, so a file mixing the two dialects is read correctly with
+        // both on. forester-Java never had this guard, so it was never part of
+        // the shared contract -- and throwing on a combination a user
+        // plausibly wants is what forced callers into workarounds.
 
         let ancs = [];
         let x = {};
@@ -3560,6 +3611,117 @@
             {name: 'Miaolingian', young: 497, old: 506.5, color: '#A6CF86'},
             {name: 'Series 2', young: 506.5, old: 521, color: '#99C078'},
             {name: 'Terreneuvian', young: 521, old: 538.8, color: '#8CB06C'}
+        ],
+        // The 101 ratified Phanerozoic stages, plus the Pridoli: a Series with
+        // no stages of its own, standing in the stage row for its own span
+        // (419.62-422.7 Ma) as on the printed ICS chart -- without it the row
+        // would have a hole there. Same source as every rank above
+        // (Macrostrat international timescale, id 11), which the ranks above
+        // match byte for byte; the desktop generated its table from the same
+        // query, so the two programs band from identical data.
+        age: [
+            {name: 'Meghalayan', young: 0, old: 0.0042, color: '#FEF2E0'},
+            {name: 'Northgrippian', young: 0.0042, old: 0.0082, color: '#FEF2E0'},
+            {name: 'Greenlandian', young: 0.0082, old: 0.0117, color: '#FEF2E0'},
+            {name: 'Late Pleistocene', young: 0.0117, old: 0.129, color: '#FFF2C7'},
+            {name: 'Chibanian', young: 0.129, old: 0.774, color: '#FFF2C7'},
+            {name: 'Calabrian', young: 0.774, old: 1.8, color: '#FFF2C7'},
+            {name: 'Gelasian', young: 1.8, old: 2.58, color: '#FFEDB3'},
+            {name: 'Piacenzian', young: 2.58, old: 3.6, color: '#FFFFBF'},
+            {name: 'Zanclean', young: 3.6, old: 5.333, color: '#FFFFB3'},
+            {name: 'Messinian', young: 5.333, old: 7.246, color: '#FFFF73'},
+            {name: 'Tortonian', young: 7.246, old: 11.63, color: '#FFFF66'},
+            {name: 'Serravallian', young: 11.63, old: 13.82, color: '#FFFF59'},
+            {name: 'Langhian', young: 13.82, old: 15.98, color: '#FFFF4D'},
+            {name: 'Burdigalian', young: 15.98, old: 20.45, color: '#FFFF41'},
+            {name: 'Aquitanian', young: 20.45, old: 23.04, color: '#FFFF33'},
+            {name: 'Chattian', young: 23.04, old: 27.3, color: '#FEE6AA'},
+            {name: 'Rupelian', young: 27.3, old: 33.9, color: '#FED99A'},
+            {name: 'Priabonian', young: 33.9, old: 37.71, color: '#FDCDA1'},
+            {name: 'Bartonian', young: 37.71, old: 41.03, color: '#FDC091'},
+            {name: 'Lutetian', young: 41.03, old: 48.07, color: '#FCB482'},
+            {name: 'Ypresian', young: 48.07, old: 56, color: '#FCA773'},
+            {name: 'Thanetian', young: 56, old: 59.24, color: '#FDBF6F'},
+            {name: 'Selandian', young: 59.24, old: 61.66, color: '#FEBF65'},
+            {name: 'Danian', young: 61.66, old: 66, color: '#FDB462'},
+            {name: 'Maastrichtian', young: 66, old: 72.2, color: '#F2FA8C'},
+            {name: 'Campanian', young: 72.2, old: 83.6, color: '#E6F47F'},
+            {name: 'Santonian', young: 83.6, old: 85.7, color: '#D9EF74'},
+            {name: 'Coniacian', young: 85.7, old: 89.8, color: '#CCE968'},
+            {name: 'Turonian', young: 89.8, old: 93.9, color: '#BFE35D'},
+            {name: 'Cenomanian', young: 93.9, old: 100.5, color: '#B3DE53'},
+            {name: 'Albian', young: 100.5, old: 113.2, color: '#CCEA97'},
+            {name: 'Aptian', young: 113.2, old: 121.4, color: '#BFE48A'},
+            {name: 'Barremian', young: 121.4, old: 125.77, color: '#B3DF7F'},
+            {name: 'Hauterivian', young: 125.77, old: 132.6, color: '#A6D975'},
+            {name: 'Valanginian', young: 132.6, old: 137.05, color: '#99D36A'},
+            {name: 'Berriasian', young: 137.05, old: 143.1, color: '#8CCD60'},
+            {name: 'Tithonian', young: 143.1, old: 149.2, color: '#D9F1F7'},
+            {name: 'Kimmeridgian', young: 149.2, old: 154.8, color: '#CCECF4'},
+            {name: 'Oxfordian', young: 154.8, old: 161.5, color: '#BFE7F1'},
+            {name: 'Callovian', young: 161.5, old: 165.3, color: '#BFE7E5'},
+            {name: 'Bathonian', young: 165.3, old: 168.2, color: '#B3E2E3'},
+            {name: 'Bajocian', young: 168.2, old: 170.9, color: '#A6DDE0'},
+            {name: 'Aalenian', young: 170.9, old: 174.7, color: '#9AD9DD'},
+            {name: 'Toarcian', young: 174.7, old: 184.2, color: '#99CEE3'},
+            {name: 'Pliensbachian', young: 184.2, old: 192.9, color: '#80C5DD'},
+            {name: 'Sinemurian', young: 192.9, old: 199.5, color: '#67BCD8'},
+            {name: 'Hettangian', young: 199.5, old: 201.4, color: '#4EB3D3'},
+            {name: 'Rhaetian', young: 201.4, old: 205.7, color: '#E3B9DB'},
+            {name: 'Norian', young: 205.7, old: 227.3, color: '#D6AAD3'},
+            {name: 'Carnian', young: 227.3, old: 237, color: '#C99BCB'},
+            {name: 'Ladinian', young: 237, old: 241.464, color: '#C983BF'},
+            {name: 'Anisian', young: 241.464, old: 246.7, color: '#BC75B7'},
+            {name: 'Olenekian', young: 246.7, old: 249.9, color: '#B051A5'},
+            {name: 'Induan', young: 249.9, old: 251.902, color: '#A4469F'},
+            {name: 'Changhsingian', young: 251.902, old: 254.14, color: '#FCC0B2'},
+            {name: 'Wuchiapingian', young: 254.14, old: 259.51, color: '#FCB4A2'},
+            {name: 'Capitanian', young: 259.51, old: 264.28, color: '#FB9A85'},
+            {name: 'Wordian', young: 264.28, old: 266.9, color: '#FB8D76'},
+            {name: 'Roadian', young: 266.9, old: 274.4, color: '#FB8069'},
+            {name: 'Kungurian', young: 274.4, old: 283.3, color: '#E38776'},
+            {name: 'Artinskian', young: 283.3, old: 290.1, color: '#E37B68'},
+            {name: 'Sakmarian', young: 290.1, old: 293.52, color: '#E36F5C'},
+            {name: 'Asselian', young: 293.52, old: 298.9, color: '#E36350'},
+            {name: 'Gzhelian', young: 298.9, old: 303.7, color: '#CCD4C7'},
+            {name: 'Kasimovian', young: 303.7, old: 307, color: '#BFD0C5'},
+            {name: 'Moscovian', young: 307, old: 315.2, color: '#C7CBB9'},
+            {name: 'Bashkirian', young: 315.2, old: 323.4, color: '#99C2B5'},
+            {name: 'Serpukhovian', young: 323.4, old: 330.3, color: '#BFC26B'},
+            {name: 'Visean', young: 330.3, old: 346.7, color: '#A6B96C'},
+            {name: 'Tournaisian', young: 346.7, old: 358.86, color: '#8CB06C'},
+            {name: 'Famennian', young: 358.86, old: 372.15, color: '#F2EDC5'},
+            {name: 'Frasnian', young: 372.15, old: 382.31, color: '#F2EDAD'},
+            {name: 'Givetian', young: 382.31, old: 387.95, color: '#F1E185'},
+            {name: 'Eifelian', young: 387.95, old: 393.47, color: '#F1D576'},
+            {name: 'Emsian', young: 393.47, old: 410.62, color: '#E5D075'},
+            {name: 'Pragian', young: 410.62, old: 413.02, color: '#E5C468'},
+            {name: 'Lochkovian', young: 413.02, old: 419.62, color: '#E5B75A'},
+            {name: 'Pridoli', young: 419.62, old: 422.7, color: '#E6F5E1'},
+            {name: 'Ludfordian', young: 422.7, old: 425, color: '#D9F0DF'},
+            {name: 'Gorstian', young: 425, old: 426.7, color: '#CCECDD'},
+            {name: 'Homerian', young: 426.7, old: 430.6, color: '#CCEBD1'},
+            {name: 'Sheinwoodian', young: 430.6, old: 432.9, color: '#BFE6C3'},
+            {name: 'Telychian', young: 432.9, old: 438.6, color: '#BFE6CF'},
+            {name: 'Aeronian', young: 438.6, old: 440.5, color: '#B3E1C2'},
+            {name: 'Rhuddanian', young: 440.5, old: 443.1, color: '#A6DCB5'},
+            {name: 'Hirnantian', young: 443.1, old: 445.2, color: '#A6DBAB'},
+            {name: 'Katian', young: 445.2, old: 452.8, color: '#99D69F'},
+            {name: 'Sandbian', young: 452.8, old: 458.2, color: '#8CD094'},
+            {name: 'Darriwilian', young: 458.2, old: 469.4, color: '#74C69C'},
+            {name: 'Dapingian', young: 469.4, old: 471.3, color: '#66C092'},
+            {name: 'Floian', young: 471.3, old: 477.1, color: '#41B087'},
+            {name: 'Tremadocian', young: 477.1, old: 486.85, color: '#33A97E'},
+            {name: 'Stage 10', young: 486.85, old: 491, color: '#E6F5C9'},
+            {name: 'Jiangshanian', young: 491, old: 494.2, color: '#D9F0BB'},
+            {name: 'Paibian', young: 494.2, old: 497, color: '#CCEBAE'},
+            {name: 'Guzhangian', young: 497, old: 500.5, color: '#CCDFAA'},
+            {name: 'Drumian', young: 500.5, old: 504.5, color: '#BFD99D'},
+            {name: 'Wuliuan', young: 504.5, old: 506.5, color: '#B3D492'},
+            {name: 'Stage 4', young: 506.5, old: 514.5, color: '#B3CA8E'},
+            {name: 'Stage 3', young: 514.5, old: 521, color: '#A6C583'},
+            {name: 'Stage 2', young: 521, old: 529, color: '#A6BA80'},
+            {name: 'Fortunian', young: 529, old: 538.8, color: '#99B575'}
         ]
     };
 
@@ -3573,10 +3735,26 @@
         return ivs.length > 0 ? ivs[ivs.length - 1].old : 0;
     };
 
-    // The [coarse, fine] rank pair for a tree reaching back oldMa: always the
-    // finest pair that still fully covers the range, so a deep tree never
-    // shows blank band segments.
-    forester.geoBandRanks = function (oldMa) {
+    // The [coarse, fine] rank pair for the span [youngMa, oldMa] a tree
+    // actually occupies -- the youngest tip to the root, not 0 to the root,
+    // so a fossil-only clade bands on its own window rather than on the
+    // whole stretch back from the present.
+    //
+    // It adapts FINER as well as coarser. A narrow Phanerozoic window --
+    // one or two Series -- bands Series over STAGE (the ICS ages), which is
+    // what a 66-100 Ma dinosaur tree needs to say anything at all: over
+    // Period/Epoch it would read "Cretaceous / Late Cretaceous" and nothing
+    // more. Wider than two Series the stages would be slivers, so the
+    // existing ladder takes over: the finest pair that still fully covers the
+    // range, so a deep tree never shows blank band segments. Shared rule with
+    // the desktop's GeologicTimeScale.bandRanks -- change both or neither.
+    forester.geoBandRanks = function (youngMa, oldMa) {
+        if (oldMa <= forester.geoCoverage('age')) {   // stages are Phanerozoic-only
+            let series = forester.geoOverlapping('epoch', youngMa, oldMa).length;
+            if (series > 0 && series <= 2) {
+                return ['epoch', 'age'];
+            }
+        }
         if (oldMa <= forester.geoCoverage('epoch')) {
             return ['period', 'epoch'];
         }
@@ -4075,6 +4253,114 @@
     // extractors: {name, taxonomy, sequence}, each a function(externalNode)
     // returning the text that field would contribute to the node's label, or
     // null / '' when it contributes nothing.
+    /**
+     * Reads bare numeric internal node labels as confidence values -- the
+     * dialect nearly every tree writer emits (RAxML, IQ-TREE, FastTree, MEGA,
+     * BV-BRC) writes branch support as `)100:0.05`, which the New Hampshire
+     * grammar makes an internal node NAME.
+     *
+     * The rule is shared with the desktop Java Archaeopteryx; change it only
+     * together with that implementation.
+     *
+     * mode 'auto' (the default) is ALL-OR-NOTHING: every candidate label must
+     * look like support, so a tree of real clade names is never touched.
+     * mode 'confidence' is PER-NODE and unbounded: every numeric label is
+     * promoted whatever its value, which is how a user forces a mixed tree
+     * (some clade names, some support) or an out-of-range scale. mode 'label'
+     * does nothing -- the labels stay names.
+     *
+     * The ROOT is never promoted in any mode: a confidence belongs to the
+     * branch ABOVE a node and the root has none, so a numeric label there is
+     * almost always the tree's name -- `)99;` would otherwise lose it while
+     * `)MyTree;` kept it.
+     *
+     * Promotion MOVES: the label is cleared as the confidence is added, or the
+     * value would be drawn twice.
+     *
+     * Pure apart from the mutation it is asked to make, and returns the number
+     * of labels promoted so the CALLER can react (the viewer switches its
+     * confidence display on, so support values appear rather than names
+     * silently vanishing). Deliberately does not touch display state itself.
+     *
+     * @param phy - the phylogeny
+     * @param mode - 'auto' | 'confidence' | 'label'
+     * @returns {number} how many internal labels became confidences
+     */
+    forester.promoteInternalLabelsToConfidence = function (phy, mode) {
+        if (mode === 'label') {
+            return 0;
+        }
+        if (mode !== 'confidence') {
+            mode = 'auto';
+        }
+        let root = forester.getTreeRoot(phy);
+        let candidates = [];
+        let anyConfidence = false;
+        forester.preOrderTraversalAll(root, function (n) {
+            if (n === root || !(n.children || n._children)) {
+                return;
+            }
+            if (n.confidences && n.confidences.length > 0) {
+                anyConfidence = true;
+            }
+            if (typeof n.name === 'string' && n.name.length > 0) {
+                candidates.push(n);
+            }
+        });
+        if (candidates.length < 1) {
+            return 0;
+        }
+        let numeric = candidates.map(function (n) {
+            let v = Number(n.name);
+            return (n.name.trim().length > 0 && isFinite(v)) ? v : null;
+        });
+        let chosen;
+        if (mode === 'confidence') {
+            // Per node: promote what parses, leave the rest alone.
+            chosen = candidates.filter(function (n, i) {
+                return numeric[i] !== null;
+            });
+        } else {
+            // A file mixing `)[100]:` and `)95:` leaves the bracketed nodes
+            // with no label at all, so one bare numeric label beside real
+            // confidences is corroborated rather than lonely. Without this a
+            // mixed-dialect tree ships some confidences and one stray name.
+            let need = anyConfidence ? 1 : 2;
+            if (candidates.length < need) {
+                return 0;
+            }
+            if (numeric.some(function (v) {
+                // All-or-nothing: one real clade name and the tree is names.
+                // The range covers every scale in use -- 0-1 posteriors,
+                // 0-100 bootstrap, 0-1000 MrBayes -- and excludes identifiers
+                // such as NCBI taxids that would read as "support 9606".
+                return v === null || v < 0 || v > 1000;
+            })) {
+                return 0;
+            }
+            // Clade numbering is overwhelmingly 1..N, each exactly once. A
+            // real support tree containing every integer 1..N once and nothing
+            // else is essentially impossible at n >= 3, and without this guard
+            // a clade-numbered tree silently becomes "1%, 2%, 3% support".
+            let distinct = new Set(numeric);
+            let min = Math.min.apply(null, numeric);
+            let max = Math.max.apply(null, numeric);
+            if (distinct.size === numeric.length && min === 1 && max === numeric.length) {
+                return 0;
+            }
+            chosen = candidates;
+        }
+        chosen.forEach(function (n) {
+            let v = Number(n.name);
+            // Type deliberately left unset: the value cannot distinguish
+            // bootstrap from posterior from aLRT from TBE, and a wrong type
+            // printed beside a number in a published figure is worse than none.
+            pushConfidence(n, v, '');
+            n.name = '';
+        });
+        return chosen.length;
+    };
+
     forester.suggestLabelFields = function (root, extractors) {
         const FIELDS = ['name', 'taxonomy', 'sequence'];
         const CONTAINMENT_MIN = 0.9;

package/package.json

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