archaeopteryx 3.3.0 → 3.4.0

package/README.md

@@ -202,6 +202,42 @@ panel: **rectangular** (root at left), **circular**, and **unrooted** — the
 desktop's equal-angle fan, where each subtree opens a wedge proportional to
 how many tips it holds.
 
+In the rectangular layouts a rooted tree shows a short **stub** branch into
+its root; a tree that declares itself unrooted (phyloXML `rooted="false"`, a
+Nexus `[&U]` tree) shows none, and the circular layout never draws one. A
+subtree view always shows the stub, since a clade has a definite root,
+whatever the branch above it was. When the whole tree is a phylogram and the
+file gives the root a branch length, that branch is drawn to scale instead
+of the stub — except in the **unrooted** display, which draws no root branch
+of any kind, real or stub: there the root is a point of the fan, not the end
+of a branch from nowhere. The root itself wears a circle only for the reasons
+any node does — an event, a search hit, a selection, a visualization.
+
+**Collapsing a clade.** The node menu's **Collapse/Uncollapse** folds an
+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
+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
+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
+program's.
+
+A phylogram carries a **scale bar** at the bottom left: a round number of
+branch-length units (1, 2 or 5 × 10ᵏ, whichever makes the bar about 100 px)
+with its length written above it. It is drawn with the tree, so it zooms and
+exports with it and its label always holds. A cladogram has nothing to
+measure and shows none, and a tree under a time axis leaves the measuring to
+the axis.
+
 In the two radial layouts the zoom row changes meaning, exactly as on the
 desktop: **Y+ / Y− become the plain + / − zoom** (a circle has one diameter;
 the mouse wheel zooms too, and never rotates), **X− / X+ become rotate** (a
@@ -212,6 +248,36 @@ 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).
 
+## Metadata tables
+
+A tree file rarely carries everything known about its tips. A **metadata
+table** beside it does: TSV or CSV, a header row, the first column naming the
+tip and every other column a piece of data. On the [open page](https://cmzmasek.github.io/archaeopteryx-js/open.html)
+drop, choose or paste the table before or after the tree — a table pasted
+first waits for the tree; one added while a tree is showing joins it and the
+view relaunches — and the toolbar says how many columns joined how many tips,
+with the rows that matched no tip and the tips without a row a hover away.
+
+Each column becomes a node property (`meta:` plus the header, so "Collection
+Date" comes back as `Collection Date` in every menu; a header that already
+reads as `namespace:name` is kept as it is). From there nothing is special:
+the columns are offered for **Color-by** and **Shape** by the same rules as
+any property, with the same legends; they are **search** fields, typed
+numeric when every filled cell is a number; they appear in the **node data**;
+and they are written into a phyloXML export, so a saved tree keeps them.
+Tip names are matched exactly, then case-insensitively; empty cells add
+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.
+
+Embedders do the same in two lines, before `launch()`:
+
+```js
+const tree = archaeopteryx.parseTree(name, treeText);
+const report = forester.joinMetadataTable(tree, tableText);  // {columns, tips, matchedTips, unmatchedTips, unmatchedRows, properties}
+archaeopteryx.launch('#tree', tree, config);
+```
+
 ## Searching
 
 Two search boxes (A and B), each with its own **field** menu (built from what
@@ -232,12 +298,62 @@ press centres the previous / next hit in the viewport, wrapping around.
 
 ## Keyboard
 
-Deliberately minimal: **Esc** or **Home** resets the view, **O** cycles the
-overview between corners, **PageUp / PageDown** change the font size — and
-the **mouse wheel** zooms (Shift: vertical only; Shift+Alt: horizontal;
-Ctrl+Shift: font size). Everything else is a button; the old Alt+letter
-combos are gone (macOS labels that key Option and types glyphs with it).
-Nothing fires while the cursor is in a text box.
+The same actions on every platform; only the modifier differs: **⌘** on
+macOS, **Ctrl** on Windows and Linux. **⌘/** (Ctrl+/) shows this list in
+the viewer, drawn for the platform you are on; the About box links to it
+too.
+
+| macOS | Windows / Linux | Does |
+|---|---|---|
+| ⌘0 | Ctrl+0 | Fit the tree to the window |
+| ⌘+ / ⌘− | Ctrl++ / Ctrl+− | Zoom in / out |
+| ⌘⇧↑ / ⌘⇧↓ | Ctrl+Shift+↑ / ↓ | Zoom in / out vertically |
+| ⌘⇧→ / ⌘⇧← | Ctrl+Shift+→ / ← | Zoom in / out horizontally (circular: rotate) |
+| ⌘⇧E | Ctrl+Shift+E | Expand vertically until the labels fit |
+| ⌘⇧L | Ctrl+Shift+L | Next layout: rectangular, circular, unrooted |
+| ⌘⇧D | Ctrl+Shift+D | Next display type: phylogram, aligned, cladogram |
+| ⌘⇧X | Ctrl+Shift+X | Time axis on / off |
+| ⌘⇧O | Ctrl+Shift+O | Ladderize |
+| ⌘⇧U | Ctrl+Shift+U | Uncollapse every clade |
+| ⌘F | Ctrl+F | Go to the search box |
+| ⌘G / ⌘⇧G | Ctrl+G / Ctrl+Shift+G | Next / previous search hit |
+| ⌘⇧< / ⌘⇧> | Ctrl+Shift+< / > | Previous / next tree of a multi-tree file |
+| ⌘/ | Ctrl+/ | The shortcut list |
+| Esc or Home | Esc or Home | Back to the whole tree, the launch view |
+| O | O | Move the overview to the next corner |
+| Page Up / Page Down | PageUp / PageDown | Larger / smaller font |
+
+Mouse wheel, also the same everywhere: plain zooms both axes, **Shift**
+vertical only, **Shift+Alt** (macOS: Shift+Option) horizontal only,
+**Ctrl+Shift** the font size. Inside a text box only the combos that cannot
+interfere with typing fire (fit, zoom, search, the list); the plain keys
+never do. The letters follow the desktop Archaeopteryx where it has the
+action (its Alt+O, Alt+U, Alt+E and ⌘0, ⌘G). There is no key for
+re-rooting, by decision. On Linux, Ctrl+Shift+U inside a text field is the
+desktop's Unicode entry: it stays with the text field there, as it should.
+
+## Sharing a view
+
+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
+`#` 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
+keeps the view in the hash too, so the same file reopened at that address
+comes back as you left it. Zoom, pan, the legend's position and the node
+selection are not part of a view; a shared view opens fitted.
+
+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,
+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
+the tree it was made on; a key a view leaves out keeps its current value,
+and anything that does not fit the tree is skipped.
 
 ## Protein domain architectures
 
@@ -400,6 +516,13 @@ const viewer = archaeopteryx.launchArchaeopteryx(container, fileName, data, conf
 const tree = archaeopteryx.parseTree(fileName, data);
 const viewer = archaeopteryx.launch(container, tree, config);
 
+// every tree the file holds (a Nexus TREES block, a multi-tree Newick,
+// several phylogenies): launch() takes the list, shows the first, and
+// the panel gets a picker for the rest
+const trees = archaeopteryx.parseTrees(fileName, data);
+const viewer = archaeopteryx.launch(container, trees, config);
+viewer.showTree(1);   // also viewer.getTreeIndex(), viewer.getTreeCount()
+
 // later, e.g. when an SPA removes the view:
 viewer.destroy();
 ```
@@ -489,9 +612,13 @@ The parser is picked from the data and the `location`: content starting with
 `#NEXUS` (or a name ending in `.nex`/`.nexus`) is read as Nexus, JSON content
 (or a name ending in `.json`) as an **Auspice/Nextstrain v2** `dataset.json`,
 a name ending in `xml` as phyloXML, anything else as New Hampshire (Newick).
-A Nexus file shows its **first** tree; a protein/DNA/RNA characters matrix in
-the file (sequential or interleaved) lands on the tips as an aligned
-`mol_seq`, so the alignment track appears just as it does for phyloXML.
+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
+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.
 
 An Auspice dataset opens on the **time view** (branch lengths from `num_date`
 differences; a divergence-only build falls back to `div` differences): the
@@ -531,6 +658,7 @@ a popup any more, and nothing fails silently.
 | **Auspice / Nextstrain** `dataset.json` (v2) | in | Phylodynamic builds: sampling dates and their confidence, cumulative divergence, and discrete traits (country, clade, host, ...) with their posterior distributions. | [5] |
 | **BEAST** / BEAST 2 / TreeAnnotator annotations | in (embedded in Newick/Nexus) | `[&posterior=...,height_95%_HPD={lo,hi},rate=...]`-style blobs: posterior clade support, node-age confidence intervals, per-branch rates and other traits. FigTree's `!color` is read the same way. | [6, 7] |
 | **MrBayes** annotations | in (embedded in Newick/Nexus) | `prob=`/`prob.stddev=` blobs: posterior-probability clade support. | [8] |
+| **Metadata table** (`.tsv`, `.csv`) | in (beside a tree) | A header row and one row per tip, the first column naming the tip: every other column is joined onto the tips as a property, so it is offered for Color-by and Shape, searched, shown in the node data and written into phyloXML exports. See [Metadata tables](#metadata-tables). | — |
 | **FASTA** | out | The molecular sequence(s) of the selected tip(s), or every sequence the tree carries. Offered in the Download menu only when the tree actually carries molecular sequences (aligned or not). | [9] |
 | SVG · PNG · vector PDF | out | A snapshot of the drawn tree for publication or further editing — vector (SVG, PDF) or raster (PNG). General-purpose graphics formats, not phylogenetic data, so no literature reference applies. | — |
 
@@ -623,7 +751,7 @@ shorter than the dot itself stays clean.
 One object, passed as the third argument. It is optional, and the best
 configuration is usually an empty one — almost everything that used to be
 configured is now read off the tree (see **Intelligent pre-sets** above). The
-twenty-eight keys below are the ones no tree can answer for you.
+thirty keys below are the ones no tree can answer for you.
 
 There used to be two objects, `options` and `settings`, split by whether the
 user could also change the value from the control panel. That was a fact about
@@ -659,6 +787,8 @@ copy-pastable JSON.
 | `showSupportDots` | `false` | Open with the Support Dots marks on (the checkbox appears whenever the tree has confidences). |
 | `supportDotMinimum` | `95` | Support Dots threshold, as a percentage. On a tree whose confidences top out at 1 (posterior probabilities) it is read on the 0–1 scale, so the default means ≥ 0.95 there and ≥ 95 on a bootstrap tree. |
 | `searchAinitialValue` | `null` | Prefill search box A. |
+| `view` | `null` | Open straight into a saved view — the object `getViewState()` returns, or `decodeViewState()` reads from a URL hash: layout, display type, labels, colours, searches, the clade and the collapsed clades, sizes. See **Sharing a view**. |
+| `onViewChange` | `null` | `function (state, encoded)`, called once per settled redraw when the view changed: `state` as `getViewState()` returns it, `encoded` its hash-ready string. The demo pages write it into the URL. |
 | `searchBinitialValue` | `null` | Prefill search box B. |
 | `enableVisualizations` | `true` | Offer the Color / Shape visualizations (which fields they cover is decided from the tree). |
 | `initialVisualization` | `null` | The visualization to open with, by its Color-menu name (e.g. `'Host'`; case-insensitive). A name the tree cannot honour logs a console warning and falls back to the automatic choice, so a site-wide value is safe on trees without that field. Default: Archaeopteryx.js picks the most informative field itself. |
@@ -1241,7 +1371,9 @@ labels shown AND, in a radial layout, radial rather than upright labels.
 Scale: one factor for the tree, `f = W_eff / Lmax × 0.9` px per residue.
 `W` (the track width) starts at `0.25 × viewport width`; `d+` / `d−` scale it
 by 1.2 / 0.8 and stop at 2000 / 20. `W_eff = W` in the rectangular layout,
-`min(W, 0.2 × radius)` in the radial ones. `Lmax` is the longest architecture
+a width of the radial layouts' own, which starts at `min(W, 0.2 × radius)`
+and is then stepped by the same buttons (the desktop caps the drawn width at
+that fifth of the radius instead). `Lmax` is the longest architecture
 in the displayed tree, counting every domain whatever its E-value, so the
 threshold never rescales. The rectangular layout reserves `20 + W + 10` px
 from `_w` past the label reservation (`_domainReserve`, counted wherever `_w`

package/archaeopteryx.d.ts

@@ -73,6 +73,9 @@ export interface ArchaeopteryxConfig {
     nhConfidenceValuesInBrackets?: boolean;
     nhExportWriteConfidences?: boolean;
     nodeLabels?: Record<string, NodeLabelSpec> | null;
+    /** Called once per settled redraw when the view changed: the state as
+     * getViewState() returns it, and its hash-ready string. */
+    onViewChange?: ((state: ViewState, encoded: string) => void) | null;
     pngExportScale?: number;
     rootOffset?: number;
     searchAinitialValue?: string | null;
@@ -82,27 +85,103 @@ export interface ArchaeopteryxConfig {
     showTimeAxis?: boolean;
     supportDotMinimum?: number;
     timeAxisGrid?: boolean;
+    /** Open straight into a view (getViewState / decodeViewState). */
+    view?: ViewState | null;
     visualizationsLegendXpos?: number;
     visualizationsLegendYpos?: number;
     zoomToFitUponWindowResize?: boolean;
 }
 
+/** One search box in a view: the field by its menu label, the mode, the
+ * value (and the range's second value). */
+export interface ViewSearch {
+    field?: string;
+    mode?: string;
+    value: string;
+    value2?: string;
+}
+
+/** A view of a tree as the control panel left it: what getViewState()
+ * returns, what the config's view key and applyViewState() take, and what
+ * encodeViewState() / decodeViewState() turn into a URL-hash string and
+ * back. Every key is optional; a key left out keeps its current value,
+ * except searchA / searchB, which an absent key clears. Nodes (subtree,
+ * collapsed) are named by their launch-time preorder index. */
+export interface ViewState {
+    /** Which tree of a multi-tree launch (0-based). */
+    tree?: number;
+    layout?: Layout;
+    display?: 'phylogram' | 'aligned' | 'cladogram';
+    /** The ladderize direction applied. */
+    order?: 'asc' | 'desc';
+    /** Midpoint re-rooted. */
+    root?: 'midpoint';
+    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,
+     * supportDots, shortNames, autoHide, visualizations, visualStyles, and
+     * custom:<key> for a nodeLabels checkbox. */
+    show?: string[];
+    font?: number;
+    node?: number;
+    branch?: number;
+    /** Radial rotation in button presses (pi/32 each). */
+    rotation?: number;
+    horizontalLabels?: boolean;
+    msa?: boolean;
+    domains?: boolean;
+    domainLabels?: 'none' | 'domains' | 'legend';
+    domainGlow?: boolean;
+    domainEvalue?: number;
+    timeAxis?: boolean;
+    timeGrid?: boolean;
+    searchA?: ViewSearch;
+    searchB?: ViewSearch;
+    combine?: 'and' | 'or';
+    matchCase?: boolean;
+    inverse?: boolean;
+}
+
 /** What launch() returns: the per-viewer surface an embedder needs after
  * launching. */
 export interface ViewerHandle {
     /** The nodes the user has selected via the node menu (when
      * enableManualNodeSelection is on). */
     getSelectedNodes(): PhylogenyNode[];
+    /** How many trees the launch holds: one, or every tree the file held
+     * (launch() with the array parseTrees returns). */
+    getTreeCount(): number;
+    /** Which of them is shown (0-based). */
+    getTreeIndex(): number;
+    /** Shows another tree of the launch in the same container under the
+     * same config; it opens fresh. Returns the handle for the new viewer. */
+    showTree(index: number): ViewerHandle;
+    /** The view as the panel left it (see ViewState). */
+    getViewState(): ViewState;
+    /** Opens a view on the running viewer; a view of another tree of the
+     * launch relaunches into that tree. */
+    applyViewState(state: ViewState): void;
     /** Unmounts the viewer completely: the DOM inside the container, the
      * body-level pieces, the window resize listener and every page-level
      * key/wheel handler. A later launch() works normally. */
     destroy(): void;
 }
 
+/** How bare numeric internal labels of a Newick / Nexus tree are read:
+ * 'auto' decides per tree, 'confidence' takes every one as a support
+ * value, 'label' keeps them as names. */
+export type InternalNumericLabels = 'auto' | 'confidence' | 'label';
+
 export interface Archaeopteryx {
     /** Launch the viewer into a container (a CSS selector or the element
-     * itself; an unresolvable container throws). Exactly three arguments. */
-    launch(container: string | Element, tree: Phylogeny, config?: ArchaeopteryxConfig): ViewerHandle;
+     * itself; an unresolvable container throws). Exactly three arguments.
+     * A tree, or every tree of a file (parseTrees): the first is shown and
+     * the control panel gets a picker for the others. */
+    launch(container: string | Element, tree: Phylogeny | Phylogeny[], config?: ArchaeopteryxConfig): ViewerHandle;
 
     /** Parse-and-launch in one step. Fetch the file content yourself; the
      * fileName picks the parser (extension; content is sniffed too).
@@ -112,23 +191,34 @@ export interface Archaeopteryx {
 
     /** Parse tree data, auto-detecting the format from content and fileName:
      * Nexus (#NEXUS / .nex / .nexus), Auspice/Nextstrain v2 JSON ({ / .json),
-     * phyloXML (*xml), otherwise New Hampshire (Newick). */
+     * phyloXML (*xml), otherwise New Hampshire (Newick). The FIRST tree the
+     * data holds; parseTrees returns them all. */
     parseTree(fileName: string, data: string,
-        nhConfidenceValuesInBrackets?: boolean,
-        nhConfidenceValuesAsInternalNames?: boolean): Phylogeny;
+        internalNumericLabels?: InternalNumericLabels): Phylogeny;
+    /** Every tree the data holds, in file order: a Nexus TREES block, a
+     * Newick text with one tree per ';', a phyloXML with several
+     * phylogenies (an Auspice dataset is one tree). Hand the array to
+     * launch(). */
+    parseTrees(fileName: string, data: string,
+        internalNumericLabels?: InternalNumericLabels): Phylogeny[];
 
     parsePhyloXML(data: string): Phylogeny;
     parseNewHampshire(data: string,
-        confidenceValuesInBrackets?: boolean,
-        confidenceValuesAsInternalNames?: boolean): Phylogeny;
-    /** A Nexus file can hold several trees; the FIRST is returned. */
+        internalNumericLabels?: InternalNumericLabels): Phylogeny;
+    /** A Nexus file can hold several trees; the FIRST is returned
+     * (parseTrees returns them all). */
     parseNexus(data: string,
-        confidenceValuesInBrackets?: boolean,
-        confidenceValuesAsInternalNames?: boolean): Phylogeny;
+        internalNumericLabels?: InternalNumericLabels): Phylogeny;
     parseAuspiceJson(data: string | object): Phylogeny;
 
     /** Module-level twin of the handle's getSelectedNodes. */
     getSelectedNodes(): PhylogenyNode[];
+
+    /** A view as a "key=value&..." string for a URL hash, and back. decode
+     * accepts a leading '#', ignores what it does not know, and returns
+     * null for nothing. */
+    encodeViewState(state: ViewState): string;
+    decodeViewState(text: string | null | undefined): ViewState | null;
 }
 
 export const archaeopteryx: Archaeopteryx;