react-msaview 9.1.0 → 9.1.1

package/src/featurePanels.ts

@@ -0,0 +1,269 @@
+import { notEmpty } from '@jbrowse/core/util'
+
+import { packDomainLanes } from './components/msa/packDomainLanes.ts'
+import { defaultFeaturePanelWidth } from './constants.ts'
+import { featureField } from './featureFields.ts'
+import { resolveScale } from './scales.ts'
+import { outlineColor } from './util.ts'
+
+import type { ScaleSpec } from './scales.ts'
+import type {
+  Annotation,
+  DomainBand,
+  RowFeaturesSpec,
+  RowPanelSpan,
+  RowPanelSpec,
+} from './types.ts'
+
+// the fill of a span under a scale that gives its value no color, such as a
+// gene a `map` over gene names leaves out
+const UNSCALED_FEATURE = '#d9d9d9'
+
+// the fraction of a span a following one may cover before it takes a lane of
+// its own in a `features` panel
+const laneOverlap = 0.1
+
+// a row panel's own width, or a default: the row height, which makes a strip
+// cell square, and a gene neighborhood's width for a features panel. The row
+// height is read only when used, so a panel with a width of its own does not
+// recompute on a vertical zoom
+export function rowPanelWidth(
+  panel: RowPanelSpec,
+  view: { rowHeight: number },
+) {
+  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
+export 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
+export function colorByRow(
+  rowData: Record<string, Record<string, string> | undefined>,
+  field: string,
+  colorOf: (value: string) => string | undefined,
+) {
+  const colors = new Map<string, string>()
+  for (const [name, row] of Object.entries(rowData)) {
+    const value = row?.[field]
+    const color = value === undefined ? undefined : colorOf(value)
+    if (color) {
+      colors.set(name, color)
+    }
+  }
+  return colors
+}
+
+// the fill and outline of every feature in a list: its own GFF `color=` first,
+// then the scale an encoding resolves over one of its fields, then the
+// accession palette
+export function featureColorMap(
+  annotations: Annotation[],
+  encoding:
+    | { field: string; colorOf: (value: string) => string | undefined }
+    | undefined,
+  fillPalette: Record<string, string>,
+) {
+  const strokes = new Map<string, string>()
+  const strokeOf = (fill: string) => {
+    const hit = strokes.get(fill)
+    if (hit !== undefined) {
+      return hit
+    }
+    const stroke = outlineColor(fill)
+    strokes.set(fill, stroke)
+    return stroke
+  }
+  return new Map(
+    annotations.map(annotation => {
+      const value = encoding
+        ? featureField(annotation, encoding.field)
+        : undefined
+      const fill =
+        annotation.color ??
+        (value === undefined ? undefined : encoding!.colorOf(value)) ??
+        (encoding ? UNSCALED_FEATURE : fillPalette[annotation.accession]!)
+      return [annotation, { fill, stroke: strokeOf(fill) }]
+    }),
+  )
+}
+
+// the text a label channel draws inside each span, for the features carrying
+// the field it names
+export function featureLabelMap(annotations: Annotation[], field: string) {
+  const labels = new Map<Annotation, string>()
+  for (const annotation of annotations) {
+    const value = featureField(annotation, field)
+    if (value !== undefined) {
+      labels.set(annotation, value)
+    }
+  }
+  return labels
+}
+
+/** what `packDomainLanes` needs to lay a row out, before it has its lane */
+type Unlaned = Omit<RowPanelSpan, 'lane' | 'laneCount'> & {
+  startCol: number
+  endCol: number
+}
+
+/**
+ * Lanes for `position: "strandpile"`, gggenomes' `position_strandpile`: the
+ * forward features stack above the line and the reverse below it, each strand
+ * packing on its own. The deepest row on each side sets the grid every row lays
+ * out on, so the line between the strands sits at one height down the panel and
+ * a reader can scan it. A feature with no strand piles with the forward ones.
+ */
+function strandpileLanes(
+  rows: [string, Unlaned[]][],
+): Map<string, RowPanelSpan[]> {
+  const piled = rows.map(([name, bands]) => {
+    const reverse = packDomainLanes(
+      bands.filter(b => b.annotation.strand === -1),
+    )
+    const forward = packDomainLanes(
+      bands.filter(b => b.annotation.strand !== -1),
+    )
+    return { name, forward, reverse }
+  })
+  const up = Math.max(0, ...piled.map(p => p.forward[0]?.laneCount ?? 0))
+  const down = Math.max(0, ...piled.map(p => p.reverse[0]?.laneCount ?? 0))
+  const laneCount = up + down
+  return new Map(
+    piled.map(({ name, forward, reverse }) => [
+      name,
+      [
+        // forward level 0 is the lane just above the line, stacking upward
+        ...forward.map(b => ({ ...b, lane: up - 1 - b.lane, laneCount })),
+        ...reverse.map(b => ({ ...b, lane: up + b.lane, laneCount })),
+      ],
+    ]),
+  )
+}
+
+/** one row's spans laid out by the panel's `position` */
+function panelLanes(
+  panel: RowFeaturesSpec,
+  rows: [string, Unlaned[]][],
+): Map<string, RowPanelSpan[]> {
+  return panel.position === 'strandpile'
+    ? strandpileLanes(rows)
+    : new Map(rows.map(([name, bands]) => [name, packDomainLanes(bands)]))
+}
+
+/**
+ * The spans a `features` panel draws, keyed by row name and measured in the
+ * panel's own pixels. `column` takes the bands the overlay draws, at the
+ * alignment's column width. `position` packs each row's features in its own
+ * residue positions, shifted by an `align` transform, and maps the extent they
+ * cover across every row onto the panel width, so a row with no alignment
+ * still has an x.
+ */
+export function featurePanelSpans({
+  panel,
+  width,
+  colWidth,
+  domainBands,
+  annotationsByRow,
+  shifts,
+}: {
+  panel: RowFeaturesSpec
+  width: number
+  colWidth: number
+  domainBands: Map<string, DomainBand[]>
+  annotationsByRow: Record<string, Annotation[]>
+  shifts: Map<string, number> | undefined
+}): Map<string, RowPanelSpan[]> {
+  if (panel.x === 'column') {
+    return panelLanes(
+      panel,
+      [...domainBands].map(([name, bands]) => [
+        name,
+        bands.map(band => ({
+          ...band,
+          xStart: band.startCol * colWidth,
+          xEnd: band.endCol * colWidth,
+        })),
+      ]),
+    )
+  }
+  const shifted = Object.entries(annotationsByRow).map(
+    ([name, annotations]) => {
+      const shift = shifts?.get(name) ?? 0
+      return [
+        name,
+        annotations.map(annotation => ({
+          annotation,
+          start: annotation.start - 1 + shift,
+          end: annotation.end + shift,
+        })),
+      ] as const
+    },
+  )
+  let min = Infinity
+  let max = -Infinity
+  for (const [, features] of shifted) {
+    for (const { start, end } of features) {
+      min = Math.min(min, start)
+      max = Math.max(max, end)
+    }
+  }
+  // a gene arrow ends where its feature does, so the extent maps onto the whole
+  // panel less the pixel the rightmost stroke needs
+  const drawable = Math.max(1, width - 1)
+  const scale = max > min ? drawable / (max - min) : 0
+  // a lane opens where a span covers more than a tenth of the one before it,
+  // which keeps the genes of an operon on one lane: adjacent genes commonly
+  // share a few bases, and a stop codon overlapping the next start reads as a
+  // second lane over the whole row
+  return panelLanes(
+    panel,
+    shifted.map(([name, features]) => [
+      name,
+      features.map(({ annotation, start, end }) => ({
+        annotation,
+        xStart: (start - min) * scale,
+        xEnd: (end - min) * scale,
+        startCol: start,
+        endCol: end - (end - start) * laneOverlap,
+      })),
+    ]),
+  )
+}
+
+// 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
+export 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,
+    ...resolved,
+    legend: resolved.legend.filter(entry => shown.has(entry.id)),
+  }
+}

package/src/filehandleLoader.ts

@@ -0,0 +1,136 @@
+import { openLocation } from '@jbrowse/core/util/io'
+import { addDisposer, isAlive } from '@jbrowse/mobx-state-tree'
+import { autorun, transaction } from 'mobx'
+
+import { fetchTextWithProgress, isAbortError } from './fetchUtils.ts'
+
+import type { FetchStatus } from './fetchUtils.ts'
+import type { FileLocation } from '@jbrowse/core/util/types'
+import type { IStateTreeNode } from '@jbrowse/mobx-state-tree'
+
+interface LoaderHost extends IStateTreeNode {
+  setStatus: (status?: FetchStatus) => void
+  setError: (error?: unknown) => void
+  addWarning: (warning: string) => void
+}
+
+interface FilehandleLoader {
+  /** the layer's name in a failure message */
+  what: string
+  getFilehandle: () => FileLocation | undefined
+  onLoad: (text: string) => void
+  setLoading?: (loading: boolean) => void
+  /** runs after a local file loads, since a blob has no URL to refetch, and on cancel */
+  clearFilehandle?: () => void
+  /** a failure adds a warning instead of an error */
+  optional?: boolean
+}
+
+/**
+ * Latest-wins abort rotation, after `createAbortRotation` in
+ * jbrowse-components. Each `begin()` aborts the previous fetch and returns a
+ * signal with an `isCurrent()` guard; gate every write after an await on it so a
+ * superseded or torn-down fetch cannot overwrite fresher data. `end()` in the
+ * `finally` closes the guard of a fetch that completed.
+ */
+export function createAbortRotation(self: IStateTreeNode) {
+  let current: { controller: AbortController; ended: boolean } | undefined
+  return {
+    /** aborts the running fetch, and returns whether one was running */
+    cancel() {
+      const running = current !== undefined && !current.ended
+      current?.controller.abort()
+      current = undefined
+      return running
+    },
+    begin() {
+      current?.controller.abort()
+      const mine = { controller: new AbortController(), ended: false }
+      current = mine
+      return {
+        controller: mine.controller,
+        isCurrent: () => !mine.ended && mine === current && isAlive(self),
+        end() {
+          mine.ended = true
+        },
+      }
+    },
+  }
+}
+
+/**
+ * Fetches the filehandle whenever it changes and hands the text to `onLoad`. A
+ * superseded or cleared request is aborted and clears its status line.
+ */
+export function installFilehandleLoader(
+  self: LoaderHost,
+  {
+    what,
+    getFilehandle,
+    onLoad,
+    setLoading,
+    clearFilehandle,
+    optional = false,
+  }: FilehandleLoader,
+) {
+  const rotation = createAbortRotation(self)
+  const cancel = () => {
+    if (rotation.cancel() && isAlive(self)) {
+      self.setStatus(undefined)
+    }
+  }
+  addDisposer(self, cancel)
+  addDisposer(
+    self,
+    autorun(async () => {
+      const filehandle = getFilehandle()
+      cancel()
+      if (!filehandle) {
+        setLoading?.(false)
+        return
+      }
+      const { controller, isCurrent, end } = rotation.begin()
+      try {
+        setLoading?.(true)
+        if (!optional) {
+          self.setError(undefined)
+        }
+        const text = await fetchTextWithProgress(
+          openLocation(filehandle),
+          status => {
+            if (isCurrent()) {
+              self.setStatus(status)
+            }
+          },
+          { controller },
+        )
+        if (isCurrent()) {
+          transaction(() => {
+            onLoad(text)
+            if (filehandle.locationType === 'BlobLocation') {
+              clearFilehandle?.()
+            }
+          })
+        }
+      } catch (e) {
+        if (isCurrent()) {
+          if (isAbortError(e)) {
+            clearFilehandle?.()
+          } else {
+            console.error(e)
+            if (optional) {
+              self.addWarning(`The ${what} did not load: ${e}`)
+            } else {
+              self.setError(e)
+            }
+          }
+        }
+      } finally {
+        if (isCurrent()) {
+          setLoading?.(false)
+        }
+        end()
+      }
+    }),
+  )
+}

package/src/index.ts

@@ -25,10 +25,13 @@ export type {
   RegionShorthand,
 } from './expandSpec.ts'
 export { default as MSAView } from './components/Loading.tsx'
+export type { ToolbarSlots } from './components/header/Header.tsx'
 export { default as MSAViewer } from './components/MSAViewer.tsx'
 export type { MSAViewerProps } from './components/MSAViewer.tsx'
 // the snapshot MSAViewer builds from its props, for the CLI's --props
 export { resolveTheme, viewerSnapshot } from './viewerSnapshot.ts'
+// the active scheme's hex color for a row residue, to paint a structure with
+export { schemeResidueColor } from './schemeResidueColor.ts'
 export { mount } from './mount.tsx'
 export { defineMsaElement } from './element.ts'
 export { useMsaSvgFigure } from './useMsaSvgFigure.ts'
@@ -47,6 +50,7 @@ export type { InterProScanResults } from 'msa-parsers'
 // reason.
 export type { ColumnCounts } from './columnCounts.ts'
 export type { ColumnStats } from './columnStats.ts'
+export type { ZoomSnapshot } from './zoomSnapshot.ts'
 // the scale an encoding reads its field through, and what resolving one gives
 export type { ResolvedScale, ScaleSpec } from './scales.ts'
 export type {

package/src/model/treeModel.ts

@@ -10,6 +10,7 @@ import {
   defaultShowBranchLen,
   defaultTreeOrder,
   defaultShowTreeOverview,
+  defaultShowTreeScaleBar,
   treeOrders,
 } from '../constants.ts'
 import { stripDefault } from '../stripDefault.ts'
@@ -93,6 +94,12 @@ export function TreeModelF() {
        */
       showTreeOverview: stripDefault(types.boolean, defaultShowTreeOverview),
 
+      /**
+       * #property
+       * draw the branch-length scale bar above the tree of a phylogram
+       */
+      showTreeScaleBar: stripDefault(types.boolean, defaultShowTreeScaleBar),
+
       /**
        * #property
        * height of the tree overview band, px
@@ -163,6 +170,12 @@ export function TreeModelF() {
       setShowTreeOverview(arg: boolean) {
         self.showTreeOverview = arg
       },
+      /**
+       * #action
+       */
+      setShowTreeScaleBar(arg: boolean) {
+        self.showTreeScaleBar = arg
+      },
       /**
        * #action
        */