archaeopteryx 3.18.0 → 3.20.0

package/forester.js

@@ -20,7 +20,7 @@
  *
  */
 
-// v 3.18.0
+// v 3.20.0
 // 2026-09-17
 //
 // forester.js is a general suite for dealing with phylogenetic trees.
@@ -2091,7 +2091,12 @@
         return p.applies_to === 'node' || p.applies_to === 'clade';
     };
 
-    forester.visualizationCandidates = function (tree) {
+    // options.keepConstant: also return a NUMERIC field that has one value on
+    // every tip. There is nothing to colour by in it, so the selection never
+    // asks for it -- but a matrix does: a single-copy core gene is a column
+    // of 1s, and dropping it from the heat map hid a gene the file lists.
+    forester.visualizationCandidates = function (tree, options) {
+        let keepConstant = !!(options && options.keepConstant);
         let total = 0;
         let stats = Object.create(null);   // id -> {kind, ref, label, nodes, values:Set, multi}; null-proto: ids embed file refs
 
@@ -2255,7 +2260,7 @@
             // The legend already carries the honest part: a "no value" row
             // with the uncovered count, at reduced opacity.
             let sparse = covered * VIS_MIN_COVERAGE_DEN < total * VIS_MIN_COVERAGE_NUM;
-            if (distinct < 2) {
+            if (distinct < 2 && !(keepConstant && numeric)) {
                 return;
             }
             let colorMode;
@@ -2883,11 +2888,18 @@
      * 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) {
+    forester.heatmapColumns = function (tree, only) {
+        let wanted = null;               // the figure's columns, when a file names them
+        if (Array.isArray(only)) {
+            wanted = Object.create(null);
+            only.forEach(function (ref) {
+                wanted[ref] = true;
+            });
+        }
         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) {
+        forester.visualizationCandidates(tree, {keepConstant: true}).forEach(function (c) {
+            if (c && c.kind === 'property' && c.numeric === true && c.ref && (!wanted || wanted[c.ref])) {
                 numeric[c.ref] = true;
                 label[c.ref] = c.label || c.ref;
             }
@@ -2933,6 +2945,179 @@
         };
     };
 
+    // --------------------------------------------------------------
+    // The desktop's figure setting (aptx:figure)
+    // --------------------------------------------------------------
+    // The desktop Archaeopteryx stores what a tree is to be drawn with in one
+    // property of the PHYLOGENY: <property ref="aptx:figure" applies_to=
+    // "phylogeny"> as a direct child of <phylogeny>. Its value (FigureSpec
+    // on the desktop) is "v1;key=value;..." with every value escaped
+    // (PropertyTextCodec): \\ \t \n \r, \_ a space, \p "|", \s "~",
+    // \c ";", \e "=". columns= is a "|" list of ref~TYPE~SHAPE~normalized.
+    // Only a direct child of <phylogeny> counts (Christian, 2026-09-30: "a
+    // hard break"): desktops 0.11.117 to 0.11.172 wrote it on the root clade,
+    // and such a copy is ignored here and dropped on the way out, as the
+    // desktop does. An unknown version is no figure; unknown keys are ignored.
+    forester.FIGURE_REF = 'aptx:figure';
+
+    forester.unescapeFigureValue = function (v) {
+        const map = {'\\': '\\', 't': '\t', 'n': '\n', 'r': '\r', '_': ' ', 'p': '|', 's': '~', 'c': ';', 'e': '='};
+        return String(v).replace(/\\(.)/g, function (all, c) {
+            return map[c] !== undefined ? map[c] : all;
+        });
+    };
+
+    // {columns: [{ref, type, shape, normalized}]} from the tree's figure, or
+    // null when it has none (or one this version cannot read).
+    forester.readFigure = function (tree) {
+        let props = tree && Array.isArray(tree.properties) ? tree.properties : [];
+        let p = props.find(function (q) {
+            return q && q.ref === forester.FIGURE_REF;
+        });
+        if (!p || typeof p.value !== 'string') {
+            return null;
+        }
+        let parts = p.value.trim().split(';');
+        if (parts[0] !== 'v1') {
+            return null;
+        }
+        // labelProps: the properties the label shows, in order (null when the
+        // figure does not say, [] when it says none); show: the desktop's
+        // display switches by DisplayOption name ("show.SHOW_PROPERTIES=true")
+        let figure = {columns: [], labelProps: null, show: {}};
+        parts.slice(1).forEach(function (kv) {
+            let at = kv.indexOf('=');
+            if (at < 1) {
+                return;
+            }
+            let key = kv.substring(0, at);
+            let value = forester.unescapeFigureValue(kv.substring(at + 1));
+            if (key === 'labelprops') {
+                figure.labelProps = value.split('|').filter(function (r) {
+                    return r.length > 0;
+                });
+                return;
+            }
+            if (key.indexOf('show.') === 0 && (value === 'true' || value === 'false')) {
+                figure.show[key.substring(5)] = value === 'true';
+                return;
+            }
+            if (key !== 'columns') {
+                return;
+            }
+            value.split('|').forEach(function (col) {
+                let f = col.split('~');
+                if (f[0] && f[0].length > 0) {
+                    figure.columns.push({ref: f[0], type: f[1] || '', shape: f[2] || 'CIRCLE',
+                        normalized: f[3] === 'true'});
+                }
+            });
+        });
+        return figure;
+    };
+
+    // The refs the figure draws as a MATRIX, in its order ([] without one).
+    forester.figureMatrixRefs = function (tree) {
+        let figure = forester.readFigure(tree);
+        let seen = Object.create(null);
+        return figure ? figure.columns.filter(function (c) {
+            let keep = c.type === 'MATRIX' && !seen[c.ref];
+            seen[c.ref] = true;
+            return keep;
+        }).map(function (c) {
+            return c.ref;
+        }) : [];
+    };
+
+    // ---- Properties in the tip label (the desktop's "Properties" option) ----
+
+    // A property a reader would want to see: not the viewer's own aptx:
+    // metadata, not a style: instruction.
+    const LABEL_PROPERTY_SEPARATOR = ' | ';
+
+    forester.isUserVisiblePropertyRef = function (ref) {
+        return typeof ref === 'string' && ref.length > 0 && ref.indexOf('aptx:') !== 0 && ref.indexOf('style:') !== 0;
+    };
+
+    // Every user-visible property ref any node carries, internal nodes
+    // included, sorted by the name the reader sees (then by ref): what the
+    // label-field chooser offers. Deliberately BROADER than the colour-by
+    // candidates, which drop constant, per-tip-unique and internal-only fields
+    // -- all perfectly good label text (the desktop's userVisiblePropertyRefs).
+    forester.labelPropertyRefs = function (tree) {
+        let seen = Object.create(null);
+        forester.preOrderTraversalAll(tree, function (n) {
+            (n.properties || []).forEach(function (p) {
+                if (p && forester.isUserVisiblePropertyRef(p.ref)
+                    && p.value !== undefined && p.value !== null && String(p.value).trim().length > 0) {
+                    seen[p.ref] = true;
+                }
+            });
+        });
+        return Object.keys(seen).sort(function (a, b) {
+            let da = forester.propertyDisplayName(a).toLowerCase();
+            let db = forester.propertyDisplayName(b).toLowerCase();
+            return da < db ? -1 : (da > db ? 1 : (a < b ? -1 : (a > b ? 1 : 0)));
+        });
+    };
+
+    // A node's properties as one line of label text: values only, a unit
+    // after its value (without its namespace), joined by " | " as the rest of
+    // the label is. Not by ", " as on the desktop (Christian, 2026-09-30): a
+    // value often holds a comma itself -- a BV-BRC host "Bottlenose dolphin,
+    // Tursiops truncatus" -- and "host, species" then reads as three fields. `refs` picks and orders the fields; null is every
+    // user-visible property in the node's own order, less `excluded` (the
+    // heat map's columns: a field has one display role).
+    forester.labelPropertiesText = function (node, refs, excluded) {
+        let props = (node && node.properties) || [];
+        let parts = [];
+        let add = function (p) {
+            if (!p || !forester.isUserVisiblePropertyRef(p.ref) || p.value === undefined || p.value === null) {
+                return;
+            }
+            let v = String(p.value).trim();
+            if (v.length < 1) {
+                return;
+            }
+            if (typeof p.unit === 'string' && p.unit.length > 0) {
+                v += ' ' + p.unit.substring(p.unit.lastIndexOf(':') + 1);
+            }
+            parts.push(v);
+        };
+        if (refs) {
+            refs.forEach(function (ref) {
+                props.forEach(function (p) {
+                    if (p && p.ref === ref) {
+                        add(p);
+                    }
+                });
+            });
+        } else {
+            props.forEach(function (p) {
+                if (!(excluded && p && excluded[p.ref])) {
+                    add(p);
+                }
+            });
+        }
+        return parts.join(LABEL_PROPERTY_SEPARATOR);
+    };
+
+    // Removes an aptx:figure from every clade (the old place, now ignored),
+    // so a tree saved from here carries no dead copy. Returns how many.
+    forester.dropCladeFigures = function (tree) {
+        let n = 0;
+        forester.preOrderTraversalAll(tree, function (node) {
+            if (node !== tree && Array.isArray(node.properties)) {
+                let kept = node.properties.filter(function (q) {
+                    return !(q && q.ref === forester.FIGURE_REF);
+                });
+                n += node.properties.length - kept.length;
+                node.properties = kept;
+            }
+        });
+        return n;
+    };
+
     /**
      * The number in `node`'s heat-map cell for `ref`, or `null` when there is none.
      *
@@ -9461,13 +9646,22 @@
     // Tick ages for a "Ma before present" ruler: ~8 nice steps from 0 back
     // to the root age.
     forester.maAxisTickValues = function (rootAge) {
-        if (!(rootAge > 0) || !isFinite(rootAge)) {
+        return forester.distanceAxisTickValues(rootAge);
+    };
+
+    // Tick values for a distance axis: ~8 nice steps from 0 (the root) out
+    // to maxDist (the deepest tip), in the tree's branch-length units.
+    forester.distanceAxisTickValues = function (maxDist) {
+        if (!(maxDist > 0) || !isFinite(maxDist)) {
+            return [];
+        }
+        let step = forester.niceAxisStep(maxDist / 8);
+        if (!(step > 0)) {
             return [];
         }
-        let step = forester.niceAxisStep(rootAge / 8);
         let vals = [];
-        for (let v = 0; v <= rootAge + 1e-9; v += step) {
-            vals.push(Math.round(v * 1e6) / 1e6);
+        for (let i = 0; (i * step) <= maxDist + (step * 1e-9); ++i) {
+            vals.push(Number((i * step).toPrecision(12)));
         }
         return vals;
     };

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "archaeopteryx",
-  "version": "3.18.0",
+  "version": "3.20.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",
@@ -35,7 +35,7 @@
   },
   "dependencies": {
     "d3": "^7.9.0",
-    "phyloxml": "^1.1.2"
+    "phyloxml": "^1.1.7"
   },
   "devDependencies": {
     "@eslint/js": "^9.13.0",