archaeopteryx 3.25.0 → 3.26.0

package/README.md

@@ -255,10 +255,14 @@ program's.
 
 A phylogram carries a **scale bar** at the bottom left: a round number of
 branch-length units (1, 2 or 5 × 10ᵏ, whichever makes the bar about 100 px)
-with its length written above it. It is drawn with the tree, so it zooms and
-exports with it and its label always holds. A cladogram has nothing to
-measure and shows none, and a tree under a scale axis leaves the measuring to
-the axis.
+with its length written above it, followed by the unit the tree states
+(phyloXML's `branch_length_unit`, e.g. `0.05 subs/site`) and by nothing when
+it states none: a tree that does not say what its lengths measure gets no
+guess. It is drawn with the tree, so it zooms and exports with it and its
+label always holds. A cladogram has nothing to measure and shows none, and a
+tree under a scale axis leaves the measuring to the axis. **Scale** under
+Display Data > Options hides it (on by default; config `showScaleBar`, view
+key `scaleBar`; the desktop's switch has the same name and defaults to off).
 
 **Scale Axis** under Display Data (off by default, as on the desktop) draws a
 labelled ruler under a phylogram, from 0 at the root out to the deepest tip, in
@@ -1552,6 +1556,7 @@ copy-pastable JSON.
 | `geneFamily` | `'auto'` | The annotation namespace that colours the genes and anchors the rows: `'auto'` (the one most genes carry) or a prefix such as `'pgfam'`. |
 | `geneLabels` | `'genes'` | Where gene symbols go: `'genes'` (on the arrows), `'legend'` (a card of the families), or `'none'`. |
 | `showScaleAxis` | tree-derived | Open with the scale axis shown: the time axis on a time tree whose branches show time, a distance axis on any other phylogram. Default: on when the tree carries `<date>` elements and opens shown in time, off otherwise (a dated tree that opens in divergence is a divergence tree on screen) — an explicit `true`/`false` overrides that. |
+| `showScaleBar` | `true` | Open with the scale bar at the bottom left of a phylogram (a round length in the tree's branch-length unit). It gives way while the scale axis is shown either way. |
 | `showScaleGrid` | `false` | Open with the Scale Grid lines on (only meaningful — and only offered as a checkbox — while the scale axis itself is shown). |
 | `showSupportDots` | `false` | Open with the Support Dots marks on (the checkbox appears whenever the tree has confidences). |
 | `supportDotMinimum` | `95` | Support Dots threshold, as a percentage. On a tree whose confidences top out at 1 (posterior probabilities) it is read on the 0–1 scale, so the default means ≥ 0.95 there and ≥ 95 on a bootstrap tree. |
@@ -1919,17 +1924,29 @@ exists, and clears the per-legend chip states.
 Highest first, at each paint:
 
 * **Label colour**: search/selection highlight → active Color visualization
-  → `style:font_color` → phyloXML branch colour → theme ink.
+  (its colour; the theme ink for a node without a value) → `style:font_color`
+  → phyloXML branch colour → theme ink.
 * **Node fill**: highlight → duplication/speciation event colour → active
-  Color visualization → `style:node_color` (else `style:font_color`) →
-  background.
+  Color visualization (its colour; a node without a value draws no dot,
+  or a hollow one while Node events are shown) → `style:node_color` (else
+  `style:font_color`) → background.
 * **Node outline**: darkened highlight → event colour → visualization fill
-  → style colour → branch colour → branch default.
+  → style colour (not while a Color visualization is active) → branch colour
+  → branch default.
 * **Node shape path**: suppressed for highlighted/event nodes; chosen Shape
   visualization → `style:node_shape`. A node earns its default dot when a
   Color visualization is active (and no shape was drawn), or when it
   carries `style:node_color` — `font_color` alone paints only the label.
 
+While a Color visualization is active the style colours are **not consulted
+for any node**, valued or not: not for the label, the dot, its outline, the
+hover glow or the clock plot's points. The visualization owns the colours and
+its legend explains them; a node without a value takes the default label
+colour and draws no dot. That is the desktop's rule (its TreePanel.setColor).
+Clearing the Color menu brings the file's colours back. Branch colours,
+shapes, font sizes and styles are not colours of the visualization's kind
+and stay.
+
 ### Legend anatomy
 
 One draggable SVG card per active visualization (colour, then shape,
@@ -2126,8 +2143,9 @@ honoured: `style:font_color`, `style:node_color`, `style:node_shape`
 The **Visual Styles** checkbox — the desktop's "Visual Styles/Branch Colors",
 shown when the tree carries either, on by default — turns them off and on,
 and gates phyloXML `<color>` branch colours too, exactly as on the desktop.
-An active Color visualization outranks `style:font_color`, also as on the
-desktop: set the Color menu to default to see the tree as its file styled it.
+An active Color visualization outranks the style colours for every node,
+valued or not, on labels and node dots alike, as on the desktop: set the
+Color menu to default to see the tree as its file styled it.
 `style:` never appears in the Color / Shape menus — it is rendering, not data.
 
 ### Moving the legends

package/archaeopteryx.d.ts

@@ -138,6 +138,8 @@ export interface ArchaeopteryxConfig {
      * branches show time, a distance axis on any other. Default: on for a
      * time tree, off otherwise. */
     showScaleAxis?: boolean;
+    /** The scale bar at the bottom left of a phylogram; on unless false. */
+    showScaleBar?: boolean;
     /** Grid lines (rings, in circular) at the scale axis's ticks. */
     showScaleGrid?: boolean;
     showSupportDots?: boolean;
@@ -213,6 +215,7 @@ export interface ViewState {
     geneLabels?: 'none' | 'genes' | 'legend';
     scaleAxis?: boolean;
     scaleGrid?: boolean;
+    scaleBar?: boolean;
     /** @deprecated the name of scaleAxis in older links; still read. */
     timeAxis?: boolean;
     /** @deprecated the name of scaleGrid in older links; still read. */

package/archaeopteryx.js

@@ -20,7 +20,7 @@
  *
  */
 
-// v 3.25.0
+// v 3.26.0
 // 2026-09-17
 //
 // Archaeopteryx.js is a software tool for the visualization and
@@ -103,7 +103,7 @@ function (root, d3, forester, phyloXml) {
     // IIFE's own function name -- a plain object says what it is.)
     let archaeopteryx = {};
 
-    const VERSION = '3.25.0';
+    const VERSION = '3.26.0';
     const WEBSITE = 'https://cmzmasek.github.io/archaeopteryx-js/';
     const DESKTOP_WEBSITE = 'https://cmzmasek.github.io/archaeopteryx/';
     const SOURCE_WEBSITE = 'https://github.com/cmzmasek/archaeopteryx-js';
@@ -390,6 +390,7 @@ function (root, d3, forester, phyloXml) {
     const GENE_LABELS_SELECT = 'gene_labels';
     const SCALE_AXIS_CB = 'scaleaxis_cb';
     const SCALE_GRID_CB = 'scalegrid_cb';
+    const SCALE_BAR_CB = 'scalebar_cb';
     const MSA_SCROLL_ID = 'aptxmsascroll';
     const FONT_SIZE_SLIDER = 'fs_sl';
     const EXTERNAL_LABEL_CB = 'extl_cb';
@@ -1447,8 +1448,9 @@ function (root, d3, forester, phyloXml) {
     // a node coloured by Host Group glows in its host colour -- and the UI
     // accent otherwise. As on the desktop (TreePanel.hoverGlowColor). The
     // precedence is the one the node itself is painted by: the Color-by
-    // value, then a per-node visual style, then an event colour, then a
-    // colourised clade's branch colour. NEVER the found/search colour: a
+    // value, then a per-node visual style (not while a Color-by is active,
+    // see nodeStyleColor), then an event colour, then a colourised clade's
+    // branch colour. NEVER the found/search colour: a
     // focus ring must not read as a selection state.
     //
     // The glow is a 13-23% alpha wash, so a dark or a pale colour would
@@ -1462,10 +1464,7 @@ function (root, d3, forester, phyloXml) {
             c = vis;
         }
         if (!c) {
-            let style = nodeStyle(d);
-            if (style && (style.nodeColor || style.fontColor)) {
-                c = style.nodeColor || style.fontColor;
-            }
+            c = nodeStyleColor(d);
         }
         if (!c && _state.showNodeEvents && d.events && d.children) {
             c = makeNodeEventsDependentColor(d.events);
@@ -2430,6 +2429,36 @@ function (root, d3, forester, phyloXml) {
         return ((_vis && _vis.colorId) ? _vis.byId[_vis.colorId] : null) || null;
     }
 
+    // A Color visualization is on screen: it owns every node's colour, and the
+    // file's style colours wait until the Color menu is cleared (the desktop's
+    // rule; see makeLabelColor and makeNodeFillColor).
+    function colorVisActive() {
+        return !!_state.showVisualizations && !!currentColorVis();
+    }
+
+    // The colour a node's style gives it, or null: style:node_color (else
+    // style:font_color) for the node's mark, style:font_color for its label.
+    // Null while a Color visualization is active -- the desktop's rule
+    // (TreePanel.setColor): the visualization owns every node's colour and
+    // its legend explains them; a node without a value takes the default ink
+    // and no dot rather than the file's colour. Until 2026-10-08 the valueless
+    // nodes fell through to the file's colour on their dots, so BV-BRC's
+    // trees -- style:font_color on every tip, following Genus -- showed two
+    // palettes under Color by Host (Christian: adopt the desktop's rule).
+    // EVERY reader of a style colour goes through here, so none can forget
+    // the rule: the label, the dot, its outline, the hover glow, the clock
+    // plot's points (which a first version of the rule missed).
+    function nodeStyleColor(node, forLabel) {
+        if (colorVisActive()) {
+            return null;
+        }
+        let style = nodeStyle(node);
+        if (!style) {
+            return null;
+        }
+        return (forLabel ? style.fontColor : (style.nodeColor || style.fontColor)) || null;
+    }
+
     function currentShapeVis() {
         return ((_vis && _vis.shapeId) ? _vis.byId[_vis.shapeId] : null) || null;
     }
@@ -3676,11 +3705,9 @@ function (root, d3, forester, phyloXml) {
         if (visColor !== _state.backgroundColorDefault) {
             return visColor;
         }
-        let style = nodeStyle(phynode);
-        if (style && (style.nodeColor || style.fontColor)) {
-            return style.nodeColor || style.fontColor;
-        }
-        return visColor;
+        // the style colour, or the background -- which, under an active Color
+        // visualization, drawTreeGeometry turns into no dot at all
+        return nodeStyleColor(phynode) || visColor;
     };
 
     // A darker shade of a node's found/selected highlight color, used as a thin
@@ -3713,10 +3740,11 @@ function (root, d3, forester, phyloXml) {
                 return v;
             }
         }
-        let style = nodeStyle(phynode);
-        if (style && (style.nodeColor || style.fontColor)) {
-            return style.nodeColor || style.fontColor;
+        let styleColor = nodeStyleColor(phynode);
+        if (styleColor) {
+            return styleColor;
         }
+        // the branch colour, unlike a style colour, holds under a Color-by (desktop)
         if (_state.useVisualStyles && phynode.color) {
             let c = phynode.color;
             return "rgb(" + c.red + "," + c.green + "," + c.blue + ")";
@@ -3729,17 +3757,15 @@ function (root, d3, forester, phyloXml) {
         if (foundColor) {
             return foundColor;
         }
-        if (_state.showVisualizations && currentColorVis()) {
-            let color = makeVisLabelColor(phynode);
-            if (color) {
-                return color;
-            }
+        // an active Color visualization owns the colours: its colour where
+        // the node has a value, the default ink where it has none (and
+        // nodeStyleColor is null meanwhile, see there)
+        if (colorVisActive()) {
+            return makeVisLabelColor(phynode);
         }
-        // an active Color visualization outranks style:font_color, as on the
-        // desktop; clear the Color menu to see the tree as its file styled it
-        let style = nodeStyle(phynode);
-        if (style && style.fontColor) {
-            return style.fontColor;
+        let fontColor = nodeStyleColor(phynode, true);
+        if (fontColor) {
+            return fontColor;
         }
         if (_state.useVisualStyles && phynode.color) {
             let c = phynode.color;
@@ -5747,6 +5773,7 @@ function (root, d3, forester, phyloXml) {
         'geneFamily',
         'geneLabels',
         'showScaleAxis',
+        'showScaleBar',
         'showScaleGrid',
         'showSupportDots',
         'searchAinitialValue',
@@ -6113,6 +6140,8 @@ function (root, d3, forester, phyloXml) {
             _state.showScaleAxis = !!(_timeInfo && _timeInfo.type) && !branchesShowDivergence();
         }
         _state.showScaleGrid = _state.showScaleGrid === true; // desktop default: off
+        // the scale bar is on unless the caller says no; it gives way to the axis anyway
+        _state.showScaleBar = _state.showScaleBar !== false;
         _state.showSupportDots = _state.showSupportDots === true;
         _state.showNodeEvents = _basicTreeProperties.nodeEvents === true;
         _state.showBranchEvents = _basicTreeProperties.branchEvents === true;
@@ -10018,6 +10047,7 @@ function (root, d3, forester, phyloXml) {
         if (_basicTreeProperties.branchLengths === true) {
             s.scaleAxis = _state.showScaleAxis === true;
             s.scaleGrid = _state.showScaleGrid === true;
+            s.scaleBar = _state.showScaleBar === true;
         }
         if (_branchScaleAvailable) {
             s.scale = _state.branchScale;   // time or divergence: which layout the branches show
@@ -10199,6 +10229,9 @@ function (root, d3, forester, phyloXml) {
         if (typeof grid === 'boolean') {
             _state.showScaleGrid = grid;
         }
+        if (typeof s.scaleBar === 'boolean') {
+            _state.showScaleBar = s.scaleBar;
+        }
         if (!radialDisplay()) {
             _radialLabelsHorizontal = false;
         } else if ((_state.showDomainArchitectures && _basicTreeProperties.domainArchitectures)
@@ -10275,6 +10308,7 @@ function (root, d3, forester, phyloXml) {
         syncHeatmapControls();
         setCheckboxValue(SCALE_AXIS_CB, _state.showScaleAxis === true);
         setCheckboxValue(SCALE_GRID_CB, _state.showScaleGrid === true);
+        setCheckboxValue(SCALE_BAR_CB, _state.showScaleBar === true);
         setCheckboxValue(DOMAIN_GLOW_CB, _state.domainGlow === true);
         setValue(DOMAIN_LABELS_SELECT, _state.domainLabels);
         syncDomainControls();
@@ -10355,7 +10389,7 @@ function (root, d3, forester, phyloXml) {
     const VIEW_INT_KEYS = ['tree', 'subtree', 'rotation', 'domainEvalue'];
     const VIEW_NUMBER_KEYS = ['font', 'node', 'branch'];
     const VIEW_BOOL_KEYS = ['horizontalLabels', 'msa', 'msaLogo', 'heatmap', 'domains', 'domainGlow', 'genes',
-        'scaleAxis', 'scaleGrid', 'timeAxis', 'timeGrid', 'matchCase', 'inverse'];
+        'scaleAxis', 'scaleGrid', 'scaleBar', 'timeAxis', 'timeGrid', 'matchCase', 'inverse'];
     // Lists of strings, comma-joined. A property ref carries ':' but never a
     // comma, and encodeViewValue leaves both readable in a hash.
     const VIEW_LIST_KEYS = ['heatmapManual', 'labelFields'];
@@ -11350,9 +11384,9 @@ function (root, d3, forester, phyloXml) {
         if (vis) {
             return vis;
         }
-        let style = nodeStyle(node);
-        if (style && (style.nodeColor || style.fontColor)) {
-            return style.nodeColor || style.fontColor;
+        let styleColor = nodeStyleColor(node);   // null under an active Color-by, as in the tree
+        if (styleColor) {
+            return styleColor;
         }
         if (_state.useVisualStyles && node.color) {
             return 'rgb(' + node.color.red + ',' + node.color.green + ',' + node.color.blue + ')';
@@ -13501,7 +13535,8 @@ function (root, d3, forester, phyloXml) {
     const SCALE_BAR_RESERVE = 30;
 
     function scaleBarShown() {
-        return _state.phylogram === true && _basicTreeProperties.branchLengths === true && !scaleAxisShown();
+        return _state.phylogram === true && _basicTreeProperties.branchLengths === true && !scaleAxisShown()
+            && _state.showScaleBar !== false;
     }
 
     // pixels per branch-length unit in the current layout's own coordinates
@@ -13527,7 +13562,9 @@ function (root, d3, forester, phyloXml) {
         if (!scaleBarShown()) {
             return;
         }
-        let bar = forester.scaleBarLength(branchLengthPixelsPerUnit(), SCALE_BAR_TARGET_PX);
+        // the unit the file states, as the distance axis prints it; none when it states none
+        let unit = _treeData && typeof _treeData.branch_length_unit === 'string' ? _treeData.branch_length_unit.trim() : '';
+        let bar = forester.scaleBarLength(branchLengthPixelsPerUnit(), SCALE_BAR_TARGET_PX, unit);
         if (!bar) {
             return;
         }
@@ -14161,6 +14198,11 @@ function (root, d3, forester, phyloXml) {
         scheduleUpdate(null, 0);
     }
 
+    function scaleBarCbClicked() {
+        _state.showScaleBar = getCheckboxValue(SCALE_BAR_CB);
+        scheduleUpdate(null, 0);
+    }
+
     // Fit the circular tree into the viewport, centred. The root is at the
     // group origin (0,0), so we place that at the viewport centre and scale so
     // the outer label ring fits. Computed from the known radial extent rather
@@ -15319,6 +15361,12 @@ function (root, d3, forester, phyloXml) {
             gridCb.disabled = _state.unrootedDisplay === true || _state.phylogram !== true
                 || _state.showScaleAxis !== true;
         }
+        let barCb = byId(SCALE_BAR_CB);
+        if (barCb) {
+            // a cladogram has nothing to measure, and under the axis the bar
+            // has given way; every layout can carry it otherwise
+            barCb.disabled = _state.phylogram !== true || scaleAxisShown();
+        }
         let minus = byId(ZOOM_OUT_X);
         let plus = byId(ZOOM_IN_X);
         let expandV = byId(ZOOM_TO_EXPAND_Y);
@@ -18407,6 +18455,7 @@ function (root, d3, forester, phyloXml) {
         on(GENE_ANCHOR_SELECT, 'change', geneAnchorChanged);
         on(GENE_FAMILY_SELECT, 'change', geneFamilyChanged);
         on(GENE_LABELS_SELECT, 'change', geneLabelsChanged);
+        on(SCALE_BAR_CB, 'click', scaleBarCbClicked);
         on(SCALE_AXIS_CB, 'click', scaleAxisCbClicked);
         on(SCALE_GRID_CB, 'click', scaleGridCbClicked);
 
@@ -18944,6 +18993,9 @@ function (root, d3, forester, phyloXml) {
                 let timeAxis = _timeInfo && _timeInfo.type
                     ? (_timeInfo.type === 'geologic' ? 'the geologic (ICS) time axis' : 'the calendar time axis')
                     : null;
+                // "Scale", the desktop's label for the same switch (its Settings > Overlays > Scale & Grid)
+                opts.push(makeCheckboxItem('Scale', SCALE_BAR_CB, 'to show/hide the scale bar at the bottom left of a'
+                    + ' phylogram: a round length in the tree\'s branch-length unit (it gives way while the scale axis is on)'));
                 opts.push(makeCheckboxItem('Scale Axis', SCALE_AXIS_CB, 'to show/hide '
                     + (timeAxis ? timeAxis + ' and node-age bars (a distance axis while the branches show divergence)'
                         : 'a labeled distance axis from the root to the deepest tip')
@@ -19359,6 +19411,7 @@ function (root, d3, forester, phyloXml) {
         syncHeatmapControls();
         setCheckboxValue(SCALE_AXIS_CB, _state.showScaleAxis);
         setCheckboxValue(SCALE_GRID_CB, _state.showScaleGrid);
+        setCheckboxValue(SCALE_BAR_CB, _state.showScaleBar);
         setCheckboxValue(SHORTEN_NODE_NAME_CB, _state.shortenNodeNames);
         populateVisualizationMenus();
         initializeSearchOptions();

package/forester.js

@@ -20,7 +20,7 @@
  *
  */
 
-// v 3.25.0
+// v 3.26.0
 // 2026-09-17
 //
 // forester.js is a general suite for dealing with phylogenetic trees.
@@ -8784,7 +8784,11 @@
     // -- 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) {
+    // The label carries the tree's stated unit after the number ("0.05
+    // subs/site"), as the distance axis does at its end, and nothing when
+    // the file states none: a tree that does not say what its lengths
+    // measure gets no guess (a BV-BRC user asked for units, 2026-10-08).
+    forester.scaleBarLength = function (pxPerUnit, targetPx, unit) {
         if (!(pxPerUnit > 0) || !isFinite(pxPerUnit)) {
             return null;
         }
@@ -8793,7 +8797,8 @@
         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};
+        let u = typeof unit === 'string' ? unit.trim() : '';
+        return {length: length, label: String(length) + (u ? ' ' + u : ''), px: length * pxPerUnit};
     };
 
     // --------------------------------------------------------------

package/package.json

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