archaeopteryx 3.0.0 → 3.1.0

package/README.md

@@ -16,6 +16,14 @@ they run entirely in your browser:
 
 **https://cmzmasek.github.io/archaeopteryx-js/**
 
+**Try your own tree:**
+[**cmzmasek.github.io/archaeopteryx-js/open.html**](https://cmzmasek.github.io/archaeopteryx-js/open.html)
+— paste or open a Newick / NHX / Nexus / phyloXML / Auspice JSON file and
+Archaeopteryx.js will visualize it. The tree is read locally in your browser;
+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)
 * [BEAST annotations (Nexus)](https://cmzmasek.github.io/archaeopteryx-js/demo.html?tree=beast)
@@ -24,10 +32,12 @@ they run entirely in your browser:
 * [Caliciviridae (186 strains)](https://cmzmasek.github.io/archaeopteryx-js/demo.html?tree=caliciviridae_500)
 * [Adenoviridae (321 strains)](https://cmzmasek.github.io/archaeopteryx-js/demo.html?tree=adenoviridae)
 * [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)
 * [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)
+* [Late Cretaceous time tree (stages)](https://cmzmasek.github.io/archaeopteryx-js/demo.html?tree=late_cretaceous)
 * [Apaf-1 gene family](https://cmzmasek.github.io/archaeopteryx-js/demo.html?tree=apaf)
 * [Bcl-2 family](https://cmzmasek.github.io/archaeopteryx-js/demo.html?tree=bcl2)
 * [Confidence values](https://cmzmasek.github.io/archaeopteryx-js/demo.html?tree=confidences)
@@ -36,10 +46,12 @@ they run entirely in your browser:
 * [Start circular](https://cmzmasek.github.io/archaeopteryx-js/demo.html?tree=circular)
 * [Woese tree of life (start unrooted)](https://cmzmasek.github.io/archaeopteryx-js/demo.html?tree=woese)
 * [Start with collapsed controls](https://cmzmasek.github.io/archaeopteryx-js/demo.html?tree=collapsed)
+* [H5N1 segment 3 (13,246 tips)](https://cmzmasek.github.io/archaeopteryx-js/demo.html?tree=flu_h5n1_seg3)
 
 
 ### Detailed developer documentation
-https://docs.google.com/document/d/1COVe0iYbKtcBQxGTP4_zuimpk2FH9iusOVOgd5xCJ3A/edit
+To be written. For now, the [For Developers](#for-developers) section below
+covers the entry points, configuration, and the visualization system.
 
 ### Dependencies
 Archaeopteryx.js has the following dependencies:
@@ -361,9 +373,8 @@ Both entry points take **exactly** the arguments shown — a call with the old
 trailing arguments (the separate settings bag, `nodeVisualizations`,
 `nodeLabels`, `specialVisualizations`, or the positional Newick parse
 options) **throws** with a message saying where each one went: everything now
-lives in the **one config object** (`nodeLabels`,
-`nhConfidenceValuesInBrackets`, `nhConfidenceValuesAsInternalNames` are
-config keys). `config` itself is optional — `archaeopteryx.launch('#phylogram1',
+lives in the **one config object** (`nodeLabels` and
+`internalNumericLabels` are config keys). `config` itself is optional — `archaeopteryx.launch('#phylogram1',
 tree)` works.
 
 `container` is a **CSS selector or the DOM element itself** (frameworks hand
@@ -372,12 +383,45 @@ render nothing and say nothing. Both entry points return a **viewer handle**:
 
 ```js
 viewer.getSelectedNodes(); // the node-menu selections (enableManualNodeSelection)
+viewer.ready;              // a Promise: resolved once the tree is drawn
 viewer.destroy();          // unmount COMPLETELY: the container DOM, the node
                            // menu / dialogs / alignment scroller, the window
                            // resize listener and every page-level key/wheel
                            // handler; a later launch() works normally
 ```
 
+**Big trees draw on the next frame.** Above 2,000 nodes, `launch()` does all
+its validation, shows a "Drawing N nodes" card over the tree area, and
+returns within milliseconds — the label analysis, visualization candidates,
+control panel and the draw itself all run one frame later, so the browser
+can paint the card instead of appearing frozen for the seconds a large tree
+takes. Every error still throws synchronously from `launch()`
+exactly as before; only the draw is deferred. `viewer.ready` resolves when it
+has run (immediately for a small tree, which stays fully synchronous). Later
+redraws on a big tree — a checkbox, a slider, a search — work the same way:
+they show a "Redrawing" card and run on the next frame, and every redraw
+requested in the same tick collapses into one. Wait on `ready` before reading
+the tree's DOM after `launch()`:
+
+```js
+const viewer = archaeopteryx.launch(container, tree, config);
+await viewer.ready;   // the SVG exists now
+```
+
+The one part the library cannot defer for you is your own parse of a big
+file before `launch()`. `archaeopteryx.busy()` shows the same card for that,
+yields a frame so it paints, runs your work, and removes it:
+
+```js
+archaeopteryx.busy(container, 'Reading ' + name, sizeMb + ' MB', function () {
+    const tree = archaeopteryx.parseTree(name, text);
+    viewer = archaeopteryx.launch(container, tree, config);
+});
+```
+
+Pass `document.body` as the container for a whole-page card; without the
+work function it returns a remover and the yielding is up to you.
+
 One viewer per page: the library keeps its display state in one place, so a
 second launch — into any container — replaces the first. Launching into the
 same container is the supported way to switch trees (the demo pages do
@@ -459,6 +503,14 @@ The parser for a given input is auto-detected (see **The entry points**
 above); the Download menu offers whichever output formats the current tree
 can carry.
 
+Newick and Nexus files usually carry branch support as a bare internal label
+(`)100:0.05`). Archaeopteryx.js recognises those automatically and treats them
+as confidence values, so support-based features work without any setup. If your
+internal labels are clade names rather than support, set
+`internalNumericLabels: 'label'`. Bracketed values (`)[95]:0.05`) are
+always read as confidences; a bracket that is not a number is a comment and is
+ignored.
+
 ### References
 
 1. Felsenstein, J. *PHYLIP (Phylogeny Inference Package)*. Department of
@@ -547,6 +599,11 @@ keep working; it logs a deprecation warning.
 
 ### Still used
 
+Every key below can be tried live in the
+[open-your-own-tree page](https://cmzmasek.github.io/archaeopteryx-js/open.html)'s
+**Expert options** panel, which also emits the resulting config as
+copy-pastable JSON.
+
 | Key | Default | What it does |
 | --- | --- | --- |
 | `collapseControlPanel` | `false` | Open with the control panel collapsed to just its header bar — the same state its own hide/show button toggles. |
@@ -571,8 +628,7 @@ keep working; it logs a deprecation warning.
 | `enableDownloads` | `true` | Offer the download buttons. |
 | `pngExportScale` | `4` | PNG export resolution multiplier. |
 | `nhExportWriteConfidences` | `true` | Write confidences into exported Newick. |
-| `nhConfidenceValuesInBrackets` | `true` | Newick parsing: read `[90]`-style bracketed values as confidences. |
-| `nhConfidenceValuesAsInternalNames` | `false` | Newick parsing: read internal node names as confidence values. |
+| `internalNumericLabels` | `'auto'` | Newick / Nexus parsing: how a bare numeric internal label (`)100:0.05`) is read. `'auto'` reads them as confidence values only when *every* internal label looks like support; `'confidence'` reads every numeric label as one, whatever its value; `'label'` keeps them as names. Replaces `nhConfidenceValuesAsInternalNames` (still accepted, with a warning; its `true` maps to `'confidence'`). |
 | `nodeLabels` | `null` | Custom label-field checkboxes: `{key: {label, description, propertyRef, showButton, selected}}` — each adds a panel checkbox labelling nodes with the named property's value. (Was `launch()`'s sixth positional argument.) |
 | `enableSubtreeDeletion` | `true` | Offer node / subtree deletion in the node menu. |
 | `enableAccessToDatabases` | `true` | Offer the “Access DB” link in the node menu. |
@@ -581,7 +637,8 @@ keep working; it logs a deprecation warning.
 ### Anything else throws
 
 An unrecognised key is an error, whether it was removed in this modernization
-or simply mistyped:
+or simply mistyped (the two deprecated keys below are the exception — they
+warn rather than throw):
 
 ```
 ArchaeopteryxJS: ERROR: removed config key(s) passed to launch:
@@ -593,6 +650,17 @@ ArchaeopteryxJS: ERROR: unknown config key(s) passed to launch: "enableDownlods"
 An ignored key looks like it worked. If you are upgrading, run once and fix
 whatever it names.
 
+### Accepted, with a warning
+
+Two keys are neither current nor removed: they are accepted so an existing
+embed keeps working, and warn on the console. Both concern Newick support
+values.
+
+| Key | What happens |
+|---|---|
+| `nhConfidenceValuesAsInternalNames` | Translated to `internalNumericLabels`. **`true` becomes `'confidence'`, not `'auto'`** — `'auto'` is all-or-nothing and promotes nothing in a tree that mixes clade names with support, so a caller moved to it silently would lose promotions they had. An explicit `internalNumericLabels` always wins. |
+| `nhConfidenceValuesInBrackets` | Retired: ignored. It gated whether `[95]` is read as a confidence, but setting it `false` never reinterpreted the bracket — it *discarded* it, so the option's only effect was to throw support values away. A bracket that is not a number is a Newick comment and was ignored either way, and NHX / BEAST blobs go through a different path. Bracketed values are now always read as confidences. |
+
 ### What replaced the rest
 
 A few of these are worth spelling out, because they are decisions rather than
@@ -1152,9 +1220,18 @@ denominator); information = `(log₂K − H)/log₂K × nonGapFraction`, K = 4 o
 20; consensus = most common non-gap residue, ties alphabetical. The hover
 readout (`forester.msaResidueInfo`, `msaUngappedPosition`) names the residue
 (desktop vocabulary, selenocysteine and pyrrolysine included), its class
-(purine/pyrimidine for bases) and Kyte-Doolittle hydropathy. Scrolling: a
-lazily-created fixed HTML range input plus wheel-over-track, both moving
-`_msaColOffset`; the tree never moves.
+(purine/pyrimidine for bases) and Kyte-Doolittle hydropathy.
+
+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
+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 time axes
 
@@ -1191,6 +1268,31 @@ etc., 69 intervals, frozen) is byte-identical to the desktop's; reference:
 Cohen, K.M., Harper, D.A.T., Gibbard, P.L. & Car, N. (2025, updated),
 Episodes 48: 105-115; www.stratigraphy.org.
 
+Banding ranks (`forester.geoBandRanks(youngMa, oldMa)`, shared with the
+desktop — change both or neither) take the span the tree actually occupies,
+youngest tip to root, not zero to root, so a fossil-only clade bands on its
+own window. A window overlapping one or two Series bands Series over **Stage**
+(the 101 ratified Phanerozoic stages plus the Pridoli, standing in for its own
+span as the printed ICS chart does); wider windows fall through the
+Period/Epoch → Era/Period → Eon/Era ladder, the finest pair that still fully
+covers the range. The overlap test is strict at both ends, so a window that
+merely touches a Series does not count it. A band label is drawn only where it
+fits its cell; a narrow stage keeps its colour and loses its name.
+
+**Floating strips.** The axes and the alignment's conservation/consensus/ruler
+strip live on `_floatGroup`, a sibling of the zoomed tree group that is not
+itself transformed. Each is drawn in tree coordinates as usual and registered
+with `floatStripGroup(cls, top, height)`; `placeFloatingOverlays()` then gives
+it the tree's x and scale but a **sticky** y — `min(tree y, viewport bottom −
+strip)` — so it rides at the tree's bottom edge until that edge would leave
+the viewport and holds there instead. Each carries an opaque backdrop with a
+top rule, so tips panned underneath do not show through. Grid lines, per-node
+age bars and the alignment rows stay in the tree group, being bound to tips or
+spanning the tree's height. Exports re-anchor every strip to the tree, so a
+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.)
+
 ## Node selection
 
 With `enableManualNodeSelection` on, the node menu gains **Select/Deselect Node**
@@ -1204,14 +1306,7 @@ 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.
 
-### The "Submit Selected" button is dormant
-
-There is also a **Submit Selected** button in the source, which would dispatch a
-`submit_selected_nodes_event` on `document` for the surrounding application to
-listen for. **It is not wired up**: the call that would add the button to the
-control panel is commented out, so the button never appears and the event is
-never fired. Poll `getSelectedNodes()` instead.
-
-This is left as it is on purpose, rather than either finished or deleted, until
-there is a reason to decide one way or the other. If you are looking for the
-event because something upstream expects it, that is the reason — say so.
+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.)