jbrowse-plugin-graphgenomeviewer 1.0.0 → 3.0.3

package/src/GraphGenomeView/layout/walkRows.test.ts

@@ -0,0 +1,178 @@
+import { existsSync, readFileSync } from 'fs'
+
+import { walkRows } from './walkRows'
+import { parseGFA } from '../../gfa-core/index'
+import { convertGFAToGraph } from '../gfa/gfaConverter'
+import { anchorGraph, pathOrigin } from '../pathAnchoring'
+
+function pggbGraph() {
+  const gfa = readFileSync(
+    require.resolve('../../../test_data/ecoli_pggb_subgraph.gfa'),
+    'utf8',
+  )
+  return anchorGraph(convertGFAToGraph(parseGFA(gfa), 'pggb'), 'K12')
+}
+
+const KIV2 = '.test-jbrowse-variants/test_data/graphgenomeview/kiv2_eight.gfa'
+
+test('one row per non-reference path, longest first, bp summed over its nodes', () => {
+  const graph = pggbGraph()
+  const result = walkRows(graph)!
+  expect(result.reference.label).toBe('K12')
+  expect(result.rows.map(r => r.label).sort()).toEqual([
+    'CFT073',
+    'IAI39',
+    'NCTC86',
+    'Sakai',
+  ])
+  for (let i = 1; i < result.rows.length; i++) {
+    expect(result.rows[i - 1]!.bp).toBeGreaterThanOrEqual(result.rows[i]!.bp)
+  }
+  const byId = new Map(graph.nodes.map(n => [n.id, n.length]))
+  for (const row of [result.reference, ...result.rows]) {
+    const path = graph.paths!.find(p => p.name === row.name)!
+    const total = path.nodeIds.reduce((s, id) => s + byId.get(id)!, 0)
+    expect(row.bp).toBe(total)
+    expect(row.runs.reduce((s, r) => s + r.bp, 0)).toBe(total)
+    expect(row.complete).toBe(true)
+  }
+  expect(result.reference.offReferenceBp).toBe(0)
+})
+
+test('runs alternate and cover the row without gaps', () => {
+  const { rows } = walkRows(pggbGraph())!
+  for (const row of rows) {
+    let pos = 0
+    row.runs.forEach((run, i) => {
+      expect(run.start).toBe(pos)
+      if (i > 0) {
+        expect(run.onReference).not.toBe(row.runs[i - 1]!.onReference)
+      }
+      pos += run.bp
+    })
+  }
+})
+
+test('a region measures between its flanking reference nodes', () => {
+  const graph = pggbGraph()
+  const byId = new Map(graph.nodes.map(n => [n.id, n.length]))
+  const reference = graph.paths!.find(
+    p => pathOrigin(p.name).name === graph.referencePath,
+  )!
+  const start = graph.anchorPaths!.find(
+    p => p.name === graph.referencePath,
+  )!.start
+  const ends = [start]
+  for (const id of reference.nodeIds) {
+    ends.push(ends.at(-1)! + byId.get(id)!)
+  }
+  const n = reference.nodeIds.length
+  // flanks are the 2nd node and the 2nd-to-last, so the slice is nodes 2..n-3
+  const region = { start: ends[2]!, end: ends[n - 2]! }
+  const cut = walkRows(graph, region)!
+  expect(cut.origin).toBe(region.start)
+  expect(cut.reference.bp).toBe(ends[n - 2]! - ends[2]!)
+  expect(cut.reference.complete).toBe(true)
+  const whole = walkRows(graph)!
+  expect(cut.reference.bp).toBeLessThan(whole.reference.bp)
+})
+
+test('a walk that skips the flanking node is cut at the next one it visits', () => {
+  const graph = pggbGraph()
+  const byId = new Map(graph.nodes.map(n => [n.id, n.length]))
+  const reference = graph.paths!.find(
+    p => pathOrigin(p.name).name === graph.referencePath,
+  )!
+  const start = graph.anchorPaths!.find(
+    p => p.name === graph.referencePath,
+  )!.start
+  const ends = [start]
+  for (const id of reference.nodeIds) {
+    ends.push(ends.at(-1)! + byId.get(id)!)
+  }
+  const n = reference.nodeIds.length
+  const region = { start: ends[3]!, end: ends[n - 3]! }
+  const skipper = {
+    ...reference,
+    name: 'skipper',
+    nodeIds: reference.nodeIds.filter((_, i) => i !== 2 && i !== n - 3),
+  }
+  const cut = walkRows({ ...graph, paths: [...graph.paths!, skipper] }, region)!
+  const row = cut.rows.find(r => r.name === 'skipper')!
+  expect(row.complete).toBe(true)
+  expect(row.bp).toBe(cut.reference.bp)
+})
+
+// The numbers scripts/layout-lab/copycount.mjs reports for the hosted
+// eight-haplotype KIV-2 cut: GRCh38 about 33 kb through the window, HG00133
+// about 149 kb, so HG00133 carries roughly 21 more units of 5,548 bp.
+test.skipIf(!existsSync(KIV2))(
+  'KIV-2: HG00133 carries ~116 kb GRCh38 does not',
+  () => {
+    const graph = anchorGraph(
+      convertGFAToGraph(parseGFA(readFileSync(KIV2, 'utf8')), 'kiv2'),
+      'GRCh38',
+    )
+    const result = walkRows(graph)!
+    expect(result.reference.label).toBe('GRCh38#0')
+    expect(result.reference.bp).toBeGreaterThan(32_000)
+    expect(result.reference.bp).toBeLessThan(34_000)
+    expect(result.rows[0]!.label).toBe('HG00133#1')
+    expect(result.rows[0]!.bp).toBeGreaterThan(145_000)
+    expect(result.rows[0]!.offReferenceBp / 5548).toBeGreaterThan(19)
+    expect(result.rows.map(r => r.label)).toHaveLength(8)
+  },
+)
+
+test('a cut that stops at the window leaves whole walks, not partial ones', () => {
+  const graph = pggbGraph()
+  const byId = new Map(graph.nodes.map(n => [n.id, n.length]))
+  const reference = graph.paths!.find(
+    p => pathOrigin(p.name).name === graph.referencePath,
+  )!
+  const start = graph.anchorPaths!.find(
+    p => p.name === graph.referencePath,
+  )!.start
+  let end = start
+  for (const id of reference.nodeIds) {
+    end += byId.get(id)!
+  }
+  // the region IS the reference walk, so no node lies outside it
+  const rows = walkRows(graph, { start, end })!
+  expect(rows.rows.every(r => r.complete)).toBe(true)
+  expect(rows.reference.complete).toBe(true)
+})
+
+test('a walk that crosses the window backwards reads in reference direction', () => {
+  const graph = pggbGraph()
+  const byId = new Map(graph.nodes.map(n => [n.id, n.length]))
+  const reference = graph.paths!.find(
+    p => pathOrigin(p.name).name === graph.referencePath,
+  )!
+  const start = graph.anchorPaths!.find(
+    p => p.name === graph.referencePath,
+  )!.start
+  const ends = [start]
+  for (const id of reference.nodeIds) {
+    ends.push(ends.at(-1)! + byId.get(id)!)
+  }
+  const n = reference.nodeIds.length
+  const region = { start: ends[2]!, end: ends[n - 2]! }
+  const forward = walkRows(graph, region)!.rows.find(
+    r => r.complete && r.runs.length > 1,
+  )!
+  expect(forward).toBeDefined()
+  const path = graph.paths!.find(p => p.name === forward.name)!
+  const backwards = {
+    ...path,
+    name: 'backwards',
+    nodeIds: [...path.nodeIds].reverse(),
+  }
+  const cut = walkRows(
+    { ...graph, paths: [...graph.paths!, backwards] },
+    region,
+  )!
+  const row = cut.rows.find(r => r.name === 'backwards')!
+  expect(row.complete).toBe(true)
+  expect(row.runs).toEqual(forward.runs)
+})

package/src/GraphGenomeView/layout/walkRows.ts

@@ -0,0 +1,177 @@
+import { panSNSample } from '../../pansn'
+import { pathOrigin } from '../pathAnchoring'
+
+import type { Graph, GraphPath } from '../types'
+
+// Each haplotype walk on its own bp axis, so what a walk carries through the
+// window is its bar length. Reference-anchored rows cannot state that: a
+// haplotype's private copies of a repeat consume no reference and collapse to
+// a mark, which is why the KIV-2 array reads as a knot in every node layout
+// and as a ladder here.
+//
+// A base-level graph does not revisit reference nodes through a repeat array,
+// so a copy count is not a visit count; it is the sequence a walk spends
+// between the reference nodes flanking the window, divided by the unit. Runs
+// distinguish sequence the reference walk also carries from sequence it does
+// not, so an expansion is the purple stretch of a row.
+
+export interface WalkRun {
+  // bp offset from the start of this walk's slice
+  start: number
+  bp: number
+  onReference: boolean
+}
+
+export interface WalkRow {
+  name: string
+  label: string
+  sample: string
+  bp: number
+  offReferenceBp: number
+  // false when the walk does not reach both flanking reference nodes, in which
+  // case the whole walk is measured and the bar says so
+  complete: boolean
+  runs: WalkRun[]
+}
+
+export interface WalkRows {
+  // reference bp the rows' bars start at, so a row's x is origin + run.start
+  origin: number
+  // repeat unit in bp when a repeat annotation supplied one; the bars tile by it
+  unit?: number
+  reference: WalkRow
+  // every other walk, longest first
+  rows: WalkRow[]
+}
+
+function sampleOf(path: GraphPath) {
+  return path.sample ?? panSNSample(path.name)
+}
+
+function labelOf(path: GraphPath) {
+  return path.haplotype !== undefined && path.sample !== undefined
+    ? `${path.sample}#${path.haplotype}`
+    : sampleOf(path)
+}
+
+// Each walk is cut at the nearest reference nodes IT visits on either side of
+// the region, so a walk that skips one flanking node at a SNP is still measured
+// between flanks rather than whole.
+function sliceBetween(
+  nodeIds: string[],
+  span: Map<string, { start: number; end: number }>,
+  region: { start: number; end: number } | undefined,
+  flanked = true,
+) {
+  // A cut that stops at the window carries no flanking reference for anyone,
+  // so every walk is whole and the slice is the walk.
+  if (!region || !flanked) {
+    return { ids: nodeIds, complete: true }
+  }
+  let i0 = -1
+  let i1 = -1
+  let bestEnd = -Infinity
+  let bestStart = Infinity
+  nodeIds.forEach((id, i) => {
+    const s = span.get(id)
+    if (s) {
+      if (s.end <= region.start && s.end > bestEnd) {
+        bestEnd = s.end
+        i0 = i
+      }
+      if (s.start >= region.end && s.start < bestStart) {
+        bestStart = s.start
+        i1 = i
+      }
+    }
+  })
+  if (i0 < 0 || i1 < 0) {
+    return { ids: nodeIds, complete: false }
+  }
+  const ids = nodeIds.slice(Math.min(i0, i1) + 1, Math.max(i0, i1))
+  return { ids: i0 < i1 ? ids : ids.reverse(), complete: true }
+}
+
+export function walkRows(
+  graph: Graph,
+  region?: { start: number; end: number },
+  unit?: number,
+): WalkRows | undefined {
+  const paths = graph.paths ?? []
+  // `referencePath` is the anchor name, which pathOrigin has already stripped
+  // of the range suffix odgi leaves on a P record's name
+  const reference =
+    paths.find(p => pathOrigin(p.name).name === graph.referencePath) ?? paths[0]
+  if (!reference || paths.length < 2) {
+    return undefined
+  }
+  const lengthOf = new Map(graph.nodes.map(n => [n.id, n.length]))
+  const onReference = new Set(reference.nodeIds)
+  const referenceStart =
+    graph.anchorPaths?.find(p => p.name === pathOrigin(reference.name).name)
+      ?.start ?? 0
+
+  const cut = region && region.end > region.start ? region : undefined
+  const span = new Map<string, { start: number; end: number }>()
+  let pos = referenceStart
+  for (const id of reference.nodeIds) {
+    const len = lengthOf.get(id) ?? 0
+    if (!span.has(id)) {
+      span.set(id, { start: pos, end: pos + len })
+    }
+    pos += len
+  }
+
+  // Whether the reference reaches past the region on both sides, i.e. whether
+  // a flanking node exists for any walk to be cut at.
+  const flanked =
+    cut === undefined ||
+    ([...span.values()].some(s => s.end <= cut.start) &&
+      [...span.values()].some(s => s.start >= cut.end))
+
+  const rowOf = (path: GraphPath): WalkRow => {
+    const { ids, complete } = sliceBetween(path.nodeIds, span, cut, flanked)
+    const runs: WalkRun[] = []
+    let bp = 0
+    let offReferenceBp = 0
+    for (const id of ids) {
+      const len = lengthOf.get(id) ?? 0
+      const shared = onReference.has(id)
+      const last = runs.at(-1)
+      if (last?.onReference === shared) {
+        last.bp += len
+      } else {
+        runs.push({ start: bp, bp: len, onReference: shared })
+      }
+      bp += len
+      if (!shared) {
+        offReferenceBp += len
+      }
+    }
+    return {
+      name: path.name,
+      label: labelOf(path),
+      sample: sampleOf(path),
+      bp,
+      offReferenceBp,
+      complete,
+      runs,
+    }
+  }
+
+  const origin = cut ? cut.start : referenceStart
+  return {
+    origin,
+    unit,
+    reference: rowOf(reference),
+    rows: paths
+      .filter(p => p !== reference)
+      .map(rowOf)
+      .sort(
+        (a, b) =>
+          Number(b.complete) - Number(a.complete) ||
+          b.bp - a.bp ||
+          a.label.localeCompare(b.label),
+      ),
+  }
+}

package/src/GraphGenomeView/layoutModes.ts

@@ -0,0 +1,131 @@
+import { isBackbone, isOffReference } from './anchoredNodes'
+import { anchoredLayout } from './layout/anchoredLayout'
+import { orderedLayout } from './layout/orderedLayout'
+import { sampleRowLayout } from './layout/sampleRowLayout'
+import { variantMapLayout } from './layout/variantMapLayout'
+import { walkRowLayout } from './layout/walkRowLayout'
+
+import type { Graph, LayoutResult } from './types'
+
+// The force layout's menu label. jbrowse-components' check-menu-labels scans
+// this src/ for string literals, so a documented **Layout → …** path is held
+// to what the dropdown renders.
+export const FORCE_LAYOUT_LABEL = 'Force-directed layout'
+
+// One table drives the persisted enum, the toolbar dropdown, and the dispatch in
+// the model, so adding a layout is one entry rather than several edits that can
+// disagree.
+//
+// `run` returning undefined means "this mode can't draw this graph" and hands
+// off to the remote Bandage FMMM engine. 'auto' uses it when a GFA has no
+// rank-0 backbone — neither declared in rGFA tags nor derivable from P/W lines
+// (pathAnchoring.ts) — and 'force' is simply the mode that always takes it.
+export interface LayoutMode {
+  value: string
+  label: string
+  description: string
+  // `region` is the interval the cut was made for, absent for a whole-file
+  // import. The reference-anchored modes scale their rows and their allele
+  // floor against it rather than against the backbone they were handed, which
+  // a long-range allele's far anchor stretches well past the window
+  // (referenceSpan).
+  run: (
+    graph: Graph,
+    region?: { start: number; end: number },
+  ) => LayoutResult | undefined
+  // whether this mode can draw this graph at all; the dropdown greys out the
+  // rest rather than hiding them, so the reason a mode is unavailable stays
+  // visible instead of the menu silently changing shape between graphs
+  available: (graph: Graph) => boolean
+  // whether `run` draws this graph itself, as opposed to handing off to the
+  // engine. Not the same question as `available` and not derivable from it:
+  // 'force' is available for every graph and draws none of them itself. The two
+  // coincide for the anchored modes, which is stated by sharing the predicate
+  // rather than by restating it.
+  drawsLocally: (graph: Graph) => boolean
+}
+
+const hasBackbone = (graph: Graph) => graph.nodes.some(isBackbone)
+const hasWalks = (graph: Graph) =>
+  hasBackbone(graph) && (graph.paths?.length ?? 0) > 1
+const hasAlleles = (graph: Graph) =>
+  hasBackbone(graph) && graph.nodes.some(isOffReference)
+
+// `satisfies` rather than a `: LayoutMode[]` annotation: the annotation widened
+// every `value` to string, which collapsed LayoutModeValue to string and left the
+// persisted enum unable to state which values it accepts.
+export const LAYOUT_MODES = [
+  {
+    value: 'auto',
+    label: 'Anchored',
+    description:
+      'x is reference bp, one row per stable rank. Needs rGFA tags or a reference path.',
+    run: anchoredLayout,
+    available: hasBackbone,
+    drawsLocally: hasBackbone,
+  },
+  {
+    value: 'samplerows',
+    label: 'Sample rows',
+    description:
+      'x is reference bp, one row per contributing assembly. Needs rGFA tags or a reference path.',
+    run: sampleRowLayout,
+    available: hasAlleles,
+    drawsLocally: hasAlleles,
+  },
+  {
+    value: 'walkrows',
+    label: 'Walk rows',
+    description:
+      "x is each walk's own bp: one bar per haplotype, sequence the reference also carries in blue and sequence it does not in purple, so a repeat expansion reads as bar length. Needs W or P lines.",
+    run: walkRowLayout,
+    available: hasWalks,
+    drawsLocally: hasWalks,
+  },
+  {
+    value: 'ordered',
+    label: 'Ordered',
+    description:
+      'x is reference order, not bp: every node gets room, bubbles read as lenses. Needs rGFA tags or a reference path.',
+    run: orderedLayout,
+    available: hasBackbone,
+    drawsLocally: hasBackbone,
+  },
+  {
+    value: 'variants',
+    label: 'Variant map',
+    description:
+      'The reference as a line with one typed glyph per bubble, from the bubble index or from the graph itself: SNP, indel, deletion, inversion, repeat array. Click a glyph to open the graph inside it.',
+    run: variantMapLayout,
+    available: hasBackbone,
+    drawsLocally: hasBackbone,
+  },
+  {
+    value: 'force',
+    label: FORCE_LAYOUT_LABEL,
+    description: 'OGDF FMMM, via the external Bandage engine.',
+    run: () => undefined,
+    available: () => true,
+    drawsLocally: () => false,
+  },
+] as const satisfies readonly LayoutMode[]
+
+export type LayoutModeValue = (typeof LAYOUT_MODES)[number]['value']
+
+export const LAYOUT_MODE_VALUES = LAYOUT_MODES.map(m => m.value)
+
+// Whether the drawing a mode produces for a graph comes from the FMMM engine.
+// The settings that only the engine reads — layout quality, bubble spread —
+// are shown against this, so a control that cannot do anything to the drawing
+// on screen says so instead of appearing to work.
+export function modeUsesLayoutEngine(value: string, graph: Graph) {
+  return !layoutModeByValue(value).drawsLocally(graph)
+}
+
+export function layoutModeByValue(value: string) {
+  // An unknown value can only come from a snapshot written by a build that had
+  // a mode this one doesn't. It falls back to 'auto' rather than to the model's
+  // own default of 'force', because 'auto' declines any graph it cannot draw and
+  // hands off to force anyway, so this is the fallback that covers both.
+  return LAYOUT_MODES.find(m => m.value === value) ?? LAYOUT_MODES[0]
+}