archaeopteryx 3.17.0 → 3.19.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
@@ -722,25 +734,55 @@ Ages (`unit="mya"` and friends, or values that look like ages) get the
 **geologic axis**: two rows of ICS intervals in their official colours —
 Period over Epoch for most trees, coarser pairs for Precambrian-deep ones —
 plus a "Ma before present" ruler. Years (`unit="year"`, or values that look
-like calendar years) get a labelled **calendar axis** instead. The tree's
-layout itself never changes: time is an overlay calibrated by the dates, so
-it also works for a fossil-only tree, where the axis simply stops at the
-youngest tip and labels that age (the ammonite demo ends at the K-Pg, 66).
+like calendar years) get a labelled **calendar axis**. The layout itself
+never changes: time is an overlay calibrated by the dates, so it also works
+for a fossil-only tree, where the axis stops at the youngest tip and labels
+that age (the ammonite demo ends at the K-Pg, 66).
 
 Nodes with a date **range** (`minimum`/`maximum` — minimum is the younger
 bound) draw uncertainty bars: translucent blue **HPD age bars** on internal
-nodes, and on tips whatever the axis says the range means. On **geologic**
-time it is a fossil's observed range: sepia **fossil-range (FAD/LAD) bars with
-end caps**. On **calendar** time it is the uncertainty of a **sampling date**
-— a virus sample dated only to its month or year — drawn like an age bar,
-slimmer, and only when it has a width: a tip dated to the day draws nothing.
-Node
-tooltips show the date. The **Time Axis** checkbox under Display Data toggles
-everything; the axis needs a phylogram (branch lengths carry the time) and
-the rectangular layout. **Time Grid** (off by default, like the desktop's
-"Time axis grid lines") adds faint vertical lines behind the tree at the
-fine geologic-interval boundaries or the calendar year ticks, so a node's
-position can be read against the axis.
+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
+**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. **Scale Grid** (off
+by default) adds faint lines, or rings, at the fine interval boundaries or
+the calendar years.
+
+### Time | Div
+
+Where a tree can be laid out by **time** and by **divergence**, a
+**Time | Div** switch appears beside the phylogram buttons (⌘⇧X). Two kinds
+of tree state a divergence: an Auspice build, on its nodes (`div`), and a
+BEAST clock-model tree, as a clock `rate` on every branch — its branch
+lengths are time, and its divergence is each length times its rate, in
+substitutions per site. A tree with neither has no second layout. A rate or
+a recorded divergence is a plain decimal number (`0.01abc` is not one); a
+negative divergence is a value, drawn at 0.
+
+The switch is offered only when both layouts can state **every** branch —
+every node dated, every branch with a length, and divergence on every node
+or a rate on every branch — and each picture has some depth. A value the
+file states counts, whether zero or negative; where one is missing the
+switch is withheld rather than a branch drawn at a length the file never
+gave. Whether the two pictures differ is not asked: a strict clock's
+divergence is its time at another scale, and it is offered like any other.
+
+Back in Time the tree has exactly the lengths it arrived with. A span that
+runs backwards — a child dated before its parent, which real Nextstrain
+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, 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.
 
 # forester.js
 forester.js is a general suite for dealing with phylogenetic trees.
@@ -940,16 +982,21 @@ A protein/DNA/RNA characters matrix in a Nexus file
 (sequential or interleaved) lands on the tips as an aligned `mol_seq`, so the
 alignment track appears just as it does for phyloXML.
 
-An Auspice dataset opens on the **time view** (branch lengths from `num_date`
-differences; a divergence-only build falls back to `div` differences): the
-calendar time axis and node-age bars come from `num_date` and its confidence
-interval, and every trait (country, host, clade, ...) becomes a
+An Auspice dataset has no branch lengths of its own, so it opens in the
+metric it states completely: the **time view** when every node states a
+`num_date` (branch lengths are the `num_date` differences, sign kept), else
+the divergence view when every node states a `div`, else time if any node is
+dated. In the time view the calendar time axis and node-age bars come from
+`num_date` and its confidence interval, and every trait (country, host,
+clade, ...) becomes a
 `nextstrain:<trait>` node property — so Color-by, search and the node dialog
 pick them up. Both metrics are retained, and
 `forester.applyTimeBranchLengths(phy)` /
 `forester.applyDivergenceBranchLengths(phy)` /
-`forester.hasTimeAndDivergence(phy)` are the plumbing for a future
-time↔divergence display toggle.
+`forester.hasTimeAndDivergence(phy)` are the plumbing behind the
+**Time | Div** switch. The two `apply` functions answer `true` when they
+laid the tree out, and `false` — leaving every branch length as it was —
+when their layout cannot state every branch.
 
 **BEAST-style and NHX annotations** in Newick/Nexus input are always parsed
 (they used to be discarded): in a `[&key=value,...]` blob — as written by
@@ -1129,7 +1176,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**
@@ -1145,8 +1193,8 @@ between them rather than either one being shrunk.
 
 The **control panel itself** follows the same idea. It opens showing the
 sections that describe the tree — what it can be coloured by, what it shows —
-plus Search, and folds the ones that are adjustments to make later: Zoom,
-Sizes and the domain controls. Whatever you open or close is then remembered, for the
+plus Search, and folds the ones that are adjustments to make later: View &
+Tools, Sizes and the domain controls. Whatever you open or close is then remembered, for the
 page and across reloads, so a panel you have arranged stays arranged, even
 when you switch to another tree. In a short window it also keeps itself to one
 screen: opening a section folds the one you opened longest ago, and dragging
@@ -1313,8 +1361,8 @@ copy-pastable JSON.
 | `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. |
@@ -1337,7 +1385,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):
 
 ```
@@ -1352,14 +1400,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
 
@@ -2233,11 +2282,15 @@ loops). Calibration: the **largest** date value is the root age (geologic)
 or the present (calendar) — no unit conversion is done, so a Ga-valued tree
 is misbanded exactly as on the desktop.
 
-Rendering (phylogram + rectangular only; the layout never changes): age→x is
-`anchorX + (anchorAge − age) × corr` with `corr` the branch-length scale's
-slope, anchored at the **deepest dated tip** rather than the root — the root
-and its direct children carry a synthetic half-average branch length, which
-would shift every band. The geologic axis draws
+Rendering (phylogram, rectangular or circular; the layout never changes):
+age→x is `anchorX + (anchorAge − age) × corr` with `corr` the branch-length
+scale's slope, anchored at the **deepest dated tip** rather than the root,
+so the root's own branch, drawn to scale where the file states one, shifts
+no band. In circular the same arithmetic runs along each spoke: a bar is a
+segment of its node's spoke (a bound past the root's estimate a negative
+radius, continued through the centre), the ruler a ray along the gap between
+the last tip and the first, the grid and the geologic intervals rings. The
+geologic axis draws
 `forester.geoBandRanks(rootAge)` — the finest of Period/Epoch, Era/Period,
 Eon/Era that still covers the range — as two 13 px rows of ICS intervals
 (official colours; ink by the same luminance rule), clipped to

package/archaeopteryx.d.ts

@@ -104,9 +104,17 @@ 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 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;
@@ -165,7 +173,11 @@ export interface ViewState {
     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;