archaeopteryx 3.22.0 → 3.24.0

package/README.md

@@ -24,8 +24,8 @@ nothing is uploaded. Its **Expert options** panel exercises every launch
 config key live and shows the exact config JSON to copy into your own
 `launch()` call.
 
-* [Auspice / Nextstrain JSON](https://cmzmasek.github.io/archaeopteryx-js/demo.html?tree=auspice)
-* [Swine H1 HA1 + alignment (Nexus)](https://cmzmasek.github.io/archaeopteryx-js/demo.html?tree=swh1)
+* [Auspice / Nextstrain JSON (Time | Div, Clock plot)](https://cmzmasek.github.io/archaeopteryx-js/demo.html?tree=auspice)
+* [Swine H1 HA1 + alignment (Nexus; Clock plot from the years in the names)](https://cmzmasek.github.io/archaeopteryx-js/demo.html?tree=swh1)
 * [BEAST annotations (Nexus)](https://cmzmasek.github.io/archaeopteryx-js/demo.html?tree=beast)
 * [Flavivirus mature peptides (10 trees)](https://cmzmasek.github.io/archaeopteryx-js/demo.html?tree=flavivirus)
 * [SARS-CoV-2 time tree (calendar)](https://cmzmasek.github.io/archaeopteryx-js/demo.html?tree=sarscov2)
@@ -886,6 +886,76 @@ branches show divergence, and the Scale Axis measures distance instead. Each lay
 Div is on screen says so and opens again showing divergence. All of this is
 shared with the desktop.
 
+### Clock plot
+
+Beside the switch, a **Clock plot** button opens a panel that plots each
+tip's **date** against its **divergence** from the root, with a straight
+line through the tips — the root-to-tip plot of TempEst and TreeTime, and
+Auspice's clock view. Under the plot:
+
+- **Rate** — the slope of the line: substitutions per site per year (per
+  unit of the tree's dates where they are not calendar years). Negative
+  where the tips' divergence falls with time.
+- **Root date, by the line** — the date at which the line comes down to the
+  root's divergence — over **Root date, in the tree**, the one the tree
+  states. How far apart they are is the point of showing both.
+- **R²** and the number of **Tips** in the fit.
+
+The line is ordinary least squares over the **tips only**: a tip's date is
+an observation, an ancestor's was inferred (usually with a clock), and
+counting it would have the estimate confirm itself. It is not forced through
+the root. Tips share ancestry, so R² describes the fit and is no
+significance test. On a BEAST clock-model tree the divergence *is* each
+branch's time × its clock rate, so there the plot shows the model's rates,
+not a measurement of its own (a strict clock is a perfect line), and the
+panel says so.
+
+The panel is **linked to the tree** and stays open while you work in it
+(drag it by its title):
+
+- a point wears its node's colour in the tree — the Color visualization,
+  search hits, the selection;
+- pointing at a point lights its node in the tree (the collapsed clade
+  holding it, if it is hidden in one), and pointing at a node in the tree
+  rings its point;
+- **clicking** a point selects or deselects its node, and **dragging** a box
+  selects the tips in it — the tree's own selection, so an outlier found on
+  the plot is found in the tree. **Deselect all** clears it;
+- tips with one date and one divergence — identical sequences sampled on one
+  day — are drawn on one spot, and that dot answers for all of them: the
+  readout says how many tips are there and names the first five, all of them
+  light up in the tree, and a click selects them all (or deselects them all,
+  where all were selected);
+- in a subtree view the plot is the clade's, with the clade's own line.
+
+**Regression line** shows and hides the line. **Internal nodes** adds the
+ancestors' points, each at its own date and divergence; the panel opens
+without them, since the line is the tips' and a deep root would crowd them
+into a corner.
+
+The button is offered on two kinds of tree, whenever the line can be drawn
+(three tips or more, not all on one date; a tree sampled at one moment has
+no slope to estimate):
+
+- a tree that has **Time | Div**: every node is dated and has a divergence,
+  so the ancestors can be shown too;
+- a tree whose **branch lengths are its divergence and whose tips alone are
+  dated** — the tree a root-to-tip plot is run on *before* dating, TempEst's
+  case. A tip's divergence is the sum of the branch lengths from the root;
+  the plot has tips only (**Internal nodes** is not offered, since no
+  ancestor is dated); **Root date, in the tree** says `none`, since the tree
+  states no root date, and **Rate** is in the tree's own branch length unit,
+  where it states one. A tip's date is what the file states for it (a
+  phyloXML `<date>`, a `num_date` annotation) or, failing that, the date in
+  its **name**, as TempEst reads it: the rightmost date the label carries
+  (`A/swine/Iowa/A02524571/2020|1A.3.3.3` is 2020; a year alone is taken as
+  mid-year, 2020.5; a day/month-ambiguous `03/04/2020` is read day first),
+  and the panel's note says how many names it read and how many were
+  ambiguous. An ancestor is never dated by its name. Every tip must be
+  dated, by the file or by its name, and every branch must have a length: a
+  tree with a gap is not offered the plot, rather than plotted with tips
+  missing.
+
 # forester.js
 forester.js is a general suite for dealing with phylogenetic trees.
 
@@ -1096,7 +1166,10 @@ pick them up. Both metrics are retained, and
 `forester.applyTimeBranchLengths(phy)` /
 `forester.applyDivergenceBranchLengths(phy)` /
 `forester.hasTimeAndDivergence(phy)` are the plumbing behind the
-**Time | Div** switch. The two `apply` functions answer `true` when they
+**Time | Div** switch (and `forester.clockPlotKind(phy)` /
+`forester.clockPlotData(phy, view)` / `forester.clockRegression(xs, ys)`
+behind the **Clock plot**: which trees have one, its points and its
+least-squares line). 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.
 
@@ -2540,6 +2613,56 @@ figure never carries an artefact of where the view happened to be scrolled.
 (The desktop pins its axes to the viewport bottom always; sticky is a
 deliberate difference.)
 
+### The clock plot
+
+**Model** (`forester.js`, pure). `forester.clockPlotKind(phy)` answers
+`'divergence'`, `'root-to-tip'` or `null`: `'divergence'` where the tree has
+Time and Div (`forester.hasTimeAndDivergence`); `'root-to-tip'` where every
+tip is dated (by the file, or by the date in its name:
+`forester.parseTipLabelDate`), no ancestor is, every branch states a length
+and no branch states a clock rate (a clock-model tree's lengths are time) — and in
+both cases three tips or more, not all on one date. It is asked of the
+**tree**, never of the view. `forester.clockPlotData(phy, view)` returns
+`{kind, forward, unit, divUnit, fromRates, points, root, fit}`: a point
+`{node, date, div, tip}` per node of the view (a tip also carries its
+`residual`; on a root-to-tip tree the tips only, their `div` the sum of the
+branch lengths from the tree's root), `forward` false where the dates are
+ages (on a root-to-tip tree: where their unit is geologic), `divUnit` the
+divergence's unit (`subs/site` on a Time | Div tree, a root-to-tip tree's
+stated branch length unit, or `null`), `fromRates` true where the divergence
+is time × clock rate, `calendar` true where the dates are calendar years
+(their unit says so, or they were read off the tips' names), `fromNames` and
+`ambiguousNames` how many tips a root-to-tip tree dates by their names and
+how many of those are day/month-ambiguous (read day first), `root.date`
+`null` on a root-to-tip tree, and `fit` =
+`forester.clockRegression(dates, divergences)` over the tips — ordinary least
+squares about the means, `{n, slope, intercept, r2}` — plus `rate` (the slope
+in the direction time runs) and `rootDate` (where the line reaches the view
+root's divergence; `null` unless the rate is positive). `fit` is `null` for a
+view with fewer than three tips or one date. `forester.calendarTickMonths`
+gives month ticks for a span too short for whole years.
+
+**Panel** (`archaeopteryx.js`, the "Clock plot" section). A modeless
+`makeDialogShell` dialog, dragged by its title, placed in the tree area's top
+right corner and below anything the host page keeps there. The drawing is one
+SVG in the panel's own `--p-*` inks. `renderClockPlot` runs at the end of
+every `update()`: it works the points out and lays them down again only when
+the top of the view or its node count changed, or a checkbox did; otherwise
+it only goes over the points' colours. A point's colour is its node's in the
+tree (found, selected, the Color visualization, the file's styles).
+
+**The link.** Pointer events on the SVG: the nearest point within 7 px, and
+with it every point of its kind within 1 px of it — one dot for tips that
+share a date and a divergence. The dot's nodes are lit through
+`showHoverGlow(node, also)` (each as the tree shows it: a tip hidden in a
+collapsed clade lights the clade); a click toggles them in `_selectedNodes`,
+a dragged box adds the tips inside it; `mouseover` on a tree node rings its
+point. Closing is synchronous: nothing waits for the dialog's `close` event.
+
+There is no config key and no view key for the panel yet, and it is not part
+of any download. The numbers are pinned in `test/clock_test.js` (computed by
+hand), the panel in `test/browser/clock_plot.html`.
+
 ## Node selection
 
 With `enableManualNodeSelection` on, the node menu gains **Select/Deselect Node**
@@ -2553,7 +2676,12 @@ var selected = archaeopteryx.getSelectedNodes();   // array of node objects
 Selected nodes are drawn in the selection colour, which is fixed so that it
 stays distinguishable from the two search colours.
 
-There is no push mechanism (no button or event that announces "the user is done
-selecting") — the embedding application reads the selection whenever it wants,
-typically from its own button. (Versions before 3.0 carried a dormant,
-never-rendered "Submit Selected" button in the source; it was removed.)
+The **Clock plot** selects too, whatever this setting says: a click on a
+point, or a box dragged over tips, changes the same selection.
+
+Every change of the selection — from the node menu or from the clock plot —
+dispatches a `selected_nodes_changed_event` on `document`, so the embedding
+application can read the selection then, or whenever it wants from its own
+button. Nothing announces "the user is done selecting". (Versions before 3.0
+carried a dormant, never-rendered "Submit Selected" button in the source; it
+was removed.)