archaeopteryx 3.22.0 → 3.23.0

package/README.md

@@ -24,7 +24,7 @@ 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)
+* [Auspice / Nextstrain JSON (Time | Div, Clock plot)](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)
 * [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)
@@ -886,6 +886,59 @@ 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 a tree that has **Time | Div** and whose 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 whose branch lengths are divergence
+and whose tips alone are dated — the tree a root-to-tip plot is run on
+*before* dating — has no plot yet.)
+
 # forester.js
 forester.js is a general suite for dealing with phylogenetic trees.
 
@@ -1096,7 +1149,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 +2596,46 @@ 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'` or `null`: the tree has Time and Div
+(`forester.hasTimeAndDivergence`) and three tips or more, not all on one
+date. It is asked of the **tree**, never of the view. A second kind,
+`'root-to-tip'` — divergence branch lengths, dated tips, no dated ancestors —
+is described beside the function and not built. `forester.clockPlotData(phy,
+view)` returns `{kind, forward, unit, fromRates, points, root, fit}`: a point
+`{node, date, div, tip}` per node of the view (a tip also carries its
+`residual`), `forward` false where the dates are ages, `fromRates` true where
+the divergence is time × clock rate, 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 +2649,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.)