archaeopteryx 3.18.0 → 3.20.0

package/README.md

@@ -247,9 +247,20 @@ 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 time axis leaves the measuring to
+measure and shows none, and a tree under a scale axis leaves the measuring to
 the axis.
 
+**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
+the tree's branch-length units, with the unit at its end when the tree states
+one. **Scale Grid** adds a faint line at every tick, behind the tree. In the
+circular layout the ruler runs out from the root along the gap between the last
+tip and the first, and the grid lines become rings; the unrooted layout has no
+axis. The ruler floats at the bottom of the window as the tree scrolls, and it
+starts at a subtree view's own root. On a time tree the same switch draws the
+time axis instead (below): a tree flipped to **Div** gets the distance ruler,
+and one flipped back gets its time axis.
+
 In the two radial layouts the zoom row changes meaning, exactly as on the
 desktop: **Y+ / Y− become the plain + / − zoom** (a circle has one diameter;
 the mouse wheel zooms too, and never rotates), **X− / X+ become rotate** (a
@@ -479,7 +490,7 @@ too.
 | ⌘⇧E | Ctrl+Shift+E | Expand vertically until the labels fit |
 | ⌘⇧L | Ctrl+Shift+L | Next layout: rectangular, circular, unrooted |
 | ⌘⇧D | Ctrl+Shift+D | Next display type: phylogram, aligned, cladogram |
-| ⌘⇧X | Ctrl+Shift+X | Time axis on / off |
+| ⌘⇧X | Ctrl+Shift+X | Time \| Div, where the tree offers it; the Scale Axis on / off otherwise |
 | ⌘⇧O | Ctrl+Shift+O | Ladderize |
 | ⌘⇧U | Ctrl+Shift+U | Uncollapse every clade |
 | ⌘F | Ctrl+F | Go to the search box |
@@ -504,9 +515,10 @@ desktop's Unicode entry: it stays with the text field there, as it should.
 A view is what you made of a tree with the panel: the layout and display
 type, which labels show, the colour and shape fields, both searches, the
 clade you switched to, the clades you collapsed, the font, node and branch
-sizes, the rotation, and the tracks — which track is shown, the heat map's
-column order (including one you arranged by hand) and whether the alignment
-is summarised as a logo. On the demo pages it rides in the URL's
+sizes, the rotation, whether the branches show time or divergence, and the
+tracks — which track is shown, the heat map's column order (including one
+you arranged by hand) and whether the alignment is summarised as a logo. On
+the demo pages it rides in the URL's
 `#` hash and follows every change, so the address bar is always a link to
 what is on screen: copy it (**Copy link to this view** in the toolbar) and
 the recipient opens the same tree in the same view. Opening your own file
@@ -649,16 +661,42 @@ number wherever it appears — that is what makes a block of related columns
 readable as a block, and it is the point of a heat map rather than a row of
 independent stripes. The scale spans the whole tree, so entering a subtree
 narrows the rows and leaves the colours where they were. The columns that
-appear are exactly the numeric fields the **Color by** menu offers, so the two
-agree about what the tree holds; by default their left-to-right order follows
+appear are the numeric fields the **Color by** menu offers, so the two agree
+about what the tree holds — plus a field with **one value on every tip**, which
+has nothing to colour by but is a column all the same (a single-copy core gene
+is a column of 1s); by default their left-to-right order follows
 the order the file lists them in, which keeps a producer's grouping (core genes,
 then resistance, then prophages) intact even where some tips are missing a
 field — see **Order columns** below for the alternatives.
 
+Where a cell is at least 5 px on screen, each cell is drawn on its own with a
+**thin border in its own hue, darker** — a block of equal values still reads
+as a block, and each cell can be counted. The border stays 0.75 px at any
+zoom. Smaller cells, or a matrix of more than 60,000 cells, are drawn as merged
+runs of equal colour instead, and zooming across that threshold switches
+between the two.
+
 A cell **nobody filled in** is drawn as an outlined empty box, never as the
 scale's low end: on a presence/absence matrix, reading a missing field as zero
 states the opposite of what the file says. The key beside the scale names it.
 
+**A file can open straight into its matrix.** The desktop Archaeopteryx
+stores its figure setting as one property of the phylogeny, directly under
+`<phylogeny>`:
+
+```xml
+<property ref="aptx:figure" datatype="xsd:string" applies_to="phylogeny">v1;columns=pgfam:PGF_00019355\sMATRIX\sCIRCLE\sfalse\ppgfam:PGF_00019313\sMATRIX\sCIRCLE\sfalse</property>
+```
+
+When it names two or more `MATRIX` columns the tree has, the tree opens with the
+heat map on, showing **only those columns, in that order** (the order is then
+`manual`, and **Order columns** can still change it). Other column types are
+the desktop's and are not drawn here. Only a property directly under
+`<phylogeny>` counts: an `aptx:figure` on a clade — where desktops
+0.11.117 to 0.11.172 wrote it — is ignored and left out of what is saved; the phylogeny's
+own is saved back unchanged. An explicit `showHeatmap`, `heatmapColumnOrder`
+or `heatmapManualOrder` in the config wins over the file.
+
 **Hover any cell** for its tip, the column and its value — or `not assessed` —
 and the scale it was coloured against. The column names stand under the matrix,
 turned; a matrix with more columns than will fit shows a window and says so
@@ -733,12 +771,12 @@ nodes, and on tips whatever the axis says the range means — on geologic
 time a fossil's observed range, sepia **FAD/LAD bars with end caps**; on
 calendar time the uncertainty of a **sampling date**, drawn like an age bar,
 slimmer, and only when it has a width. Node tooltips show the date. The
-**Time Axis** checkbox under Display Data toggles everything; the axis needs
+**Scale Axis** checkbox under Display Data toggles everything; the axis needs
 a phylogram and the rectangular or circular layout. In **circular** the bars
 run along each node's spoke — on through the centre where a range reaches
 back past the root's own age — the ruler runs out from the root along the
 gap between the last tip and the first, turning with the tree, and a
-geologic axis lays its intervals down as coloured rings. **Time Grid** (off
+geologic axis lays its intervals down as coloured rings. **Scale Grid** (off
 by default) adds faint lines, or rings, at the fine interval boundaries or
 the calendar years.
 
@@ -767,7 +805,7 @@ builds state — keeps its sign, and is drawn at length 0 like any negative
 branch length. The switch acts on the whole tree, also from a subtree view,
 and a node deleted meanwhile leaves the branch that takes its place spanning
 what both spanned, in either layout. The time axis is hidden while the
-branches show divergence. Each layout stamps the tree's `branch_length_unit`
+branches show divergence, and the Scale Axis measures distance instead. Each layout stamps the tree's `branch_length_unit`
 (`subs/site`; for time the dates' unit, or `time`), so a tree saved while
 Div is on screen says so and opens again showing divergence. All of this is
 shared with the desktop.
@@ -1164,7 +1202,8 @@ developer spec below). The checkboxes are still there to override it.
 
 The same data-driven rule applies to the two big overlays: a tree whose tips
 carry an aligned `mol_seq` opens with its **sequence alignment** showing, and
-a tree with phyloXML `<date>` elements opens with its **time axis** drawn —
+a tree with phyloXML `<date>` elements that opens shown in time has its
+**time axis** drawn —
 each with a checkbox under Display Data to turn it off.
 
 Support and branch-length values draw **2 px smaller than the label font**
@@ -1340,16 +1379,18 @@ copy-pastable JSON.
 | `layout` | `'rectangular'` | The starting layout: `'rectangular'`, `'circular'`, or `'unrooted'`. |
 | `ladderizeTree` | `true` | Ladderize the tree on load: at each node, the larger clade first (any number of children, so a polytomy sorts too). |
 | `showMsa` | tree-derived | Open with the alignment track shown. Default: on when the tree carries an aligned `mol_seq`, off otherwise — an explicit `true`/`false` overrides that. |
+| `showProperties` | tree-derived | Open with the nodes' property values in their labels. Default: off, unless the file's figure setting (`show.SHOW_PROPERTIES=true`) says on. See [Properties in the label](#properties-in-the-label). |
+| `labelProperties` | tree-derived | Which properties the label shows, in order, as an array of refs (`['BVBRC:species', 'BVBRC:host_name']`). Default: the figure setting's `labelprops`, else `null` — every property but the heat map's columns. |
 | `showMsaLogo` | `false` | Open with the alignment summarised as a sequence logo instead of a conservation bar: a stack of letters per column, as tall as its information content, over the tips currently on screen. Only drawn while the alignment track is shown. |
-| `showHeatmap` | `false` | Open with the heat map shown. Offered whenever the tree carries two or more numeric per-tip fields, but off unless asked for: almost any annotated tree has such fields, so turning it on by itself would be an opinion about the tree rather than a service. |
+| `showHeatmap` | tree-derived | Open with the heat map shown. Offered whenever the tree carries two or more numeric per-tip fields, but off unless asked for — almost any annotated tree has such fields, so turning it on by itself would be an opinion about the tree rather than a service — or unless the file's own figure setting (`aptx:figure`, see [Heat maps](#heat-maps)) draws them as a matrix. |
 | `heatmapColumnOrder` | tree-derived | How the heat map's columns are ordered: `'document'` (as the file lists them), `'clustered'` (Euclidean), `'clustered-presence'` (Bray–Curtis), `'alphabetical'`, `'frequency'`. The clustered modes also draw the dendrogram. Default: a **clustered** order, with the distance chosen from the values — Bray–Curtis where the matrix has zeros to ignore and nothing negative, Euclidean otherwise. An explicit value always wins and is never re-derived. |
 | `heatmapManualOrder` | `null` | The heat map's columns in your own order, as an array of property refs (`['meta:recA', 'meta:gyrA', …]`). Only read while `heatmapColumnOrder` is `'manual'`. A ref the tree has not got is ignored, and a column the list does not name follows the ones it does. |
 | `showDomainArchitectures` | tree-derived | Open with the domain tracks shown. Default: on when any tip carries a `<domain_architecture>`, off otherwise — an explicit `true`/`false` overrides that. |
 | `domainLabels` | `'domains'` | Where domain names go: `'domains'` (on the boxes), `'legend'` (a card), or `'none'`. |
 | `domainGlow` | `false` | Open with the glow around each domain box on. |
 | `domainEvalueExponent` | `-3` | The E-value threshold's exponent at launch, an integer from `-20` to `3`: domains with an E-value at or under `10^exponent` are drawn. |
-| `showTimeAxis` | tree-derived | Open with the time axis shown. Default: on when the tree carries `<date>` elements, off otherwise — an explicit `true`/`false` overrides that. |
-| `timeAxisGrid` | `false` | Open with the Time Grid vertical lines on (only meaningful — and only offered as a checkbox — while the time axis itself is shown). |
+| `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. |
+| `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. |
 | `searchAinitialValue` | `null` | Prefill search box A. |
@@ -1372,7 +1413,7 @@ copy-pastable JSON.
 ### Anything else throws
 
 An unrecognised key is an error, whether it was removed in this modernization
-or simply mistyped (the two deprecated keys below are the exception — they
+or simply mistyped (the deprecated keys below are the exception — they
 warn rather than throw):
 
 ```
@@ -1387,14 +1428,15 @@ whatever it names.
 
 ### Accepted, with a warning
 
-Two keys are neither current nor removed: they are accepted so an existing
-embed keeps working, and warn on the console. Both concern Newick support
-values.
+Four keys are neither current nor removed: they are accepted so an existing
+embed keeps working, and warn on the console.
 
 | Key | What happens |
 |---|---|
 | `nhConfidenceValuesAsInternalNames` | Translated to `internalNumericLabels`. **`true` becomes `'confidence'`, not `'auto'`** — `'auto'` is all-or-nothing and promotes nothing in a tree that mixes clade names with support, so a caller moved to it silently would lose promotions they had. An explicit `internalNumericLabels` always wins. |
 | `nhConfidenceValuesInBrackets` | Retired: ignored. It gated whether `[95]` is read as a confidence, but setting it `false` never reinterpreted the bracket — it *discarded* it, so the option's only effect was to throw support values away. A bracket that is not a number is a Newick comment and was ignored either way, and NHX / BEAST blobs go through a different path. Bracketed values are now always read as confidences. |
+| `showTimeAxis` | Translated to `showScaleAxis`, value unchanged: the switch now also draws a distance axis on a tree that is not in time. An explicit `showScaleAxis` always wins. |
+| `timeAxisGrid` | Translated to `showScaleGrid`, value unchanged. |
 
 ### What replaced the rest
 
@@ -1835,6 +1877,28 @@ rather than 300 identical "Influenz.." labels).
 Both menus live in the single control panel, above Display Data, which is where
 the desktop puts them.
 
+### Properties in the label
+
+A tip's other fields — a species, a host, a country, anything a node carries
+as a `<property>` — can go into its label, as on the desktop. **Properties**
+under Display Data (offered when nodes carry properties, off by default) adds
+their **values** after the rest of the label, joined by ` | ` as the rest of the
+label is: `255457.3 | Brucella lupini | host`, or `Brucella lupini` alone with
+Node Name off. (The desktop joins them with `, `; a pipe was chosen here
+because values often contain commas — a host such as `Bottlenose dolphin,
+Tursiops truncatus`.) A unit follows its value. With nothing chosen, every property shows in the
+node's own order, except the heat map's columns while it is shown — a field
+has one display role. **Label fields…** picks which properties, and in what
+order; picking one turns Properties on. The checkbox and the fields travel in
+a shared view (`show=…,properties`, `labelFields=`), and the config keys are
+`showProperties` and `labelProperties`.
+
+A file can choose for itself: the desktop's figure setting (`aptx:figure`,
+see [Heat maps](#heat-maps)) carries `labelprops=` (the properties, in order)
+and the display switches `show.SHOW_PROPERTIES=true` and
+`show.SHOW_NODE_NAMES=false`, and a tree opens labelled that way in both
+programs. The config wins over the file.
+
 ### Initial label fields
 
 Which of the three label checkboxes — Node Name, Taxonomy, Sequence — start
@@ -2070,8 +2134,10 @@ bottom reserve the fit allows for follows that.
 
 Model (`forester.heatmapColumns(tree)` → `{refs:[{ref,label}], min, max}`,
 pure, in `test/heatmap_test.js`): a column is any candidate that
-`forester.visualizationCandidates` already calls a **numeric property** — so
-candidacy is not re-invented here and the refusal rules are inherited — carried
+`forester.visualizationCandidates(tree, {keepConstant: true})` calls a
+**numeric property** — so candidacy is not re-invented here and the refusal
+rules are inherited, except the one against a field with a single value, which
+suits colour-by and not a matrix — carried
 by at least one **tip**; an internal node has no row, so a ref only internal
 nodes hold is not a column and its values never reach the scale. `min`/`max`
 span every drawn cell of the whole tree. `forester.heatmapValue(node, ref)`
@@ -2174,8 +2240,16 @@ order the columns happened to be in. Measured: without it, the 6×6 linkage
 fixture fed in reverse clustered to `h6,h5,h3,h4,h2,h1` instead of R's
 `h6,h3,h5,h4,h1,h2` — the index order drives the tie-break and the leaf order,
 so the incoming order really does leak through. The normaliser deliberately does
-**not** go through `heatmapColumns`: that applies candidacy rules (a constant
-column is refused), and ordering must not move with them.
+**not** go through `heatmapColumns`: that applies candidacy rules, and
+ordering must not move with them.
+
+`forester.heatmapColumns(tree, only)` keeps just the refs in `only` — the
+figure's MATRIX columns (`forester.figureMatrixRefs(tree)`, from
+`forester.readFigure`, which reads the phylogeny's own `aptx:figure` only:
+`"v1;key=value;…"`, values escaped as the desktop's `PropertyTextCodec` does,
+`columns=` a `|` list of `ref~TYPE~SHAPE~normalized`; an unknown version is no
+figure, unknown keys are ignored). `forester.dropCladeFigures(tree)` removes
+the old clade-level copies at launch.
 
 Distances are `forester.heatmapEuclideanDistances` (R's `dist` convention for
 missing values: pairwise deletion, the squared sum scaled up by `tips / used`;

package/archaeopteryx.d.ts

@@ -104,9 +104,21 @@ export interface ArchaeopteryxConfig {
      * bar: each column a stack of letters as tall as its information content,
      * over the tips currently on screen. Only drawn with the track shown. */
     showMsaLogo?: boolean;
+    /** The nodes' property values in their labels (the desktop's "Properties"). */
+    showProperties?: boolean;
+    /** Which properties the label shows, in order; null for all but the heat map's columns. */
+    labelProperties?: string[] | null;
+    /** The scale axis under a phylogram: the time axis on a time tree whose
+     * branches show time, a distance axis on any other. Default: on for a
+     * time tree, off otherwise. */
+    showScaleAxis?: boolean;
+    /** Grid lines (rings, in circular) at the scale axis's ticks. */
+    showScaleGrid?: boolean;
     showSupportDots?: boolean;
+    /** @deprecated renamed showScaleAxis; still read, with a warning. */
     showTimeAxis?: boolean;
     supportDotMinimum?: number;
+    /** @deprecated renamed showScaleGrid; still read, with a warning. */
     timeAxisGrid?: boolean;
     /** Open straight into a view (getViewState / decodeViewState). */
     view?: ViewState | null;
@@ -161,11 +173,17 @@ export interface ViewState {
     heatmap?: boolean;
     heatmapOrder?: 'document' | 'clustered' | 'clustered-presence' | 'alphabetical' | 'frequency' | 'manual';
     heatmapManual?: string[];
+    /** The properties the label shows, in order (labelProperties). */
+    labelFields?: string[];
     domains?: boolean;
     domainLabels?: 'none' | 'domains' | 'legend';
     domainGlow?: boolean;
     domainEvalue?: number;
+    scaleAxis?: boolean;
+    scaleGrid?: boolean;
+    /** @deprecated the name of scaleAxis in older links; still read. */
     timeAxis?: boolean;
+    /** @deprecated the name of scaleGrid in older links; still read. */
     timeGrid?: boolean;
     searchA?: ViewSearch;
     searchB?: ViewSearch;