react-msaview 5.4.1 → 5.6.0

package/src/model/treeModel.ts

@@ -19,25 +19,25 @@ export function TreeModelF() {
       /**
        * #property
        */
-      drawLabels: defaultDrawLabels,
+      drawLabels: types.stripDefault(types.boolean, defaultDrawLabels),
       /**
        * #property
        * right-align the labels
        */
-      labelsAlignRight: defaultLabelsAlignRight,
+      labelsAlignRight: types.stripDefault(types.boolean, defaultLabelsAlignRight),
 
       /**
        * #property
        * width of the area the tree is drawn in, px
        */
-      treeAreaWidth: types.optional(types.number, defaultTreeAreaWidth),
+      treeAreaWidth: types.stripDefault(types.number, defaultTreeAreaWidth),
 
       /**
        * #property
        * width of the tree within the treeArea, px. automatically synced to
        * fit within treeAreaWidth
        */
-      treeWidth: types.optional(types.number, defaultTreeWidth),
+      treeWidth: types.stripDefault(types.number, defaultTreeWidth),
 
       /**
        * #property
@@ -45,19 +45,27 @@ export function TreeModelF() {
        * lengths. if false, the layout is a "cladogram" that does not take into
        * account evolutionary distances
        */
-      showBranchLen: defaultShowBranchLen,
+      showBranchLen: types.stripDefault(types.boolean, defaultShowBranchLen),
 
       /**
        * #property
        * draw tree, boolean
        */
-      drawTree: defaultDrawTree,
+      drawTree: types.stripDefault(types.boolean, defaultDrawTree),
 
       /**
        * #property
        * draw clickable node bubbles on the tree
        */
-      drawNodeBubbles: defaultDrawNodeBubbles,
+      drawNodeBubbles: types.stripDefault(types.boolean, defaultDrawNodeBubbles),
+
+      /**
+       * #property
+       * auto-size treeAreaWidth to fit the row labels (plus the tree, if drawn)
+       * instead of using a fixed width. useful when there is no tree, so the
+       * label gutter isn't padded out to the default 400px
+       */
+      autoTreeAreaWidth: types.stripDefault(types.boolean, false),
     })
     .actions(self => ({
       /**
@@ -87,6 +95,12 @@ export function TreeModelF() {
       setDrawTree(arg: boolean) {
         self.drawTree = arg
       },
+      /**
+       * #action
+       */
+      setAutoTreeAreaWidth(arg: boolean) {
+        self.autoTreeAreaWidth = arg
+      },
 
       /**
        * #action

package/src/model.ts

@@ -20,29 +20,23 @@ import ConservationTrack from './components/ConservationTrack.tsx'
 import TextTrack from './components/TextTrack.tsx'
 import {
   defaultAllowedGappyness,
-  defaultBgColor,
   defaultColWidth,
   defaultColorSchemeName,
   defaultCurrentAlignment,
-  defaultDrawLabels,
   defaultDrawMsaLetters,
-  defaultDrawNodeBubbles,
-  defaultDrawTree,
   defaultHeight,
   defaultHideGaps,
-  defaultLabelsAlignRight,
   defaultRowHeight,
   defaultScrollX,
   defaultScrollY,
   defaultScrollZoom,
-  defaultShowBranchLen,
   defaultShowDomains,
   defaultSubFeatureRows,
-  defaultTreeAreaWidth,
-  defaultTreeWidth,
   maxCellSize,
   minColWidth,
   minRowHeight,
+  segmentFeatureTypes,
+  segmentShades,
 } from './constants.ts'
 import { createPaletteMap } from './createPaletteMap.ts'
 import { fetchTextWithProgress, isAbortError } from './fetchUtils.ts'
@@ -70,6 +64,7 @@ import { MSAModelF } from './model/msaModel.ts'
 import { TreeModelF } from './model/treeModel.ts'
 import { calculateNeighborJoiningTree } from './neighborJoining.ts'
 import { parseAsn1 } from './parseAsn1.ts'
+import { calculatePropertyConservation } from './propertyConservation.ts'
 import {
   globalColToVisibleCol,
   visibleColToGlobalCol,
@@ -95,6 +90,14 @@ function parseTreeText(text: string) {
 
 /**
  * #stateModel MsaView
+ *
+ * The main MSAView state model. Holds the loaded alignment, tree, and optional
+ * InterProScan domain annotations, plus all display state (color scheme, zoom,
+ * scroll, collapsed clades). It composes in members from `DialogQueueSessionMixin`,
+ * `Tree`, and `MSAModel` (see Inherited members below). Data is loaded reactively
+ * from the `msaFilehandle` / `treeFilehandle` / `gffFilehandle` properties, or set
+ * directly with `setData`. Most state is persisted into the shareable URL.
+ *
  * #example
  * ```js
  * import { MSAModelF } from 'react-msaview'
@@ -121,19 +124,22 @@ function stateModelFactory() {
         /**
          * #property
          */
-        showDomains: defaultShowDomains,
+        showDomains: types.stripDefault(types.boolean, defaultShowDomains),
         /**
          * #property
          */
-        hideGaps: defaultHideGaps,
+        hideGaps: types.stripDefault(types.boolean, defaultHideGaps),
         /**
          * #property
          */
-        allowedGappyness: defaultAllowedGappyness,
+        allowedGappyness: types.stripDefault(
+          types.number,
+          defaultAllowedGappyness,
+        ),
         /**
          * #property
          */
-        subFeatureRows: defaultSubFeatureRows,
+        subFeatureRows: types.stripDefault(types.boolean, defaultSubFeatureRows),
 
         /**
          * #property
@@ -144,43 +150,43 @@ function stateModelFactory() {
         /**
          * #property
          */
-        drawMsaLetters: defaultDrawMsaLetters,
+        drawMsaLetters: types.stripDefault(types.boolean, defaultDrawMsaLetters),
 
         /**
          * #property
          * zoom in/out on plain mouse-wheel without holding ctrl
          */
-        scrollZoom: defaultScrollZoom,
+        scrollZoom: types.stripDefault(types.boolean, defaultScrollZoom),
 
         /**
          * #property
          * height of the div containing the view, px
          */
-        height: types.optional(types.number, defaultHeight),
+        height: types.stripDefault(types.number, defaultHeight),
 
         /**
          * #property
          * height of each row, px
          */
-        rowHeight: defaultRowHeight,
+        rowHeight: types.stripDefault(types.number, defaultRowHeight),
 
         /**
          * #property
          * scroll position, Y-offset, px
          */
-        scrollY: defaultScrollY,
+        scrollY: types.stripDefault(types.number, defaultScrollY),
 
         /**
          * #property
          * scroll position, X-offset, px
          */
-        scrollX: defaultScrollX,
+        scrollX: types.stripDefault(types.number, defaultScrollX),
 
         /**
          * #property
          * width of columns, px
          */
-        colWidth: defaultColWidth,
+        colWidth: types.stripDefault(types.number, defaultColWidth),
 
         /**
          * #property
@@ -210,14 +216,17 @@ function stateModelFactory() {
         /**
          * #property
          */
-        currentAlignment: defaultCurrentAlignment,
+        currentAlignment: types.stripDefault(
+          types.number,
+          defaultCurrentAlignment,
+        ),
 
         /**
          * #property
          * array of tree parent nodes that are 'collapsed' (all children are
          * hidden)
          */
-        collapsed: types.array(types.string),
+        collapsed: types.stripDefault(types.array(types.string), []),
 
         /**
          * #property
@@ -228,7 +237,7 @@ function stateModelFactory() {
          * #property
          * turned off tracks
          */
-        turnedOffTracks: types.map(types.boolean),
+        turnedOffTracks: types.stripDefault(types.map(types.boolean), {}),
 
         /**
          * #property
@@ -244,7 +253,7 @@ function stateModelFactory() {
         /**
          * #property
          */
-        featureFilters: types.map(types.boolean),
+        featureFilters: types.stripDefault(types.map(types.boolean), {}),
         /**
          * #property
          */
@@ -269,8 +278,7 @@ function stateModelFactory() {
        * #volatile
        */
       status: undefined as
-        | { msg: string; url?: string; onCancel?: () => void }
-        | undefined,
+        { msg: string; url?: string; onCancel?: () => void } | undefined,
       /**
        * #volatile
        * high resolution scale factor, helps make canvas look better on hi-dpi
@@ -333,8 +341,7 @@ function stateModelFactory() {
        * the currently hovered tree node ID and its descendant leaf names
        */
       hoveredTreeNode: undefined as
-        | { nodeId: string; descendantNames: string[] }
-        | undefined,
+        { nodeId: string; descendantNames: string[] } | undefined,
 
       /**
        * #volatile
@@ -367,18 +374,20 @@ function stateModelFactory() {
        * #volatile
        */
       interProAnnotations: undefined as
-        | undefined
-        | Record<string, InterProScanResults>,
+        undefined | Record<string, InterProScanResults>,
     }))
     .actions(self => ({
       /**
        * #action
+       * draw the alignment with positions numbered relative to the given row's
+       * sequence (its node id), instead of in raw MSA-column coordinates
        */
       drawRelativeTo(id: string | undefined) {
         self.relativeTo = id
       },
       /**
        * #action
+       * hide columns that are entirely (or mostly, see allowedGappyness) gaps
        */
       setHideGaps(arg: boolean) {
         self.hideGaps = arg
@@ -457,6 +466,7 @@ function stateModelFactory() {
       },
       /**
        * #action
+       * toggle the InterProScan protein-domain overlay on the alignment
        */
       setShowDomains(arg: boolean) {
         self.showDomains = arg
@@ -510,6 +520,7 @@ function stateModelFactory() {
 
       /**
        * #action
+       * collapse or un-collapse the subtree rooted at the given tree node id
        */
       toggleCollapsed(node: string) {
         if (self.collapsed.includes(node)) {
@@ -521,6 +532,8 @@ function stateModelFactory() {
 
       /**
        * #action
+       * show only the subtree rooted at the given node id (pass undefined to
+       * show the whole tree again)
        */
       setShowOnly(node?: string) {
         self.showOnly = node
@@ -528,6 +541,8 @@ function stateModelFactory() {
 
       /**
        * #action
+       * set the alignment/tree/metadata/domain data directly from strings,
+       * bypassing the filehandle loaders
        */
       setData(data: {
         msa?: string
@@ -1025,6 +1040,17 @@ function stateModelFactory() {
           return conservation * (1 - gapFraction)
         })
       },
+      /**
+       * #getter
+       * Per-column conservation of physicochemical property class (amino acids
+       * only). Surfaces conservative-substitution sites that identity-based
+       * conservation misses. Empty for nucleotide alignments.
+       */
+      get propertyConservation() {
+        return this.sequenceType === 'amino'
+          ? calculatePropertyConservation(this.colStats, this.colStatsSums)
+          : []
+      },
       /**
        * #getter
        * generates a new tree that is clustered with x,y positions
@@ -1232,6 +1258,7 @@ function stateModelFactory() {
 
       /**
        * #action
+       * restore the default column width and row height
        */
       resetZoom() {
         self.setColWidth(defaultColWidth)
@@ -1446,10 +1473,24 @@ function stateModelFactory() {
             id: 'conservation',
             name: 'Conservation',
             height: self.conservationTrackHeight,
+            barColor: 'gray',
           },
           ReactComponent: ConservationTrack,
         }
-        return [...this.adapterTrackModels, conservationTrack]
+        const propertyConservationTrack: BasicTrack = {
+          model: {
+            id: 'property-conservation',
+            name: 'Property conservation',
+            height: self.conservationTrackHeight,
+            barColor: '#6a51a3',
+          },
+          ReactComponent: ConservationTrack,
+        }
+        return [
+          ...this.adapterTrackModels,
+          conservationTrack,
+          ...(self.sequenceType === 'amino' ? [propertyConservationTrack] : []),
+        ]
       },
 
       /**
@@ -1592,13 +1633,15 @@ function stateModelFactory() {
                 val.matches.flatMap(({ signature, locations }) => {
                   const { entry } = signature
                   return entry
-                    ? locations.map(({ start, end }) => ({
+                    ? locations.map(({ start, end, strand }) => ({
                         id,
                         name: entry.name,
                         accession: entry.accession,
                         description: entry.description,
+                        featureType: entry.featureType,
                         start,
                         end,
+                        strand,
                       }))
                     : []
                 }),
@@ -1630,8 +1673,38 @@ function stateModelFactory() {
       get verticalScrollbarWidth() {
         return self.showVerticalScrollbar ? 20 : 0
       },
+      /**
+       * #getter
+       * ordinal segment types (exons etc.), ordered by sequence position so
+       * exon-1..exon-14 read left-to-right; colored by alternating shade and
+       * labeled by number rather than each getting a distinct hue + legend row
+       */
+      get segmentDomainTypes() {
+        return [...self.tidyInterProAnnotationTypes.values()]
+          .filter(d => segmentFeatureTypes.has(d.featureType ?? ''))
+          .toSorted((a, b) => a.start - b.start)
+      },
+      /**
+       * #getter
+       * categorical feature types (InterPro domains and the like) that each get
+       * their own color and a legend entry
+       */
+      get categoricalDomainTypes() {
+        return [...self.tidyInterProAnnotationTypes.values()].filter(
+          d => !segmentFeatureTypes.has(d.featureType ?? ''),
+        )
+      },
       get fillPalette() {
-        return createPaletteMap([...self.tidyInterProAnnotationTypes.keys()])
+        const segments = Object.fromEntries(
+          this.segmentDomainTypes.map((d, i) => [
+            d.accession,
+            segmentShades[i % segmentShades.length]!,
+          ]),
+        )
+        const categorical = createPaletteMap(
+          this.categoricalDomainTypes.map(d => d.accession),
+        )
+        return { ...segments, ...categorical }
       },
       get strokePalette() {
         return transform(this.fillPalette, ([key, val]) => [
@@ -1640,6 +1713,92 @@ function stateModelFactory() {
         ])
       },
 
+      /**
+       * #getter
+       * accession -> number drawn on each segment band: the trailing number of
+       * the feature name ("exon-3" -> "3"), else its 1-based position
+       */
+      get segmentLabels() {
+        return new Map(
+          this.segmentDomainTypes.map((d, i) => {
+            const m = /(\d+)\s*$/.exec(d.name)
+            return [d.accession, m ? m[1]! : `${i + 1}`]
+          }),
+        )
+      },
+
+      /**
+       * #getter
+       * the domain types currently drawn on the alignment (filtered-on), shared
+       * by the on-screen legend and the SVG export legend. Ordinal segments
+       * (exons) are excluded — they read as a numbered gene model, not a color
+       * key — so this is the categorical types ordered by sequence position
+       */
+      get visibleDomainTypes() {
+        return this.categoricalDomainTypes
+          .filter(d => self.featureFilters.get(d.accession))
+          .toSorted((a, b) => a.start - b.start)
+      },
+
+      /**
+       * #getter
+       * domain annotations under the mouse, hit-tested against the exact visible
+       * column span each box is drawn at (so it matches the overlay across gaps)
+       */
+      get mouseOverDomains() {
+        const { mouseCol } = self
+        const name = self.mouseOverRowName
+        if (name !== undefined && mouseCol !== undefined) {
+          const entry = self.tidyFilteredGatheredInterProAnnotations[name] ?? []
+          return entry.filter(d => {
+            const m1 = self.seqPosToVisibleCol(name, d.start - 1)
+            const m2 = self.seqPosToVisibleCol(name, d.end)
+            return (
+              m1 !== undefined &&
+              m2 !== undefined &&
+              mouseCol >= m1 &&
+              mouseCol < m2
+            )
+          })
+        }
+        return []
+      },
+
+      /**
+       * #getter
+       * per-column summary statistics for the hovered column: consensus residue
+       * and its identity fraction, conservation score, gap fraction, and the
+       * sorted non-gap residue distribution. undefined when nothing is hovered.
+       */
+      get mouseOverColumnStats() {
+        const { mouseCol } = self
+        if (mouseCol === undefined) {
+          return undefined
+        }
+        const stats = self.colStats[mouseCol]
+        const total = self.colStatsSums[mouseCol]
+        if (!stats || !total) {
+          return undefined
+        }
+        const gaps = (stats['-'] ?? 0) + (stats['.'] ?? 0)
+        const distribution = Object.entries(stats)
+          .filter(([letter]) => letter !== '-' && letter !== '.')
+          .sort((a, b) => b[1] - a[1])
+        const consensus = distribution[0]
+        return {
+          col: mouseCol,
+          total,
+          gaps,
+          gapFraction: gaps / total,
+          conservation: self.conservation[mouseCol] ?? 0,
+          propertyConservation: self.propertyConservation[mouseCol],
+          consensusLetter: consensus?.[0] ?? '',
+          consensusCount: consensus?.[1] ?? 0,
+          consensusFraction: consensus ? consensus[1] / total : 0,
+          distribution,
+        }
+      },
+
       /**
        * #method
        */
@@ -1943,6 +2102,23 @@ function stateModelFactory() {
           }),
         )
 
+        // autorun: when autoTreeAreaWidth is set and no tree is drawn, shrink the
+        // tree area to fit the row labels rather than padding it to the fixed
+        // default. Gated on noTree/!drawTree so it never fights the treeWidth sync
+        // below (treeAreaWidth here depends only on labelsWidth, not treeWidth).
+        addDisposer(
+          self,
+          autorun(() => {
+            if (
+              self.autoTreeAreaWidth &&
+              (self.noTree || !self.drawTree) &&
+              self.labelsWidth
+            ) {
+              self.setTreeAreaWidth(self.labelsWidth + self.marginLeft + 12)
+            }
+          }),
+        )
+
         // autorun synchronizes treeWidth with treeAreaWidth
         addDisposer(
           self,
@@ -1957,93 +2133,19 @@ function stateModelFactory() {
         )
       },
     }))
-    .postProcessSnapshot(result => {
-      const snap = result as Omit<typeof result, symbol>
-      const {
-        data: { tree, msa, treeMetadata },
-        // Main model properties
-        showDomains,
-        hideGaps,
-        allowedGappyness,
-        subFeatureRows,
-        drawMsaLetters,
-        height,
-        rowHeight,
-        scrollY,
-        scrollX,
-        colWidth,
-        currentAlignment,
-        collapsed,
-        showOnly,
-        turnedOffTracks,
-        featureFilters,
-        relativeTo,
-        // MSA model properties
-        bgColor,
-        colorSchemeName,
-        // Tree model properties
-        drawLabels,
-        labelsAlignRight,
-        treeAreaWidth,
-        treeWidth,
-        showBranchLen,
-        drawTree,
-        drawNodeBubbles,
-        // Always include
-        ...rest
-      } = snap
-
-      const defaults: Record<string, unknown> = {
-        showDomains: defaultShowDomains,
-        hideGaps: defaultHideGaps,
-        allowedGappyness: defaultAllowedGappyness,
-        subFeatureRows: defaultSubFeatureRows,
-        drawMsaLetters: defaultDrawMsaLetters,
-        height: defaultHeight,
-        rowHeight: defaultRowHeight,
-        scrollY: defaultScrollY,
-        scrollX: defaultScrollX,
-        colWidth: defaultColWidth,
-        currentAlignment: defaultCurrentAlignment,
-        bgColor: defaultBgColor,
-        colorSchemeName: defaultColorSchemeName,
-        drawLabels: defaultDrawLabels,
-        labelsAlignRight: defaultLabelsAlignRight,
-        treeAreaWidth: defaultTreeAreaWidth,
-        treeWidth: defaultTreeWidth,
-        showBranchLen: defaultShowBranchLen,
-        drawTree: defaultDrawTree,
-        drawNodeBubbles: defaultDrawNodeBubbles,
-      }
-
-      const nonDefaults = Object.fromEntries(
-        Object.entries(defaults)
-          .filter(([key, def]) => snap[key as keyof typeof snap] !== def)
-          .map(([key]) => [key, snap[key as keyof typeof snap]]),
-      )
-
-      return {
-        ...rest,
-        data: {
-          ...(result.treeFilehandle ? {} : { tree }),
-          ...(result.msaFilehandle ? {} : { msa }),
-          ...(result.treeMetadataFilehandle ? {} : { treeMetadata }),
-        },
-        ...nonDefaults,
-        // eslint-disable-next-line @typescript-eslint/no-unnecessary-condition
-        ...(collapsed?.length ? { collapsed } : {}),
-        ...(showOnly !== undefined ? { showOnly } : {}),
-        // eslint-disable-next-line @typescript-eslint/no-unnecessary-condition
-        ...(turnedOffTracks && Object.keys(turnedOffTracks).length > 0
-          ? { turnedOffTracks }
-          : {}),
-        // eslint-disable-next-line @typescript-eslint/no-unnecessary-condition
-        ...(featureFilters && Object.keys(featureFilters).length > 0
-          ? { featureFilters }
-          : {}),
-        ...(relativeTo !== undefined ? { relativeTo } : {}),
-      } as typeof snap
-    })
+    .postProcessSnapshot(({ data, ...rest }) => ({
+      // per-property defaults are stripped by types.stripDefault; the only thing
+      // it can't express is this cross-field rule: drop inline tree/msa/metadata
+      // when a sibling filehandle can refetch them, keeping sessions/URLs small
+      ...rest,
+      data: {
+        ...(rest.treeFilehandle ? {} : { tree: data.tree }),
+        ...(rest.msaFilehandle ? {} : { msa: data.msa }),
+        ...(rest.treeMetadataFilehandle
+          ? {}
+          : { treeMetadata: data.treeMetadata }),
+      },
+    }))
 }
 
 export default stateModelFactory

package/src/propertyConservation.test.ts

@@ -0,0 +1,47 @@
+import { describe, expect, test } from 'vitest'
+
+import { calculatePropertyConservation } from './propertyConservation.ts'
+
+function counts(letters: string) {
+  const stats: Record<string, number> = {}
+  for (const c of letters) {
+    stats[c] = (stats[c] ?? 0) + 1
+  }
+  return stats
+}
+
+function propertyConservation(columns: string[]) {
+  const colStats = columns.map(counts)
+  const colStatsSums = colStats.map(s =>
+    Object.values(s).reduce((a, b) => a + b, 0),
+  )
+  return calculatePropertyConservation(colStats, colStatsSums)
+}
+
+describe('property conservation', () => {
+  test('an invariant column scores 1', () => {
+    expect(propertyConservation(['LLLL'])[0]).toBe(1)
+  })
+
+  test('a column varying only within one property class stays fully conserved', () => {
+    // L/I/V/M are all hydrophobic: identity varies but the property does not
+    expect(propertyConservation(['LIVM'])[0]).toBe(1)
+  })
+
+  test('mixing opposite-charge classes lowers the score', () => {
+    // K/R (positive) vs D/E (negative): two equally-sized classes
+    const score = propertyConservation(['KRDE'])[0]!
+    expect(score).toBeGreaterThan(0)
+    expect(score).toBeLessThan(1)
+  })
+
+  test('gaps reduce the score proportionally', () => {
+    const full = propertyConservation(['LLLL'])[0]!
+    const halfGapped = propertyConservation(['LL--'])[0]!
+    expect(halfGapped).toBeCloseTo(full * 0.5)
+  })
+
+  test('an all-gap column scores 0', () => {
+    expect(propertyConservation(['----'])[0]).toBe(0)
+  })
+})