archaeopteryx 3.3.0 → 3.4.0

package/forester.js

@@ -20,7 +20,7 @@
  *
  */
 
-// v 3.3.0
+// v 3.4.0
 // 2026-09-10
 //
 // forester.js is a general suite for dealing with phylogenetic trees.
@@ -1602,11 +1602,23 @@
     // everything found here is in the candidate's domain and keeps its
     // colour. A numeric candidate also gets the view's colour-mode band
     // (see visNumericModes); a category keeps its mode.
+    // `root` is a node, walked in preorder, or an array of the tips to
+    // describe (the viewer passes what is on screen, which a collapsed clade
+    // shortens).
     forester.visualizationSummary = function (candidate, root) {
         let counts = Object.create(null);
         let total = 0;
         let coverage = 0;
-        forester.preOrderTraversalAll(root, function (n) {
+        let tips = root;
+        if (!Array.isArray(root)) {
+            tips = [];
+            forester.preOrderTraversalAll(root, function (n) {
+                if (!n.children) {
+                    tips.push(n);
+                }
+            });
+        }
+        tips.forEach(function (n) {
             if (n.children) {
                 return;
             }
@@ -2318,6 +2330,17 @@
         // the shared contract -- and throwing on a combination a user
         // plausibly wants is what forced callers into workarounds.
 
+        // A text holding several trees (one per ';') reads as its FIRST;
+        // parseNewHampshireTrees reads them all. Before this the statements
+        // ran together and the LAST tree came back, the others silently
+        // dropped.
+        {
+            let statements = forester.splitNewHampshire(nhStr);
+            if (statements.length > 1) {
+                nhStr = statements[0];
+            }
+        }
+
         let ancs = [];
         let x = {};
 
@@ -2569,6 +2592,66 @@
         }
     };
 
+    // Splits a New Hampshire text into its tree statements, one per ';'
+    // outside quotes and [...] comments (a ';' inside a quoted label or a
+    // [&...] annotation is data), each trimmed; blank statements are
+    // dropped. A text without a terminating ';' is one statement.
+    forester.splitNewHampshire = function (nhStr) {
+        let s = String(nhStr);
+        let parts = [];
+        let start = 0;
+        let inSingle = false;
+        let inDouble = false;
+        let depth = 0;
+        for (let i = 0, n = s.length; i < n; ++i) {
+            let c = s.charAt(i);
+            if (inSingle) {
+                if (c === "'") {
+                    inSingle = false;
+                }
+            } else if (inDouble) {
+                if (c === '"') {
+                    inDouble = false;
+                }
+            } else if (depth > 0) {
+                if (c === ']') {
+                    --depth;
+                } else if (c === '[') {
+                    ++depth;
+                }
+            } else if (c === "'") {
+                inSingle = true;
+            } else if (c === '"') {
+                inDouble = true;
+            } else if (c === '[') {
+                depth = 1;
+            } else if (c === ';') {
+                parts.push(s.substring(start, i + 1));
+                start = i + 1;
+            }
+        }
+        parts.push(s.substring(start));
+        return parts.map(function (p) {
+            return p.trim();
+        }).filter(function (p) {
+            return p.length > 0;
+        });
+    };
+
+    // Every tree in a New Hampshire text (a file can hold many, one per
+    // ';'), each parsed as parseNewHampshire does, in file order. A text
+    // with no statement at all is handed to parseNewHampshire whole, so it
+    // fails the way an empty tree always did.
+    forester.parseNewHampshireTrees = function (nhStr, confidenceValuesInBrackets, confidenceValuesAsInternalNames) {
+        let statements = forester.splitNewHampshire(nhStr);
+        if (statements.length === 0) {
+            return [forester.parseNewHampshire(nhStr, confidenceValuesInBrackets, confidenceValuesAsInternalNames)];
+        }
+        return statements.map(function (statement) {
+            return forester.parseNewHampshire(statement, confidenceValuesInBrackets, confidenceValuesAsInternalNames);
+        });
+    };
+
     // Parses a Nexus-formatted string and returns an ARRAY of tree objects,
     // each in the same shape parseNewHampshire produces (a Nexus file can
     // hold any number of trees). Ported from the desktop's
@@ -3793,6 +3876,209 @@
         return {backbone: {x: start, w: Number(da.length) * f}, boxes: boxes};
     };
 
+    // --------------------------------------------------------------
+    // Scale bar
+    // --------------------------------------------------------------
+    // A phylogram's scale bar spans a round number of branch-length units
+    // -- 1, 2 or 5 times a power of ten -- chosen so the bar comes out about
+    // targetPx long at pxPerUnit pixels per unit. Returns {length, label,
+    // px}, or null when the scale is unusable (zero, negative or infinite).
+    forester.scaleBarLength = function (pxPerUnit, targetPx) {
+        if (!(pxPerUnit > 0) || !isFinite(pxPerUnit)) {
+            return null;
+        }
+        let raw = (targetPx || 100) / pxPerUnit;
+        let k = Math.floor(Math.log10(raw));
+        let base = raw / Math.pow(10, k);
+        let nice = base < 1.5 ? 1 : (base < 3.5 ? 2 : (base < 7.5 ? 5 : 10));
+        let length = Number((nice * Math.pow(10, k)).toPrecision(2));
+        return {length: length, label: String(length), px: length * pxPerUnit};
+    };
+
+    // --------------------------------------------------------------
+    // Metadata tables
+    // --------------------------------------------------------------
+    // A table beside the tree -- TSV or CSV with a header row, the first
+    // column naming the tip -- joined onto the tips as node properties, so
+    // that everything downstream of a property sees the columns as if the
+    // file had carried them: the automatic Color-by and Shape candidates,
+    // the legends, the search fields, the node-data dialog, the phyloXML
+    // writer. Every other browser viewer takes such a table; it was the one
+    // input this library lacked (field review, 2026-09-13).
+
+    forester.METADATA_NAMESPACE = 'meta';
+
+    function splitDelimitedLine(line, delimiter) {
+        let out = [];
+        let cur = '';
+        let quoted = false;
+        for (let i = 0; i < line.length; ++i) {
+            let c = line.charAt(i);
+            if (quoted) {
+                if (c === '"') {
+                    if (line.charAt(i + 1) === '"') {   // a doubled quote is a literal one
+                        cur += '"';
+                        i++;
+                    } else {
+                        quoted = false;
+                    }
+                } else {
+                    cur += c;
+                }
+            } else if (c === '"') {
+                quoted = true;
+            } else if (c === delimiter) {
+                out.push(cur);
+                cur = '';
+            } else {
+                cur += c;
+            }
+        }
+        out.push(cur);
+        return out.map(function (s) {
+            return s.trim();
+        });
+    }
+
+    // Splits delimited text into its header and rows. The delimiter is
+    // whichever of tab, comma and semicolon occurs most in the header line
+    // (tab when none does); fields may be double-quoted; blank lines and
+    // lines starting with '#' are skipped; Windows line ends are fine.
+    // Header names and cells come back trimmed. Throws when there is no
+    // header or fewer than two columns.
+    forester.parseDelimitedTable = function (text) {
+        let lines = String(text || '').split(/\r?\n/).filter(function (l) {
+            return l.trim().length > 0 && l.charAt(0) !== '#';
+        });
+        if (lines.length === 0) {
+            throw new Error('the table is empty');
+        }
+        let delimiter = '\t';
+        let best = -1;
+        ['\t', ',', ';'].forEach(function (d) {
+            let n = lines[0].split(d).length - 1;
+            if (n > best) {
+                best = n;
+                delimiter = d;
+            }
+        });
+        let columns = splitDelimitedLine(lines[0], delimiter);
+        if (columns.length < 2) {
+            throw new Error('the table needs a header row with at least two columns: the tip name, then the data');
+        }
+        let rows = [];
+        for (let i = 1; i < lines.length; ++i) {
+            rows.push(splitDelimitedLine(lines[i], delimiter));
+        }
+        return {columns: columns, rows: rows, delimiter: delimiter};
+    };
+
+    // The property ref for a column. A header that already reads as a
+    // phyloXML ref (ns:local, no whitespace) is kept as it is; any other
+    // becomes "meta:" plus the header with its whitespace as '_' -- the
+    // display name prettifies that back to spaces, so "Collection Date"
+    // stays "Collection Date" in every menu.
+    forester.metadataColumnRef = function (header, index) {
+        let h = String(header || '').trim();
+        if (h.length === 0) {
+            h = 'column_' + (index + 1);
+        }
+        if (/^[A-Za-z0-9_]+:\S+$/.test(h)) {
+            return h;
+        }
+        return forester.METADATA_NAMESPACE + ':' + h.replace(/\s+/g, '_');
+    };
+
+    // Joins a table onto the tree's tips. The first column is the key,
+    // matched to the tip's name exactly, then case-insensitively. Every
+    // other column becomes one property per matched tip with a non-empty
+    // cell (applies_to node; the datatype is xsd:integer or xsd:double when
+    // every filled cell of the column is such a number, xsd:string
+    // otherwise). A property the tip already carries under the same ref is
+    // replaced -- the table wins. Returns what happened:
+    //   {columns: [{header, ref, datatype, filled}], tips, matchedTips,
+    //    unmatchedTips: [names], unmatchedRows: [keys], properties}
+    forester.joinMetadataTable = function (tree, text) {
+        let table = forester.parseDelimitedTable(text);
+        let tips = forester.getAllExternalNodes(tree);
+        let byName = Object.create(null);
+        let byLower = Object.create(null);
+        tips.forEach(function (n) {
+            if (n.name) {
+                byName[n.name] = n;
+                let lower = n.name.toLowerCase();
+                if (!byLower[lower]) {
+                    byLower[lower] = n;
+                }
+            }
+        });
+        let columns = [];
+        for (let j = 1; j < table.columns.length; ++j) {
+            let filled = table.rows.map(function (r) {
+                return r[j] === undefined ? '' : r[j];
+            }).filter(function (v) {
+                return v.length > 0;
+            });
+            let datatype = 'xsd:string';
+            if (filled.length > 0) {
+                if (filled.every(function (v) { return /^[+-]?\d+$/.test(v); })) {
+                    datatype = 'xsd:integer';
+                } else if (filled.every(function (v) { return VIS_NUMERIC_RE.test(v); })) {
+                    datatype = 'xsd:double';
+                }
+            }
+            columns.push({header: table.columns[j], ref: forester.metadataColumnRef(table.columns[j], j),
+                datatype: datatype, filled: 0});
+        }
+        let matched = new Set();
+        let unmatchedRows = [];
+        let properties = 0;
+        table.rows.forEach(function (r) {
+            let key = r[0] === undefined ? '' : r[0];
+            if (key.length === 0) {
+                return;
+            }
+            let tip = byName[key] || byLower[key.toLowerCase()];
+            if (!tip) {
+                unmatchedRows.push(key);
+                return;
+            }
+            matched.add(tip);
+            columns.forEach(function (col, k) {
+                let v = r[k + 1] === undefined ? '' : r[k + 1];
+                if (v.length === 0) {
+                    return;
+                }
+                if (!tip.properties) {
+                    tip.properties = [];
+                }
+                let existing = null;
+                for (let i = 0; i < tip.properties.length; ++i) {
+                    if (tip.properties[i].ref === col.ref) {
+                        existing = tip.properties[i];
+                        break;
+                    }
+                }
+                if (existing) {
+                    existing.value = v;
+                    existing.datatype = col.datatype;
+                    existing.applies_to = 'node';
+                } else {
+                    tip.properties.push({ref: col.ref, value: v, datatype: col.datatype, applies_to: 'node'});
+                }
+                col.filled++;
+                properties++;
+            });
+        });
+        let unmatchedTips = tips.filter(function (n) {
+            return !matched.has(n);
+        }).map(function (n) {
+            return n.name || '';
+        });
+        return {columns: columns, tips: tips.length, matchedTips: matched.size,
+            unmatchedTips: unmatchedTips, unmatchedRows: unmatchedRows, properties: properties};
+    };
+
     // --------------------------------------------------------------
     // Search engine
     // --------------------------------------------------------------

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "archaeopteryx",
-  "version": "3.3.0",
+  "version": "3.4.0",
   "description": "Archaeopteryx.js is a software tool for the visualization and analysis of highly annotated phylogenetic trees.",
   "main": "archaeopteryx.js",
   "types": "archaeopteryx.d.ts",
@@ -20,7 +20,7 @@
     "LICENSE"
   ],
   "scripts": {
-    "test": "node test/forester_test.js && node test/search_test.js && node test/visualization_test.js && node test/domain_test.js",
+    "test": "node test/forester_test.js && node test/search_test.js && node test/visualization_test.js && node test/domain_test.js && node test/metadata_test.js",
     "lint": "eslint .",
     "lint:fix": "eslint . --fix",
     "format": "prettier --write .",