archaeopteryx 3.11.0 → 3.12.0

package/README.md

@@ -37,6 +37,7 @@ config key live and shows the exact config JSON to copy into your own
 * [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)
+* [Sequence logo (the motif changes by clade)](https://cmzmasek.github.io/archaeopteryx-js/demo.html?tree=sequence_logo)
 * [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)
@@ -455,7 +456,9 @@ desktop's Unicode entry: it stays with the text field there, as it should.
 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
+sizes, the rotation, and the tracks — which track is shown, the heat map's
+column order (including one you arranged by hand) and whether the alignment
+is summarised as a logo. 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
@@ -472,7 +475,9 @@ 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
-`archaeopteryx.encodeViewState()` / `decodeViewState()` for the hash form,
+`archaeopteryx.encodeViewState()` / `decodeViewState()` for the hash form
+(every key the state can hold survives the hash — a test reads `getViewState`
+and fails on any key the codec does not know),
 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
@@ -530,6 +535,23 @@ checkbox under Display Data toggles the whole track.
 To find a motif, pick **Molecular Sequence** in a search box: it matches the
 residues as written, gap characters included, as the desktop does.
 
+**Sequence Logo** (the checkbox under **Alignment**) replaces the conservation
+bar with a **logo**: every column a stack of letters, as tall as that column's
+information content in bits and shared out by residue frequency, most frequent
+on top — the display the MEME Suite and WebLogo draw. A conserved column is one
+tall letter, a variable one a short pile, and the caption gives the scale
+(0 to 2 bits for nucleotides, 0 to 4.3 for amino acids).
+
+It summarises **the tips currently on screen**, so entering a clade gives that
+clade's motif rather than the file's, and the caption names how many tips that
+is (`n = 12`). Two consequences worth knowing: gaps are not a letter —
+frequencies are taken over the residues present, and the stack is then scaled
+by the column's occupancy, so a column held up by two sequences out of fifty
+draws short rather than perfectly conserved; and there is **no small-sample
+correction**, because entering a three-tip clade is a normal thing to do and
+Schneider's correction would subtract more than the maximum and leave the
+column blank. Read `n` and judge.
+
 Alignments arrive with the tree: as phyloXML `<mol_seq is_aligned="true">`
 elements, or in a **Nexus** file whose characters matrix accompanies its tree.
 The **Nexus** entry in the Download menu writes the current tree *and* its
@@ -1041,6 +1063,7 @@ copy-pastable JSON.
 | `layout` | `'rectangular'` | The starting layout: `'rectangular'`, `'circular'`, or `'unrooted'`. |
 | `ladderizeTree` | `true` | Ladderize the tree on load: at each node, the larger clade first (any number of children, so a polytomy sorts too). |
 | `showMsa` | tree-derived | Open with the alignment track shown. Default: on when the tree carries an aligned `mol_seq`, off otherwise — an explicit `true`/`false` overrides that. |
+| `showMsaLogo` | `false` | Open with the alignment summarised as a sequence logo instead of a conservation bar: each column a stack of letters as tall as its information content, over the tips currently on screen. Only drawn while the alignment track is shown. |
 | `showHeatmap` | `false` | Open with the heat map shown. Offered whenever the tree carries two or more numeric per-tip fields, but off unless asked for: almost any annotated tree has such fields, so turning it on by itself would be an opinion about the tree rather than a service. |
 | `heatmapColumnOrder` | tree-derived | How the heat map's columns are ordered: `'document'` (as the file lists them), `'clustered'` (Euclidean), `'clustered-presence'` (Bray–Curtis), `'alphabetical'`, `'frequency'`. The clustered modes also draw the dendrogram. Default: a **clustered** order, with the distance chosen from the values — Bray–Curtis where the matrix has zeros to ignore and nothing negative, Euclidean otherwise. An explicit value always wins and is never re-derived. |
 | `heatmapManualOrder` | `null` | The heat map's columns in your own order, as an array of property refs (`['meta:recA', 'meta:gyrA', …]`). Only read while `heatmapColumnOrder` is `'manual'`. A ref the tree has not got is ignored, and a column the list does not name follows the ones it does. |
@@ -1716,8 +1739,32 @@ 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 sequence logo** (`showMsaLogo`, `forester.msaLogo`) replaces the
+conservation bar and the consensus row rather than joining them: a stack's
+height *is* the column's conservation and its top letter *is* the consensus,
+so all three would say one thing three times. Per column the model returns
+`bits` = `log₂K − H` over the non-gap residues, `occupancy` = non-gap / rows,
+`height` = `bits × occupancy`, and the letters most frequent first (ties
+alphabetical, so a figure reproduces). Rows are the **displayed** tips over
+the visible window, which is what makes entering a clade re-read the summary.
+**No small-sample correction**: Schneider's `e_n = (K−1)/(2 ln2 · n)` is for a
+motif sampled from many sequences, and at n = 3 for protein it exceeds the
+4.32-bit maximum, so a perfectly conserved column of a small clade would draw
+nothing — the caption names `n` instead.
+
+Each letter is scaled to fill its slice: `sy = hpx / (ascent + descent)` of
+**that glyph's** ink box, measured once per character off a canvas, with the
+baseline placed at `y − descent × sy` so the ink lands inside the slice.
+Measured off one glyph instead, Q and G hung their descenders through the
+ruler. Note that an SVG `<text>`'s `getBoundingClientRect` is the *font's*
+layout box, not the ink, so it cannot check this — `test_trees/msa_logo.html`
+compares letters and order through the DOM and the ink itself is measured from
+rendered pixels.
+
+The conservation bar or logo, the consensus row and the column ruler are a
+**floating strip** (see the time axes below); the residue rows stay with their
+tips. The strip's height follows what it holds (`msaBottomReserve()`), and the
+bottom reserve the fit allows for follows that.
 
 ### The heat map
 

package/archaeopteryx.d.ts

@@ -98,6 +98,10 @@ export interface ArchaeopteryxConfig {
     heatmapManualOrder?: string[] | null;
     showHeatmap?: boolean;
     showMsa?: boolean;
+    /** Summarize the alignment as a sequence logo instead of a conservation
+     * bar: each column a stack of letters as tall as its information content,
+     * over the tips currently on screen. Only drawn with the track shown. */
+    showMsaLogo?: boolean;
     showSupportDots?: boolean;
     showTimeAxis?: boolean;
     supportDotMinimum?: number;
@@ -150,6 +154,8 @@ export interface ViewState {
     rotation?: number;
     horizontalLabels?: boolean;
     msa?: boolean;
+    /** The alignment summarized as a sequence logo. */
+    msaLogo?: boolean;
     heatmap?: boolean;
     heatmapOrder?: 'document' | 'clustered' | 'clustered-presence' | 'alphabetical' | 'frequency' | 'manual';
     heatmapManual?: string[];

package/archaeopteryx.js

@@ -20,7 +20,7 @@
  *
  */
 
-// v 3.11.0
+// v 3.12.0
 // 2026-09-17
 //
 // Archaeopteryx.js is a software tool for the visualization and
@@ -103,7 +103,7 @@ function (root, d3, forester, phyloXml) {
     // IIFE's own function name -- a plain object says what it is.)
     let archaeopteryx = {};
 
-    const VERSION = '3.11.0';
+    const VERSION = '3.12.0';
     const WEBSITE = 'https://cmzmasek.github.io/archaeopteryx-js/';
     const DESKTOP_WEBSITE = 'https://cmzmasek.github.io/archaeopteryx/';
     const SOURCE_WEBSITE = 'https://github.com/cmzmasek/archaeopteryx-js';
@@ -363,6 +363,7 @@ function (root, d3, forester, phyloXml) {
     const DOWNLOAD_BUTTON = 'dl_b';
     const DYNAHIDE_CB = 'dynahide_cb';
     const MSA_CB = 'msa_cb';
+    const MSA_LOGO_CB = 'msa_logo_cb';
     const HEATMAP_CB = 'heatmap_cb';
     const HEATMAP_CONTROLS = 'heatmap_controls';
     const HEATMAP_ORDER_SELECT = 'heatmap_order';
@@ -547,7 +548,11 @@ function (root, d3, forester, phyloXml) {
     const MSA_MAX_VIEWPORT_FRACTION = 0.6;// nor grows past this share of the display
     const MSA_CONS_BAR_H = 22;            // conservation bar band height
     const MSA_CONS_TOP_GAP = 4;
-    const MSA_BOTTOM_RESERVE = 56;        // vertical room under the rows (conservation + ruler)
+    const MSA_CONS_ROW_H = 13;            // the consensus letter row
+    const MSA_RULER_H = 17;               // the column ruler under it
+    const MSA_LOGO_H = 46;                // the sequence logo's stack, full height
+    const MSA_LOGO_CAP_H = 11;            // ... and the caption line above it
+    const MSA_LOGO_FONT_PX = 24;          // the size logo glyphs are measured at, then scaled
     const MSA_NAV_RESERVE = 46;           // ... plus the navigation bar floating at the viewport bottom
     const MSA_MIN_TREE_PX = 220;          // the tree itself never shrinks below this
     let _msaColOffset = 0;                // first shown alignment column (0-based)
@@ -4927,6 +4932,7 @@ function (root, d3, forester, phyloXml) {
     const STATE_KEYS = [
         'layout',
         'showMsa',
+        'showMsaLogo',
         'showHeatmap',
         'heatmapColumnOrder',
         'heatmapManualOrder',
@@ -5169,6 +5175,12 @@ function (root, d3, forester, phyloXml) {
         if (_state.showHeatmap === undefined) {
             _state.showHeatmap = false;
         }
+        // The logo is a summary of the alignment, not a second view of the
+        // tree, so it waits to be asked for: an alignment opens showing its
+        // residues, which is what a reader came for.
+        if (_state.showMsaLogo === undefined) {
+            _state.showMsaLogo = false;
+        }
         // The columns' order. Left unset it is resolved from the data on first
         // use (heatmapMode / forester.heatmapDefaultOrder): a clustered order,
         // because reading block structure is what a heat map beside a tree is
@@ -6824,6 +6836,64 @@ function (root, d3, forester, phyloXml) {
             && _basicTreeProperties.maxMolSeqLength > 0;
     }
 
+    // The logo replaces the conservation bar and the consensus row rather
+    // than joining them: a stack's height IS the column's conservation and its
+    // top letter IS the consensus, so drawing all three would say the same
+    // thing three times and take three times the room.
+    function msaLogoShown() {
+        return _state.showMsaLogo === true && msaShown();
+    }
+
+    // What the strip under the alignment needs. The conservation form is the
+    // 56 px this was a constant for; the logo form is taller and drops the
+    // consensus row it subsumes.
+    function msaBottomReserve() {
+        return MSA_CONS_TOP_GAP
+            + (msaLogoShown() ? MSA_LOGO_CAP_H + MSA_LOGO_H : MSA_CONS_BAR_H + MSA_CONS_ROW_H)
+            + MSA_RULER_H;
+    }
+
+    // Logo letters are drawn at a fixed size and then scaled to their cell and
+    // to their share of the stack, so what is needed is how much ink this face
+    // actually puts on the page for THIS letter -- measured, not assumed: a
+    // 0.6 advance and a 0.72 cap height are true of some monospace faces and
+    // not others, and a letter scaled by the wrong constant overflows its
+    // column.
+    //
+    // Per letter, because a logo's letters must each fill their slice exactly:
+    // measured off one glyph, Q and G hung their descenders through the
+    // baseline and across the ruler, and every letter without a descender sat
+    // a little short. What is scaled to the slice is the glyph's INK BOX
+    // (ascent + descent), and the baseline is then placed so that box lands
+    // inside the slice.
+    let _logoGlyphs = {};
+
+    function logoGlyphMetrics(ch) {
+        if (_logoGlyphs[ch]) {
+            return _logoGlyphs[ch];
+        }
+        if (!_legendMeasureCtx) {
+            _legendMeasureCtx = document.createElement('canvas').getContext('2d');
+        }
+        _legendMeasureCtx.font = MSA_LOGO_FONT_PX + 'px monospace';
+        let m = _legendMeasureCtx.measureText(ch);
+        let ascent = m.actualBoundingBoxAscent;
+        let descent = m.actualBoundingBoxDescent;
+        if (!(ascent > 0)) {
+            ascent = MSA_LOGO_FONT_PX * 0.72;   // a face that will not say
+            descent = 0;
+        }
+        if (!(descent > 0)) {
+            descent = 0;                        // no descender, or none reported
+        }
+        _logoGlyphs[ch] = {
+            width: m.width || (MSA_LOGO_FONT_PX * 0.6),
+            ascent: ascent,
+            descent: descent
+        };
+        return _logoGlyphs[ch];
+    }
+
     function msaRowSeq(d) {
         if (d.sequences && d.sequences.length > 0) {
             let s = d.sequences[0];
@@ -7014,12 +7084,15 @@ function (root, d3, forester, phyloXml) {
                 .attr('stroke', ink).attr('stroke-opacity', 0.7).attr('stroke-width', 1);
         }
 
-        // conservation band (consensus identity) + consensus letters
-        // scored over the visible WINDOW only -- the whole alignment would
-        // cost rows x total per redraw; indices below are window-relative
-        let cons = forester.msaConservation(tips.map(function (t) {
+        // Scored over the visible WINDOW only -- the whole alignment would
+        // cost rows x total per redraw; indices below are window-relative.
+        // The rows are the tips ON SCREEN: enter a clade and the summary is
+        // that clade's, which is the whole point of putting it next to a tree.
+        let windowRows = tips.map(function (t) {
             return msaRowSeq(t).slice(offset, offset + visible);
-        }), visible, 'identity', isNuc);
+        });
+        let logo = msaLogoShown() ? forester.msaLogo(windowRows, visible, isNuc) : null;
+        let cons = logo ? null : forester.msaConservation(windowRows, visible, 'identity', isNuc);
         // A faint dashed guide from each tip -- from the end of its label, or
         // from the node itself when the label is hidden -- across to its row
         // in the track, so a row can be read back to its sequence without
@@ -7055,34 +7128,91 @@ function (root, d3, forester, phyloXml) {
         }
 
         // ---- conservation, consensus, ruler: a FLOATING strip ----
-        let strip = floatStripGroup('aptx-msa-strip', _clusterH, MSA_BOTTOM_RESERVE);
+        let stripH = msaBottomReserve();
+        let strip = floatStripGroup('aptx-msa-strip', _clusterH, stripH);
         strip.append('rect').attr('x', Math.round(originX) - 2).attr('y', _clusterH)
-            .attr('width', trackW + 4).attr('height', MSA_BOTTOM_RESERVE)
+            .attr('width', trackW + 4).attr('height', stripH)
             .attr('fill', _state.backgroundColorDefault);
         let consTop = _clusterH + MSA_CONS_TOP_GAP;
-        strip.append('rect').attr('x', Math.round(originX)).attr('y', consTop)
-            .attr('width', trackW).attr('height', MSA_CONS_BAR_H)
-            .attr('fill', ink).attr('fill-opacity', 0.08);
-        for (let i = 0; i < visible; ++i) {
-            let score = cons.scores[i] || 0;
-            if (score <= 0) {
-                continue;
+        // A caption on the panel's own background, so it stays readable over
+        // whatever the band happens to draw underneath it.
+        let caption = function (txt, y) {
+            if (trackW <= 170) {
+                return;
             }
-            let bh = Math.max(1, Math.round(score * MSA_CONS_BAR_H));
-            let x0 = Math.round(originX + (i * cw));
-            let x1 = Math.round(originX + ((i + 1) * cw));
-            strip.append('rect').attr('x', x0).attr('y', (consTop + MSA_CONS_BAR_H) - bh)
-                .attr('width', Math.max(1, x1 - x0)).attr('height', bh)
-                .attr('fill', ink).attr('fill-opacity', 0.7);
-        }
-        if (trackW > 170) {
-            strip.append('text').attr('x', Math.round(originX) + trackW - 3).attr('y', consTop + 9)
+            let font = '8px ' + FONT_DEFAULTS;
+            let w = legendTextWidth(txt, font) + 6;
+            let xe = Math.round(originX) + trackW - 3;
+            strip.append('rect').attr('x', xe - w).attr('y', y - 8)
+                .attr('width', w).attr('height', 11)
+                .attr('fill', _state.backgroundColorDefault).attr('fill-opacity', 0.85);
+            strip.append('text').attr('x', xe - 3).attr('y', y)
                 .attr('text-anchor', 'end')
                 .style('font-size', '8px').style('fill', ink).style('fill-opacity', 0.9)
-                .text('Consensus identity (n = ' + n + ')');
-        }
-        let consensusRow = cw >= 7;
-        if (consensusRow) {
+                .text(txt);
+        };
+        if (logo) {
+            // Each column a stack of letters: total height the column's
+            // information content in bits, each letter's share its frequency.
+            // Least frequent at the BOTTOM, so the eye reads the consensus
+            // off the top of the stack.
+            //
+            // The caption gets a line of its own above the stacks (hence the
+            // CAP_H here). Laid over them it washed out the very letters it
+            // was labelling, which is a poor trade for eleven pixels.
+            let floor = consTop + MSA_LOGO_CAP_H + MSA_LOGO_H;
+            strip.append('line')
+                .attr('x1', Math.round(originX)).attr('x2', Math.round(originX) + trackW)
+                .attr('y1', floor).attr('y2', floor)
+                .attr('stroke', ink).attr('stroke-opacity', 0.5).attr('stroke-width', 1);
+            for (let i = 0; i < visible; ++i) {
+                let col = logo.columns[i];
+                if (!col || !(col.height > 0)) {
+                    continue;
+                }
+                let x0 = Math.round(originX + (i * cw));
+                let x1 = Math.round(originX + ((i + 1) * cw));
+                let y = floor;
+                for (let k = col.letters.length - 1; k >= 0; --k) {
+                    let letter = col.letters[k];
+                    let hpx = (letter.h / logo.maxBits) * MSA_LOGO_H;
+                    if (hpx < 0.5) {
+                        continue;   // under half a pixel of ink: nothing to draw
+                    }
+                    let glyph = logoGlyphMetrics(letter.ch);
+                    let sy = hpx / (glyph.ascent + glyph.descent);
+                    let rgb = forester.msaResidueRgb(letter.ch, isNuc);
+                    strip.append('text')
+                        .attr('transform', 'translate(' + (x0 + ((x1 - x0) / 2)) + ','
+                            + (y - (glyph.descent * sy)) + ')'
+                            + ' scale(' + (Math.max(1, x1 - x0) / glyph.width) + ',' + sy + ')')
+                        .attr('text-anchor', 'middle')
+                        .style('font-family', 'monospace')
+                        .style('font-size', MSA_LOGO_FONT_PX + 'px')
+                        .style('fill', rgb === null ? ink : 'rgb(' + rgb.join(',') + ')')
+                        .text(letter.ch);
+                    y -= hpx;
+                }
+            }
+            caption('Sequence logo \u2014 0 to ' + logo.maxBits.toFixed(1)
+                + ' bits (n = ' + n + ')', consTop + 8);
+        } else {
+            strip.append('rect').attr('x', Math.round(originX)).attr('y', consTop)
+                .attr('width', trackW).attr('height', MSA_CONS_BAR_H)
+                .attr('fill', ink).attr('fill-opacity', 0.08);
+            for (let i = 0; i < visible; ++i) {
+                let score = cons.scores[i] || 0;
+                if (score <= 0) {
+                    continue;
+                }
+                let bh = Math.max(1, Math.round(score * MSA_CONS_BAR_H));
+                let x0 = Math.round(originX + (i * cw));
+                let x1 = Math.round(originX + ((i + 1) * cw));
+                strip.append('rect').attr('x', x0).attr('y', (consTop + MSA_CONS_BAR_H) - bh)
+                    .attr('width', Math.max(1, x1 - x0)).attr('height', bh)
+                    .attr('fill', ink).attr('fill-opacity', 0.7);
+            }
+            caption('Consensus identity (n = ' + n + ')', consTop + 9);
             for (let i = 0; i < visible; ++i) {
                 let cc = cons.consensus[i];
                 if (!cc) {
@@ -7099,7 +7229,7 @@ function (root, d3, forester, phyloXml) {
 
         // the 1-based column ruler: absolute column numbers at nice steps,
         // and always the first and last column when their edge is in view
-        let rulerY = consTop + MSA_CONS_BAR_H + (consensusRow ? 13 : 3);
+        let rulerY = consTop + (logo ? MSA_LOGO_CAP_H + MSA_LOGO_H : MSA_CONS_BAR_H + MSA_CONS_ROW_H);
         strip.append('line').attr('x1', Math.round(originX)).attr('x2', Math.round(originX) + trackW)
             .attr('y1', rulerY).attr('y2', rulerY)
             .attr('stroke', ink).attr('stroke-opacity', 0.8).attr('stroke-width', 1);
@@ -7357,6 +7487,11 @@ function (root, d3, forester, phyloXml) {
         scheduleUpdate(null, 0);
     }
 
+    function msaLogoCbClicked() {
+        _state.showMsaLogo = getCheckboxValue(MSA_LOGO_CB);
+        scheduleUpdate(null, 0);
+    }
+
     // ===================== Heat map =====================
     // The desktop's MATRIX annotation columns: one cell per (tip, numeric
     // per-tip property) to the right of the labels, every column painted on
@@ -8930,6 +9065,9 @@ function (root, d3, forester, phyloXml) {
         }
         if (_basicTreeProperties.alignedMolSeqs === true && _basicTreeProperties.maxMolSeqLength > 0) {
             s.msa = _state.showMsa === true;
+            if (_state.showMsaLogo === true) {
+                s.msaLogo = true;
+            }
         }
         if (heatmapAvailable()) {
             s.heatmap = _state.showHeatmap === true;
@@ -9058,6 +9196,9 @@ function (root, d3, forester, phyloXml) {
         if (typeof s.msa === 'boolean') {
             _state.showMsa = s.msa;
         }
+        if (typeof s.msaLogo === 'boolean') {
+            _state.showMsaLogo = s.msaLogo;
+        }
         if (typeof s.heatmap === 'boolean') {
             _state.showHeatmap = s.heatmap;
         }
@@ -9168,6 +9309,7 @@ function (root, d3, forester, phyloXml) {
             }
         });
         setCheckboxValue(MSA_CB, _state.showMsa === true);
+        setCheckboxValue(MSA_LOGO_CB, _state.showMsaLogo === true);
         setCheckboxValue(HEATMAP_CB, _state.showHeatmap === true);
         syncHeatmapControls();
         setCheckboxValue(TIME_AXIS_CB, _state.showTimeAxis === true);
@@ -9241,10 +9383,20 @@ function (root, d3, forester, phyloXml) {
     // Lists are comma-joined, booleans 1 / 0, the two searches flattened
     // to a / af / am / a2 and b / bf / bm / b2. Made for a URL hash, where
     // none of these characters needs escaping.
-    const VIEW_TEXT_KEYS = ['layout', 'display', 'order', 'root', 'colorBy', 'shapeBy', 'domainLabels', 'combine'];
+    // Every key getViewState writes has to be here, or a view survives
+    // getViewState/applyViewState (what an embedder uses) and is silently
+    // dropped from the URL hash (what "Copy link to this view" produces).
+    // The heat map's four keys and the alignment logo went in exactly that
+    // way, while the README promised a link reproduced the figure.
+    const VIEW_TEXT_KEYS = ['layout', 'display', 'order', 'root', 'colorBy', 'shapeBy', 'domainLabels', 'combine',
+        'heatmapOrder'];
     const VIEW_INT_KEYS = ['tree', 'subtree', 'rotation', 'domainEvalue'];
     const VIEW_NUMBER_KEYS = ['font', 'node', 'branch'];
-    const VIEW_BOOL_KEYS = ['horizontalLabels', 'msa', 'domains', 'domainGlow', 'timeAxis', 'timeGrid', 'matchCase', 'inverse'];
+    const VIEW_BOOL_KEYS = ['horizontalLabels', 'msa', 'msaLogo', 'heatmap', 'domains', 'domainGlow',
+        'timeAxis', 'timeGrid', 'matchCase', 'inverse'];
+    // Lists of strings, comma-joined. A property ref carries ':' but never a
+    // comma, and encodeViewValue leaves both readable in a hash.
+    const VIEW_LIST_KEYS = ['heatmapManual'];
     const VIEW_SEARCH_KEYS = [['searchA', 'a'], ['searchB', 'b']];
 
     function encodeViewValue(v) {
@@ -9278,6 +9430,12 @@ function (root, d3, forester, phyloXml) {
         if (Array.isArray(state.collapsed) && state.collapsed.length > 0) {
             put('collapsed', state.collapsed.join(','));
         }
+        VIEW_LIST_KEYS.forEach(function (k) {
+            let v = state[k];
+            if (Array.isArray(v) && v.length > 0) {
+                parts.push(k + '=' + v.map(encodeViewValue).join(','));
+            }
+        });
         VIEW_BOOL_KEYS.forEach(function (k) {
             if (typeof state[k] === 'boolean') {
                 put(k, state[k] ? 1 : 0);
@@ -9344,6 +9502,16 @@ function (root, d3, forester, phyloXml) {
                 return parseInt(x, 10);
             });
         }
+        VIEW_LIST_KEYS.forEach(function (k) {
+            if (raw[k] !== undefined) {
+                let list = raw[k].split(',').filter(function (x) {
+                    return x.length > 0;
+                });
+                if (list.length > 0) {
+                    state[k] = list;
+                }
+            }
+        });
         VIEW_SEARCH_KEYS.forEach(function (sk) {
             let p = sk[1];
             if (raw[p]) {
@@ -10324,7 +10492,7 @@ function (root, d3, forester, phyloXml) {
         // own bottom rows (conservation, consensus, ruler) must end above it
         // or the bar covers them -- the old bare slider did exactly that.
         // The scale bar sits in the same band, under the tree's last row.
-        return Math.max(msaShown() ? MSA_BOTTOM_RESERVE + MSA_NAV_RESERVE : 0, timeAxisBottomReserve(),
+        return Math.max(msaShown() ? msaBottomReserve() + MSA_NAV_RESERVE : 0, timeAxisBottomReserve(),
             heatmapBottomReserve(),
             scaleBarShown() && !radialDisplay() ? SCALE_BAR_RESERVE : 0);
     }
@@ -11793,6 +11961,11 @@ function (root, d3, forester, phyloXml) {
         if (msaCb) {
             msaCb.disabled = radialDisplay();
         }
+        let msaLogoCb = byId(MSA_LOGO_CB);
+        if (msaLogoCb) {
+            // nothing to summarize while the alignment itself is not drawn
+            msaLogoCb.disabled = radialDisplay() || _state.showMsa !== true;
+        }
         let heatCb = byId(HEATMAP_CB);
         if (heatCb) {
             // circular draws the columns as rings; only unrooted cannot
@@ -14093,6 +14266,7 @@ function (root, d3, forester, phyloXml) {
 
         on(DYNAHIDE_CB, 'click', dynaHideCbClicked);
         on(MSA_CB, 'click', msaCbClicked);
+        on(MSA_LOGO_CB, 'click', msaLogoCbClicked);
         on(HEATMAP_CB, 'click', heatmapCbClicked);
         on(HEATMAP_ORDER_SELECT, 'change', heatmapOrderChanged);
         on(HEATMAP_REORDER_BUTTON, 'click', showHeatmapReorderDialog);
@@ -14637,6 +14811,7 @@ function (root, d3, forester, phyloXml) {
             // labels -- they live here
             if (_basicTreeProperties.alignedMolSeqs && _basicTreeProperties.maxMolSeqLength > 0) {
                 opts.push(makeCheckboxItem('Alignment', MSA_CB, 'to show/hide the sequence alignment beside the tree (rectangular layout only)'));
+                opts.push(makeCheckboxItem('Sequence Logo', MSA_LOGO_CB, 'to summarize the alignment under it as a sequence logo: each column a stack of letters, as tall as that column\'s information content and shared out by residue frequency. Over the tips currently on screen, so entering a clade summarizes that clade'));
             }
             if (_basicTreeProperties.domainArchitectures) {
                 opts.push(makeCheckboxItem('Domain Architectures', DOMAINS_CB, 'to show/hide the protein domain architectures beside the tips', true));
@@ -14971,6 +15146,7 @@ function (root, d3, forester, phyloXml) {
         setCheckboxValue(VIS_CB, _state.showVisualizations);
         setCheckboxValue(DYNAHIDE_CB, _state.dynahide);
         setCheckboxValue(MSA_CB, _state.showMsa);
+        setCheckboxValue(MSA_LOGO_CB, _state.showMsaLogo === true);
         setCheckboxValue(HEATMAP_CB, _state.showHeatmap);
         syncDomainControls();
         syncHeatmapControls();

package/forester.js

@@ -20,7 +20,7 @@
  *
  */
 
-// v 3.11.0
+// v 3.12.0
 // 2026-09-17
 //
 // forester.js is a general suite for dealing with phylogenetic trees.
@@ -8440,6 +8440,70 @@
         return {scores: scores, consensus: consensus};
     };
 
+    // Per-column sequence logo over the given rows -- the stack of letters
+    // whose total height is the column's information content in BITS and whose
+    // shares are the residue frequencies (Schneider & Stephens 1990), which is
+    // the display the MEME Suite and WebLogo draw.
+    //
+    // No small-sample correction. Schneider's e_n = (K-1)/(2 ln2 n) is meant
+    // for a motif sampled from many sequences; here the rows are the tips
+    // currently on screen, so n is routinely 3 or 4 -- and for protein at n=3
+    // the correction (4.57 bits) EXCEEDS the maximum (4.32), so a perfectly
+    // conserved column of a small clade would draw nothing at all, exactly
+    // when the reader has asked about that clade. The caller names n instead.
+    //
+    // Gaps are not a letter: frequencies are taken over the non-gap residues,
+    // and the stack is then scaled by the column's occupancy, so a column held
+    // up by two residues out of fifty is short rather than perfectly conserved.
+    // `bits` and `occupancy` are returned separately so a caller can say which
+    // of the two made a column short.
+    //
+    // Letters come back most frequent FIRST, ties broken alphabetically, so a
+    // figure is reproducible rather than at the mercy of key order.
+    forester.msaLogo = function (rows, length, nucleotide) {
+        let maxBits = Math.log(nucleotide ? 4 : 20) / Math.LN2;
+        if (!(length >= 0) || !isFinite(length)) {
+            return {columns: [], maxBits: maxBits};
+        }
+        length = Math.floor(length);
+        let n = rows.length;
+        let columns = new Array(length);
+        for (let c = 0; c < length; ++c) {
+            let counts = {};
+            let nonGap = 0;
+            for (let r = 0; r < n; ++r) {
+                let row = rows[r];
+                let ch = (row && c < row.length) ? row.charAt(c) : '-';
+                if (forester.isMsaGap(ch)) {
+                    continue;
+                }
+                ch = ch.toUpperCase();
+                ++nonGap;
+                counts[ch] = (counts[ch] || 0) + 1;
+            }
+            if (n < 1 || nonGap < 1) {
+                columns[c] = {bits: 0, occupancy: 0, height: 0, letters: []};
+                continue;
+            }
+            let H = 0;
+            Object.keys(counts).forEach(function (ch) {
+                let p = counts[ch] / nonGap;
+                H -= p * (Math.log(p) / Math.LN2);
+            });
+            let bits = Math.max(0, maxBits - H);
+            let occupancy = nonGap / n;
+            let height = bits * occupancy;
+            let letters = Object.keys(counts).sort().sort(function (a, b) {
+                return counts[b] - counts[a];   // count first, alphabetical within a tie
+            }).map(function (ch) {
+                let p = counts[ch] / nonGap;
+                return {ch: ch, p: p, h: p * height};
+            });
+            columns[c] = {bits: bits, occupancy: occupancy, height: height, letters: letters};
+        }
+        return {columns: columns, maxBits: maxBits};
+    };
+
     // The hover readout's description of one residue: full name, class (amino
     // acids), Kyte-Doolittle hydropathy. Returns null for a gap.
     forester.msaResidueInfo = function (ch, nucleotide) {

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "archaeopteryx",
-  "version": "3.11.0",
+  "version": "3.12.0",
   "description": "Archaeopteryx.js is a software tool for the visualization and analysis of highly annotated phylogenetic trees.",
   "main": "archaeopteryx.js",
   "types": "archaeopteryx.d.ts",