archaeopteryx 3.21.0 → 3.23.0

package/README.md

@@ -24,7 +24,7 @@ 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)
+* [Auspice / Nextstrain JSON (Time | Div, Clock plot)](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)
 * [Flavivirus mature peptides (10 trees)](https://cmzmasek.github.io/archaeopteryx-js/demo.html?tree=flavivirus)
@@ -33,6 +33,7 @@ config key live and shows the exact config JSON to copy into your own
 * [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)
 * [Apaf-1 gene family (domain architectures)](https://cmzmasek.github.io/archaeopteryx-js/demo.html?tree=apaf)
+* [Genome regions (gene arrows, anchored)](https://cmzmasek.github.io/archaeopteryx-js/demo.html?tree=genome_regions)
 * [Clustergram (heat map + column clustering)](https://cmzmasek.github.io/archaeopteryx-js/demo.html?tree=clustergram)
 * [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)
@@ -589,6 +590,81 @@ warning, never fatal. The tracks ride into the SVG, PDF and PNG exports.
 This is the desktop's domain display, drawn to the same numbers
 (`test/domain_test.js` holds them).
 
+## Genome regions
+
+A tree whose tips are genomes can carry (part of) each genome: its genes as
+`<sequence>` elements, one per gene, each with a `<location>` on a contig and
+its family in an `<annotation ref="…">`, plus one `<sequence type="dna">`
+record per contig. The viewer draws them as a **gene track** beside the
+tips: a thin backbone per genome with an **arrow per gene**, pointing by
+strand, coloured by family, on one scale shared by the whole tree so
+distances compare across genomes. The rows are **anchored**: the anchor
+family's gene sits at the same place in every row, pointing right, and the
+neighbours follow — a genome carrying it on the other strand is mirrored —
+so gene order, inversions, insertions and deletions read down the tree, as
+in BV-BRC's Compare Region Viewer. A family met in one genome only is grey,
+a gene with no family lighter grey, so conserved order stands out. A bar at
+the end of a backbone marks a contig end; the track's own scale bar under
+the rows reads in kb. The track appears from the start whenever a tree
+carries regions; the **Genes** checkbox under Display Data toggles it, and
+the **Genome regions** section holds the controls:
+
+* **Track width** `−` / `+` — the widest row starts at a quarter of the
+  window and scales by 0.8 / 1.2 per press (hold to repeat).
+* **Anchor** — `Auto` (the family single-copy in the most genomes, at least
+  half of them; the choice is named), any family that can anchor two
+  genomes or more, or `None`, which left-aligns the rows.
+* **Family** — which annotation namespace colours the genes and anchors the
+  rows, offered when the genes carry more than one (a BV-BRC export carries
+  both PGfams and PLfams).
+* **Labels** — `On genes` (the symbol, when it fits), `Legend` (a card of
+  the families with their commonest product and genome counts, draggable,
+  double-click to send it home), or `None`.
+
+**Hovering an arrow** reads the gene out: symbol, product, family, location,
+length, the genome it belongs to and its accession; **clicking** opens its
+BV-BRC feature page for a BV-BRC accession (`fig|…`) or NCBI's protein page
+for a GenBank / RefSeq one. In the circular and unrooted layouts the arrows
+ride each named tip's spoke, as the domain tracks do, and both tracks can
+show at once, the genes past the domains. Whole genomes are for viruses; a
+bacterial genome is shown as a window of a few dozen genes around a gene of
+interest, chosen by whoever writes the file. The tree is labelled by node
+name: a genome's sequences describe the region beside the tip, not the tip.
+
+The file needs nothing phyloXML has not got — `<location>` is the schema's
+"location of a sequence on a genome/chromosome", an annotation's `ref` its
+reference to an external database:
+
+```xml
+<clade>
+  <name>Brucella melitensis bv. 1 str. 16M</name>
+  <sequence type="dna">                      <!-- the contig record, FIRST -->
+    <accession source="RefSeq">NC_003317.1</accession>
+    <name>chromosome I</name>
+    <location>NC_003317.1:1-2117144</location>
+  </sequence>
+  <sequence type="protein">                  <!-- one per gene, any order -->
+    <accession source="BV-BRC">fig|224914.11.peg.1021</accession>
+    <symbol>dnaK</symbol>
+    <name>Chaperone protein DnaK</name>
+    <location>NC_003317.1:1055720-1057636(-)</location>
+    <annotation ref="pgfam:PGF_00019355"></annotation>
+  </sequence>
+</clade>
+```
+
+A location is `contig:start-end(+)`, 1-based and inclusive, split on its
+last colon; a located sequence **with** a strand is a gene, one **without**
+is the contig's record, whose span says where the contig ends. The record
+comes first because a tip's first sequence is "the" sequence to every other
+reader. A tip's genes on a second contig are not drawn (one contig per
+genome: the one with the most genes) and a location not in the grammar is
+skipped; both are counted in a console warning. The demo is synthetic
+([Genome regions](https://cmzmasek.github.io/archaeopteryx-js/demo.html?tree=genome_regions),
+twelve genomes with one row per rule: an inversion, a deletion, two
+insertions, a mirrored genome, a contig end, two contigs, overlapping genes,
+a doubled anchor); `test/gene_test.js` pins its numbers.
+
 ## Sequence alignments
 
 A tree whose tips carry `<mol_seq is_aligned="true">` shows the alignment as
@@ -810,6 +886,59 @@ branches show divergence, and the Scale Axis measures distance instead. Each lay
 Div is on screen says so and opens again showing divergence. All of this is
 shared with the desktop.
 
+### Clock plot
+
+Beside the switch, a **Clock plot** button opens a panel that plots each
+tip's **date** against its **divergence** from the root, with a straight
+line through the tips — the root-to-tip plot of TempEst and TreeTime, and
+Auspice's clock view. Under the plot:
+
+- **Rate** — the slope of the line: substitutions per site per year (per
+  unit of the tree's dates where they are not calendar years). Negative
+  where the tips' divergence falls with time.
+- **Root date, by the line** — the date at which the line comes down to the
+  root's divergence — over **Root date, in the tree**, the one the tree
+  states. How far apart they are is the point of showing both.
+- **R²** and the number of **Tips** in the fit.
+
+The line is ordinary least squares over the **tips only**: a tip's date is
+an observation, an ancestor's was inferred (usually with a clock), and
+counting it would have the estimate confirm itself. It is not forced through
+the root. Tips share ancestry, so R² describes the fit and is no
+significance test. On a BEAST clock-model tree the divergence *is* each
+branch's time × its clock rate, so there the plot shows the model's rates,
+not a measurement of its own (a strict clock is a perfect line), and the
+panel says so.
+
+The panel is **linked to the tree** and stays open while you work in it
+(drag it by its title):
+
+- a point wears its node's colour in the tree — the Color visualization,
+  search hits, the selection;
+- pointing at a point lights its node in the tree (the collapsed clade
+  holding it, if it is hidden in one), and pointing at a node in the tree
+  rings its point;
+- **clicking** a point selects or deselects its node, and **dragging** a box
+  selects the tips in it — the tree's own selection, so an outlier found on
+  the plot is found in the tree. **Deselect all** clears it;
+- tips with one date and one divergence — identical sequences sampled on one
+  day — are drawn on one spot, and that dot answers for all of them: the
+  readout says how many tips are there and names the first five, all of them
+  light up in the tree, and a click selects them all (or deselects them all,
+  where all were selected);
+- in a subtree view the plot is the clade's, with the clade's own line.
+
+**Regression line** shows and hides the line. **Internal nodes** adds the
+ancestors' points, each at its own date and divergence; the panel opens
+without them, since the line is the tips' and a deep root would crowd them
+into a corner.
+
+The button is offered on a tree that has **Time | Div** and whose line can
+be drawn: three tips or more, not all on one date. A tree sampled at one
+moment has no slope to estimate. (A tree whose branch lengths are divergence
+and whose tips alone are dated — the tree a root-to-tip plot is run on
+*before* dating — has no plot yet.)
+
 # forester.js
 forester.js is a general suite for dealing with phylogenetic trees.
 
@@ -1020,7 +1149,10 @@ pick them up. Both metrics are retained, and
 `forester.applyTimeBranchLengths(phy)` /
 `forester.applyDivergenceBranchLengths(phy)` /
 `forester.hasTimeAndDivergence(phy)` are the plumbing behind the
-**Time | Div** switch. The two `apply` functions answer `true` when they
+**Time | Div** switch (and `forester.clockPlotKind(phy)` /
+`forester.clockPlotData(phy, view)` / `forester.clockRegression(xs, ys)`
+behind the **Clock plot**: which trees have one, its points and its
+least-squares line). 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.
 
@@ -1100,7 +1232,7 @@ when the sequences are of unequal length, why it cannot.
   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
+  shape, domains, gene families, 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
@@ -1389,6 +1521,10 @@ copy-pastable JSON.
 | `domainLabels` | `'domains'` | Where domain names go: `'domains'` (on the boxes), `'legend'` (a card), or `'none'`. |
 | `domainGlow` | `false` | Open with the glow around each domain box on. |
 | `domainEvalueExponent` | `-3` | The E-value threshold's exponent at launch, an integer from `-20` to `3`: domains with an E-value at or under `10^exponent` are drawn. |
+| `showGenes` | tree-derived | Open with the gene track shown. Default: on when any tip carries a genome region (two or more located genes), off otherwise — an explicit `true`/`false` overrides that. |
+| `geneAnchor` | `'auto'` | The family the gene track's rows line up on: `'auto'` (the family single-copy in the most genomes), `'none'` (left-aligned rows), or a family ref such as `'pgfam:PGF_00019355'`. |
+| `geneFamily` | `'auto'` | The annotation namespace that colours the genes and anchors the rows: `'auto'` (the one most genes carry) or a prefix such as `'pgfam'`. |
+| `geneLabels` | `'genes'` | Where gene symbols go: `'genes'` (on the arrows), `'legend'` (a card of the families), or `'none'`. |
 | `showScaleAxis` | tree-derived | Open with the scale axis shown: the time axis on a time tree whose branches show time, a distance axis on any other phylogram. Default: on when the tree carries `<date>` elements and opens shown in time, off otherwise (a dated tree that opens in divergence is a divergence tree on screen) — an explicit `true`/`false` overrides that. |
 | `showScaleGrid` | `false` | Open with the Scale Grid lines on (only meaningful — and only offered as a checkbox — while the scale axis itself is shown). |
 | `showSupportDots` | `false` | Open with the Support Dots marks on (the checkbox appears whenever the tree has confidences). |
@@ -1930,7 +2066,10 @@ Two rules, in order:
    of the current pick's (substantially more economical) takes it.
 
 A field with no printable values is never checked (apaf's sequences carry
-only domain architectures, so its Sequence box starts unchecked). The choice
+only domain architectures, so its Sequence box starts unchecked). On a tree
+of genomes the sequence field has none either: a tip's located sequences —
+its contig record and its genes — describe the region drawn beside it, not
+the tip, so the node name stands. The choice
 is logged to the console at launch, and the user can recheck anything — the
 rules only set the initial state.
 
@@ -2063,6 +2202,68 @@ numbers — apaf.xml: 31 tips, `Lmax` 2080, 202 domains; 9 names / 166 boxes
 at 1e−3; the palette; 22_MOUSE's box offsets at `W = 300` — are the
 desktop's, in `test/domain_test.js`.
 
+### The gene track
+
+Data model (forester): a tip's `sequences` with a `location` the grammar
+reads (`forester.parseSequenceLocation`: `contig:start-end(+)`, split on the
+last colon, 1-based, `end ≥ start`) are genes when the strand is given and
+contig records when not; `forester.geneRegionOf(node)` is the tip's genes
+on ONE contig (the most genes, ties to the first listed) in position order,
+that contig's record, the span and the count left out; null without a gene.
+A gene's family in a namespace is its first annotation ref with that prefix
+(`geneFamilyOf`); `geneFamilyNamespaces` ranks the prefixes by use.
+`collectBasicTreeProperties` sets `geneRegions` when some tip carries two
+genes or more (a gene-family tree locating one gene per tip is not a tree
+of genomes) and `maxGeneRegionLength`; `treeStatistics` counts
+`tipsWithGenes`. Anchor: `geneAnchorCandidates` counts per family the
+regions carrying it exactly once (`single`) and at all; `geneDefaultAnchor`
+is the top one when `single` is at least half the regions, ties by code
+unit. Rows: `geneTrackRows(regions, anchor, ns)` maps every row onto one
+coordinate in bp — an anchored row's anchor midpoint at 0, mirrored
+(`x → −x`, directions flipped) when the anchor is on `−`; a row with no
+anchor gene, or two, left-aligned at the anchored rows' leftmost edge (0
+without any). The backbone is the span padded by 2% (`GENE_REGION_PAD`),
+clamped to the record's span with a cap where it was clamped (caps swap
+with the flip). Lanes: greedy by start, the first of two that is free, else
+the one that frees first. Scale: `f = W / (extent.max − extent.min) × 0.9`
+px per bp, `W` by the domain track's rules (a quarter of the viewport,
+−/+ by 0.8/1.2, 20…2000; radial `min(W, 0.2 × radius)`), kept apart from
+the domain track's width. Placement as the domain tracks and past them when
+both show: rectangular `start = _w + nodeLabelGap + labelSpace +
+_domainReserve + 20`, reserve `20 + W + 10` in `_geneReserve` (counted
+wherever `_w` is); circular `r0 = maxRad + labelSpace + domainRadialExtent
++ 4`; unrooted `start = labelSpace + domainRadialExtent + 4`; the radial fit
+adds `4 + W + 10`. Arrow: `geneArrowPath(x, y, w, h, dir)`, head
+`min(h/2, w)`, a triangle when shorter than its head; two lanes share the
+height (`max(3, h/2)` each); each arrow is its own path carrying
+`__aptxGene` for the readout, with a 1 px `darken(base, 0.3)` border; the
+backbone (1 px) and the caps (1.5 px bars) are one path per track, one per
+row in the radial layouts. Symbol (or gene name) on the body in `min(font,
+h − 2)` px when over 4 px and at most `w − head − 4` wide, rectangular
+only. Colours: the families SHARED over the tree (two regions or more),
+sorted by code unit, take the domain palette (`domainQualitativeColor`) in
+order; a singleton `#9e9e9e`, no family `#cfcfcf`; dealt at load and on a
+namespace change. The kb bar: `geneScaleBar(f, 80)`, a round number of bp
+labelled in kb from 1000 up, 12 px under the lowest row. Legend
+(`'legend'`): title `Gene families (<ns>)`, rows `product (regions)` in
+screen order over the view (`geneFamilySummary` with the tree's shared set,
+so a family shown once in a subtree keeps its colour), then `unique to one
+genome (n)` and `no family (n)`; home bottom-right, drag keeps its place as
+a fraction of the view, double-click sends it home. Links: `geneReference`
+— BV-BRC's feature page for `fig|…` or a BV-BRC / PATRIC source, NCBI's
+protein page for GenBank / RefSeq / UniProt. State: `showGenes` (auto-on
+with `geneRegions`), `geneAnchor` (`'auto'` | `'none'` | a ref),
+`geneFamily` (`'auto'` | a namespace), `geneLabels`; the view carries
+`genes`, `geneLabels`, and `geneAnchor` / `geneFamily` as the EFFECTIVE
+values. Labels: on a tree with `geneRegions`, a tip whose first sequence is
+located contributes no sequence text to the label suggestion
+(`suggestLabelFields`), so the node name stands. Gates as the domain
+tracks (external labels on, radial labels in a radial layout, a name the
+crowding rule left). Fixture `test/data/genome_regions.xml`, generated by
+`test/make_genome_regions_fixture.js` (the demo copy is byte-identical and
+a test says so); the numbers in `test/gene_test.js`, the SVG in
+`test/browser/genes.html`.
+
 ### The alignment track
 
 Data model: per-tip `sequences[0].mol_seq = {is_aligned, value}` (the gapped
@@ -2212,7 +2413,7 @@ the tree ≥ 220 px))`. It is budgeted **before** the alignment, and the
 alignment's own band then yields to it: the matrix wants a fixed, finite width
 while the alignment's band is a window that scrolls and so loses nothing by
 giving way. (Budgeted the other way round, an 18-column matrix got a 60 px
-sliver.) It sits between the domain tracks and the alignment, its right edge at
+sliver.) It sits between the domain and gene tracks and the alignment, its right edge at
 `displayWidth − rootOffset − msaReserve`. Rows tile the cluster height by the
 same once-derived midpoints the alignment uses. Column width is
 `clamp(band / columns, 3, 14)`; past `band / 3` columns the matrix shows a
@@ -2395,6 +2596,46 @@ 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.)
 
+### The clock plot
+
+**Model** (`forester.js`, pure). `forester.clockPlotKind(phy)` answers
+`'divergence'` or `null`: the tree has Time and Div
+(`forester.hasTimeAndDivergence`) and three tips or more, not all on one
+date. It is asked of the **tree**, never of the view. A second kind,
+`'root-to-tip'` — divergence branch lengths, dated tips, no dated ancestors —
+is described beside the function and not built. `forester.clockPlotData(phy,
+view)` returns `{kind, forward, unit, fromRates, points, root, fit}`: a point
+`{node, date, div, tip}` per node of the view (a tip also carries its
+`residual`), `forward` false where the dates are ages, `fromRates` true where
+the divergence is time × clock rate, and `fit` =
+`forester.clockRegression(dates, divergences)` over the tips — ordinary least
+squares about the means, `{n, slope, intercept, r2}` — plus `rate` (the slope
+in the direction time runs) and `rootDate` (where the line reaches the view
+root's divergence; `null` unless the rate is positive). `fit` is `null` for a
+view with fewer than three tips or one date. `forester.calendarTickMonths`
+gives month ticks for a span too short for whole years.
+
+**Panel** (`archaeopteryx.js`, the "Clock plot" section). A modeless
+`makeDialogShell` dialog, dragged by its title, placed in the tree area's top
+right corner and below anything the host page keeps there. The drawing is one
+SVG in the panel's own `--p-*` inks. `renderClockPlot` runs at the end of
+every `update()`: it works the points out and lays them down again only when
+the top of the view or its node count changed, or a checkbox did; otherwise
+it only goes over the points' colours. A point's colour is its node's in the
+tree (found, selected, the Color visualization, the file's styles).
+
+**The link.** Pointer events on the SVG: the nearest point within 7 px, and
+with it every point of its kind within 1 px of it — one dot for tips that
+share a date and a divergence. The dot's nodes are lit through
+`showHoverGlow(node, also)` (each as the tree shows it: a tip hidden in a
+collapsed clade lights the clade); a click toggles them in `_selectedNodes`,
+a dragged box adds the tips inside it; `mouseover` on a tree node rings its
+point. Closing is synchronous: nothing waits for the dialog's `close` event.
+
+There is no config key and no view key for the panel yet, and it is not part
+of any download. The numbers are pinned in `test/clock_test.js` (computed by
+hand), the panel in `test/browser/clock_plot.html`.
+
 ## Node selection
 
 With `enableManualNodeSelection` on, the node menu gains **Select/Deselect Node**
@@ -2408,7 +2649,12 @@ 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.
 
-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.)
+The **Clock plot** selects too, whatever this setting says: a click on a
+point, or a box dragged over tips, changes the same selection.
+
+Every change of the selection — from the node menu or from the clock plot —
+dispatches a `selected_nodes_changed_event` on `document`, so the embedding
+application can read the selection then, or whenever it wants from its own
+button. Nothing announces "the user is done selecting". (Versions before 3.0
+carried a dormant, never-rendered "Submit Selected" button in the source; it
+was removed.)

package/archaeopteryx.d.ts

@@ -60,12 +60,25 @@ export interface ArchaeopteryxConfig {
     collapseControlPanel?: boolean;
     displayHeight?: number;
     displayWidth?: number;
+    /** The domain tracks' E-value threshold at launch, as an exponent: -20 to 3. */
+    domainEvalueExponent?: number;
+    domainGlow?: boolean;
+    domainLabels?: 'none' | 'domains' | 'legend';
     enableAccessToDatabases?: boolean;
     enableDownloads?: boolean;
     enableDynamicSizing?: boolean;
     enableManualNodeSelection?: boolean;
     enableSubtreeDeletion?: boolean;
     enableVisualizations?: boolean;
+    /** The family the gene track's rows line up on: 'auto' (the family
+     * single-copy in the most genomes), 'none' (left-aligned rows), or a
+     * family ref such as 'pgfam:PGF_00019355'. */
+    geneAnchor?: string;
+    /** The annotation namespace that colours the genes and anchors the rows:
+     * 'auto' (the one most genes carry) or a prefix such as 'pgfam'. */
+    geneFamily?: string;
+    /** Where gene symbols go: on the arrows, in a legend of the families, or nowhere. */
+    geneLabels?: 'none' | 'genes' | 'legend';
     initialVisualization?: string | null;
     ladderizeTree?: boolean;
     layout?: Layout;
@@ -98,6 +111,11 @@ export interface ArchaeopteryxConfig {
      * while heatmapColumnOrder is 'manual'. A ref the tree has not got is
      * ignored; a column this does not name follows the ones it does. */
     heatmapManualOrder?: string[] | null;
+    /** The domain tracks. Default: on when any tip carries a domain architecture. */
+    showDomainArchitectures?: boolean;
+    /** The gene track (genome regions). Default: on when any tip carries two
+     * or more located genes. */
+    showGenes?: boolean;
     showHeatmap?: boolean;
     showMsa?: boolean;
     /** Summarize the alignment as a sequence logo instead of a conservation
@@ -179,6 +197,12 @@ export interface ViewState {
     domainLabels?: 'none' | 'domains' | 'legend';
     domainGlow?: boolean;
     domainEvalue?: number;
+    genes?: boolean;
+    /** The anchor family in effect: a ref, or 'none'. */
+    geneAnchor?: string;
+    /** The family namespace in effect. */
+    geneFamily?: string;
+    geneLabels?: 'none' | 'genes' | 'legend';
     scaleAxis?: boolean;
     scaleGrid?: boolean;
     /** @deprecated the name of scaleAxis in older links; still read. */