react-msaview 7.0.0 → 8.1.0

package/src/constants.ts

@@ -5,22 +5,22 @@ export const defaultHeight = 550
 export const defaultScrollX = 0
 export const defaultScrollY = 0
 export const defaultCurrentAlignment = 0
-// Annotations are loaded on purpose -- a gff filehandle, a file picked in the
-// dialog -- so they are drawn unless the reader has said otherwise. Since only
-// the "no" is stored, a shared link with the overlay hidden reopens hidden, and
-// one that never mentions it opens showing whatever annotations it carries.
+// Only a hidden overlay is stored, so a link that never mentions it opens
+// showing its annotations.
 export const defaultShowDomains = true
 export const defaultShowDomainLegend = true
 export const defaultHideGaps = true
 export const defaultAllowedGappyness = 100
 export const defaultSubFeatureRows = false
-// row height for each stacked feature when subFeatureRows is on
+// height of one sub-row when subFeatureRows is on, unless the row has more
+// lanes than fit at this height (see renderBoxFeatureCanvasBlock)
 export const subFeatureRowHeight = 4
+// height of the bar the overlay draws under a row in letter-color mode
+export const domainUnderlineHeight = 3
 
-// Feature types that are ordinal *segments* of a single transcript (exons and
-// the like) rather than categorical domains. Their identity is their position,
-// so the overlay alternates two shades to mark boundaries and labels them by
-// number, instead of assigning every one a distinct hue + legend row.
+// Feature types that are ordinal segments of one transcript. The overlay
+// alternates two shades across them and labels them by number, where a domain
+// type gets its own hue and legend row.
 export const segmentFeatureTypes = new Set([
   'exon',
   'CDS',
@@ -35,12 +35,24 @@ export const segmentShades = ['#9fb6d4', '#d4dcea']
 export const defaultDrawMsaLetters = true
 export const defaultScrollZoom = false
 
+// Which cell dimensions a wheel zoom scales. 'horizontal' holds the row height,
+// which fixes the label and letter font size while the columns compress.
+// 'vertical' does the reverse.
+export const scrollZoomAxes = ['both', 'horizontal', 'vertical'] as const
+export type ScrollZoomAxis = (typeof scrollZoomAxes)[number]
+export const defaultScrollZoomAxis: ScrollZoomAxis = 'both'
+
 // Cell size floors for drawing residue letters and tree labels. Below these a
-// 500px block holds thousands of glyphs, and fillText -- which no sprite atlas
-// beats, measured -- dominates every zoom frame.
+// 500px block holds thousands of glyphs, and fillText dominates every zoom
+// frame. A sprite atlas measured slower.
 export const minLetterRowHeight = 8
 export const minLetterColWidth = 5
 
+// A feature span draws its label at two pixels under its height, capped at 11,
+// so a span shorter than this holds no readable text: an underline bar, a
+// sub-row band or a features panel over small rows
+export const minFeatureLabelHeight = 9
+
 // Tree labels are measured once at this size and scaled to the current font
 // size, so a vertical zoom never re-measures the tree.
 export const labelReferenceFontSize = 16
@@ -65,18 +77,45 @@ export const defaultTreeWidth = 300
 export const defaultShowBranchLen = true
 export const defaultDrawTree = true
 export const defaultDrawNodeBubbles = true
+export const defaultDrawNodeLabels = false
+export const defaultShowTreeOverview = false
+export const defaultOverviewHeight = 120
 
-// Neighbor joining refuses above this many rows. The distance matrix is O(n^2*L)
-// and the join loop O(n^3), both on the main thread with no progress and no
-// cancel: 400 rows measured 1.5s, 800 rows 10s, and 1600 would be about seventy.
-// See agent-docs/ideas/neighbor-joining-scaling.md for why the RapidNJ fix is a
-// real algorithm change rather than a port, and why capping is the honest answer
-// -- NJ on thousands of sequences is the wrong tool however fast it runs.
+// Neighbor joining does not run above this many rows. The distance matrix is
+// O(n^2*L) and the join loop O(n^3), both on the main thread with no progress
+// and no cancel: 400 rows measured 1.5s, 800 rows 10s, and 1600 would be about
+// seventy. See agent-docs/ideas/neighbor-joining-scaling.md.
 export const maxNeighborJoiningRows = 500
 
-// The largest inline document the snapshot carries. Past this a pasted or
-// locally-opened file stays in the live model and leaves the snapshot, since a
-// session or a shared URL holding megabytes of sequence is not a link anyone
-// can send. `unshareableData` reads the same number, so what the viewer warns
-// about and what the snapshot drops cannot drift apart.
+// The opacity a `rowTint` encoding draws its scale's color at, so the residues
+// under the wash stay readable. A color the producer already gave an alpha
+// keeps it.
+export const rowTintAlpha = 0.25
+
+// The fill a `clades` record with the `highlight` mark draws behind its rows,
+// and the opacity a producer's own color takes when it carries none.
+export const cladeHighlightColor = '#fff3c4'
+export const cladeHighlightAlpha = 0.6
+
+// The largest inline document the snapshot carries. A larger pasted or
+// locally-opened file stays in the live model and out of the snapshot, keeping
+// shared URLs sendable. `unshareableData` warns using the same number.
 export const maxInlineSnapshotBytes = 50_000
+
+// Height of the band the `rowPanels` headers draw in, above the strips in the
+// top area beside the tree ruler and the minimap. A panel wider than the band
+// is tall writes its header across, where it has more room.
+export const rowPanelHeaderHeight = 56
+
+// Height of the branch-length scale bar above the tree.
+export const treeScaleBarHeight = 22
+
+// Width of a `features` row panel that names none, wide enough for a gene
+// neighborhood of a few arrows to read.
+export const defaultFeaturePanelWidth = 200
+
+// The alignment's overlay canvas draws the mouseover, the persisted highlights
+// and the row tints over the residues, and the legend key floats above that,
+// so a tint reaching the top right corner leaves the key readable.
+export const msaOverlayZIndex = 1000
+export const legendZIndex = msaOverlayZIndex + 1

package/src/createPaletteMap.ts

@@ -3,17 +3,18 @@ import { colord } from 'colord'
 import palettes from './ggplotPalettes.ts'
 
 /**
- * Creates a map from keys to colors. Up to the largest ggplot palette (8 keys)
- * we use the hand-picked ggplot colors; beyond that — e.g. a gene-structure
- * overlay with one feature per exon — we generate evenly spaced HSL hues so
- * every key still gets a distinct, stable color instead of running off the end
- * of the palette.
+ * Creates a map from keys to colors. `palette` names the colors to take in
+ * order, such as the list a scale asked for by name; without it the keys take
+ * the ggplot palette of their own size. Beyond the colors available — a
+ * gene-structure overlay with one feature per exon, or nine keys on an
+ * eight-color palette — every key gets an evenly spaced HSL hue instead, so no
+ * two keys share a color.
  */
-export function createPaletteMap(keys: string[]) {
+export function createPaletteMap(keys: string[], palette?: readonly string[]) {
   const n = keys.length
-  if (n <= palettes.length) {
-    const palette = palettes[n - 1]!
-    return Object.fromEntries(keys.map((key, i) => [key, palette[i]!]))
+  const colors = palette ?? palettes[n - 1]
+  if (colors && n <= colors.length) {
+    return Object.fromEntries(keys.map((key, i) => [key, colors[i]!]))
   }
   return Object.fromEntries(
     keys.map((key, i) => [

package/src/element.ts

@@ -0,0 +1,321 @@
+import { when } from 'mobx'
+
+import { mount } from './mount.tsx'
+
+import type { MSAViewerProps } from './components/MSAViewer.tsx'
+import type { MsaViewModel } from './model.ts'
+import type { MountedViewer } from './mount.tsx'
+import type {
+  Cell,
+  ColumnTrackSpec,
+  Highlight,
+  ResidueMapping,
+  Viewport,
+} from './types.ts'
+
+type ElementData = Pick<
+  MSAViewerProps,
+  'msa' | 'tree' | 'gff' | 'highlights' | 'columnTracks' | 'residueMappings'
+>
+
+interface NightingaleManager extends HTMLElement {
+  register: (element: HTMLElement) => void
+  unregister: (element: HTMLElement) => void
+}
+
+const ownAttributes = [
+  'msa-url',
+  'tree-url',
+  'gff-url',
+  'color-scheme',
+  'height',
+  'hide-header',
+  'theme',
+  'reference-row',
+  'tree-area-width',
+] as const
+
+// the attributes a <nightingale-manager> writes on the elements it holds
+const nightingaleAttributes = ['display-start', 'display-end', 'highlight']
+
+function location(uri: string | null) {
+  return uri ? { uri, locationType: 'UriLocation' as const } : undefined
+}
+
+function numberAttribute(value: string | null | undefined) {
+  const n = value ? Number(value) : Number.NaN
+  return Number.isFinite(n) ? n : undefined
+}
+
+// Nightingale writes a highlight as "start:end,start:end", 1-based inclusive
+function parseHighlight(value: string | null, row?: string): Highlight[] {
+  return (value ?? '').split(',').flatMap(span => {
+    const [start, end] = span.split(':').map(numberAttribute)
+    return start === undefined ? [] : [{ row, start, end: end ?? start }]
+  })
+}
+
+function residueAtColumn(model: MsaViewModel, row: string, column: number) {
+  const visible = model.globalColToVisibleCol(column - 1)
+  return visible === undefined
+    ? undefined
+    : model.visibleColToSeqPosOneBased(row, visible)
+}
+
+// the first and last residues of `row` inside the viewport's columns
+function residueRange(model: MsaViewModel, row: string, viewport: Viewport) {
+  let start: number | undefined
+  let end: number | undefined
+  for (let c = viewport.startColumn; c <= viewport.endColumn && !start; c++) {
+    start = residueAtColumn(model, row, c)
+  }
+  for (let c = viewport.endColumn; c >= viewport.startColumn && !end; c--) {
+    end = residueAtColumn(model, row, c)
+  }
+  return start && end ? { start, end } : undefined
+}
+
+/**
+ * Registers a custom element that renders MSAViewer, for pages with no React.
+ * Attributes: msa-url, tree-url, gff-url, color-scheme, height, hide-header,
+ * theme, tree-area-width and reference-row. Properties: msa, tree and gff text, highlights,
+ * columnTracks and residueMappings. Events: cell-hover, cell-click and
+ * viewport-change, each with the MSAViewer callback's value as detail.
+ *
+ * Inside a <nightingale-manager>, the element registers with it and speaks its
+ * protocol: it follows the display-start, display-end and highlight attributes
+ * the manager writes, and reports its own range and hovered residue as change
+ * events. Positions are residues of reference-row, or columns without one.
+ */
+export function defineMsaElement(tagName = 'jbrowse-msa') {
+  const existing = customElements.get(tagName)
+  if (existing) {
+    return existing
+  }
+
+  class MsaElement extends HTMLElement {
+    static observedAttributes = [...ownAttributes, ...nightingaleAttributes]
+
+    #viewer?: MountedViewer
+    #model?: MsaViewModel
+    #manager?: NightingaleManager
+    #cancelRange?: () => void
+    #rangePending = false
+    #reported?: { start: number; end: number }
+    #data: ElementData = {}
+
+    get msa() {
+      return this.#data.msa
+    }
+    set msa(value: string | undefined) {
+      this.#setData({ msa: value })
+    }
+    get tree() {
+      return this.#data.tree
+    }
+    set tree(value: string | undefined) {
+      this.#setData({ tree: value })
+    }
+    get gff() {
+      return this.#data.gff
+    }
+    set gff(value: string | undefined) {
+      this.#setData({ gff: value })
+    }
+    get highlights() {
+      return this.#data.highlights
+    }
+    set highlights(value: Highlight[] | undefined) {
+      this.#setData({ highlights: value })
+    }
+    get columnTracks() {
+      return this.#data.columnTracks
+    }
+    set columnTracks(value: ColumnTrackSpec[] | undefined) {
+      this.#setData({ columnTracks: value })
+    }
+    get residueMappings() {
+      return this.#data.residueMappings
+    }
+    set residueMappings(value: ResidueMapping[] | undefined) {
+      this.#setData({ residueMappings: value })
+    }
+
+    get #referenceRow() {
+      return this.getAttribute('reference-row') ?? undefined
+    }
+
+    #setData(data: ElementData) {
+      this.#data = { ...this.#data, ...data }
+      this.#viewer?.update(this.#props())
+    }
+
+    #props(): MSAViewerProps {
+      const theme = this.getAttribute('theme')
+      return {
+        ...this.#data,
+        msaFilehandle: location(this.getAttribute('msa-url')),
+        treeFilehandle: location(this.getAttribute('tree-url')),
+        gffFilehandle: location(this.getAttribute('gff-url')),
+        colorScheme: this.getAttribute('color-scheme') ?? undefined,
+        height: numberAttribute(this.getAttribute('height')),
+        treeAreaWidth: numberAttribute(this.getAttribute('tree-area-width')),
+        hideHeader: this.hasAttribute('hide-header'),
+        theme: theme === 'dark' ? 'dark' : 'light',
+        onCellHover: cell => {
+          this.#emit('cell-hover', cell)
+          this.#reportHover(cell)
+        },
+        onCellClick: cell => {
+          this.#emit('cell-click', cell)
+        },
+        onViewportChange: viewport => {
+          this.#emit('viewport-change', viewport)
+          this.#reportRange(viewport)
+        },
+        onModel: model => {
+          this.#model = model
+          this.#followRange()
+          this.#followHighlight()
+        },
+      }
+    }
+
+    #emit(type: string, detail: unknown) {
+      this.dispatchEvent(new CustomEvent(type, { detail }))
+    }
+
+    #nightingaleChange(detail: Record<string, unknown>) {
+      if (this.#manager) {
+        this.dispatchEvent(
+          new CustomEvent('change', {
+            detail,
+            bubbles: true,
+            cancelable: true,
+          }),
+        )
+      }
+    }
+
+    #reportHover(cell: Cell | undefined) {
+      const model = this.#model
+      const row = this.#referenceRow
+      const position =
+        cell && model && row
+          ? residueAtColumn(model, row, cell.column)
+          : cell?.column
+      this.#nightingaleChange({
+        type: 'highlight',
+        value: position === undefined ? null : `${position}:${position}`,
+      })
+    }
+
+    #reportRange(viewport: Viewport | undefined) {
+      const model = this.#model
+      const row = this.#referenceRow
+      if (!viewport || !model) {
+        return
+      }
+      const range = row
+        ? residueRange(model, row, viewport)
+        : { start: viewport.startColumn, end: viewport.endColumn }
+      const shownStart = numberAttribute(this.getAttribute('display-start'))
+      const shownEnd = numberAttribute(this.getAttribute('display-end'))
+      // a range the manager just wrote comes back within a column of itself,
+      // since the viewer shows whole columns
+      const echo =
+        range &&
+        shownStart !== undefined &&
+        shownEnd !== undefined &&
+        Math.abs(range.start - shownStart) <= 1 &&
+        Math.abs(range.end - shownEnd) <= 1
+      if (range && !echo) {
+        this.#reported = range
+        this.#nightingaleChange({
+          'display-start': range.start,
+          'display-end': range.end,
+        })
+      }
+    }
+
+    #followRange() {
+      const model = this.#model
+      const start = numberAttribute(this.getAttribute('display-start'))
+      const end = numberAttribute(this.getAttribute('display-end'))
+      const reported = this.#reported
+      // the manager writes the range this element reported back onto it, and
+      // zooming to it again would snap the reader's own zoom to whole residues
+      if (reported && reported.start === start && reported.end === end) {
+        return
+      }
+      this.#cancelRange?.()
+      if (model && start !== undefined && end !== undefined) {
+        const row = this.#referenceRow
+        this.#cancelRange = when(
+          () => model.viewInitialized && model.numColumns > 0,
+          () => {
+            model.zoomToRegion({ row, start, end })
+          },
+        )
+      }
+    }
+
+    #followHighlight() {
+      const spans = parseHighlight(
+        this.getAttribute('highlight'),
+        this.#referenceRow,
+      )
+      if (spans.length) {
+        this.#model?.applyHighlight('nightingale', spans)
+      } else {
+        this.#model?.clearHighlight('nightingale')
+      }
+    }
+
+    connectedCallback() {
+      if (!this.style.display) {
+        this.style.display = 'block'
+      }
+      this.#viewer = mount(this, this.#props())
+      const manager = this.closest<NightingaleManager>('nightingale-manager')
+      if (manager) {
+        void customElements.whenDefined('nightingale-manager').then(() => {
+          if (this.isConnected) {
+            this.#manager = manager
+            manager.register(this)
+          }
+        })
+      }
+    }
+
+    disconnectedCallback() {
+      this.#manager?.unregister(this)
+      this.#manager = undefined
+      this.#cancelRange?.()
+      this.#viewer?.destroy()
+      this.#viewer = undefined
+      this.#model = undefined
+    }
+
+    attributeChangedCallback(name: string) {
+      if (name === 'display-start' || name === 'display-end') {
+        // the manager writes the two attributes one after the other, and a
+        // zoom between them reports a range that overwrites the second
+        if (!this.#rangePending) {
+          this.#rangePending = true
+          queueMicrotask(() => {
+            this.#rangePending = false
+            this.#followRange()
+          })
+        }
+      } else if (name === 'highlight') {
+        this.#followHighlight()
+      } else {
+        this.#viewer?.update(this.#props())
+      }
+    }
+  }
+
+  customElements.define(tagName, MsaElement)
+  return MsaElement
+}

package/src/featureFields.ts

@@ -0,0 +1,19 @@
+import type { Annotation } from './types.ts'
+
+/**
+ * The value a feature gives an encoded field: an Annotation property, else one
+ * of the GFF attributes the parser kept.
+ */
+export function featureField(annotation: Annotation, field: string) {
+  const own = (annotation as unknown as Record<string, unknown>)[field]
+  const value = own ?? annotation.attributes?.[field]
+  return typeof value === 'string' ? value : undefined
+}
+
+/**
+ * The name a feature answers to in a transform: its GFF `Name` attribute, else
+ * the name the parser gave it.
+ */
+export function featureName(annotation: Annotation) {
+  return featureField(annotation, 'Name') ?? featureField(annotation, 'name')
+}

package/src/flatToTree.ts

@@ -22,8 +22,7 @@ export function flatToTree(items: FlatItem[]): TreeNode {
         item.id,
         {
           id: `${item.id}`,
-          // the label is what NCBI's own tree viewer shows; falling back to the
-          // node id would render a tree of bare numbers
+          // NCBI's tree viewer shows the label
           name: item.label || `${item.id}`,
           ...(length !== undefined && Number.isFinite(length)
             ? { length }

package/src/ggplotPalettes.ts

@@ -19,3 +19,63 @@ const palettes = [
 ]
 
 export default palettes
+
+/**
+ * Fixed categorical palettes a scale names. `ggplot` is not one of them: it is
+ * the ramp above, which picks its colors from the number of keys.
+ */
+export const namedPalettes: Record<string, readonly string[]> = {
+  set1: [
+    '#e41a1c',
+    '#377eb8',
+    '#4daf4a',
+    '#984ea3',
+    '#ff7f00',
+    '#ffff33',
+    '#a65628',
+    '#f781bf',
+    '#999999',
+  ],
+  dark2: [
+    '#1b9e77',
+    '#d95f02',
+    '#7570b3',
+    '#e7298a',
+    '#66a61e',
+    '#e6ab02',
+    '#a6761d',
+    '#666666',
+  ],
+  // Okabe-Ito, which stays distinguishable under the common forms of color
+  // blindness
+  okabeito: [
+    '#e69f00',
+    '#56b4e9',
+    '#009e73',
+    '#f0e442',
+    '#0072b2',
+    '#d55e00',
+    '#cc79a7',
+    '#000000',
+  ],
+  tableau: [
+    '#4e79a7',
+    '#f28e2b',
+    '#e15759',
+    '#76b7b2',
+    '#59a14f',
+    '#edc948',
+    '#b07aa1',
+    '#ff9da7',
+    '#9c755f',
+    '#bab0ac',
+  ],
+}
+
+/**
+ * The colors a palette name asks for. `ggplot`, an unknown name, and no name at
+ * all give undefined, which `createPaletteMap` answers with the hue ramp.
+ */
+export function paletteNamed(name?: string) {
+  return name === undefined ? undefined : namedPalettes[name]
+}

package/src/hierarchy.ts

@@ -38,10 +38,8 @@ export interface HierarchyNode<T = NodeWithIds> extends CoreHierarchyNode<T> {
   collapsedTipXFar?: number
 }
 
-// The generic traversals live in @gmod/newick now, shared with the tree sidebar
-// in jbrowse-components. They are iterative there for the reason they were here:
-// a phylogenetic tree can be a caterpillar, whose depth equals its leaf count,
-// and the recursive form overflows the stack somewhere past 5000 tips.
+// The @gmod/newick traversals are iterative: a caterpillar tree's depth equals
+// its leaf count, and recursion overflows the stack past about 5000 tips.
 export {
   descendants,
   find,
@@ -54,11 +52,8 @@ export {
 }
 export type { HierarchyLink } from '@gmod/newick'
 
-// coreHierarchy builds base nodes, and the layout fields above are written onto
-// them afterwards by this package. Every one of those fields is optional, so the
-// two node types are mutually assignable and this needs no cast -- it exists
-// only to declare the wider return type, which is what lets those later
-// assignments typecheck.
+// declares the wider return type so the layout code can assign the optional
+// fields above onto coreHierarchy's nodes
 export function hierarchy<T>(
   data: T,
   childrenAccessor: (d: T) => T[] | undefined,
@@ -219,3 +214,76 @@ export function setBrLength(d: HierarchyNode, y0: number, k: number) {
     }
   }
 }
+
+/**
+ * Every leaf by name, with a name two leaves share mapping to undefined: a tip
+ * set naming it cannot say which tip it means.
+ */
+export function leafIndex<T extends { name: string }>(root: HierarchyNode<T>) {
+  const index = new Map<string, HierarchyNode<T> | undefined>()
+  for (const leaf of leaves(root)) {
+    const { name } = leaf.data
+    index.set(name, index.has(name) ? undefined : leaf)
+  }
+  return index
+}
+
+/**
+ * The most recent common ancestor of a set of tip names, or undefined when a
+ * name is not a tip of this tree or names two of them.
+ *
+ * Each name lifts through `parent` to the ancestor the names before it share,
+ * so the walk holds two nodes. Recording a root-to-tip path per name instead
+ * costs the depth in memory per name, and a caterpillar tree's depth is its tip
+ * count. `index` is `leafIndex(root)`, which a caller resolving several tip
+ * sets against one tree builds once.
+ */
+export function mrca<T extends { name: string }>(
+  root: HierarchyNode<T>,
+  names: string[],
+  index = leafIndex(root),
+) {
+  let node: HierarchyNode<T> | undefined
+  for (const name of names) {
+    let other = index.get(name)
+    if (!other) {
+      return undefined
+    }
+    if (!node) {
+      node = other
+      continue
+    }
+    while (node.depth > other.depth) {
+      node = node.parent!
+    }
+    while (other.depth > node.depth) {
+      other = other.parent!
+    }
+    while (node !== other) {
+      node = node.parent!
+      other = other.parent!
+    }
+  }
+  return node
+}
+
+/**
+ * The deepest node whose subtree covers a run of rows, given in the row-space
+ * coordinates clusterLayout writes to xMin/xMax. A subtree's leaves are one
+ * contiguous run, so at most one child per level covers the run and the descent
+ * visits the tree's depth rather than its nodes.
+ */
+export function nodeCoveringRows<T>(
+  root: HierarchyNode<T>,
+  top: number,
+  bottom: number,
+) {
+  let node = root
+  for (;;) {
+    const child = node.children?.find(c => c.xMin! <= top && c.xMax! >= bottom)
+    if (!child) {
+      return node
+    }
+    node = child
+  }
+}