archaeopteryx 3.3.0 → 3.4.1

package/forester.js

@@ -20,7 +20,7 @@
  *
  */
 
-// v 3.3.0
+// v 3.4.1
 // 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,301 @@
         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.
+    // The tips' data as a table, one row per tip in the order given, header
+    // first: what the node menu's "Download Ext. Node Data" writes. The
+    // columns and their names are the desktop's (NodeDataExporter.toNodeDataTsv),
+    // 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.
+    forester.externalNodeDataTable = function (tips, idOf) {
+        tips = tips || [];
+        if (tips.length === 0) {
+            return {columns: [], rows: []};
+        }
+        let clean = function (v) {
+            return (v === undefined || v === null) ? '' : String(v).replace(/[\t\n\r]/g, ' ');
+        };
+        let tax = function (n) {
+            return (n.taxonomies && n.taxonomies[0]) || {};
+        };
+        let seq = function (n) {
+            return (n.sequences && n.sequences[0]) || {};
+        };
+        let cols = [];
+        let add = function (name, extract, force) {
+            let vals = tips.map(function (n, i) {
+                return clean(extract(n, i));
+            });
+            if (force || vals.some(function (v) { return v.length > 0; })) {
+                cols.push({name: name, vals: vals});
+            }
+        };
+        let seen = new Set();
+        let unique = tips.every(function (n) {
+            if (!n.name || seen.has(n.name)) {
+                return false;
+            }
+            seen.add(n.name);
+            return true;
+        });
+        if (!unique) {
+            add('node_id', function (n, i) { return idOf ? idOf(n, i) : i + 1; }, true);
+        }
+        add('name', function (n) { return n.name; }, true);
+        add('taxonomy_scientific_name', function (n) { return tax(n).scientific_name; });
+        add('taxonomy_common_name', function (n) { return tax(n).common_name; });
+        add('taxonomy_code', function (n) { return tax(n).code; });
+        add('taxonomy_id', function (n) { return tax(n).id && tax(n).id.value; });
+        add('taxonomy_rank', function (n) { return tax(n).rank; });
+        add('sequence_name', function (n) { return seq(n).name; });
+        add('gene_name', function (n) { return seq(n).gene_name; });
+        add('sequence_symbol', function (n) { return seq(n).symbol; });
+        add('sequence_accession', function (n) { return seq(n).accession && seq(n).accession.value; });
+        add('sequence_type', function (n) { return seq(n).type; });
+        add('branch_length', function (n) { return (typeof n.branch_length === 'number') ? n.branch_length : ''; });
+        let refs = new Set();
+        tips.forEach(function (n) {
+            (n.properties || []).forEach(function (p) {
+                if (p.ref) {
+                    refs.add(p.ref);
+                }
+            });
+        });
+        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 : '';
+            });
+        });
+        return {
+            columns: cols.map(function (c) { return c.name; }),
+            rows: tips.map(function (n, i) {
+                return cols.map(function (c) { return c.vals[i]; });
+            })
+        };
+    };
+
+    // externalNodeDataTable as tab-separated text, header line first; empty
+    // for no tips.
+    forester.externalNodeDataTsv = function (tips, idOf) {
+        let t = forester.externalNodeDataTable(tips, idOf);
+        if (t.columns.length === 0) {
+            return '';
+        }
+        return [t.columns].concat(t.rows).map(function (r) {
+            return r.join('\t');
+        }).join('\n') + '\n';
+    };
+
+    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
     // --------------------------------------------------------------
@@ -3849,7 +4227,13 @@
     const SEARCH_DOMAIN = textField('Domain', n => searchSeqs(n).reduce((a, s) => a.concat((s.domain_architecture && s.domain_architecture.domains) ? s.domain_architecture.domains.map(d => d.name) : []), []).filter(Boolean));
     const SEARCH_ANNOTATION = textField('Annotation', n => searchSeqs(n).reduce((a, s) => a.concat((s.annotations || []).reduce((b, an) => b.concat([an.desc, an.ref]), [])), []).filter(Boolean), {anyText: true});
     const SEARCH_CROSS_REFERENCE = textField('Cross-Reference', n => searchSeqs(n).reduce((a, s) => a.concat((s.cross_references || []).reduce((b, x) => b.concat([x.value, x.source, x.comment]), [])), []).filter(Boolean), {anyText: true});
-    const SEARCH_MOLECULAR_SEQUENCE = textField('Molecular Sequence', n => searchSeqs(n).map(s => s.mol_seq).filter(Boolean), {suggest: false});
+    // The residues: the phyloXML and Nexus readers give mol_seq as {value,
+    // is_aligned}, and a hand-built tree may carry the plain string. Reading
+    // the object itself compared every query against "[object Object]", so
+    // this field never matched a real file (its test built the string form).
+    const SEARCH_MOLECULAR_SEQUENCE = textField('Molecular Sequence', n => searchSeqs(n).map(function (s) {
+        return (s.mol_seq && typeof s.mol_seq === 'object') ? s.mol_seq.value : s.mol_seq;
+    }).filter(Boolean), {suggest: false});
     // in menu order
     const SEARCH_TEXT_FIELDS = [
         SEARCH_NODE_NAME, SEARCH_TAXONOMY_SCIENTIFIC_NAME, SEARCH_TAXONOMY_COMMON_NAME, SEARCH_TAXONOMY_CODE,

package/package.json

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