archaeopteryx 3.6.1 → 3.8.0

package/README.md

@@ -322,6 +322,39 @@ a Newick or Nexus download never puts one where a support value goes.
    gene families. *PLOS ONE*, 15(5), e0232950.
    <https://journals.plos.org/plosone/article?id=10.1371/journal.pone.0232950>
 
+## Representative tips
+
+A large tree often holds many near-identical tips. The tool row's
+**representative tips** button thins them out the way the desktop
+Archaeopteryx's Tools → Select Representative Tips does: the tips are grouped
+into the largest clades whose tips are all close to each other, and one tip of
+each group is kept. Distance is patristic, the sum of the branch lengths on
+the path between two tips; in a tree without branch lengths it counts edges.
+
+The dialog takes either a **distance cutoff**, and no two tips of a group are
+then farther apart than it, or a **target number** of representatives, for
+which the cutoff giving the nearest count the tree allows is used (a tie keeps
+more tips; the count reached is reported). A distance cutoff needs branch
+lengths. The tip kept is the group's **most central** one (the medoid, with
+the smallest summed distance to its group-mates) or its **most divergent** one
+(the longest terminal branch). Tips that are selected or found by a search can
+be kept whatever their group: they stand in for their group's representative,
+so more tips than the target may stay.
+
+The tips kept show as search A's hits, with its colour, hit count and
+step-through, and a summary offers **Create tree**: a tree of only those tips,
+added to the tree picker and opened drawn as the tree was — the same layout
+and display type (phylogram, aligned or cladogram). It is named after the
+tree and the count, as in
+`mammals_233reps`, and its description says how it was made. An internal node
+left with one child is replaced by that child, whose branch gains the node's
+length; the new root keeps the original root's own branch length. The original
+tree is not changed.
+
+The grouping and the tips kept are the desktop's: they match its own results
+on 129 generated trees in 5,666 settings (`test/fixtures/rep-contract.tsv`,
+made by running the desktop's code).
+
 ## Metadata tables
 
 A tree file rarely carries everything known about its tips. A **metadata
@@ -428,6 +461,12 @@ 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.
 
+In a file holding **several trees** each tree keeps its own view, so moving
+between them with the picker brings each tree back as you had it (see
+**Reading trees** below). The hash holds the view of the tree on screen, so
+a link opens that tree the way it looks; the other trees' views last as long
+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
@@ -508,7 +547,12 @@ youngest tip and labels that age (the ammonite demo ends at the K-Pg, 66).
 
 Nodes with a date **range** (`minimum`/`maximum` — minimum is the younger
 bound) draw uncertainty bars: translucent blue **HPD age bars** on internal
-nodes, sepia **fossil-range (FAD/LAD) bars with end caps** on tips. Node
+nodes, and on tips whatever the axis says the range means. On **geologic**
+time it is a fossil's observed range: sepia **fossil-range (FAD/LAD) bars with
+end caps**. On **calendar** time it is the uncertainty of a **sampling date**
+— a virus sample dated only to its month or year — drawn like an age bar,
+slimmer, and only when it has a width: a tip dated to the day draws nothing.
+Node
 tooltips show the date. The **Time Axis** checkbox under Display Data toggles
 everything; the axis needs a phylogram (branch lengths carry the time) and
 the rectangular layout. **Time Grid** (off by default, like the desktop's
@@ -702,8 +746,15 @@ 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, nothing collapsed, the way a new tab
-does on the desktop. A protein/DNA/RNA characters matrix in a Nexus file
+between them (also ⌘⇧< / ⌘⇧>). **Each tree is its own workspace:** you leave
+a tree as you had it — layout, display type, labels, colours, sizes, tracks,
+both searches, the clade you switched to and the ones you collapsed — and it
+comes back that way. A tree you have not opened yet starts on its own
+presets, read from its own content, in the layout and sizes you are already
+using: stepping through ten trees of one file keeps them all circular, while
+each still labels and colours itself its own way. Zoom and pan are not kept
+(a tree opens fitted), and the views last as long as the page.
+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.
 
@@ -725,9 +776,34 @@ BEAST, BEAST 2, TreeAnnotator, FigTree and MrBayes — `posterior`, `prob`
 (median/mean) with its `95%_HPD` (or range) becomes the node date the age
 bars draw, FigTree's `!color` becomes the branch colour, and every other
 field (`rate`, traits, ...) becomes a `beast:<key>` node property for
-Color-by and search. Classic `[&&NHX:...]` tags map to their phyloXML
+Color-by and search (`mutations`, `mcc` and FigTree's `!`-prefixed display
+directives are always text, never a gradient). **TreeTime**'s trees open as
+what they are: its `timetree.nexus` carries dates only as `date=` annotations,
+and those become node dates — calendar axis and all — where the date
+differences reproduce the branch lengths, which is true of the time tree and
+not of `divergence_tree.nexus`, though both carry the same annotations. Its
+annotations land as `treetime:<key>` rather than `beast:<key>`, and its
+`auspice_tree.json` opens as the Auspice dataset it is. FigTree's colour on a **taxon** — `'name'[&!color=...]` in the
+TAXLABELS block — is that tip's **label** colour, carried as the desktop's
+`style:font_color` property and drawn by Visual Styles. A number is a plain
+decimal with an optional exponent: `0x1A` and `3f` are text.
+**Auspice's "download Nexus"** annotations land where the
+Auspice JSON reader puts the same dataset, so one Nextstrain build opens the
+same way in either format: `num_date` is the node's date in years (and a
+`nextstrain:num_date` property), `num_date_CI={lo,hi}` its interval — on a tip
+too, where it is the sampling-date uncertainty — and `div` a
+`nextstrain:div` property — but only on a tree that is actually time-scaled,
+since Auspice writes the same annotations on its divergence tree: where the
+year differences do not reproduce the branch lengths the dates stay properties
+and no calendar axis is drawn. Inside an annotation a quote opens a string
+only where a value starts, so a bare `country=Côte d'Ivoire` is one field with
+an apostrophe in it. Classic `[&&NHX:...]` tags map to their phyloXML
 equivalents (`S=` taxonomy, `T=` taxonomy id, `B=` support, `D=`
-duplication/speciation event, `GN=`/`AC=` sequence name/accession). Plain
+duplication/speciation event, `GN=`/`AC=` sequence name/accession), read as
+the desktop reads them: unquoted whitespace is formatting noise (`S=Homo
+sapiens` is `Homosapiens`), a quoted value keeps its content
+(`S="Homo sapiens"` is `Homo sapiens`), and the quotes themselves are never
+part of the value. Plain
 `[number]` brackets keep their old meaning (confidence values).
 
 Both entry points **throw** on bad input — an undefined or empty tree, an
@@ -833,6 +909,21 @@ 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.
 
+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 —
+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
+also start the whole panel tighter and narrower with
+[`panelDensity: 'compact'`](#configuration), or collapsed to its header bar
+with `collapseControlPanel`.
+
 ## Configuration
 
 One object, passed as the third argument. It is optional, and the best
@@ -857,6 +948,7 @@ 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. |
+| `panelDensity` | `'comfortable'` | `'compact'` tightens the control panel's spacing and narrows it from 214 to 196px, with the tree's left margin following. The same controls, nothing hidden — for a host page that has little room to give. |
 | `enableDynamicSizing` | `true` | Size the tree to its container, and follow window resizes. |
 | `displayWidth` | `800` | Width — only when dynamic sizing is off. |
 | `displayHeight` | `600` | Height — only when dynamic sizing is off. |

package/archaeopteryx.d.ts

@@ -76,6 +76,9 @@ export interface ArchaeopteryxConfig {
     /** 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;
+    /** 'compact' tightens the control panel's spacing and narrows it (the
+     * tree's left margin follows). The same controls, nothing hidden. */
+    panelDensity?: 'comfortable' | 'compact';
     pngExportScale?: number;
     rootOffset?: number;
     searchAinitialValue?: string | null;
@@ -158,7 +161,9 @@ export interface ViewerHandle {
     /** 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. */
+     * same config: as you left it, or -- a tree not opened yet -- on its own
+     * presets in the current layout and sizes. Returns the handle for the
+     * new viewer. */
     showTree(index: number): ViewerHandle;
     /** The view as the panel left it (see ViewState). */
     getViewState(): ViewState;