archaeopteryx 3.16.0 → 3.18.0

package/README.md

@@ -630,7 +630,8 @@ 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.
+rather than padding them into an alignment that does not exist, and the
+Nexus entry of the Download menu says so before you choose it.
 
 ## Heat maps
 
@@ -721,25 +722,55 @@ Ages (`unit="mya"` and friends, or values that look like ages) get the
 **geologic axis**: two rows of ICS intervals in their official colours —
 Period over Epoch for most trees, coarser pairs for Precambrian-deep ones —
 plus a "Ma before present" ruler. Years (`unit="year"`, or values that look
-like calendar years) get a labelled **calendar axis** instead. The tree's
-layout itself never changes: time is an overlay calibrated by the dates, so
-it also works for a fossil-only tree, where the axis simply stops at the
-youngest tip and labels that age (the ammonite demo ends at the K-Pg, 66).
+like calendar years) get a labelled **calendar axis**. The layout itself
+never changes: time is an overlay calibrated by the dates, so it also works
+for a fossil-only tree, where the axis stops at the 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, 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
-"Time axis grid lines") adds faint vertical lines behind the tree at the
-fine geologic-interval boundaries or the calendar year ticks, so a node's
-position can be read against the axis.
+nodes, and on tips whatever the axis says the range means — on geologic
+time a fossil's observed range, sepia **FAD/LAD bars with end caps**; on
+calendar time the uncertainty of a **sampling date**, drawn like an age bar,
+slimmer, and only when it has a width. Node tooltips show the date. The
+**Time Axis** checkbox under Display Data toggles everything; the axis needs
+a phylogram and the rectangular or circular layout. In **circular** the bars
+run along each node's spoke — on through the centre where a range reaches
+back past the root's own age — the ruler runs out from the root along the
+gap between the last tip and the first, turning with the tree, and a
+geologic axis lays its intervals down as coloured rings. **Time Grid** (off
+by default) adds faint lines, or rings, at the fine interval boundaries or
+the calendar years.
+
+### Time | Div
+
+Where a tree can be laid out by **time** and by **divergence**, a
+**Time | Div** switch appears beside the phylogram buttons (⌘⇧X). Two kinds
+of tree state a divergence: an Auspice build, on its nodes (`div`), and a
+BEAST clock-model tree, as a clock `rate` on every branch — its branch
+lengths are time, and its divergence is each length times its rate, in
+substitutions per site. A tree with neither has no second layout. A rate or
+a recorded divergence is a plain decimal number (`0.01abc` is not one); a
+negative divergence is a value, drawn at 0.
+
+The switch is offered only when both layouts can state **every** branch —
+every node dated, every branch with a length, and divergence on every node
+or a rate on every branch — and each picture has some depth. A value the
+file states counts, whether zero or negative; where one is missing the
+switch is withheld rather than a branch drawn at a length the file never
+gave. Whether the two pictures differ is not asked: a strict clock's
+divergence is its time at another scale, and it is offered like any other.
+
+Back in Time the tree has exactly the lengths it arrived with. A span that
+runs backwards — a child dated before its parent, which real Nextstrain
+builds state — keeps its sign, and is drawn at length 0 like any negative
+branch length. The switch acts on the whole tree, also from a subtree view,
+and a node deleted meanwhile leaves the branch that takes its place spanning
+what both spanned, in either layout. The time axis is hidden while the
+branches show divergence. Each layout stamps the tree's `branch_length_unit`
+(`subs/site`; for time the dates' unit, or `time`), so a tree saved while
+Div is on screen says so and opens again showing divergence. All of this is
+shared with the desktop.
 
 # forester.js
 forester.js is a general suite for dealing with phylogenetic trees.
@@ -939,16 +970,21 @@ 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
-calendar time axis and node-age bars come from `num_date` and its confidence
-interval, and every trait (country, host, clade, ...) becomes a
+An Auspice dataset has no branch lengths of its own, so it opens in the
+metric it states completely: the **time view** when every node states a
+`num_date` (branch lengths are the `num_date` differences, sign kept), else
+the divergence view when every node states a `div`, else time if any node is
+dated. In the time view the calendar time axis and node-age bars come from
+`num_date` and its confidence interval, and every trait (country, host,
+clade, ...) becomes a
 `nextstrain:<trait>` node property — so Color-by, search and the node dialog
 pick them up. Both metrics are retained, and
 `forester.applyTimeBranchLengths(phy)` /
 `forester.applyDivergenceBranchLengths(phy)` /
-`forester.hasTimeAndDivergence(phy)` are the plumbing for a future
-time↔divergence display toggle.
+`forester.hasTimeAndDivergence(phy)` are the plumbing behind the
+**Time | Div** switch. The two `apply` functions answer `true` when they
+laid the tree out, and `false` — leaving every branch length as it was —
+when their layout cannot state every branch.
 
 **BEAST-style and NHX annotations** in Newick/Nexus input are always parsed
 (they used to be discarded): in a `[&key=value,...]` blob — as written by
@@ -1004,12 +1040,62 @@ a popup any more, and nothing fails silently.
 | **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. | — |
+| SVG · PNG · vector PDF | out | The drawn tree for publication or further editing — vector (SVG, PDF) or raster (PNG), either as shown on screen or the whole tree at full size (see [Downloads](#downloads)). General-purpose graphics formats, not phylogenetic data, so no literature reference applies. | — |
 
 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.
 
+### Downloads
+
+The panel's **Download** section (folded until you open it) holds the choices
+every download shares, and its **Download…** button opens the format menu,
+grouped as Graphics, Tree and Tip data. Each entry says what that format keeps — phyloXML everything the
+tree carries, Newick only names, branch lengths and support — and the Nexus
+entry says, before you pick it, whether the file will carry the alignment or,
+when the sequences are of unequal length, why it cannot.
+
+* **Name** — the file name; each format adds its own extension (a typed
+  `.svg` or `.tre` is not doubled). It starts as the tree's name.
+* **Graphics: As shown / Full size** — what SVG, PDF and PNG draw. *As shown*
+  is the window: the part of the tree in view, at the current zoom. *Full
+  size* (the default) is the whole tree, re-laid-out large enough that no tip
+  name has to be hidden — in rows in the rectangular layout, around the ring in
+  the circular one — and cropped to the drawing, with the legends (colour,
+  shape, domains, the heat-map ring's scale) stacked beside the tree rather
+  than over it. The window itself is left exactly as it was. An unrooted fan
+  is enlarged only while that still frees names: tips on very short branches
+  can collide at any size. An alignment track is drawn as its window, the
+  columns in view, in a full-size figure too: a genome-length alignment drawn
+  whole would be hundreds of thousands of cells.
+* **PNG: 2× / 4× / 8×** — the image's resolution relative to the screen
+  (`pngExportScale` sets the starting choice, snapped to one of the three). A browser caps how large a
+  canvas it will paint; past that the PNG comes out at the largest scale it can
+  paint, with a console warning, rather than blank.
+* **Copy Newick** puts the tree on the clipboard, exactly as the Newick
+  download writes it.
+* **Copy PNG** puts the picture on the clipboard, drawn as the Graphics and PNG
+  choices say — ready to paste into a Word document or a slide. It needs a
+  secure page (https, or localhost) and canvg, and is offered only where both
+  are there.
+
+**In a subtree, and with clades collapsed.** Every download follows the tree
+you are looking at. In a **subtree** the files hold the subtree only — the
+menu's Tree and Tip data groups say so ("subtree, 19 of 50 tips"), and
+phyloXML and Nexus name it after the tree, marked "(subtree)"; the subtree is
+written as a rooted tree of its own, its root keeping the branch that leads
+into it. A **collapsed** clade is how the tree is drawn, not what it holds:
+the graphics draw it collapsed, as on screen, and every file writes it in
+full.
+
+**TSV** (under Tip data) writes every tip's data as a table, one row per tip in
+the order drawn: the node menu's **Download Ext. Node Data** for the whole
+tree, with the same columns, and a table that joins back onto the tree as
+[metadata](#metadata-tables).
+
+A full-size PDF taller or wider than 200 inches (14,400 pt, the PDF page
+limit) is scaled onto the largest page; it is vector, so nothing is lost.
+
 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
@@ -1094,8 +1180,8 @@ 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 —
-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
+plus Search, and folds the ones that are adjustments to make later: View &
+Tools, 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, and dragging
@@ -1141,7 +1227,8 @@ 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.
+the same size always drops the same marks — on screen and in an *As shown*
+export. A *Full size* figure is drawn larger, so it has room to keep more.
 
 **The Auto-hide Labels toggle lights up while it is taking something away**,
 and its tooltip says what. The switch governs three rules and the light asks
@@ -1274,7 +1361,7 @@ copy-pastable JSON.
 | `visualizationsLegendXpos` | `254` | Legend position, x. |
 | `visualizationsLegendYpos` | `30` | Legend position, y. |
 | `enableDownloads` | `true` | Offer the download buttons. |
-| `pngExportScale` | `4` | PNG export resolution multiplier. |
+| `pngExportScale` | `4` | The PNG resolution the Download section starts on: 2, 4 or 8 (any other value is snapped to the nearest, with a console warning). |
 | `nhExportWriteConfidences` | `true` | Write confidences into exported Newick. |
 | `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.) |
@@ -1385,11 +1472,11 @@ All 118 of them, alphabetically:
 | `labelColorDefault` | The default label colour is fixed. |
 | `minBranchLengthValueToShow` | No longer configurable. |
 | `minConfidenceValueToShow` | No longer configurable. |
-| `nameForFastaDownload` | Download names follow `treeName`. |
-| `nameForNhDownload` | Download names follow `treeName`. |
-| `nameForPhyloXmlDownload` | Download names follow `treeName`. |
-| `nameForPngDownload` | Download names follow `treeName`. |
-| `nameForSvgDownload` | Download names follow `treeName`. |
+| `nameForFastaDownload` | Download names follow `treeName`, or the Download section's Name field. |
+| `nameForNhDownload` | Download names follow `treeName`, or the Download section's Name field. |
+| `nameForPhyloXmlDownload` | Download names follow `treeName`, or the Download section's Name field. |
+| `nameForPngDownload` | Download names follow `treeName`, or the Download section's Name field. |
+| `nameForSvgDownload` | Download names follow `treeName`, or the Download section's Name field. |
 | `nhExportReplaceIllegalChars` | Always on; Newick cannot carry those characters. |
 | `nodeLabelGap` | The label gap is fixed. |
 | `nodeSizeDefault` | Node size is fixed; the Node size slider changes it. |
@@ -2181,11 +2268,15 @@ loops). Calibration: the **largest** date value is the root age (geologic)
 or the present (calendar) — no unit conversion is done, so a Ga-valued tree
 is misbanded exactly as on the desktop.
 
-Rendering (phylogram + rectangular only; the layout never changes): age→x is
-`anchorX + (anchorAge − age) × corr` with `corr` the branch-length scale's
-slope, anchored at the **deepest dated tip** rather than the root — the root
-and its direct children carry a synthetic half-average branch length, which
-would shift every band. The geologic axis draws
+Rendering (phylogram, rectangular or circular; the layout never changes):
+age→x is `anchorX + (anchorAge − age) × corr` with `corr` the branch-length
+scale's slope, anchored at the **deepest dated tip** rather than the root,
+so the root's own branch, drawn to scale where the file states one, shifts
+no band. In circular the same arithmetic runs along each spoke: a bar is a
+segment of its node's spoke (a bound past the root's estimate a negative
+radius, continued through the centre), the ruler a ray along the gap between
+the last tip and the first, the grid and the geologic intervals rings. The
+geologic axis draws
 `forester.geoBandRanks(rootAge)` — the finest of Period/Epoch, Era/Period,
 Eon/Era that still covers the range — as two 13 px rows of ICS intervals
 (official colours; ink by the same luminance rule), clipped to

package/archaeopteryx.d.ts

@@ -79,6 +79,8 @@ export interface ArchaeopteryxConfig {
     /** 'compact' tightens the control panel's spacing and narrows it (the
      * tree's left margin follows). The same controls, nothing hidden. */
     panelDensity?: 'comfortable' | 'compact';
+    /** The PNG resolution the Download section starts on, snapped to its
+     * 2x, 4x or 8x. */
     pngExportScale?: number;
     rootOffset?: number;
     searchAinitialValue?: string | null;