react-msaview 9.1.0 → 9.2.0

package/src/neighborJoining.ts

@@ -1,48 +1,7 @@
 // Neighbor Joining tree construction using BLOSUM62 distances
 // Based on Saitou & Nei (1987) "The neighbor-joining method"
 
-// prettier-ignore
-const BLOSUM62_KEYS = 'ARNDCQEGHILKMFPSTWYVBZX*'
-// prettier-ignore
-const BLOSUM62_DATA = [
-  [ 4,-1,-2,-2, 0,-1,-1, 0,-2,-1,-1,-1,-1,-2,-1, 1, 0,-3,-2, 0,-2,-1, 0,-4],
-  [-1, 5, 0,-2,-3, 1, 0,-2, 0,-3,-2, 2,-1,-3,-2,-1,-1,-3,-2,-3,-1, 0,-1,-4],
-  [-2, 0, 6, 1,-3, 0, 0, 0, 1,-3,-3, 0,-2,-3,-2, 1, 0,-4,-2,-3, 3, 0,-1,-4],
-  [-2,-2, 1, 6,-3, 0, 2,-1,-1,-3,-4,-1,-3,-3,-1, 0,-1,-4,-3,-3, 4, 1,-1,-4],
-  [ 0,-3,-3,-3, 9,-3,-4,-3,-3,-1,-1,-3,-1,-2,-3,-1,-1,-2,-2,-1,-3,-3,-2,-4],
-  [-1, 1, 0, 0,-3, 5, 2,-2, 0,-3,-2, 1, 0,-3,-1, 0,-1,-2,-1,-2, 0, 3,-1,-4],
-  [-1, 0, 0, 2,-4, 2, 5,-2, 0,-3,-3, 1,-2,-3,-1, 0,-1,-3,-2,-2, 1, 4,-1,-4],
-  [ 0,-2, 0,-1,-3,-2,-2, 6,-2,-4,-4,-2,-3,-3,-2, 0,-2,-2,-3,-3,-1,-2,-1,-4],
-  [-2, 0, 1,-1,-3, 0, 0,-2, 8,-3,-3,-1,-2,-1,-2,-1,-2,-2, 2,-3, 0, 0,-1,-4],
-  [-1,-3,-3,-3,-1,-3,-3,-4,-3, 4, 2,-3, 1, 0,-3,-2,-1,-3,-1, 3,-3,-3,-1,-4],
-  [-1,-2,-3,-4,-1,-2,-3,-4,-3, 2, 4,-2, 2, 0,-3,-2,-1,-2,-1, 1,-4,-3,-1,-4],
-  [-1, 2, 0,-1,-3, 1, 1,-2,-1,-3,-2, 5,-1,-3,-1, 0,-1,-3,-2,-2, 0, 1,-1,-4],
-  [-1,-1,-2,-3,-1, 0,-2,-3,-2, 1, 2,-1, 5, 0,-2,-1,-1,-1,-1, 1,-3,-1,-1,-4],
-  [-2,-3,-3,-3,-2,-3,-3,-3,-1, 0, 0,-3, 0, 6,-4,-2,-2, 1, 3,-1,-3,-3,-1,-4],
-  [-1,-2,-2,-1,-3,-1,-1,-2,-2,-3,-3,-1,-2,-4, 7,-1,-1,-4,-3,-2,-2,-1,-2,-4],
-  [ 1,-1, 1, 0,-1, 0, 0, 0,-1,-2,-2, 0,-1,-2,-1, 4, 1,-3,-2,-2, 0, 0, 0,-4],
-  [ 0,-1, 0,-1,-1,-1,-1,-2,-2,-1,-1,-1,-1,-2,-1, 1, 5,-2,-2, 0,-1,-1, 0,-4],
-  [-3,-3,-4,-4,-2,-2,-3,-2,-2,-3,-2,-3,-1, 1,-4,-3,-2,11, 2,-3,-4,-3,-2,-4],
-  [-2,-2,-2,-3,-2,-1,-2,-3, 2,-1,-1,-2,-1, 3,-3,-2,-2, 2, 7,-1,-3,-2,-1,-4],
-  [ 0,-3,-3,-3,-1,-2,-2,-3,-3, 3, 1,-2, 1,-1,-2,-2, 0,-3,-1, 4,-3,-2,-1,-4],
-  [-2,-1, 3, 4,-3, 0, 1,-1, 0,-3,-4, 0,-3,-3,-2, 0,-1,-4,-3,-3, 4, 1,-1,-4],
-  [-1, 0, 0, 1,-3, 3, 4,-2, 0,-3,-3, 1,-1,-3,-1, 0,-1,-3,-2,-2, 1, 4,-1,-4],
-  [ 0,-1,-1,-1,-2,-1,-1,-1,-1,-1,-1,-1,-1,-1,-2, 0, 0,-2,-1,-1,-1,-1,-1,-4],
-  [-4,-4,-4,-4,-4,-4,-4,-4,-4,-4,-4,-4,-4,-4,-4,-4,-4,-4,-4,-4,-4,-4,-4, 1],
-]
-
-const NUM_SYMBOLS = BLOSUM62_KEYS.length
-const BLOSUM62 = Int8Array.from(BLOSUM62_DATA.flat())
-
-// charCode -> row/column in BLOSUM62, -1 for anything the matrix does not name.
-// On a 120x800 alignment a Map keyed by upper-cased character took 2.6s to
-// build a tree, against 0.34s for this table.
-const symbolOfCode = new Int8Array(128).fill(-1)
-for (let i = 0; i < NUM_SYMBOLS; i++) {
-  const key = BLOSUM62_KEYS[i]!
-  symbolOfCode[key.charCodeAt(0)] = i
-  symbolOfCode[key.toLowerCase().charCodeAt(0)] = i
-}
+import { BLOSUM62, NUM_SYMBOLS, symbolOfCode } from './blosum62.ts'
 
 // gap, or past the end of a row shorter than the alignment
 const GAP = -2

package/src/renderToSvg.tsx

@@ -7,7 +7,6 @@ import { visibleRowRange } from './components/getVisibleLeaves.ts'
 import MinimapSVG from './components/minimap/MinimapSVG.tsx'
 import { legendRows } from './components/msa/legendRows.ts'
 import { rasterApplies, rasterImageHref } from './components/msa/msaRaster.ts'
-import { renderBoxFeatureCanvasBlock } from './components/msa/renderBoxFeatureCanvasBlock.ts'
 import { renderPersistentHighlights } from './components/msa/renderHighlights.ts'
 import { renderMSABlock } from './components/msa/renderMSABlock.ts'
 import { visibleColRange } from './components/msa/visibleColRange.ts'
@@ -412,18 +411,6 @@ function CoreRendering({ model, theme, layout, Context, layers }: LayerProps) {
   const raster = rasterBackground({ model, theme, layout })
 
   const msaCtx = new Context(msaAreaWidth, contentHeight)
-  renderBoxFeatureCanvasBlock({
-    model,
-    theme,
-    ctx: msaCtx,
-    offsetX,
-    offsetY,
-    // the overlay culls bands to this width; without it the export falls back
-    // to the on-screen 500px block size and drops every band past it
-    blockSizeXOverride: msaAreaWidth,
-    blockSizeYOverride: contentHeight,
-    highResScaleFactorOverride: 1,
-  })
   renderMSABlock({
     model,
     theme,
@@ -434,6 +421,7 @@ function CoreRendering({ model, theme, layout, Context, layers }: LayerProps) {
     blockSizeYOverride: contentHeight,
     highResScaleFactorOverride: 1,
     rasterTiles: !!raster,
+    domains: true,
   })
   msaCtx.resetTransform()
   renderPersistentHighlights({

package/src/rerootTree.ts

@@ -13,19 +13,18 @@ export interface TreeNode {
   children?: TreeNode[]
 }
 
-function preorder<N extends TreeNode>(root: N) {
+export function preorder<N extends TreeNode>(root: N, parents?: Map<N, N>) {
   const order: N[] = []
-  const parents = new Map<N, N>()
   const stack = [root]
   while (stack.length > 0) {
     const node = stack.pop()!
     order.push(node)
     for (const child of (node.children ?? []) as N[]) {
-      parents.set(child, node)
+      parents?.set(child, node)
       stack.push(child)
     }
   }
-  return { order, parents }
+  return order
 }
 
 function hasLengths(order: TreeNode[]) {
@@ -56,7 +55,8 @@ export function rerootTree<N extends TreeNode>(
   target: N,
   offset?: number,
 ): TreeNode {
-  const { order, parents } = preorder(root)
+  const parents = new Map<N, N>()
+  const order = preorder(root, parents)
   if (!parents.has(target)) {
     return root
   }
@@ -112,7 +112,8 @@ export function rerootTree<N extends TreeNode>(
  * counts branches.
  */
 export function midpointRoot<N extends TreeNode>(root: N): TreeNode {
-  const { order, parents } = preorder(root)
+  const parents = new Map<N, N>()
+  const order = preorder(root, parents)
   const tips = order.filter(n => !n.children?.length)
   if (tips.length < 2) {
     return root

package/src/schemeResidueColor.ts

@@ -0,0 +1,37 @@
+import { colord } from 'colord'
+
+import { tileColorFn } from './components/msa/tileColor.ts'
+
+import type { MsaViewModel } from './model.ts'
+
+/**
+ * A reader for the color the active scheme gives a row's residue, as hex, for a
+ * host that paints another view, such as a structure, with the alignment's own
+ * colors. `seqPos` is 1-based, like `structureResidue`. The reader returns
+ * undefined where the scheme leaves the residue uncolored, the row lacks it, or
+ * its column is hidden.
+ *
+ * Build it inside a reaction: a new scheme, a hidden gap column or a collapsed
+ * clade then re-runs the caller.
+ */
+export function schemeResidueColor(model: MsaViewModel) {
+  const colorAt = tileColorFn(model)
+  const { columns } = model
+  const hexes = new Map<string, string | undefined>()
+  const toHex = (color: string) => {
+    if (!hexes.has(color)) {
+      const parsed = colord(color)
+      hexes.set(color, parsed.isValid() ? parsed.toHex() : undefined)
+    }
+    return hexes.get(color)
+  }
+  return (rowName: string, seqPos: number) => {
+    const col = model.seqPosToVisibleCol(rowName, seqPos - 1)
+    const letter = col === undefined ? undefined : columns.get(rowName)?.[col]
+    const color =
+      col === undefined || letter === undefined
+        ? undefined
+        : colorAt(col, letter)
+    return color === undefined ? undefined : toHex(color)
+  }
+}

package/src/similarityColors.ts

@@ -0,0 +1,112 @@
+// Similarity shading, after biotite's plot_alignment_similarity_based and
+// Jalview's BLOSUM62 score scheme. Each residue takes a shade of one hue by how
+// similar it is, on average, to the other residues of its column.
+
+import { BLOSUM62, NUM_SYMBOLS, symbolOfCode } from './blosum62.ts'
+import { letterOfResidueSlot, numResidueSlots } from './columnCounts.ts'
+
+import type { ColumnCounts } from './columnCounts.ts'
+
+const AMINO_ACIDS = 20
+const HUE = 240
+const SATURATION = 50
+const LIGHTEST = 96
+const DARKEST = 40
+
+// BLOSUM62 scaled per row to 0..1 over the twenty amino acids, so a residue's
+// own score is 1 and its worst substitution 0. Not symmetric, like biotite's.
+const normalized = new Float32Array(NUM_SYMBOLS * NUM_SYMBOLS)
+for (let a = 0; a < NUM_SYMBOLS; a++) {
+  let min = Infinity
+  let max = -Infinity
+  for (let b = 0; b < AMINO_ACIDS; b++) {
+    const score = BLOSUM62[a * NUM_SYMBOLS + b]!
+    min = Math.min(min, score)
+    max = Math.max(max, score)
+  }
+  for (let b = 0; b < NUM_SYMBOLS; b++) {
+    const scaled = (BLOSUM62[a * NUM_SYMBOLS + b]! - min) / (max - min)
+    normalized[a * NUM_SYMBOLS + b] = Math.min(Math.max(scaled, 0), 1)
+  }
+}
+
+// residue slot -> row of the matrix, -1 for a letter the matrix does not name
+const symbolOfSlot = Int8Array.from({ length: numResidueSlots }, (_, slot) => {
+  const letter = letterOfResidueSlot(slot)
+  return letter.length === 1 ? symbolOfCode[letter.charCodeAt(0)]! : -1
+})
+
+function shade(similarity: number) {
+  const lightness = Math.round(LIGHTEST - (LIGHTEST - DARKEST) * similarity)
+  return `hsl(${HUE}, ${SATURATION}%, ${lightness}%)`
+}
+
+interface Measure {
+  /** whether a residue counts toward the means at all */
+  counted: (slot: number) => boolean
+  /** whether a residue takes a shade, given it is counted */
+  shaded: (slot: number) => boolean
+  /** similarity of residue `a` to residue `b`, 0..1 */
+  score: (a: number, b: number) => number
+}
+
+/**
+ * Shades each residue of one column by its mean similarity to the column's
+ * other residues, gaps left out of the mean. A column of fewer than two counted
+ * residues has nothing to compare and colors nothing.
+ */
+function shadeColumn(counts: ColumnCounts, col: number, measure: Measure) {
+  const { counted, shaded, score } = measure
+  const present: [slot: number, count: number][] = []
+  let total = 0
+  counts.forEachResidue(col, (slot, count) => {
+    if (counted(slot)) {
+      present.push([slot, count])
+      total += count
+    }
+  })
+
+  const colors: Record<string, string> = {}
+  if (total < 2) {
+    return colors
+  }
+  for (const [a] of present) {
+    if (shaded(a)) {
+      let sum = -score(a, a)
+      for (const [b, count] of present) {
+        sum += count * score(a, b)
+      }
+      colors[letterOfResidueSlot(a)] = shade(sum / (total - 1))
+    }
+  }
+  return colors
+}
+
+const blosum62: Measure = {
+  counted: slot => symbolOfSlot[slot]! >= 0,
+  shaded: slot => symbolOfSlot[slot]! < AMINO_ACIDS,
+  score: (a, b) =>
+    normalized[symbolOfSlot[a]! * NUM_SYMBOLS + symbolOfSlot[b]!]!,
+}
+
+const identity: Measure = {
+  counted: () => true,
+  shaded: () => true,
+  score: (a, b) => (a === b ? 1 : 0),
+}
+
+/**
+ * The amino acids of a column shaded by BLOSUM62 similarity. Letters the matrix
+ * does not name, such as U, O and J, count for nothing and take no shade.
+ */
+export function blosum62ColumnColors(counts: ColumnCounts, col: number) {
+  return shadeColumn(counts, col, blosum62)
+}
+
+/**
+ * Nucleotides and anything else without a substitution matrix: a residue's
+ * similarity is the fraction of the rest of its column that equals it.
+ */
+export function identityColumnColors(counts: ColumnCounts, col: number) {
+  return shadeColumn(counts, col, identity)
+}

package/src/treeDisplay.ts

@@ -0,0 +1,278 @@
+import { generateNodeIds, parseEmfTree, parseNewick } from 'msa-parsers'
+
+import { cladeHighlightAlpha, cladeHighlightColor } from './constants.ts'
+import { flatToTree } from './flatToTree.ts'
+import {
+  collapse,
+  find,
+  forEachDescendant,
+  hierarchy,
+  leafIndex,
+  leaves,
+  mrca,
+  sort,
+  sum as hierarchySum,
+} from './hierarchy.ts'
+import { parseAsn1 } from './parseAsn1.ts'
+import { midpointRoot, preorder, rerootTree } from './rerootTree.ts'
+import { withAlpha } from './util.ts'
+
+import type { HierarchyNode } from './hierarchy.ts'
+import type { TreeNode } from './rerootTree.ts'
+import type {
+  Clade,
+  CladeMark,
+  NodeWithIds,
+  ResolvedClade,
+  TreeOrder,
+  TreeRoot,
+} from './types.ts'
+
+export function parseTreeText(text: string) {
+  if (text.startsWith('BioTreeContainer')) {
+    return flatToTree(parseAsn1(text))
+  }
+  return parseNewick(text.startsWith('SEQ') ? parseEmfTree(text).tree : text)
+}
+
+// the marks that set tree state from a node rather than drawing
+const seedingMarks = new Set<CladeMark>(['collapse', 'focus', 'rotate'])
+
+/**
+ * Each tip of the full tree in the order the tree draws it, with the on-screen
+ * row that shows it: its own, or the row of the collapsed node standing for it
+ */
+function tipRows(root: HierarchyNode<NodeWithIds>) {
+  const rows = new Map<string, { order: number; row: number }>()
+  let row = 0
+  const pushReversed = (
+    stack: HierarchyNode<NodeWithIds>[],
+    nodes: HierarchyNode<NodeWithIds>[],
+  ) => {
+    for (let i = nodes.length - 1; i >= 0; i--) {
+      stack.push(nodes[i]!)
+    }
+  }
+  const stack = [root]
+  while (stack.length > 0) {
+    const node = stack.pop()!
+    if (node.children?.length) {
+      pushReversed(stack, node.children)
+    } else {
+      const hidden = [node]
+      while (hidden.length > 0) {
+        const tip = hidden.pop()!
+        const kids = tip.children ?? tip._children
+        if (kids?.length) {
+          pushReversed(hidden, kids)
+        } else {
+          rows.set(tip.data.name, { order: rows.size, row })
+        }
+      }
+      row++
+    }
+  }
+  return rows
+}
+
+/**
+ * The rows a clade covers and the node an `mrca` names, or undefined when the
+ * clade does not resolve: a tip name the tree does not have or has twice, or a
+ * leaf count `tips` disagrees with. A `range` counts its tips in the order
+ * `tips` gives them, so a collapsed clade inside it counts every leaf it
+ * stands for. `index` is the memoized leaf pass over the tree.
+ */
+function cladeRows(
+  clade: Clade,
+  root: HierarchyNode<NodeWithIds>,
+  index: Map<string, HierarchyNode<NodeWithIds> | undefined>,
+  tips: Map<string, { order: number; row: number }>,
+): { rows: [number, number]; nodeId?: string } | undefined {
+  if (clade.range) {
+    const [a, b] = clade.range.map(name =>
+      index.get(name) ? tips.get(name) : undefined,
+    )
+    if (a === undefined || b === undefined) {
+      return undefined
+    }
+    const [first, last] = a.order <= b.order ? [a, b] : [b, a]
+    return last.order - first.order + 1 === clade.tips
+      ? { rows: [first.row, last.row] }
+      : undefined
+  }
+  const node = clade.mrca ? mrca(root, clade.mrca, index) : undefined
+  if (!node) {
+    return undefined
+  }
+  const nodeTips = leaves(node)
+  if (nodeTips.length !== clade.tips) {
+    return undefined
+  }
+  let first = Infinity
+  let last = -Infinity
+  for (const tip of nodeTips) {
+    const row = tips.get(tip.data.name)?.row
+    if (row !== undefined) {
+      first = Math.min(first, row)
+      last = Math.max(last, row)
+    }
+  }
+  return first <= last
+    ? { rows: [first, last], nodeId: node.data.id }
+    : undefined
+}
+
+/**
+ * Every clade that resolves, with its fill color settled, against the rows of
+ * `displayed`, the tree as drawn. The tree panel resolves against the
+ * displayed rows and the overview against its own, so both take the tree they
+ * draw. A `range` record names no node, so the seeding marks, which need one,
+ * drop it.
+ */
+export function resolveClades(
+  clades: Clade[],
+  root: HierarchyNode<NodeWithIds>,
+  displayed: HierarchyNode<NodeWithIds>,
+): ResolvedClade[] {
+  const index = leafIndex(root)
+  const tips = tipRows(displayed)
+  return clades.flatMap(clade => {
+    const resolved = cladeRows(clade, root, index, tips)
+    const seeding = seedingMarks.has(clade.mark)
+    return resolved && !(seeding && resolved.nodeId === undefined)
+      ? [
+          {
+            ...resolved,
+            mark: clade.mark,
+            color: withAlpha(
+              clade.color ?? cladeHighlightColor,
+              cladeHighlightAlpha,
+            ),
+            markColor: clade.color,
+            label: clade.label,
+          },
+        ]
+      : []
+  })
+}
+
+const childOrders: Record<
+  TreeOrder,
+  ((a: HierarchyNode, b: HierarchyNode) => number) | undefined
+> = {
+  input: undefined,
+  branchLength: (a, b) => (a.data.length ?? 1) - (b.data.length ?? 1),
+  ladderize: (a, b) => a.value! - b.value!,
+  ladderizeReverse: (a, b) => b.value! - a.value!,
+}
+
+/**
+ * The tree with the display transforms applied: leaf counts summed, children
+ * put in `order` and each `rotated` node's reversed, `showOnly` taken as the
+ * new root, and each `collapsed` clade folded. The overview builds the same
+ * tree without the focus, so it shows the focused subtree inside the whole.
+ */
+export function buildTreeRoot(
+  tree: NodeWithIds,
+  {
+    collapsed,
+    rotated,
+    order,
+    showOnly,
+  }: {
+    collapsed: readonly string[]
+    rotated: readonly string[]
+    order: TreeOrder
+    showOnly?: string
+  },
+) {
+  let hier = hierarchy(tree, d => d.children)
+  hierarchySum(hier, d => (d.children.length > 0 ? 0 : 1))
+  const compare = childOrders[order]
+  if (compare) {
+    sort(hier, compare)
+  }
+  if (rotated.length > 0) {
+    const flip = new Set(rotated)
+    forEachDescendant(hier, n => {
+      if (flip.has(n.data.id)) {
+        n.children?.reverse()
+      }
+    })
+  }
+
+  if (showOnly) {
+    const res = find(hier, n => n.data.id === showOnly)
+    if (res) {
+      hier = res
+    }
+  }
+
+  for (const collapsedId of collapsed) {
+    const node = find(hier, n => n.data.id === collapsedId)
+    if (node) {
+      if (node.children) {
+        collapse(node)
+      } else if (node.parent?.children) {
+        node.parent.children = node.parent.children.filter(
+          c => c.data.id !== collapsedId,
+        )
+      }
+    }
+  }
+
+  return hier
+}
+
+/**
+ * The node whose branch an outgroup roots the tree on: the outgroup's most
+ * recent common ancestor, or the rest of the tips' where that ancestor is the
+ * root, since the outgroup then straddles the root and the branch above the
+ * other side is the same branch of the unrooted tree.
+ */
+export function outgroupNode(root: HierarchyNode, outgroup: string[]) {
+  const index = leafIndex(root)
+  const node = mrca(root, outgroup, index)
+  if (node !== root) {
+    return node
+  }
+  const out = new Set(outgroup)
+  const rest = leaves(root)
+    .map(n => n.data.name)
+    .filter(name => !out.has(name))
+  const other = mrca(root, rest, index)
+  return other === root ? undefined : other
+}
+
+/**
+ * `tree` rerooted as `treeRoot` asks, with fresh path ids. The ids of the tree
+ * as written become names on unnamed nodes, and a rerooting would carry them
+ * along as labels, so they come off first.
+ */
+export function rootTree(tree: NodeWithIds, treeRoot: TreeRoot) {
+  const plain = new Map<NodeWithIds, TreeNode>()
+  for (const node of preorder(tree).reverse()) {
+    plain.set(node, {
+      name: node.name === node.id ? undefined : node.name,
+      length: node.length,
+      children: node.children.map(c => plain.get(c)!),
+    })
+  }
+  const input = plain.get(tree)!
+  if (treeRoot === 'midpoint') {
+    return generateNodeIds(midpointRoot(input))
+  }
+  const target = outgroupNode(
+    hierarchy(tree, d => d.children),
+    treeRoot.outgroup,
+  )
+  return target
+    ? generateNodeIds(rerootTree(input, plain.get(target.data)!))
+    : tree
+}
+
+// the inclusive tip indices a node covers, from its xMin/xMax in a layout one
+// row per tip
+export function tipRange(node: HierarchyNode): [number, number] {
+  return [Math.round(node.xMin! - 0.5), Math.round(node.xMax! - 0.5)]
+}

package/src/types.ts

@@ -8,7 +8,7 @@ export interface Accession {
 }
 // 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'
+export type TrackKind = 'text' | 'bar' | 'logo' | 'arc' | 'ruler' | 'reference'
 
 /**
  * Which channel the color scheme paints. `fill` colors the cell a residue sits
@@ -27,14 +27,11 @@ export type ColorScheme = string | Required<Pick<ScaleSpec, 'map'>>
 export interface BasicTrackModel {
   id: string
   name: string
-  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 {
@@ -209,6 +206,12 @@ export interface MappedStructure {
   id: string
   kind?: 'experimental' | 'predicted'
   asymId?: string
+  /**
+   * which id `asymId` is, the file's `label_asym_id` or the author's
+   * `auth_asym_id`. Unset reads as either, label first, which is right for the
+   * common entry whose two ids agree and wrong where they collide.
+   */
+  asymIdKind?: 'label' | 'auth'
   url?: string
 }