react-msaview 5.5.0 → 5.6.0

package/src/fetchUtils.ts

@@ -1,4 +1,6 @@
-import { fetchAndMaybeUnzipText } from '@jbrowse/core/util'
+import { fetchAndMaybeUnzipText, statusMessageText } from '@jbrowse/core/util'
+
+import type { RpcStatus } from '@jbrowse/core/util'
 
 export interface FetchStatus {
   msg: string
@@ -10,7 +12,7 @@ type Filehandle = Parameters<typeof fetchAndMaybeUnzipText>[0]
 
 type ProgressFetcher = (
   loc: Filehandle,
-  opts: { signal: AbortSignal; statusCallback: (msg: string) => void },
+  opts: { signal: AbortSignal; statusCallback: (status: RpcStatus) => void },
 ) => Promise<string>
 
 /**
@@ -28,7 +30,8 @@ export async function fetchTextWithProgress(
   try {
     return await fetcher(loc, {
       signal: controller.signal,
-      statusCallback: msg => {
+      statusCallback: status => {
+        const msg = statusMessageText(status)
         setStatus(
           msg
             ? {

package/src/index.ts

@@ -9,7 +9,7 @@ export { renderToSvg } from './renderToSvg.tsx'
 export { default as MSAView } from './components/Loading.tsx'
 export { default as MSAViewer } from './components/MSAViewer.tsx'
 export { type MsaViewModel, default as MSAModelF } from './model.ts'
-export type { MSAParserType } from 'msa-parsers'
+export type { MSAFormat, MSAParserType } from 'msa-parsers'
 export type { HierarchyNode } from './hierarchy.ts'
 export type { InterProScanResults } from './launchInterProScan.ts'
 export type {

package/src/model/msaModel.ts

@@ -1,6 +1,10 @@
 import { types } from '@jbrowse/mobx-state-tree'
 
-import { defaultBgColor, defaultColorSchemeName } from '../constants.ts'
+import {
+  defaultBgColor,
+  defaultColorSchemeName,
+  defaultShowColumnStats,
+} from '../constants.ts'
 
 import type { MSAFormat } from 'msa-parsers'
 
@@ -16,13 +20,20 @@ export function MSAModelF() {
        * #property
        * draw MSA tiles with a background color
        */
-      bgColor: defaultBgColor,
+      bgColor: types.stripDefault(types.boolean, defaultBgColor),
 
       /**
        * #property
        * default color scheme name
        */
-      colorSchemeName: defaultColorSchemeName,
+      colorSchemeName: types.stripDefault(types.string, defaultColorSchemeName),
+
+      /**
+       * #property
+       * show a per-column statistics tooltip (consensus, conservation, gaps,
+       * residue distribution) while hovering the alignment
+       */
+      showColumnStats: types.stripDefault(types.boolean, defaultShowColumnStats),
 
       /**
        * #property
@@ -49,6 +60,13 @@ export function MSAModelF() {
         self.bgColor = arg
       },
 
+      /**
+       * #action
+       */
+      setShowColumnStats(arg: boolean) {
+        self.showColumnStats = arg
+      },
+
       /**
        * #action
        * force a specific MSA parser, or pass undefined to auto-detect

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,26 +20,18 @@ 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,
@@ -72,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,
@@ -131,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
@@ -154,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
@@ -220,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
@@ -238,7 +237,7 @@ function stateModelFactory() {
          * #property
          * turned off tracks
          */
-        turnedOffTracks: types.map(types.boolean),
+        turnedOffTracks: types.stripDefault(types.map(types.boolean), {}),
 
         /**
          * #property
@@ -254,7 +253,7 @@ function stateModelFactory() {
         /**
          * #property
          */
-        featureFilters: types.map(types.boolean),
+        featureFilters: types.stripDefault(types.map(types.boolean), {}),
         /**
          * #property
          */
@@ -279,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
@@ -343,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
@@ -377,8 +374,7 @@ function stateModelFactory() {
        * #volatile
        */
       interProAnnotations: undefined as
-        | undefined
-        | Record<string, InterProScanResults>,
+        undefined | Record<string, InterProScanResults>,
     }))
     .actions(self => ({
       /**
@@ -1044,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
@@ -1466,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] : []),
+        ]
       },
 
       /**
@@ -1743,6 +1764,41 @@ function stateModelFactory() {
         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
        */
@@ -2046,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,
@@ -2060,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)
+  })
+})

package/src/propertyConservation.ts

@@ -0,0 +1,73 @@
+// Disjoint physicochemical classes for the 20 standard amino acids. Property
+// conservation asks a different question than identity conservation: a column
+// can vary in exact residue yet stay within one property class (a conservative
+// substitution), which often marks a functionally constrained site that plain
+// identity conservation reports as variable.
+//
+// Histidine is grouped with the aromatics (it is only weakly/conditionally
+// positive at physiological pH); this mirrors common substitution-class schemes.
+const aminoPropertyClass: Record<string, string> = {
+  A: 'hydrophobic',
+  V: 'hydrophobic',
+  L: 'hydrophobic',
+  I: 'hydrophobic',
+  M: 'hydrophobic',
+  C: 'hydrophobic',
+  F: 'aromatic',
+  W: 'aromatic',
+  Y: 'aromatic',
+  H: 'aromatic',
+  K: 'positive',
+  R: 'positive',
+  D: 'negative',
+  E: 'negative',
+  S: 'polar',
+  T: 'polar',
+  N: 'polar',
+  Q: 'polar',
+  G: 'special',
+  P: 'special',
+}
+
+const numPropertyClasses = new Set(Object.values(aminoPropertyClass)).size
+const maxPropertyEntropy = Math.log2(numPropertyClasses)
+
+/**
+ * Per-column property conservation using Shannon entropy over physicochemical
+ * classes rather than exact residues. Returns 0-1 where 1 = every non-gap
+ * residue shares one property class. Mirrors the identity-conservation formula
+ * so the two tracks are directly comparable: (1 - H/Hmax) * (1 - gapFraction).
+ */
+export function calculatePropertyConservation(
+  colStats: Record<string, number>[],
+  colStatsSums: number[],
+) {
+  return colStats.map((stats, i) => {
+    const total = colStatsSums[i]
+    if (!total) {
+      return 0
+    }
+
+    let nonGapTotal = 0
+    const classCounts: Record<string, number> = {}
+    for (const [letter, count] of Object.entries(stats)) {
+      const cls = aminoPropertyClass[letter]
+      if (cls) {
+        classCounts[cls] = (classCounts[cls] ?? 0) + count
+        nonGapTotal += count
+      }
+    }
+    if (nonGapTotal === 0) {
+      return 0
+    }
+
+    let entropy = 0
+    for (const count of Object.values(classCounts)) {
+      const freq = count / nonGapTotal
+      entropy -= freq * Math.log2(freq)
+    }
+
+    const gapFraction = (total - nonGapTotal) / total
+    return Math.max(0, 1 - entropy / maxPropertyEntropy) * (1 - gapFraction)
+  })
+}