archaeopteryx 3.13.0 → 3.15.0

package/README.md

@@ -257,8 +257,10 @@ the mouse wheel zooms too, and never rotates), **X− / X+ become rotate** (a
 direction** flip — labels riding their spokes or standing upright — while
 vertical expansion greys out. **Fit** centres and scales the fan; **Esc**
 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).
+additionally greys out the aligned-phylogram option (there is no common label
+edge). Auto-hide Labels stays live: the tip-label thinning it governs needs
+even row spacing and so does nothing in unrooted, but the crowded-branch-data
+rule it also governs applies in every layout.
 
 ## Rooting
 
@@ -526,6 +528,16 @@ section holds the controls:
   the tree), or `None`.
 * **Glow** — a soft glow in each domain's own colour around its box.
 
+**Hovering a domain** reads it out: the domain's name, its E-value (small
+ones keep their exponent, 7.20e-117), the residues it spans with its own length and the protein's,
+the tree tip it belongs to, and its accession where the file carries one.
+**Clicking the box** looks the domain up: straight to the Pfam entry when
+there is an accession, and an InterPro search by name when there is not —
+phyloXML's domain `id` is optional, and a file with names alone (our own
+`apaf.xml` among them) cannot address an entry, since InterPro resolves
+accessions and not Pfam identifiers. Only the domain boxes take the mouse, so
+the tree behind the track stays clickable.
+
 In the circular and unrooted layouts the tracks ride each tip's spoke
 outward and carry no names (the legend still works); they need radial
 labels, which switching layouts turns on. A malformed domain — a missing or
@@ -555,7 +567,7 @@ To find a motif, pick **Molecular Sequence** in a search box: it matches the
 residues as written, gap characters included, as the desktop does.
 
 **Sequence Logo** (the checkbox under **Alignment**) replaces the conservation
-bar with a **logo**: every column a stack of letters, as tall as that column's
+bar with a **logo**: a stack of letters per column, as tall as that column's
 information content in bits and shared out by residue frequency, most frequent
 on top — the display the MEME Suite and WebLogo draw. A conserved column is one
 tall letter, a variable one a short pile, and the caption gives the scale
@@ -566,7 +578,8 @@ clade's motif rather than the file's, and the caption names how many tips that
 is (`n = 12`). Two consequences worth knowing: gaps are not a letter —
 frequencies are taken over the residues present, and the stack is then scaled
 by the column's occupancy, so a column held up by two sequences out of fifty
-draws short rather than perfectly conserved; and there is **no small-sample
+draws short rather than perfectly conserved and an all-gap column draws
+nothing; and there is **no small-sample
 correction**, because entering a three-tip clade is a normal thing to do and
 Schneider's correction would subtract more than the maximum and leave the
 column blank. Read `n` and judge.
@@ -1040,11 +1053,13 @@ each with a checkbox under Display Data to turn it off.
 Support and branch-length values draw **2 px smaller than the label font**
 (never below 6 px), as on the desktop, so they annotate without competing.
 And besides the numeric display there are **Support Dots**: a filled dot at
-the midpoint of every branch whose support is at least 95% (`supportDotMinimum`;
+the midpoint of a branch whose support is at least 95% (`supportDotMinimum`;
 posterior- and bootstrap-scaled trees are told apart automatically). The dot
 is always a fixed amount wider than the branch itself, so it tracks the
 Branch Width slider instead of sitting at one fixed size. A branch drawn
-shorter than the dot itself stays clean.
+shorter than the dot itself stays clean, and so does one whose dot would land
+on a dot already drawn — see the crowding rule below, which is what decides
+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 —
@@ -1059,7 +1074,69 @@ never at all on a tall screen. Growing the window back leaves the folds where
 they are: what is open is your choice, and only running out of room overrules
 it. Anything that puts something into a folded section opens it, so jumping to
 the search box (⌘F / Ctrl+F) or a tool reporting its result as search hits
-unfolds Search. A host with little room to give can
+unfolds Search. The **ⓘ** button in the panel header (or ⌘I / Ctrl+I) opens **Tree
+properties**, modelled on the desktop Archaeopteryx's *View › Tree
+Properties* and read-only:
+
+* **Tree** — name, description, identifier, type, branch-length unit,
+  rootedness and rerootability (each shown only where the file actually says
+  so), and "tree 2 of 3" when the file held several.
+* **Structure** — tips, internal nodes, total nodes, branches, whether the
+  tree is fully binary or how many polytomies it has and the widest of them,
+  depth from root to deepest tip, the longest tip label, and how many internal
+  nodes are named.
+* **Branch lengths** — how many branches carry one, then **minimum, median,
+  maximum and mean**, the sum as total tree length, the height from root to
+  farthest tip, any zero-length or negative branches, and whether the tree is
+  ultrametric.
+* **Support** — the same n / minimum / median / maximum / mean, **one section
+  per kind**. A bootstrap and a posterior on the same branch are not on one
+  scale, so they are never pooled; MAD values are not support and are counted
+  with the annotations instead.
+* **The tree carries** — taxonomies (and how many are distinct), taxonomy
+  identifiers, sequences, molecular sequences with the alignment width, domain
+  architectures, dates, distributions, events, branch colours, and **every
+  phyloXML property `ref` with the number of nodes carrying it** — each as
+  "n of m tips" or "n of m nodes".
+* **Time** — geologic ages or calendar years, dated nodes, the oldest node or
+  most recent tip, and whether there are confidence intervals.
+
+It describes what is on screen, so inside a subtree it describes the subtree
+and says so, and it is recomputed each time it opens rather than cached (24 ms
+on the 13,246-tip demo). There is no histogram.
+
+**Auto-hide Labels** also thins out **crowded branch data**. Support values,
+branch-length values and support symbols are drawn only where they fit: each
+mark claims the box it is about to occupy, and one that would overlap a box
+already claimed in that pass is left out. The claim order is the tree's own,
+root first, so the mark nearer the root keeps its place and the same tree at
+the same size always drops the same marks — on screen and in every export.
+Numbers and symbols are kept in separate maps, since the symbol sits on the
+branch and the numbers just above and below it. Symbols are never shrunk to
+fit: where a symbol's size means something, a smaller one would report
+something else. Switch the toggle off and everything is drawn. Zero needs no
+special case — a lone zero-length branch overlaps nothing, so its number
+stays. Branch events take part too. This is the desktop Archaeopteryx's rule,
+adopted so the two programs thin the same tree the same way; the marks they
+drop are close but not identical, because the boxes come from each program's
+own font metrics.
+
+It applies in **all three layouts**. In the circular and unrooted views a mark
+rides its branch: it is drawn at the branch's midpoint, turned to the branch's
+direction and set just off the line, so the box claimed for it is the
+axis-aligned bounds of that turned rectangle, centred where the text's own
+centre lands — the desktop's formula, which carries over because both programs
+measure it in real screen space rather than in the layout's own units. A
+diagonal label's bounds are wider than its ink, so a crowded number is dropped
+rather than overprinted. The circular view of `flu_h5.xml` goes from 785 drawn
+numbers, 743 of them overlapping another, to 87 with none.
+
+One placement follows from that: in the two radial views every mark is drawn on
+the same point, the branch's midpoint, so a **branch event** sits a line clear
+of the branch-length value rather than on top of it. In the rectangular layout
+they are already apart along the branch and share the line above it.
+
+A host with little room to give can
 also start the whole panel tighter and narrower with
 [`panelDensity: 'compact'`](#configuration), or collapsed to its header bar
 with `collapseControlPanel`.
@@ -1097,7 +1174,7 @@ 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. |
-| `showMsaLogo` | `false` | Open with the alignment summarised as a sequence logo instead of a conservation bar: each column a stack of letters as tall as its information content, over the tips currently on screen. Only drawn while the alignment track is shown. |
+| `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. |
 | `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. |