react-msaview 6.5.0 → 8.0.0

package/src/rowCoordinateCalculations.ts

@@ -1,5 +1,3 @@
-import { isBlank } from './util.ts'
-
 /**
  * MSA Coordinate Systems:
  *
@@ -81,9 +79,8 @@ function countBlanksBefore(blanks: number[], globalCol: number) {
  * that is its own visible index; for a hidden one it is the index of the next
  * visible column, i.e. where the hidden column collapses to.
  *
- * That total answer is what spans want: resolving both ends of a span through
- * globalColToVisibleCol instead loses the whole span whenever either end lands
- * in a hidden column.
+ * Spans use this, since globalColToVisibleCol drops a span whenever either end
+ * lands in a hidden column.
  *
  * @param blanks - Sorted array of global column indices that are hidden
  * @param globalCol - The global column index in the full MSA
@@ -93,65 +90,22 @@ export function visibleColsBefore(blanks: number[], globalCol: number) {
 }
 
 /**
- * Convert a visible column to a row-specific sequence position.
- * Returns undefined if the position is a gap in the sequence.
+ * The ungapped position a row holds at a global column, or undefined when that
+ * column is a gap in the row or past its end.
  *
- * @param seq - The row's sequence string (including gaps)
- * @param blanks - Sorted array of global column indices that are hidden
- * @param visibleCol - The visible column index
- * @returns The sequence position, or undefined if it's a gap
+ * Binary-searches the row's ascending seqPos index; it runs on every mouse
+ * move, and scanning a 30k-column row per event takes the whole frame.
+ *
+ * @param index - The row's seqPos -> global column index (buildSeqPosIndex)
+ * @param globalCol - The global column index in the full MSA
  */
-export function visibleColToSeqPos({
-  seq,
-  blanks,
-  visibleCol,
-}: {
-  seq: string
-  blanks: number[]
-  visibleCol: number
-}) {
-  // First convert the visible column to global column
-  const globalCol = visibleColToGlobalCol(blanks, visibleCol)
-  const seqLen = seq.length
-
-  // Check if the position in the sequence is a gap
-  if (globalCol < seqLen && isBlank(seq[globalCol])) {
+export function seqPosOfGlobalCol(
+  index: Int32Array | undefined,
+  globalCol: number,
+) {
+  if (!index) {
     return undefined
   }
-
-  // Count non-gap characters up to the global position
-  let seqPos = 0
-  for (let i = 0; i < globalCol && i < seqLen; i++) {
-    if (!isBlank(seq[i])) {
-      seqPos++
-    }
-  }
-
-  return globalCol < seqLen ? seqPos : undefined
-}
-
-/**
- * Convert a visible column to a row-specific sequence position, with row lookup.
- *
- * @param rowName - The name of the row
- * @param visibleCol - The visible column index
- * @param rowMap - Map from row name to sequence string
- * @param blanks - Sorted array of global column indices that are hidden
- * @returns The sequence position, or undefined if row not found or position is a gap
- */
-export function visibleColToSeqPosForRow({
-  rowName,
-  visibleCol,
-  rowMap,
-  blanks,
-}: {
-  rowName: string
-  visibleCol: number
-  rowMap: Map<string, string>
-  blanks: number[]
-}) {
-  const seq = rowMap.get(rowName)
-  return seq !== undefined
-    ? visibleColToSeqPos({ seq, visibleCol, blanks })
-    : undefined
+  const seqPos = partitionPoint(index.length, i => index[i]! >= globalCol)
+  return index[seqPos] === globalCol ? seqPos : undefined
 }

package/src/scales.ts

@@ -0,0 +1,47 @@
+import { createPaletteMap } from './createPaletteMap.ts'
+import { paletteNamed } from './ggplotPalettes.ts'
+
+import type { LegendEntry } from './types.ts'
+
+/** how a channel reads a field: a palette by name, or a color per value */
+export interface ScaleSpec {
+  palette?: string
+  map?: Record<string, string>
+}
+
+export interface ResolvedScale {
+  kind: 'categorical'
+  colorOf: (value: string) => string | undefined
+  legend: LegendEntry[]
+}
+
+/**
+ * The scale a channel reads its field through. `values` are the field's values,
+ * in any order and with repeats; the domain is their distinct values sorted, so
+ * a value keeps its color when rows are re-ordered, collapsed or filtered.
+ *
+ * `{map}` colors the values the producer named and leaves the rest uncolored.
+ * `{palette}` takes the colors of a named palette, and a spec with neither
+ * takes the ggplot palette of the domain's size. Every scale is categorical
+ * today; a continuous one waits for a caller.
+ */
+export function resolveScale(
+  spec: ScaleSpec | undefined,
+  values: Iterable<string>,
+): ResolvedScale {
+  const domain = [...new Set(values)].sort((a, b) => a.localeCompare(b))
+  const { map, palette } = spec ?? {}
+  const colors = map ?? createPaletteMap(domain, paletteNamed(palette))
+  const present = new Set(domain)
+  const labels = map ? Object.keys(map).filter(v => present.has(v)) : domain
+  return {
+    kind: 'categorical',
+    colorOf: (value: string) => colors[value],
+    // a categorical value is its own label, and the id a legend keys on
+    legend: labels.map(value => ({
+      id: value,
+      label: value,
+      color: colors[value]!,
+    })),
+  }
+}

package/src/seqPosToGlobalCol.ts

@@ -2,9 +2,8 @@
  * The global column of every ungapped sequence position in a row, i.e.
  * index[seqPos] is the column holding the seqPos-th non-gap character.
  *
- * A row is indexed once and then answers seqPos -> column by lookup, which is
- * what makes the domain overlay affordable: it resolves one position per feature
- * per row on every redraw, and scanning the row for each would be quadratic.
+ * The domain overlay resolves one position per feature per row on every redraw,
+ * and scanning the row for each would be quadratic.
  *
  * @example
  * // Row: "A-TG-C" (A at 0, T at 2, G at 3, C at 5)
@@ -19,5 +18,7 @@ export function buildSeqPosIndex(row: string) {
       index[n++] = col
     }
   }
-  return index.subarray(0, n)
+  // slice, not subarray: a subarray keeps the whole row-length buffer alive,
+  // and a gappy alignment's indexes are held for as long as the parse is
+  return index.slice(0, n)
 }

package/src/sequenceLogo.ts

@@ -19,18 +19,13 @@ export function maxBitsFor(sequenceType: 'dna' | 'rna' | 'amino') {
  * stack bottom-up in array order.
  *
  * Heights follow Schneider & Stephens: the column's information content is
- * `log2(alphabet) - H` bits, and each residue takes the share of that its own
- * frequency earns. Frequencies come from the non-gap residues only, so a column
- * of two residues and eight gaps is read as a two-way choice rather than a
- * ten-way one -- otherwise every gappy column would look uninformative for the
- * wrong reason.
+ * `log2(alphabet) - H` bits, split among residues by frequency. Frequencies
+ * count non-gap residues only, so two residues and eight gaps form a two-way
+ * choice.
  *
- * The whole stack is then scaled by the non-gap fraction, which plain WebLogo
- * does not do. Here it earns its place: the track sits directly under an
- * alignment where the gaps are visible, and a column that is 90% gap drawing a
- * full-height stack off its one remaining pair of residues reads as a conserved
- * site. Scaling makes stack height mean "how much this column tells you about
- * the family", matching what the conservation track above it already plots.
+ * Unlike plain WebLogo, the stack is then scaled by the non-gap fraction, so a
+ * 90%-gap column with one conserved pair does not draw a full-height stack, and
+ * stack height matches the conservation track.
  */
 export function columnLogoStack(
   colStats: ColumnCounts,

package/src/stripDefault.ts

@@ -9,21 +9,14 @@ import type {
 /**
  * `types.stripDefault`, degrading to `types.optional` on hosts that lack it.
  *
- * stripDefault keeps defaulted properties out of snapshots, but it exists only
- * in the mobx-state-tree that ships with unreleased @jbrowse/core. This package
- * declares `@jbrowse/mobx-state-tree: ^5.0.0`, and inside jbrowse-web the host
- * supplies its own copy at runtime -- the plugin bundle externalizes it -- so we
- * genuinely do not know which version we are calling until we are running.
+ * stripDefault keeps defaulted properties out of snapshots, and only the
+ * mobx-state-tree in unreleased @jbrowse/core has it. The plugin bundle
+ * externalizes mobx-state-tree, so the host's copy is known only at runtime, and
+ * calling a missing stripDefault during model construction makes PluginLoader
+ * reject and the whole app show its error page.
  *
- * Calling it where it is absent throws while the model is being constructed,
- * which in a plugin bundle means PluginLoader rejects and the entire app renders
- * its error page. Losing minimal snapshots is a far better failure than losing
- * the session, so this degrades instead.
- *
- * The two signatures are identical, so behaviour differs only in that defaults
- * reappear in snapshots on older hosts (bigger session snapshots and shared
- * URLs, nothing incorrect). stripDefaultSnapshot.test.ts still pins the stripped
- * behaviour, since dev runs against a version that has it.
+ * The signatures are identical; on older hosts, defaults reappear in snapshots
+ * and shared URLs. stripDefaultSnapshot.test.ts pins the stripped behaviour.
  */
 export function stripDefault<IT extends IAnyType>(
   type: IT,

package/src/types.ts

@@ -1,3 +1,4 @@
+import type { ResolvedScale, ScaleSpec } from './scales.ts'
 import type { Annotation } from 'msa-parsers'
 
 export interface Accession {
@@ -5,10 +6,16 @@ export interface Accession {
   name: string
   description: string
 }
-// which renderer draws a track's content. Every track kind draws into the same
-// per-column coordinate space, so the kind picks the draw function rather than
-// the geometry -- see drawTracks.ts, which dispatches on it.
-export type TrackKind = 'text' | 'bar' | 'logo'
+// every kind draws into the same per-column space; drawTracks.ts dispatches on
+// it to pick the draw function
+export type TrackKind = 'text' | 'bar' | 'logo' | 'arc' | 'ruler'
+
+/**
+ * Which channel the color scheme paints. `fill` colors the cell a residue sits
+ * in, `color` colors the letter itself, the same distinction a grammar of
+ * graphics draws between a shape's interior and its own ink.
+ */
+export type ResidueEncoding = 'fill' | 'color'
 
 export interface BasicTrackModel {
   id: string
@@ -16,6 +23,11 @@ export interface BasicTrackModel {
   associatedRowName?: string
   height: number
   kind: TrackKind
+  // the model height this track's divider writes, shared with every track
+  // carrying the same key. Absent on a track no divider resizes.
+  heightKey?: string
+  // hidden until the user asks for it, unless they have already chosen
+  defaultOff?: boolean
 }
 
 export interface TextTrackModel extends BasicTrackModel {
@@ -29,20 +41,45 @@ export interface BarTrackModel extends BasicTrackModel {
   barColor?: string
 }
 
+// a pair of columns joined by an arc, resolved to 0-based visible columns for
+// the renderer
+export interface Arc {
+  start: number
+  end: number
+  color?: string
+}
+
+// a track that joins pairs of columns with arcs (RNA base pairs, disulfide
+// bonds, residue contacts)
+export interface ArcTrackModel extends BasicTrackModel {
+  arcs?: Arc[]
+  arcColor?: string
+}
+
 export interface BasicTrack {
   ReactComponent: React.FC<any>
-  model: TextTrackModel & BarTrackModel
+  model: TextTrackModel & BarTrackModel & ArcTrackModel
+}
+
+// one arc of an arc track, in the snapshot's own coordinates: 1-based and
+// inclusive, alignment columns unless the track names a `row`
+export interface ArcSpec {
+  start: number
+  end: number
+  color?: string
 }
 
 // a track supplied as data in the snapshot rather than computed from the
 // alignment. `values` (bar) or `data` (text) index alignment columns, or the
-// 1-based residues of `row` when it names one
+// 1-based residues of `row` when it names one; `arcs` (arc) name two such
+// positions each
 export interface ColumnTrackSpec {
   id: string
   name: string
-  kind: 'bar' | 'text'
+  kind: 'bar' | 'text' | 'arc'
   values?: number[]
   data?: string
+  arcs?: ArcSpec[]
   max?: number
   color?: string
   colors?: Record<string, string>
@@ -50,20 +87,225 @@ export interface ColumnTrackSpec {
   height?: number
 }
 
-// the overlay annotation itself lives in msa-parsers, alongside the adapters
-// that build it. TidyDomainAnnotation is its former name, kept because
-// downstream plugins name it in their emitted declarations.
+/**
+ * A strip panel: one cell per row, colored from a `rowData` field through
+ * `scale`, which is ggtree's `gheatmap`. `width` is in pixels and defaults to
+ * the row height, and `header` labels the column and defaults to the field.
+ * `legend` titles the strip's legend and defaults to the field, and strips
+ * naming one title share one legend.
+ */
+export interface RowStripSpec {
+  kind: 'strip'
+  field: string
+  scale?: ScaleSpec
+  width?: number
+  header?: string
+  legend?: string
+}
+
+/** the channels a `features` panel reads off the feature table */
+export interface FeatureEncodingSpec {
+  color?: { field: string; scale?: ScaleSpec }
+  label?: string
+}
+
+/**
+ * Shifts each row so that the first feature named `on` starts at zero, which
+ * is gggenes' `make_alignment_dummies`. Only `x: "position"` reads it.
+ */
+export interface AlignTransform {
+  type: 'align'
+  on: string
+}
+
+/**
+ * A features panel: the GFF's spans per row, as arrows where they carry a
+ * strand. `x: "column"` draws them in the alignment's columns, and
+ * `x: "position"` in each row's own residue positions on one linear scale, so
+ * a genome with no alignment has an x.
+ */
+export interface RowFeaturesSpec {
+  kind: 'features'
+  x: 'column' | 'position'
+  width?: number
+  header?: string
+  encoding?: FeatureEncodingSpec
+  transform?: AlignTransform[]
+}
+
+/**
+ * A panel left of the alignment on the row scale, the counterpart of
+ * ColumnTrackSpec on the column scale. See docs/layers.md
+ */
+export type RowPanelSpec = RowStripSpec | RowFeaturesSpec
+
+interface ResolvedPanelBase {
+  id: string
+  header: string
+  width: number
+  offsetX: number
+  legend: LegendEntry[]
+  /** the legend this panel's entries go under; absent means the domain key */
+  legendTitle?: string
+}
+
+/**
+ * A strip with its scale resolved: the color each row takes, keyed by row
+ * name, and the pixel column the panel draws in.
+ */
+export interface ResolvedStripPanel extends ResolvedPanelBase {
+  kind: 'strip'
+  field: string
+  colors: Map<string, string>
+}
+
+/** one feature of a features panel, at its pixel span inside the panel */
+export interface RowPanelSpan {
+  annotation: Annotation
+  xStart: number
+  xEnd: number
+  lane: number
+  laneCount: number
+}
+
+/**
+ * A features panel with its x mapping and its scale resolved: the spans per
+ * row name in panel pixels, the fill and outline of each feature, and the
+ * label its `label` channel draws. `field` is the field its color scale reads,
+ * which its legend is titled by.
+ */
+export interface ResolvedFeaturePanel extends ResolvedPanelBase {
+  kind: 'features'
+  x: 'column' | 'position'
+  field?: string
+  spans: Map<string, RowPanelSpan[]>
+  colors: Map<Annotation, { fill: string; stroke: string }>
+  labels?: Map<Annotation, string>
+}
+
+export type ResolvedRowPanel = ResolvedStripPanel | ResolvedFeaturePanel
+
+// One contiguous run where a row's residues and a structure's line up 1:1, as
+// SIFTS reports them. A position no segment covers is unmapped.
+export interface ResidueSegment {
+  rowStart: number
+  rowEnd: number
+  structStart: number
+  structEnd: number
+}
+
+// the structure half of a mapping. `id` is whatever the producer calls the
+// entry (a PDB id, an AlphaFold accession); `asymId` names the chain and
+// distinguishes two mappings onto the same entry
+export interface MappedStructure {
+  id: string
+  kind?: 'experimental' | 'predicted'
+  asymId?: string
+  url?: string
+}
+
+/**
+ * The structure residue for each residue of a row, computed outside the viewer
+ * (SIFTS, an AlphaFold model, a curator). Sequence equality misplaces tagged
+ * constructs, truncations and subsequence rows; see docs/layers.md.
+ *
+ * Positions are 1-based and inclusive on both sides, as GFF and `highlights`
+ * are. Structure positions are `label_seq_id`, the index into the entity's
+ * SEQRES; author numbering carries insertion codes and is not used.
+ *
+ * `unobserved` is in structure positions: present in SEQRES with no
+ * coordinates, as distinct from a residue the structure lacks.
+ */
+export interface ResidueMapping {
+  row: string
+  accession?: string
+  structure: MappedStructure
+  segments: ResidueSegment[]
+  unobserved?: [number, number][]
+  /**
+   * ungapped length of the row this was computed against. When set, the viewer
+   * ignores the mapping if the loaded row's length differs, as it does after a
+   * re-alignment, revision or swapped sequence.
+   */
+  rowLength?: number
+  generated?: {
+    by?: string
+    date?: string
+    sourceSha256?: string
+  }
+}
+
+// why a mapping, or one segment of it, is ignored, so a host can tell "no
+// structure for this row" from "the mapping no longer matches what is loaded"
+export interface ResidueMappingProblem {
+  row: string
+  structureId: string
+  /**
+   * `mapping` ignores the whole mapping, because the problem concerns its row.
+   * `segment` ignores only that segment and keeps the rest.
+   */
+  scope: 'mapping' | 'segment'
+  reason: string
+}
+
+// a lookup result in either direction. `observed` is false for a residue in
+// SEQRES with no coordinates.
+export interface StructureResidue {
+  structure: MappedStructure
+  position: number
+  observed: boolean
+}
+
+export interface RowResidue {
+  rowName: string
+  seqPos: number
+}
+
+/**
+ * One loaded document that the snapshot omits, and its size. `what` uses the
+ * import form's names for the documents.
+ */
+export interface UnshareableData {
+  what: 'alignment' | 'tree' | 'annotations' | 'row metadata' | 'data tracks'
+  bytes: number
+}
+
+// Annotation is defined in msa-parsers. Downstream plugins' emitted
+// declarations still name TidyDomainAnnotation.
 export type { Annotation }
 export type TidyDomainAnnotation = Annotation
 
 // an annotation resolved to the visible column span it is drawn across.
-// stackIndex is its position among the bands its row actually draws, which the
-// sub-row layout uses to stack boxes.
+// stackIndex is its position in its row's paint order; lane is the sub-row it
+// occupies, out of the laneCount the row's overlaps need.
 export interface DomainBand {
   annotation: Annotation
   startCol: number
   endCol: number
   stackIndex: number
+  lane: number
+  laneCount: number
+}
+
+/**
+ * One swatch of a categorical color key. `id` is the value the scale read, and
+ * `label` is the text drawn beside the swatch.
+ */
+export interface LegendEntry {
+  id: string
+  label: string
+  color: string
+}
+
+/**
+ * A categorical color key, drawn by the on-screen overlay and reserved as a
+ * column in the SVG export. `title` names the legend where the viewer draws
+ * more than one.
+ */
+export interface Legend {
+  id: string
+  title: string
+  entries: LegendEntry[]
 }
 
 /**
@@ -80,6 +322,104 @@ export interface Highlight {
   color?: string
 }
 
+/**
+ * What the viewer draws over a clade. `highlight` fills the rows behind it,
+ * across the tree and the alignment. `bracket` draws a bar and the clade's
+ * `label` in the gutter right of the tip labels. `collapse` and `focus` seed
+ * the collapsed list and the subtree in focus at load.
+ */
+export type CladeMark = 'highlight' | 'bracket' | 'collapse' | 'focus'
+
+/**
+ * A clade of the tree and the mark drawn over it. `mrca` names tips whose most
+ * recent common ancestor is the clade; `range` names the first and last tip of
+ * a run in display order, in either order. `tips` is the leaf count the
+ * producer measured, and a clade that resolves to a different count is dropped.
+ * `label` names the clade beside a bracket, and a highlight carrying one draws
+ * the label without the bar. See docs/layers.md
+ */
+export interface Clade {
+  mrca?: string[]
+  range?: [string, string]
+  tips: number
+  mark: CladeMark
+  color?: string
+  label?: string
+}
+
+/**
+ * A Clade resolved to the rows it covers, with its fill color settled. `color`
+ * is the highlight fill; `markColor` is the producer's own color for a bracket
+ * bar and its label, unset where the theme's text color stands. `nodeId` is the
+ * node an `mrca` resolved to, which `collapse` and `focus` seed themselves
+ * with, and a `range` record has none.
+ */
+export interface ResolvedClade {
+  rows: [number, number]
+  mark: CladeMark
+  color: string
+  markColor?: string
+  label?: string
+  nodeId?: string
+}
+
+/**
+ * A span in Highlight coordinates: 1-based inclusive residues of `row`, or
+ * columns of the file without it
+ */
+export interface Region {
+  row?: string
+  start: number
+  end: number
+}
+
+/**
+ * A cell of the alignment in the host's coordinates, 1-based like Highlight:
+ * `column` counts every column of the file, hidden gappy ones included, and
+ * `residue` counts the row's own letters, absent on a gap. A pointer over a
+ * track has a column and no row.
+ */
+export interface Cell {
+  column: number
+  row?: string
+  residue?: number
+  letter?: string
+}
+
+/** the alignment columns on screen, 1-based and inclusive */
+export interface Viewport {
+  startColumn: number
+  endColumn: number
+}
+
+/**
+ * A channel of a mark the viewer always draws. `tipLabel` colors each tip label
+ * in the tree, `rowTint` washes the row across the tree gutter and the
+ * alignment, and `branch` colors a tree edge whose tips all share one value;
+ * all three read a field of `rowData`. `featureFill` colors each span of the
+ * annotation overlay and `featureLabel` names the field drawn inside a span,
+ * both from a field of the feature table.
+ */
+export type EncodingChannel =
+  | 'tipLabel'
+  | 'rowTint'
+  | 'branch'
+  | 'featureFill'
+  | 'featureLabel'
+
+/**
+ * A channel, the field feeding it, and the scale it reads that field through.
+ * See docs/layers.md
+ */
+export interface Encoding {
+  channel: EncodingChannel
+  field: string
+  scale?: ScaleSpec
+}
+
+/** an Encoding with its scale resolved against the values in the table */
+export type ResolvedEncoding = Encoding & ResolvedScale
+
 /** a Highlight resolved to visible column indices and row indices */
 export interface ResolvedHighlight {
   startCol?: number

package/src/umd.ts

@@ -1,9 +1,11 @@
 import * as React from 'react'
 
-// a host that swaps models (the R htmlwidget on re-render) has to destroy the
-// old one, or the disposers its autoruns registered never run
+// a page that builds models with MSAModelF destroys each one it replaces, so
+// the disposers its autoruns registered run
 export { destroy } from '@jbrowse/mobx-state-tree'
 export { default as MSAView } from './components/Loading.tsx'
+export { mount } from './mount.tsx'
+export { defineMsaElement } from './element.ts'
 export { type MsaViewModel, default as MSAModelF } from './model.ts'
 
 export * from 'react-dom/client'