react-msaview 8.3.0 → 8.4.1

package/src/model.ts

@@ -26,9 +26,10 @@ import {
   parseNewick,
 } from 'msa-parsers'
 
+import { blockFasta } from './blockFasta.ts'
 import { calculateBlocks } from './calculateBlocks.ts'
 import { clustalXColumnColors } from './clustalX.ts'
-import colorSchemes from './colorSchemes.ts'
+import colorSchemes, { letterColorTable } from './colorSchemes.ts'
 import { columnCountsFromRows, letterOfResidueSlot } from './columnCounts.ts'
 import { columnStats } from './columnStats.ts'
 import { packDomainLanes } from './components/msa/packDomainLanes.ts'
@@ -58,7 +59,7 @@ import {
   defaultTreeWidth,
   labelReferenceFontSize,
   maxCellSize,
-  maxInlineSnapshotBytes,
+  maxInlineSnapshotBytes as defaultMaxInlineSnapshotBytes,
   maxNeighborJoiningRows,
   minColWidth,
   minLetterColWidth,
@@ -74,6 +75,7 @@ import {
 import { createPaletteMap } from './createPaletteMap.ts'
 import { exportFileName } from './exportFileName.ts'
 import { featureField, featureName } from './featureFields.ts'
+import { featuresToAnnotations } from './featuresLayer.ts'
 import { fetchTextWithProgress, isAbortError } from './fetchUtils.ts'
 import { flatToTree } from './flatToTree.ts'
 import {
@@ -142,9 +144,11 @@ import type {
   DomainBand,
   Encoding,
   EncodingChannel,
+  Feature,
   Highlight,
   Legend,
   LegendEntry,
+  MsaSelection,
   NodeWithIds,
   Region,
   ResidueMapping,
@@ -153,12 +157,14 @@ import type {
   ResolvedEncoding,
   ResolvedFeaturePanel,
   ResolvedHighlight,
+  ResolvedSelection,
   TreeOrder,
   TreeRoot,
   ResolvedRowPanel,
   ResolvedStripPanel,
   RowFeaturesSpec,
   RowPanelSpan,
+  RowDataInput,
   RowPanelSpec,
   RowResidue,
   StructureResidue,
@@ -225,6 +231,23 @@ function rowPanelWidth(panel: RowPanelSpec, view: { rowHeight: number }) {
   )
 }
 
+// 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: unknown) {
+  if (typeof row !== 'object' || row === null) {
+    return undefined
+  }
+  const fields: Record<string, string> = {}
+  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: Record<string, Record<string, string> | undefined>,
@@ -425,18 +448,23 @@ function featurePanelSpans({
   )
 }
 
-// a scale over the values a field takes across the features drawn
+// 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: string,
   scale: ScaleSpec | undefined,
   annotations: Annotation[],
+  drawn: Annotation[],
 ) {
+  const valuesOf = (list: Annotation[]) =>
+    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)),
   }
 }
 
@@ -457,7 +485,10 @@ function columnTrackSizes(tracks?: readonly ColumnTrackSpec[]) {
   return (tracks ?? []).map(columnTrackSize)
 }
 
-function smallColumnTracks(tracks?: ColumnTrackSpec[]) {
+function smallColumnTracks(
+  tracks: ColumnTrackSpec[] | undefined,
+  maxInlineSnapshotBytes: number,
+) {
   const sizes = columnTrackSizes(tracks)
   const kept = tracks?.filter((_t, i) => sizes[i]! <= maxInlineSnapshotBytes)
   return kept?.length ? { columnTracks: kept } : {}
@@ -484,6 +515,7 @@ export const preservedOnReset = new Set([
   'scrollZoomAxis',
   'bgColor',
   'colorSchemeName',
+  'customColorScheme',
   'showColumnStats',
   'drawLabels',
   'labelsAlignRight',
@@ -752,6 +784,20 @@ function inRanges(ranges: [number, number][] | undefined, position: number) {
   return !!ranges?.some(([start, end]) => position >= start && position <= end)
 }
 
+// sorted integers as inclusive [first, last] runs of consecutive values
+function consecutiveRuns(sorted: number[]) {
+  const runs: [number, number][] = []
+  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: (string | undefined)[]) {
@@ -794,8 +840,15 @@ function preorder(tree: NodeWithIds) {
  * 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,
+}: { maxInlineSnapshotBytes?: number } = {}) {
   return types
     .compose(
       DialogQueueSessionMixin(),
@@ -991,7 +1044,7 @@ function stateModelFactory() {
          * data from the loaded tree/msa/treeMetadata, generally loaded by
          * autorun
          */
-        data: types.optional(DataModelF(), {}),
+        data: types.optional(DataModelF(maxInlineSnapshotBytes), {}),
 
         /**
          * #property
@@ -1022,6 +1075,21 @@ function stateModelFactory() {
          * Persists in the snapshot and the URL.
          */
         highlights: stripDefault(types.array(types.frozen<Highlight>()), []),
+        /**
+         * #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<Feature>()), []),
+        /**
+         * #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<MsaSelection | undefined>(),
         /**
          * #property
          * where the view opens, in `highlights` coordinates: `{row, start,
@@ -1322,6 +1390,33 @@ function stateModelFactory() {
       setHighlights(highlights: Highlight[]) {
         self.highlights.replace(highlights)
       },
+      /**
+       * #action
+       */
+      setFeatures(features: Feature[]) {
+        self.features.replace(features)
+      },
+      /**
+       * #action
+       * select a block, in `selection` coordinates. `start` and `end` may come
+       * in either order.
+       */
+      setSelection(selection?: MsaSelection) {
+        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
@@ -1493,28 +1588,28 @@ function stateModelFactory() {
        * #action
        */
       setMSAFilehandle(msaFilehandle?: FileLocationType) {
-        self.msaFilehandle = msaFilehandle
+        self.msaFilehandle = cast(msaFilehandle)
       },
 
       /**
        * #action
        */
       setTreeFilehandle(treeFilehandle?: FileLocationType) {
-        self.treeFilehandle = treeFilehandle
+        self.treeFilehandle = cast(treeFilehandle)
       },
 
       /**
        * #action
        */
       setTreeMetadataFilehandle(treeMetadataFilehandle?: FileLocationType) {
-        self.treeMetadataFilehandle = treeMetadataFilehandle
+        self.treeMetadataFilehandle = cast(treeMetadataFilehandle)
       },
 
       /**
        * #action
        */
       setGFFFilehandle(gffFilehandle?: FileLocationType) {
-        self.gffFilehandle = gffFilehandle
+        self.gffFilehandle = cast(gffFilehandle)
       },
 
       /**
@@ -1543,9 +1638,9 @@ 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: string) {
+      setGFF(result?: string) {
         self.data.setGFF(result)
       },
     }))
@@ -1567,11 +1662,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(): Annotation[] {
+        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
@@ -1605,12 +1710,26 @@ 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
       },
 
       /**
@@ -1633,7 +1752,7 @@ function stateModelFactory() {
         return !!this.tree.noTree
       },
       get noDomains() {
-        return self.annotations.length === 0
+        return self.allAnnotations.length === 0
       },
 
       /**
@@ -1642,9 +1761,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.
        *
@@ -1687,7 +1806,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(): Record<string, Record<string, string> | undefined> {
         const text = self.data.treeMetadata
@@ -1697,7 +1817,12 @@ function stateModelFactory() {
         try {
           const parsed: unknown = JSON.parse(text)
           return typeof parsed === 'object' && parsed !== null
-            ? (parsed as Record<string, Record<string, string> | undefined>)
+            ? Object.fromEntries(
+                Object.entries(parsed).map(([name, row]) => [
+                  name,
+                  stringFields(row),
+                ]),
+              )
             : {}
         } catch (e) {
           console.error('failed to parse rowData', e)
@@ -3101,7 +3226,7 @@ function stateModelFactory() {
         // first occurrence wins; only name, description and segment start are
         // read from it
         const types = new Map<string, Annotation>()
-        for (const annot of self.annotations) {
+        for (const annot of self.allAnnotations) {
           if (!types.has(annot.accession)) {
             types.set(annot.accession, annot)
           }
@@ -3109,7 +3234,7 @@ function stateModelFactory() {
         return types
       },
       get filteredAnnotations() {
-        return self.annotations.filter(
+        return self.allAnnotations.filter(
           r => !self.turnedOffFeatures.get(r.accession),
         )
       },
@@ -3531,7 +3656,7 @@ function stateModelFactory() {
        * replace the row table, which the model keeps as the JSON string
        * `data.treeMetadata` (see docs/layers.md)
        */
-      setRowData(rowData: Record<string, Record<string, string>>) {
+      setRowData(rowData: RowDataInput) {
         self.data.setTreeMetadata(JSON.stringify(rowData))
       },
       /**
@@ -3923,19 +4048,9 @@ function stateModelFactory() {
        * on every mouse move.
        */
       get highlightedColumnRuns() {
-        const { highlightedColumns } = self
-        const runs: { start: number; end: number }[] = []
-        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 }))
       },
 
       /**
@@ -3991,6 +4106,85 @@ function stateModelFactory() {
         })
       },
 
+      /**
+       * #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(): ResolvedSelection | undefined {
+        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] as [number, number]]
+            : []
+        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] as const]
+          })
+        return blockFasta(rows, span.start, span.end)
+      },
+
       /**
        * #method
        * per-column summary statistics: consensus residue and its identity
@@ -4021,23 +4215,25 @@ 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(): ResolvedEncoding[] {
         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),
+              )),
         }))
       },
 
@@ -4055,7 +4251,12 @@ 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 {
@@ -4386,6 +4587,63 @@ function stateModelFactory() {
           )
         })
       },
+      /**
+       * #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: { col: number; row?: number },
+        head: { col: number; row?: number },
+      ) {
+        const { numColumns, numRows, rowNames } = self
+        if (numColumns === 0 || numRows === 0) {
+          return
+        }
+        const ordered = (a: number, b: number, last: number) =>
+          [clamp(a, 0, last), clamp(b, 0, last)].sort((x, y) => x - y) as [
+            number,
+            number,
+          ]
+        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
        */
@@ -4667,7 +4925,7 @@ function stateModelFactory() {
         addDisposer(
           self,
           autorun(() => {
-            if (self.colorSchemeName.includes('dynamic')) {
+            if (self.dynamicColorSchemeName) {
               // eslint-disable-next-line  @typescript-eslint/no-unused-expressions
               self.colStats
             }
@@ -4736,7 +4994,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 }),