archaeopteryx 3.11.0 → 3.13.0

package/README.md

@@ -37,6 +37,7 @@ config key live and shows the exact config JSON to copy into your own
 * [Nucleotide alignment (600 columns)](https://cmzmasek.github.io/archaeopteryx-js/demo.html?tree=alignment_nt)
 * [Genome alignment (150 × 30,000 columns)](https://cmzmasek.github.io/archaeopteryx-js/demo.html?tree=genome_alignment)
 * [Sequence alignment](https://cmzmasek.github.io/archaeopteryx-js/demo.html?tree=alignment)
+* [Sequence logo (the motif changes by clade)](https://cmzmasek.github.io/archaeopteryx-js/demo.html?tree=sequence_logo)
 * [Influenza HA (annotated)](https://cmzmasek.github.io/archaeopteryx-js/demo.html?tree=influenza)
 * [Dinosaur time tree](https://cmzmasek.github.io/archaeopteryx-js/demo.html?tree=dinosaur)
 * [Ammonite time tree (fossil ranges)](https://cmzmasek.github.io/archaeopteryx-js/demo.html?tree=ammonite)
@@ -315,6 +316,25 @@ 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.
 
+A tip is written under its **name**; where it has none, under its taxonomy
+(code, then scientific, then common name), then its sequence's name, symbol or
+gene name, then its sequence **accession**, and only if it has none of those
+under a `node<N>` placeholder numbering it by position among the tips. Each
+step is tried in turn, so a taxonomy element that is present but empty does
+not stop the search. An unlabeled *internal* node stays unlabeled — a
+placeholder there would invent a name for an ancestor. Newick and Nexus use
+the one chain, so a tree saved in both formats names its tips identically, and
+it is the desktop Archaeopteryx's chain, compared byte for byte.
+
+Newick and Nexus have **one** support slot per branch and no place to name
+what kind of support it is, so a branch carrying several confidences is
+written with the first that is not a MAD value, exactly as the desktop writes
+it, and a `bootstrap` read back from such a file is typed `unknown`. phyloXML
+keeps every one of them, typed. Everything else survives a trip through
+either format unchanged — names, branch lengths (including zero-length and
+negative branches) and aligned sequences — in both directions, which the test
+suite pins as two standing round trips.
+
 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>
@@ -455,7 +475,9 @@ 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, the tracks. On the demo pages it rides in the URL's
+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
 `#` 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
@@ -472,7 +494,9 @@ as the page does.
 Embedders get the same four pieces: the handle's `getViewState()` and
 `applyViewState(state)`, the config's `view` (open straight into one) and
 `onViewChange(state, encoded)` (called when it changes), and
-`archaeopteryx.encodeViewState()` / `decodeViewState()` for the hash form,
+`archaeopteryx.encodeViewState()` / `decodeViewState()` for the hash form
+(every key the state can hold survives the hash — a test reads `getViewState`
+and fails on any key the codec does not know),
 which reads like
 `layout=circular&colorBy=tax:common_name&show=name,external&font=9&collapsed=12,44&a=HUMAN&af=Any+Text&am=contains`.
 Nodes are named by their launch-time preorder index, so a view belongs to
@@ -530,10 +554,39 @@ 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.
 
+**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
+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
+(0 to 2 bits for nucleotides, 0 to 4.3 for amino acids).
+
+It summarises **the tips currently on screen**, so entering a clade gives that
+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
+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.
+
 Alignments arrive with the tree: as phyloXML `<mol_seq is_aligned="true">`
 elements, or in a **Nexus** file whose characters matrix accompanies its tree.
 The **Nexus** entry in the Download menu writes the current tree *and* its
-alignment back into one Nexus file (Taxa, Characters and Trees blocks).
+alignment back into one Nexus file (Taxa, Characters and Trees blocks), in the
+same bytes the desktop Archaeopteryx writes: a row per taxon rather than per
+sequence, so a tip carrying no sequence gets a row of the missing symbol `?`
+and the matrix still covers every taxon the file declares. Reading it back,
+such a row is absence of data and not a sequence of question marks. Residues
+from a Nexus matrix are normalised as the desktop normalises them — raised to
+upper case, `.` read as a gap, and anything outside the declared alphabet read
+as the unspecified residue, `X` for protein and `N` for nucleotides, so the
+missing symbol `?` arrives as `X` or `N`. A phyloXML `<mol_seq>` is kept
+exactly as written, by both programs. Sequences
+of *unequal* length are not an alignment and cannot form a character matrix,
+so they are not written at all — the file says so in a bracketed comment
+rather than padding them into an alignment that does not exist.
 
 ## Heat maps
 
@@ -999,11 +1052,14 @@ 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
 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, but only while
-the panel would not otherwise fit — on a tall screen nothing is ever folded for
-you. Anything that puts something into a folded section opens it, so jumping to
-the search box (⌘F / Ctrl+F), revealing Search B, or a tool reporting its
-result as search hits all unfold Search. A host with little room to give can
+screen: opening a section folds the one you opened longest ago, and dragging
+the window (or the element it sits in) shorter does the same — but only while
+the panel would not otherwise fit, never past the last section left open, and
+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
 also start the whole panel tighter and narrower with
 [`panelDensity: 'compact'`](#configuration), or collapsed to its header bar
 with `collapseControlPanel`.
@@ -1041,6 +1097,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. |
 | `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. |
@@ -1710,14 +1767,38 @@ readout (`forester.msaResidueInfo`, `msaUngappedPosition`) names the residue
 
 Navigation: a lazily-created bar fixed at the viewport bottom — first / page
 back / slider / page forward / last, a jump-to-column box (1-based, matching
-the hover readout) and a live "column N – M of total" — plus wheel-over-track
+the hover readout) and a live "column N M of total" — plus wheel-over-track
 at a tenth of a screen per notch. Every route lands in one `msaScrollTo()`,
 which clamps and redraws; the tree never moves. A faint dashed guide runs
 from each tip's label (or its node, when labels are hidden) across to that
 tip's row, so a row reads back to its sequence without counting.
 
-The conservation bar, consensus row and column ruler are a **floating strip**
-(see the time axes below); the residue rows stay with their tips.
+**The sequence logo** (`showMsaLogo`, `forester.msaLogo`) replaces the
+conservation bar and the consensus row rather than joining them: a stack's
+height *is* the column's conservation and its top letter *is* the consensus,
+so all three would say one thing three times. Per column the model returns
+`bits` = `log₂K − H` over the non-gap residues, `occupancy` = non-gap / rows,
+`height` = `bits × occupancy`, and the letters most frequent first (ties
+alphabetical, so a figure reproduces). Rows are the **displayed** tips over
+the visible window, which is what makes entering a clade re-read the summary.
+**No small-sample correction**: Schneider's `e_n = (K−1)/(2 ln2 · n)` is for a
+motif sampled from many sequences, and at n = 3 for protein it exceeds the
+4.32-bit maximum, so a perfectly conserved column of a small clade would draw
+nothing — the caption names `n` instead.
+
+Each letter is scaled to fill its slice: `sy = hpx / (ascent + descent)` of
+**that glyph's** ink box, measured once per character off a canvas, with the
+baseline placed at `y − descent × sy` so the ink lands inside the slice.
+Measured off one glyph instead, Q and G hung their descenders through the
+ruler. Note that an SVG `<text>`'s `getBoundingClientRect` is the *font's*
+layout box, not the ink, so it cannot check this — `test_trees/msa_logo.html`
+compares letters and order through the DOM and the ink itself is measured from
+rendered pixels.
+
+The conservation bar or logo, the consensus row and the column ruler are a
+**floating strip** (see the time axes below); the residue rows stay with their
+tips. The strip's height follows what it holds (`msaBottomReserve()`), and the
+bottom reserve the fit allows for follows that.
 
 ### The heat map
 

package/archaeopteryx.d.ts

@@ -98,6 +98,10 @@ export interface ArchaeopteryxConfig {
     heatmapManualOrder?: string[] | null;
     showHeatmap?: boolean;
     showMsa?: boolean;
+    /** Summarize the alignment 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 with the track shown. */
+    showMsaLogo?: boolean;
     showSupportDots?: boolean;
     showTimeAxis?: boolean;
     supportDotMinimum?: number;
@@ -150,6 +154,8 @@ export interface ViewState {
     rotation?: number;
     horizontalLabels?: boolean;
     msa?: boolean;
+    /** The alignment summarized as a sequence logo. */
+    msaLogo?: boolean;
     heatmap?: boolean;
     heatmapOrder?: 'document' | 'clustered' | 'clustered-presence' | 'alphabetical' | 'frequency' | 'manual';
     heatmapManual?: string[];