react-msaview 8.3.0 → 8.4.0

package/dist/model.js

@@ -4,9 +4,10 @@ import { ElementId, FileLocation } from '@jbrowse/core/util/types/mst';
 import { addDisposer, applySnapshot, cast, getSnapshot, isAlive, types, } from '@jbrowse/mobx-state-tree';
 import { autorun, compareStructural, computed, reaction, transaction, } from 'mobx';
 import { generateNodeIds, gffToAnnotations, interProScanToAnnotations, parseEmfTree, parseGFF, parseMSA, parseNewick, } from 'msa-parsers';
+import { blockFasta } from './blockFasta.js';
 import { calculateBlocks } from './calculateBlocks.js';
 import { clustalXColumnColors } from './clustalX.js';
-import colorSchemes from './colorSchemes.js';
+import colorSchemes, { letterColorTable } from './colorSchemes.js';
 import { columnCountsFromRows, letterOfResidueSlot } from './columnCounts.js';
 import { columnStats } from './columnStats.js';
 import { packDomainLanes } from './components/msa/packDomainLanes.js';
@@ -14,10 +15,11 @@ import { visibleColRange } from './components/msa/visibleColRange.js';
 import TrackBlocks from './components/tracks/TrackBlocks.js';
 import { cladeGutterWidth } from './components/tree/cladeBrackets.js';
 import { scaleBarLength } from './components/tree/scaleBar.js';
-import { cladeHighlightAlpha, cladeHighlightColor, defaultAllowedGappyness, defaultColWidth, defaultColorSchemeName, defaultCurrentAlignment, defaultDrawMsaLetters, defaultFeaturePanelWidth, defaultHeight, defaultHideGaps, defaultRowHeight, defaultScrollX, defaultScrollY, defaultScrollZoom, defaultScrollZoomAxis, defaultShowDomainLegend, defaultShowDomains, defaultSubFeatureRows, defaultTreeWidth, labelReferenceFontSize, maxCellSize, maxInlineSnapshotBytes, maxNeighborJoiningRows, minColWidth, minLetterColWidth, minLetterRowHeight, minRowHeight, rowPanelHeaderHeight, rowTintAlpha, scrollZoomAxes, segmentFeatureTypes, segmentShades, treeScaleBarHeight, } from './constants.js';
+import { cladeHighlightAlpha, cladeHighlightColor, defaultAllowedGappyness, defaultColWidth, defaultColorSchemeName, defaultCurrentAlignment, defaultDrawMsaLetters, defaultFeaturePanelWidth, defaultHeight, defaultHideGaps, defaultRowHeight, defaultScrollX, defaultScrollY, defaultScrollZoom, defaultScrollZoomAxis, defaultShowDomainLegend, defaultShowDomains, defaultSubFeatureRows, defaultTreeWidth, labelReferenceFontSize, maxCellSize, maxInlineSnapshotBytes as defaultMaxInlineSnapshotBytes, maxNeighborJoiningRows, minColWidth, minLetterColWidth, minLetterRowHeight, minRowHeight, rowPanelHeaderHeight, rowTintAlpha, scrollZoomAxes, segmentFeatureTypes, segmentShades, treeScaleBarHeight, } from './constants.js';
 import { createPaletteMap } from './createPaletteMap.js';
 import { exportFileName } from './exportFileName.js';
 import { featureField, featureName } from './featureFields.js';
+import { featuresToAnnotations } from './featuresLayer.js';
 import { fetchTextWithProgress, isAbortError } from './fetchUtils.js';
 import { flatToTree } from './flatToTree.js';
 import { calcDepthToLeaf, clusterLayout, collapse, find, forEachDescendant, hierarchy, layoutTree, leafIndex, leaves, maxLength, mrca, nodeCoveringRows, setBrLength, sort, sum as hierarchySum, } from './hierarchy.js';
@@ -82,6 +84,23 @@ function rowPanelWidth(panel, view) {
     return (panel.width ??
         (panel.kind === 'features' ? defaultFeaturePanelWidth : view.rowHeight));
 }
+// one row of the row table as the channels read it. A number or a boolean
+// reads as its string, the way a GFF value does, and null or an object drops
+function stringFields(row) {
+    if (typeof row !== 'object' || row === null) {
+        return undefined;
+    }
+    const fields = {};
+    for (const [field, value] of Object.entries(row)) {
+        if (typeof value === 'string') {
+            fields[field] = value;
+        }
+        else if (typeof value === 'number' || typeof value === 'boolean') {
+            fields[field] = String(value);
+        }
+    }
+    return fields;
+}
 // the color each row takes from a field of the row table under a scale
 function colorByRow(rowData, field, colorOf) {
     const colors = new Map();
@@ -218,11 +237,17 @@ function featurePanelSpans({ panel, width, colWidth, domainBands, annotationsByR
         })),
     ]));
 }
-// a scale over the values a field takes across the features drawn
-function resolveFeatureScale(field, scale, annotations) {
+// a scale over the values a field takes across every feature loaded, so hiding
+// a type in the filter dialog leaves the rest in their colors, and a legend of
+// the values the features drawn carry
+function resolveFeatureScale(field, scale, annotations, drawn) {
+    const valuesOf = (list) => list.map(a => featureField(a, field)).filter(notEmpty);
+    const resolved = resolveScale(scale, valuesOf(annotations));
+    const shown = new Set(valuesOf(drawn));
     return {
         field,
-        ...resolveScale(scale, annotations.map(a => featureField(a, field)).filter(notEmpty)),
+        ...resolved,
+        legend: resolved.legend.filter(entry => shown.has(entry.id)),
     };
 }
 const columnTrackBytes = new WeakMap();
@@ -239,7 +264,7 @@ function columnTrackSize(track) {
 function columnTrackSizes(tracks) {
     return (tracks ?? []).map(columnTrackSize);
 }
-function smallColumnTracks(tracks) {
+function smallColumnTracks(tracks, maxInlineSnapshotBytes) {
     const sizes = columnTrackSizes(tracks);
     const kept = tracks?.filter((_t, i) => sizes[i] <= maxInlineSnapshotBytes);
     return kept?.length ? { columnTracks: kept } : {};
@@ -265,6 +290,7 @@ export const preservedOnReset = new Set([
     'scrollZoomAxis',
     'bgColor',
     'colorSchemeName',
+    'customColorScheme',
     'showColumnStats',
     'drawLabels',
     'labelsAlignRight',
@@ -474,6 +500,20 @@ function overflows(content, viewport) {
 function inRanges(ranges, position) {
     return !!ranges?.some(([start, end]) => position >= start && position <= end);
 }
+// sorted integers as inclusive [first, last] runs of consecutive values
+function consecutiveRuns(sorted) {
+    const runs = [];
+    for (const n of sorted) {
+        const last = runs.at(-1);
+        if (last && n <= last[1] + 1) {
+            last[1] = Math.max(last[1], n);
+        }
+        else {
+            runs.push([n, n]);
+        }
+    }
+    return runs;
+}
 // the value every one of a node's children reports, or undefined where one of
 // them has no value or they disagree
 function sharedValue(values) {
@@ -514,8 +554,13 @@ function preorder(tree) {
  * const root = RootModel.create({})
  * root.view.setData({ msa: '>seq1\nACGT\n>seq2\nACGT' })
  * ```
+ *
+ * `maxInlineSnapshotBytes` is the largest pasted or local document, and the
+ * largest data track, the snapshot keeps; a larger one stays in the live model
+ * and `unshareableData` names it. The standalone app, whose links carry the
+ * snapshot in the URL fragment, raises it.
  */
-function stateModelFactory() {
+function stateModelFactory({ maxInlineSnapshotBytes = defaultMaxInlineSnapshotBytes, } = {}) {
     return types
         .compose(DialogQueueSessionMixin(), TreeModelF(), MSAModelF(), types.model('MsaView', {
         /**
@@ -676,7 +721,7 @@ function stateModelFactory() {
          * data from the loaded tree/msa/treeMetadata, generally loaded by
          * autorun
          */
-        data: types.optional(DataModelF(), {}),
+        data: types.optional(DataModelF(maxInlineSnapshotBytes), {}),
         /**
          * #property
          * the user's explicit hide choices per annotation accession, keyed by
@@ -706,6 +751,21 @@ function stateModelFactory() {
          * Persists in the snapshot and the URL.
          */
         highlights: stripDefault(types.array(types.frozen()), []),
+        /**
+         * #property
+         * features on the rows as data, `{row, start, end, name, ...}` in
+         * residues of each row, drawn with the GFF's annotations. Persists in
+         * the snapshot and the URL.
+         */
+        features: stripDefault(types.array(types.frozen()), []),
+        /**
+         * #property
+         * the block the reader selected: `{start, end}` columns of the file,
+         * 1-based inclusive like a column highlight, and `rows` by name, every
+         * row where absent. Undefined until something is selected, so a view
+         * without one adds nothing to the shared URL.
+         */
+        selection: types.frozen(),
         /**
          * #property
          * where the view opens, in `highlights` coordinates: `{row, start,
@@ -980,6 +1040,33 @@ function stateModelFactory() {
         setHighlights(highlights) {
             self.highlights.replace(highlights);
         },
+        /**
+         * #action
+         */
+        setFeatures(features) {
+            self.features.replace(features);
+        },
+        /**
+         * #action
+         * select a block, in `selection` coordinates. `start` and `end` may come
+         * in either order.
+         */
+        setSelection(selection) {
+            const next = selection && {
+                start: Math.min(selection.start, selection.end),
+                end: Math.max(selection.start, selection.end),
+                ...(selection.rows ? { rows: selection.rows } : {}),
+            };
+            if (!compareStructural(next, self.selection)) {
+                self.selection = next;
+            }
+        },
+        /**
+         * #action
+         */
+        clearSelection() {
+            this.setSelection(undefined);
+        },
         /**
          * #action
          * replace the clades the viewer marks (see docs/layers.md)
@@ -1180,7 +1267,7 @@ function stateModelFactory() {
          * store the GFF text in the snapshot like the alignment and tree. The
          * parsed annotations are volatile and a blob filehandle is cleared once
          * read, so the text is the only persisted copy. An autorun parses it
-         * into annotations.
+         * into annotations, and clears the ones it drew when the text goes.
          */
         setGFF(result) {
             self.data.setGFF(result);
@@ -1201,11 +1288,21 @@ function stateModelFactory() {
         get realAllowedGappyness() {
             return this.hideGapsEffective ? self.allowedGappyness : 100;
         },
+        /**
+         * #getter
+         * the annotations the overlay, the legend and the encodings draw: the
+         * GFF's, then the `features` layer's
+         */
+        get allAnnotations() {
+            return self.features.length > 0
+                ? [...self.annotations, ...featuresToAnnotations(self.features)]
+                : self.annotations;
+        },
         /**
          * #getter
          */
         get actuallyShowDomains() {
-            return self.showDomains && self.annotations.length > 0;
+            return self.showDomains && this.allAnnotations.length > 0;
         },
         /**
          * #getter
@@ -1239,10 +1336,25 @@ function stateModelFactory() {
          * #getter
          */
         get colorScheme() {
+            const { customColorScheme, colorSchemeName } = self;
             // colorSchemeName is a free string (menus, snapshots, URL params), so a
             // stale name falls back to the default
-            return (colorSchemes[self.colorSchemeName] ??
-                colorSchemes[defaultColorSchemeName]);
+            return customColorScheme
+                ? letterColorTable(customColorScheme)
+                : (colorSchemes[colorSchemeName] ??
+                    colorSchemes[defaultColorSchemeName]);
+        },
+        /**
+         * #getter
+         * the scheme coloring each cell from its column's statistics, or
+         * undefined while the cells take a fixed color per letter, from the
+         * built-in table or from `customColorScheme`
+         */
+        get dynamicColorSchemeName() {
+            const { customColorScheme, colorSchemeName } = self;
+            return !customColorScheme && colorSchemeName.includes('dynamic')
+                ? colorSchemeName
+                : undefined;
         },
         /**
          * #getter
@@ -1263,7 +1375,7 @@ function stateModelFactory() {
             return !!this.tree.noTree;
         },
         get noDomains() {
-            return self.annotations.length === 0;
+            return self.allAnnotations.length === 0;
         },
         /**
          * #getter
@@ -1271,9 +1383,9 @@ function stateModelFactory() {
          * from disk or pasted in becomes inline text, and DataModel drops an
          * inline document past `maxInlineSnapshotBytes`.
          *
-         * The header lists these, and the standalone app drops `?data=` from
+         * The header lists these, and the standalone app drops `#data=` from
          * the address bar while the list is non-empty or the encoded link would
-         * pass 8,000 characters, so a copied link never opens an empty viewer
+         * pass its `maxLinkLength`, so a copied link never opens an empty viewer
          * unannounced. A document fetched from a URL never appears here, since
          * the snapshot keeps its filehandle.
          *
@@ -1310,7 +1422,8 @@ function stateModelFactory() {
          * `data.treeMetadata`, the name that travels in existing links, so the
          * inline size limit and `treeMetadataFilehandle` cover it. labelWidthMap
          * reads it on every layout, so a malformed user-supplied file returns {}
-         * instead of throwing out of rendering.
+         * instead of throwing out of rendering, and every field is a string by
+         * the time a scale sorts it.
          */
         get rowData() {
             const text = self.data.treeMetadata;
@@ -1320,7 +1433,10 @@ function stateModelFactory() {
             try {
                 const parsed = JSON.parse(text);
                 return typeof parsed === 'object' && parsed !== null
-                    ? parsed
+                    ? Object.fromEntries(Object.entries(parsed).map(([name, row]) => [
+                        name,
+                        stringFields(row),
+                    ]))
                     : {};
             }
             catch (e) {
@@ -2586,7 +2702,7 @@ function stateModelFactory() {
             // first occurrence wins; only name, description and segment start are
             // read from it
             const types = new Map();
-            for (const annot of self.annotations) {
+            for (const annot of self.allAnnotations) {
                 if (!types.has(annot.accession)) {
                     types.set(annot.accession, annot);
                 }
@@ -2594,7 +2710,7 @@ function stateModelFactory() {
             return types;
         },
         get filteredAnnotations() {
-            return self.annotations.filter(r => !self.turnedOffFeatures.get(r.accession));
+            return self.allAnnotations.filter(r => !self.turnedOffFeatures.get(r.accession));
         },
         get annotationsByRow() {
             return groupBy(this.filteredAnnotations, r => r.id);
@@ -3306,18 +3422,7 @@ function stateModelFactory() {
          * on every mouse move.
          */
         get highlightedColumnRuns() {
-            const { highlightedColumns } = self;
-            const runs = [];
-            for (const col of [...(highlightedColumns ?? [])].sort((a, b) => a - b)) {
-                const last = runs.at(-1);
-                if (last && col === last.end + 1) {
-                    last.end = col;
-                }
-                else {
-                    runs.push({ start: col, end: col });
-                }
-            }
-            return runs;
+            return consecutiveRuns([...(self.highlightedColumns ?? [])].sort((a, b) => a - b)).map(([start, end]) => ({ start, end }));
         },
         /**
          * #method
@@ -3368,6 +3473,78 @@ function stateModelFactory() {
                 return span ? [{ ...base, ...span, rowIndices: [] }] : [];
             });
         },
+        /**
+         * #getter
+         * `selection` projected onto what is on screen, the way
+         * `resolvedHighlights` projects a column span and a row set. A
+         * selection whose columns are all hidden, or whose rows are all
+         * collapsed away or unknown, resolves to undefined.
+         */
+        get resolvedSelection() {
+            const { selection, rowNamesSet, numRows } = self;
+            const span = selection &&
+                self.visibleSpan({ start: selection.start, end: selection.end });
+            if (!selection || !span) {
+                return undefined;
+            }
+            const rowRuns = selection.rows
+                ? consecutiveRuns(selection.rows
+                    .map(name => rowNamesSet.get(name))
+                    .filter(notEmpty)
+                    .sort((a, b) => a - b))
+                : numRows > 0
+                    ? [[0, numRows - 1]]
+                    : [];
+            return rowRuns.length > 0 ? { ...span, rowRuns } : undefined;
+        },
+        /**
+         * #getter
+         * the columns and rows the selection covers, for the header's readout.
+         * Columns count the file's columns from `start` to `end`, hidden ones
+         * included, as `selectionFasta` copies them.
+         */
+        get selectionSize() {
+            const resolved = this.resolvedSelection;
+            const span = this.selectionFileSpan;
+            return resolved && span
+                ? {
+                    columns: span.end - span.start + 1,
+                    rows: sum(resolved.rowRuns.map(([a, b]) => b - a + 1)),
+                }
+                : undefined;
+        },
+        /**
+         * #getter
+         * `selection`'s columns clamped to the file's
+         */
+        get selectionFileSpan() {
+            const { selection } = self;
+            const width = self.MSA?.getWidth() ?? 0;
+            const start = Math.max(1, Math.floor(selection?.start ?? 0));
+            const end = Math.min(width, Math.ceil(selection?.end ?? 0));
+            return selection && start <= end ? { start, end } : undefined;
+        },
+        /**
+         * #getter
+         * the selected block as FASTA: the selected rows on screen, top to
+         * bottom, each with its letters across the file's columns from `start`
+         * to `end`, gaps included
+         */
+        get selectionFasta() {
+            const { rowNames, rowMap } = self;
+            const resolved = this.resolvedSelection;
+            const span = this.selectionFileSpan;
+            if (!resolved || !span) {
+                return '';
+            }
+            const rows = resolved.rowRuns
+                .flatMap(([first, last]) => rowNames.slice(first, last + 1))
+                .flatMap(name => {
+                const seq = rowMap.get(name);
+                return seq === undefined ? [] : [[name, seq]];
+            });
+            return blockFasta(rows, span.start, span.end);
+        },
         /**
          * #method
          * per-column summary statistics: consensus residue and its identity
@@ -3396,20 +3573,17 @@ function stateModelFactory() {
         /**
          * #getter
          * each encoding with its scale resolved against the values its field
-         * takes: a feature channel reads them across the features drawn, every
+         * takes: a feature channel reads them across every feature loaded, every
          * other channel across the row table. Resolved once per change of that
          * table or the encodings, never per row per frame.
          */
         get resolvedEncodings() {
             const rows = Object.values(self.rowData);
-            const features = self.filteredAnnotations;
             return self.encodings.map(encoding => ({
                 ...encoding,
-                ...resolveScale(encoding.scale, featureChannels.has(encoding.channel)
-                    ? features
-                        .map(a => featureField(a, encoding.field))
-                        .filter(notEmpty)
-                    : rows.map(row => row?.[encoding.field]).filter(notEmpty)),
+                ...(featureChannels.has(encoding.channel)
+                    ? resolveFeatureScale(encoding.field, encoding.scale, self.allAnnotations, self.filteredAnnotations)
+                    : resolveScale(encoding.scale, rows.map(row => row?.[encoding.field]).filter(notEmpty))),
             }));
         },
         /**
@@ -3426,7 +3600,7 @@ function stateModelFactory() {
                 if (panel.kind === 'features') {
                     const color = panel.encoding?.color;
                     const encoding = color
-                        ? resolveFeatureScale(color.field, color.scale, annotations)
+                        ? resolveFeatureScale(color.field, color.scale, self.allAnnotations, annotations)
                         : featureFillEncoding;
                     const label = panel.encoding?.label;
                     return {
@@ -3701,6 +3875,51 @@ function stateModelFactory() {
                 self.scrollX = clamp(-span.startCol * self.colWidth, self.maxScrollX, 0);
             });
         },
+        /**
+         * #action
+         * zoom and scroll so the selected columns fill the alignment's width,
+         * and, where the selection names its rows, so those rows fill its height
+         */
+        zoomToSelection() {
+            const { selection, resolvedSelection } = self;
+            if (!selection || !resolvedSelection) {
+                return;
+            }
+            transaction(() => {
+                this.zoomToRegion({ start: selection.start, end: selection.end });
+                if (selection.rows && self.viewInitialized) {
+                    const { rowRuns } = resolvedSelection;
+                    const first = rowRuns[0][0];
+                    const last = rowRuns.at(-1)[1];
+                    self.rowHeight = clamp(self.msaAreaHeight / (last - first + 1), minRowHeight, maxCellSize);
+                    self.scrollY = clamp(-first * self.rowHeight, self.maxScrollY, 0);
+                }
+            });
+        },
+        /**
+         * #action
+         * select the block between two cells given as visible column and row
+         * indices, the coordinates a drag reports, clamped to the alignment. A
+         * cell with no `row` selects the columns across every row, and so does a
+         * block spanning every row on screen.
+         */
+        selectBlock(anchor, head) {
+            const { numColumns, numRows, rowNames } = self;
+            if (numColumns === 0 || numRows === 0) {
+                return;
+            }
+            const ordered = (a, b, last) => [clamp(a, 0, last), clamp(b, 0, last)].sort((x, y) => x - y);
+            const [startCol, endCol] = ordered(anchor.col, head.col, numColumns - 1);
+            const [firstRow, lastRow] = anchor.row === undefined || head.row === undefined
+                ? [0, numRows - 1]
+                : ordered(anchor.row, head.row, numRows - 1);
+            const everyRow = firstRow === 0 && lastRow === numRows - 1;
+            self.setSelection({
+                start: self.visibleColToGlobalCol(startCol) + 1,
+                end: self.visibleColToGlobalCol(endCol) + 1,
+                ...(everyRow ? {} : { rows: rowNames.slice(firstRow, lastRow + 1) }),
+            });
+        },
         /**
          * #action
          */
@@ -3931,7 +4150,7 @@ function stateModelFactory() {
             // xref solution https://github.com/mobxjs/mobx/issues/266#issuecomment-222007278
             // xref problem https://github.com/GMOD/react-msaview/issues/75
             addDisposer(self, autorun(() => {
-                if (self.colorSchemeName.includes('dynamic')) {
+                if (self.dynamicColorSchemeName) {
                     // eslint-disable-next-line  @typescript-eslint/no-unused-expressions
                     self.colStats;
                 }
@@ -3981,7 +4200,7 @@ function stateModelFactory() {
         // stripDefault handles per-property defaults; this drops inline documents
         // whose filehandle can refetch them
         ...rest,
-        ...smallColumnTracks(columnTracks),
+        ...smallColumnTracks(columnTracks, maxInlineSnapshotBytes),
         data: {
             ...(rest.treeFilehandle ? {} : { tree: data.tree }),
             ...(rest.msaFilehandle ? {} : { msa: data.msa }),