archaeopteryx 3.4.0 → 3.5.0

package/README.md

@@ -27,6 +27,7 @@ config key live and shows the exact config JSON to copy into your own
 * [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)
 * [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)
 * [Herpesviridae DNA polymerase (201 tips)](https://cmzmasek.github.io/archaeopteryx-js/demo.html?tree=herpes_dnapol)
 * [Caliciviridae (186 strains)](https://cmzmasek.github.io/archaeopteryx-js/demo.html?tree=caliciviridae_500)
@@ -217,15 +218,24 @@ any node does — an event, a search hit, a selection, a visualization.
 internal node's whole clade into a wedge and opens it again; **Uncollapse
 Subtree** opens everything below a node; the tool row's uncollapse-all button
 (the desktop's glyph, lit only while something is collapsed) opens the whole
-tree, and so does **Esc**. The wedge is the desktop's triangle: its apex at
-the node, its vertical base at the clade's average tip distance (one depth
-step in a cladogram), so its depth stays readable; it is filled in the colour most of its tips wear under the current
-Color-by, grows gently taller with its tip count, and is named — the node's
+tree, and so does **Esc**. The wedge has its apex at the node, one edge
+reaching the clade's nearest tip and the other its farthest, so the shape
+shows how uneven the clade's branch lengths are, as iTOL draws it (one depth
+step in a cladogram). Its label stands where a tip's would: on the label
+column in the aligned phylogram and on the outer ring in circular, with the
+same guide line; it is filled in the colour most of its tips wear under the current
+Color-by (the colour
+they wore, even when no tip on screen shares their value), grows gently taller with its tip count, and is named — the node's
 own name if it has one; else the one Color-by value nearly all its tips share,
 so a clade reads "Bovine · 12 tips" while you look at hosts; else the tips'
 common name prefix; always with the tip count, and with `[found/total]` while
 a search hits inside it. Legends, alignment rows and domain tracks describe
-the tips on screen, so a collapsed clade's tips leave them. Collapsing is
+the tips on screen, so a collapsed clade's tips leave them,
+and the counts follow every clade you fold or open. A clade holding search
+hits is one dot in the overview and one stop for the hit navigator; one
+holding selected tips is outlined in the selection colour, and filled when
+all its tips are selected. Re-rooting opens any collapsed clade whose tips it
+would change, such as one the new midpoint falls inside. Collapsing is
 display state only: nothing is removed, exports and downloads carry every
 tip, and the unrooted layout, which has no rows to fold, shows every clade
 open. The controls are the desktop's; the drawing and naming are this
@@ -248,6 +258,67 @@ also resets rotation and label direction. Unrooted
 additionally greys out the aligned-phylogram option and Auto-hide Labels
 (there is no common label edge, and no even row spacing to hide against).
 
+## Rooting
+
+The tool row's re-root button asks how: **MAD re-root (Tria et al., 2017)**
+or **Midpoint re-root** (hover over the MAD entry for the full citation). A
+node's menu offers **Reroot** on the branch above that node. None of them is
+offered for a tree whose phyloXML says `rerootable="false"`, nor for a time
+tree, one whose internal nodes are mostly dated (BEAST node heights,
+Nextstrain dates, phyloXML `<date>`s): a new root would contradict the dates.
+For such a tree the re-root button and the node menu's Reroot are greyed,
+their tooltip saying why, and a shared view's root is ignored.
+
+A re-root can take the meaning away from data on internal nodes: a node's
+name, taxonomy, sequence, events, distribution, date, references or node
+properties describe its clade, and a new root changes the clade of every
+node between the old root and the new one. So before re-rooting (from the
+button's menu or the node menu), the change is worked out on a copy of the
+tree, and when it would change the clade of any internal node carrying data,
+a warning says how many (“This tree has data on 15 internal nodes.
+Re-rooting changes the clade of 3 of them, so their data may no longer
+describe them.”) with **Re-root** and **Cancel**. Branch lengths, support and
+MAD values, branch colours and `style:` properties do not count: they belong
+to the branch, or to the look.
+
+A tree its file declares unrooted (phyloXML `rooted="false"`, Nexus `[&U]`),
+shown in the unrooted layout, has no root to measure from. There the hover
+card and Display Node Data show an internal node's **Tips around** — the tips
+on each of its sides, smallest first, such as `2 · 3 · 5` — instead of
+distance to parent, depth and tips below; a tip shows its **Branch length**
+and no depth; and the Depth from Root, Distance from Root and Clade Size
+search fields are not offered. The same tree in the rectangular or circular
+layout keeps all of them, since those layouts draw a root.
+
+**MAD rooting** (minimal ancestor deviation) roots the tree without assuming
+a clock. The common ancestor of two tips ought to lie halfway between them,
+so every branch and position is scored by how far the tip pairs' ancestors
+fall from that halfway point, and the root goes where that deviation is
+smallest [1]. It has been compared with other rooting methods on prokaryotic
+gene families [2]. It needs branch lengths and at least three tips, and is
+offered only then. The algorithm is the desktop Archaeopteryx's, and gives
+the same roots; it runs in O(n²) time and O(n) memory (the 13,246-tip H5N1
+demo tree roots in 0.4 s, measured in Node).
+
+Every internal branch then carries its **MAD value**: the root-mean-square
+deviation the tree would have with the root on that branch. Lower is better,
+and the root's branch has the smallest. The **MAD Values** checkbox (Display
+Data → Labels, present while the tree carries them) writes them on the
+branches, ahead of any support value, as `MAD/support`: `0.02/95`. They are
+not support, so the Confidence labels, Support Dots and the Confidence search
+field leave them out. Midpoint or manual re-rooting removes them, since they
+describe the MAD rooting only. A shared view remembers a MAD root. A phyloXML
+download keeps them as `<confidence type="MAD">`, as the desktop writes them;
+a Newick or Nexus download never puts one where a support value goes.
+
+1. Tria, F.D.K., Landan, G., Dagan, T. (2017). Phylogenetic rooting using
+   minimal ancestor deviation. *Nature Ecology & Evolution*, 1, 0193.
+   <https://www.nature.com/articles/s41559-017-0193>
+2. Wade, T., Rangel, L.T., Kundu, S., Fournier, G.P., Bansal, M.S. (2020).
+   Assessing the accuracy of phylogenetic rooting methods on prokaryotic
+   gene families. *PLOS ONE*, 15(5), e0232950.
+   <https://journals.plos.org/plosone/article?id=10.1371/journal.pone.0232950>
+
 ## Metadata tables
 
 A tree file rarely carries everything known about its tips. A **metadata
@@ -270,6 +341,13 @@ nothing; a column the tree already carries under the same ref is replaced by
 the table's values. Quoted cells, `#` comment lines and Windows line ends are
 fine.
 
+The node menu's **Download Ext. Node Data** writes the other direction: the
+tips under a node as a tab-separated table, header first, with the desktop
+Archaeopteryx's column names (`name`, `taxonomy_scientific_name`, …,
+`branch_length`, then one column per property ref). A column no tip fills
+is left out, and a `node_id` column comes first when tip names are blank or
+repeated. Such a file opens again as a metadata table.
+
 Embedders do the same in two lines, before `launch()`:
 
 ```js
@@ -291,10 +369,12 @@ and **Inverse** apply to both.
 Hits are hard to miss: their labels take the search colour **in bold**, a
 translucent **pulsing halo** breathes behind each hit, and everything that is
 *not* a hit fades — the desktop's "dim non-matches", engaged only while at
-least one hit is actually visible, so a fruitless search never washes the
-tree out. The **overview** miniature marks every hit as a dot in the same
+least one hit is on screen, so a fruitless search never washes the tree out.
+A collapsed clade holding a hit counts as on screen: it stays bright, its
+wedge outlined in the search colour and its label counting the hits, and
+the rest fades even when every hit is inside collapsed clades. The **overview** miniature marks every hit as a dot in the same
 colour, and a **◀ k / N ▶** navigator appears under the search boxes: each
-press centres the previous / next hit in the viewport, wrapping around.
+press centres the previous / next hit in the viewport, wrapping around. A collapsed clade holding hits is one dot and one stop.
 
 ## Keyboard
 
@@ -403,6 +483,8 @@ displayed), and a 1-based **column ruler**. **Hover any residue** for its
 alignment column, its position within that sequence's own ungapped residues,
 its full name, class, and Kyte-Doolittle hydropathy. The **Alignment**
 checkbox under Display Data toggles the whole track.
+To find a motif, pick **Molecular Sequence** in a search box: it matches the
+residues as written, gap characters included, as the desktop does.
 
 Alignments arrive with the tree: as phyloXML `<mol_seq is_aligned="true">`
 elements, or in a **Nexus** file whose characters matrix accompanies its tree.
@@ -615,7 +697,7 @@ a name ending in `xml` as phyloXML, anything else as New Hampshire (Newick).
 A file holding **several trees** — a Nexus TREES block, a Newick file with one
 tree per `;`, a phyloXML with several phylogenies — opens on the first, and a
 picker with previous / next buttons at the top of the control panel moves
-between them; each tree opens fresh under the same config, the way a new tab
+between them; each tree opens fresh under the same config, nothing collapsed, the way a new tab
 does on the desktop. 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.

package/archaeopteryx.d.ts

@@ -114,15 +114,15 @@ export interface ViewState {
     display?: 'phylogram' | 'aligned' | 'cladogram';
     /** The ladderize direction applied. */
     order?: 'asc' | 'desc';
-    /** Midpoint re-rooted. */
-    root?: 'midpoint';
+    /** Re-rooted: at the midpoint, or by minimal ancestor deviation. */
+    root?: 'midpoint' | 'mad';
     subtree?: number;
     collapsed?: number[];
     /** A visualization id (as the Color-by menu values them), or 'none'. */
     colorBy?: string;
     shapeBy?: string;
     /** The panel's checked boxes: name, taxonomy, sequence, confidence,
-     * branchLength, external, internal, nodeEvents, branchEvents,
+     * madValues, branchLength, external, internal, nodeEvents, branchEvents,
      * supportDots, shortNames, autoHide, visualizations, visualStyles, and
      * custom:<key> for a nodeLabels checkbox. */
     show?: string[];