jbrowse-plugin-graphgenomeviewer 1.0.0 → 3.0.3

package/src/GraphGenomeView/repeats/walkCalls.test.ts

@@ -0,0 +1,127 @@
+import cohort from './test_data/abca7_trgt_walks.json'
+import { CALL_TOLERANCE, withCalls } from './walkCalls'
+
+import type { RepeatCall } from './repeatFeatures'
+
+function walk(sample: string, bp: number, complete = true) {
+  return { sample, bp, complete }
+}
+
+const calls = (...bps: (number | RepeatCall)[]) =>
+  bps.map(bp => (typeof bp === 'number' ? { bp } : bp))
+
+test('each haplotype takes its own allele, and one of a pair can disagree', () => {
+  const rows = withCalls([walk('HG1', 3161), walk('HG1', 3161)], {
+    HG1: calls(387, 3161),
+  })
+  expect(rows.map(r => r.call?.bp)).toEqual([387, 3161])
+  expect(rows.map(r => r.call?.agrees)).toEqual([false, true])
+})
+
+// AL comes in the genotype's order, which is the genotyper's: TRGTdb's ABCA7
+// record lists the shortest allele first, and a graph's haplotype 1 is not it.
+test('the order a record lists its alleles in does not reach the pairing', () => {
+  const short = walk('HG1', 388)
+  const long = walk('HG1', 3183)
+  for (const listed of [calls(387, 3161), calls(3161, 387)]) {
+    expect(
+      withCalls([short, long], { HG1: listed }).map(r => r.call?.bp),
+    ).toEqual([387, 3161])
+    expect(
+      withCalls([long, short], { HG1: listed }).map(r => r.call?.bp),
+    ).toEqual([3161, 387])
+  }
+})
+
+test('an allele no read spanned is shown against its walk and never scored', () => {
+  const rows = withCalls([walk('HG02559', 5525), walk('HG02559', 493)], {
+    HG02559: calls(
+      { bp: 491, spanningReads: 1 },
+      { bp: 491, spanningReads: 0 },
+    ),
+  })
+  expect(rows.map(r => r.call)).toEqual([
+    { bp: 491, spanningReads: 0, agrees: undefined },
+    { bp: 491, spanningReads: 1, agrees: true },
+  ])
+})
+
+// HG00323's two walks against a genotype whose second allele has no spanning
+// read: the walk the read-backed call fits keeps the verdict wherever the two
+// equal lengths sit, because the backed allele is paired first.
+test('the read-backed allele is paired on merit, not on tie order', () => {
+  for (const listed of [
+    calls({ bp: 2640, spanningReads: 1 }, { bp: 2640, spanningReads: 0 }),
+    calls({ bp: 2640, spanningReads: 0 }, { bp: 2640, spanningReads: 1 }),
+  ]) {
+    const rows = withCalls([walk('HG1', 1642), walk('HG1', 2639)], {
+      HG1: listed,
+    })
+    expect(rows.map(r => r.call?.spanningReads)).toEqual([0, 1])
+    expect(rows.map(r => r.call?.agrees)).toEqual([undefined, true])
+  }
+})
+
+test('a walk that does not span the array keeps its tick and gets no verdict', () => {
+  const rows = withCalls(
+    [walk('HG04199', 1476), walk('HG04199', 3655, false)],
+    { HG04199: calls(1485, 8614) },
+  )
+  expect(rows.map(r => r.call?.bp)).toEqual([1485, 8614])
+  expect(rows.map(r => r.call?.agrees)).toEqual([true, undefined])
+})
+
+// HG02976 at ABCA7: one walk spans the array and lands on the longer allele
+// almost exactly, the other stops inside it. Paired on length alone the one
+// that stops takes the allele that fits, and the walk that spans reads as a
+// disagreement against what is left.
+test("a walk that stops inside the array cannot take a spanning walk's allele", () => {
+  const rows = withCalls(
+    [walk('HG02976', 2884), walk('HG02976', 3653, false)],
+    {
+      HG02976: calls(2274, 2886),
+    },
+  )
+  expect(rows.map(r => r.call?.bp)).toEqual([2886, 2274])
+  expect(rows.map(r => r.call?.agrees)).toEqual([true, undefined])
+})
+
+test('a surplus walk or an uncalled sample carries no call', () => {
+  const rows = withCalls(
+    [walk('HG1', 400), walk('HG1', 2000), walk('HG1', 4000), walk('HG2', 900)],
+    { HG1: calls(390, 4010) },
+  )
+  expect(rows.map(r => r.call?.bp)).toEqual([390, undefined, 4010, undefined])
+  expect(withCalls([walk('HG1', 400)], undefined)[0]!.call).toBeUndefined()
+})
+
+// Where CALL_TOLERANCE comes from. test_data holds every walk the HPRC graph
+// draws through the ABCA7 VNTR beside TRGT's genotype of the same sample, and
+// the two verdicts land in bands with a gap between them, so any threshold
+// across the gap sorts the cohort the same way. The counts are there to say
+// what a change moved.
+test('the threshold falls in a gap the ABCA7 cohort leaves empty', () => {
+  const rows = withCalls(cohort.rows, cohort.calls)
+  const apart = (r: (typeof rows)[number]) =>
+    Math.abs(r.call!.bp - r.bp) / Math.max(r.call!.bp, r.bp)
+  const scored = rows.filter(r => r.call?.agrees !== undefined)
+  const near = scored.filter(r => r.call!.agrees)
+  const far = scored.filter(r => !r.call!.agrees)
+  expect(Math.max(...near.map(apart))).toBeLessThan(0.08)
+  expect(Math.min(...far.map(apart))).toBeGreaterThan(0.14)
+  expect(CALL_TOLERANCE).toBeGreaterThan(0.08)
+  expect(CALL_TOLERANCE).toBeLessThan(0.14)
+  expect({
+    agrees: near.length,
+    apart: far.length,
+    unbacked: rows.filter(r => r.call?.spanningReads === 0).length,
+    partial: rows.filter(r => r.call && !r.complete).length,
+    uncalled: rows.filter(r => !r.call).length,
+  }).toEqual({
+    agrees: 142,
+    apart: 24,
+    unbacked: 18,
+    partial: 2,
+    uncalled: 0,
+  })
+})

package/src/GraphGenomeView/repeats/walkCalls.ts

@@ -0,0 +1,132 @@
+import type { RepeatCall } from './repeatFeatures'
+
+// Which genotyped allele belongs to which haplotype walk. A VCF states a
+// sample's alleles in genotype order, which is the genotyper's own order and
+// carries no correspondence to the assembly's haplotype numbering — TRGTdb's
+// ABCA7 record, for one, lists them shortest first. So the walks and the
+// alleles are paired by length instead: the pairing whose total difference is
+// smallest, which for lengths on a line is the non-crossing one.
+//
+// A walk that does not reach both flanking reference nodes is measured whole
+// rather than across the array, and an allele no read spanned is a copy of the
+// one that was called. Neither states a length for this array, so they pair
+// last and take no verdict — pairing them first let a walk that stops inside
+// the array take the allele that fit one spanning it, and the spanning walk
+// then read as a disagreement.
+
+export interface WalkCall extends RepeatCall {
+  // undefined where the walk and the allele are not both measurements
+  agrees?: boolean
+}
+
+// Every walk/call pair over the 94 HPRC samples TRGT genotyped at the ABCA7
+// VNTR is either within 8% of its allele or more than 14% from it, so any
+// threshold across that gap separates them the same way.
+export const CALL_TOLERANCE = 0.1
+
+function agrees(walkBp: number, callBp: number) {
+  return Math.abs(callBp - walkBp) <= CALL_TOLERANCE * Math.max(walkBp, callBp)
+}
+
+// Pair two ascending lists of lengths, leaving out the surplus of whichever is
+// longer. `out[i]` is the index in `calls` that `walks[i]` took.
+function nearest(walks: number[], calls: number[]) {
+  const W = walks.length
+  const C = calls.length
+  const cost = Array.from({ length: W + 1 }, () => new Array(C + 1).fill(0))
+  const paired = Array.from({ length: W + 1 }, () =>
+    new Array<boolean>(C + 1).fill(false),
+  )
+  for (let i = W - 1; i >= 0; i--) {
+    for (let j = C - 1; j >= 0; j--) {
+      const together = Math.abs(walks[i]! - calls[j]!) + cost[i + 1]![j + 1]!
+      const dropWalk = W - i > C - j ? cost[i + 1]![j]! : Infinity
+      const dropCall = C - j > W - i ? cost[i]![j + 1]! : Infinity
+      cost[i]![j] = Math.min(together, dropWalk, dropCall)
+      paired[i]![j] = cost[i]![j] === together
+    }
+  }
+  const out = new Array<number | undefined>(W).fill(undefined)
+  for (let i = 0, j = 0; i < W && j < C;) {
+    if (paired[i]![j]) {
+      out[i++] = j++
+    } else if (W - i > C - j) {
+      i++
+    } else {
+      j++
+    }
+  }
+  return out
+}
+
+function byLength<T>(items: T[], bp: (item: T) => number) {
+  return items
+    .map((item, i) => ({ item, i }))
+    .sort((a, b) => bp(a.item) - bp(b.item))
+}
+
+const backed = (call: RepeatCall) => call.spanningReads !== 0
+
+// The walks that span the array against the alleles reads spanned, then
+// everything else against what those two left. It decides the ambiguous cases
+// on merit: which walk carries the one allele a lone spanning read supports,
+// and which allele a walk that stops inside the array is drawn against.
+function pairSample<R extends { bp: number; complete: boolean }>(
+  rows: R[],
+  calls: RepeatCall[],
+) {
+  const out = new Map<number, WalkCall>()
+  const taken = new Set<RepeatCall>()
+  const ranked = byLength(rows, r => r.bp)
+  const stages = [
+    [ranked.filter(r => r.item.complete), calls.filter(backed)],
+    [ranked, calls],
+  ] as const
+  for (const [pool, group] of stages) {
+    const free = pool.filter(r => !out.has(r.i))
+    const open = byLength(
+      group.filter(call => !taken.has(call)),
+      call => call.bp,
+    )
+    nearest(
+      free.map(r => r.item.bp),
+      open.map(c => c.item.bp),
+    ).forEach((pick, k) => {
+      if (pick !== undefined) {
+        const row = free[k]!
+        const call = open[pick]!.item
+        taken.add(call)
+        out.set(row.i, {
+          ...call,
+          agrees:
+            row.item.complete && backed(call)
+              ? agrees(row.item.bp, call.bp)
+              : undefined,
+        })
+      }
+    })
+  }
+  return out
+}
+
+export function withCalls<
+  R extends { sample: string; bp: number; complete: boolean },
+>(rows: R[], calls: Record<string, RepeatCall[]> | undefined) {
+  if (!calls) {
+    return rows as (R & { call?: WalkCall })[]
+  }
+  const paired = new Map<R, WalkCall>()
+  const bySample = new Map<string, R[]>()
+  for (const row of rows) {
+    bySample.set(row.sample, [...(bySample.get(row.sample) ?? []), row])
+  }
+  for (const [sample, group] of bySample) {
+    const called = calls[sample]
+    if (called) {
+      for (const [i, call] of pairSample(group, called)) {
+        paired.set(group[i]!, call)
+      }
+    }
+  }
+  return rows.map(row => ({ ...row, call: paired.get(row) }))
+}

package/src/GraphGenomeView/stress.test.ts

@@ -0,0 +1,214 @@
+import { parseGFA } from '../gfa-core/index'
+import { convertGFAToGraph } from './gfa/gfaConverter'
+import { Canvas2DRenderer } from './renderer/Canvas2DRenderer'
+import { buildGeometry } from './renderer/GeometryBuilder'
+import { recordingCanvas } from './renderer/recordingCanvas'
+
+import type { GraphNode, NodeSegment } from './types'
+
+// isotropic: one scale for both axes, which is every layout but the row ones
+const iso = (scale = 1) => ({ scaleX: scale, scaleY: scale })
+
+// Builds a linear chain of `bubbleCount` diamond bubbles. Each bubble is
+// source -> {altA, altB} -> sink, and the sink is shared with the next
+// bubble's source, so the whole thing is one connected component shaped like
+// a real pangenome backbone with biallelic variant sites.
+//
+// node count  = 3 * bubbleCount + 1
+// link count  = 4 * bubbleCount
+function generateBubbleGFA(bubbleCount: number) {
+  const lines: string[] = ['H\tVN:Z:1.0']
+  const segId = (i: number) => i + 1
+  const totalNodes = 3 * bubbleCount + 1
+
+  for (let i = 0; i < totalNodes; i++) {
+    lines.push(`S\t${segId(i)}\tACGTACGT`)
+  }
+
+  // Anchor (backbone) node ids: 0, 3, 6, ... ; alts for bubble b are 3b+1, 3b+2
+  const refPath: number[] = [segId(0)]
+  const altPath: number[] = [segId(0)]
+  for (let b = 0; b < bubbleCount; b++) {
+    const source = segId(3 * b)
+    const altA = segId(3 * b + 1)
+    const altB = segId(3 * b + 2)
+    const sink = segId(3 * b + 3)
+    lines.push(
+      `L\t${source}\t+\t${altA}\t+\t0M`,
+      `L\t${source}\t+\t${altB}\t+\t0M`,
+      `L\t${altA}\t+\t${sink}\t+\t0M`,
+      `L\t${altB}\t+\t${sink}\t+\t0M`,
+    )
+    refPath.push(altA, sink)
+    altPath.push(altB, sink)
+  }
+
+  lines.push(
+    `P\tref#0#chr1\t${refPath.map(id => `${id}+`).join(',')}\t*`,
+    `P\talt#0#chr1\t${altPath.map(id => `${id}+`).join(',')}\t*`,
+  )
+  return { gfa: lines.join('\n'), totalNodes, totalLinks: 4 * bubbleCount }
+}
+
+// Synthetic 2-segment positions for every node so buildGeometry can run
+// without the Bandage WASM layout step (covered by browser tests instead).
+function syntheticPositions(nodes: GraphNode[]) {
+  const positions: Record<string, NodeSegment[]> = {}
+  for (let i = 0; i < nodes.length; i++) {
+    const n = nodes[i]!
+    positions[n.id] = [
+      { x: i * 10, y: 0 },
+      { x: i * 10 + 8, y: 0 },
+    ]
+  }
+  return positions
+}
+
+test('parse + convert scales to a few thousand bubbles', () => {
+  const { gfa, totalNodes, totalLinks } = generateBubbleGFA(2000)
+
+  const t0 = performance.now()
+  const gfaGraph = parseGFA(gfa)
+  const graph = convertGFAToGraph(gfaGraph, 'stress')
+  const elapsed = performance.now() - t0
+
+  expect(gfaGraph.nodes).toHaveLength(totalNodes)
+  expect(gfaGraph.links).toHaveLength(totalLinks)
+  // forward-strand only graph -> one GraphNode per segment
+  expect(graph.nodes).toHaveLength(totalNodes)
+  expect(graph.edges).toHaveLength(totalLinks)
+  expect(graph.paths).toHaveLength(2)
+
+  // every edge that lies on a path should have pathIds populated
+  const edgesWithPaths = graph.edges.filter(e => e.pathIds?.length)
+  expect(edgesWithPaths.length).toBeGreaterThan(0)
+
+  // Generous ceiling — a linear pass over ~6k nodes / 8k links is milliseconds;
+  // this only trips on an accidental O(n^2) regression, not on a slow runner.
+  expect(elapsed).toBeLessThan(5000)
+})
+
+test('buildGeometry scales to a few thousand nodes', () => {
+  const { gfa, totalNodes } = generateBubbleGFA(2000)
+  const graph = convertGFAToGraph(parseGFA(gfa), 'stress')
+  const nodeById = new Map(graph.nodes.map(n => [n.id, n]))
+  const nodePositions = syntheticPositions(graph.nodes)
+
+  const t0 = performance.now()
+  const batch = buildGeometry({
+    nodePositions,
+    graph,
+    nodeById,
+    colorScheme: 'depth',
+    contigThickness: 10,
+    connectorThickness: 4,
+    drawPaths: true,
+    axis: iso(),
+  })
+  const elapsed = performance.now() - t0
+
+  expect(batch.nodeStrokeRuns.size).toBe(totalNodes)
+  // striped: every node is on at least one of the two paths
+  expect(batch.nodeStrokes.length).toBeGreaterThan(totalNodes)
+  expect(batch.edgeCurves.length).toBeGreaterThan(0)
+  expect(elapsed).toBeLessThan(5000)
+})
+
+test('buildGeometry scaling is roughly linear, not quadratic', () => {
+  function timeBuild(bubbleCount: number) {
+    const { gfa } = generateBubbleGFA(bubbleCount)
+    const graph = convertGFAToGraph(parseGFA(gfa), 'stress')
+    const nodeById = new Map(graph.nodes.map(n => [n.id, n]))
+    const nodePositions = syntheticPositions(graph.nodes)
+    // warm + measure
+    const opts = {
+      nodePositions,
+      graph,
+      nodeById,
+      colorScheme: 'uniform' as const,
+      contigThickness: 10,
+      connectorThickness: 4,
+      drawPaths: false,
+      axis: iso(),
+    }
+    buildGeometry(opts)
+    const t0 = performance.now()
+    buildGeometry(opts)
+    return performance.now() - t0
+  }
+
+  const small = timeBuild(500)
+  const large = timeBuild(2000) // 4x the work
+
+  // 4x input should be well under 10x time if scaling is linear. The loose
+  // bound tolerates timer noise on small absolute durations while still
+  // catching a quadratic blow-up (which would be ~16x).
+  expect(large).toBeLessThan(small * 10 + 50)
+})
+
+test('viewport culling drops the vast majority of off-screen nodes', () => {
+  const { gfa } = generateBubbleGFA(2000)
+  const graph = convertGFAToGraph(parseGFA(gfa), 'stress')
+  const nodeById = new Map(graph.nodes.map(n => [n.id, n]))
+  const nodePositions = syntheticPositions(graph.nodes)
+
+  // nodes are laid out along x at 10px spacing; this window covers ~50 of them
+  const batch = buildGeometry({
+    nodePositions,
+    graph,
+    nodeById,
+    colorScheme: 'uniform',
+    contigThickness: 10,
+    connectorThickness: 4,
+    drawPaths: false,
+    axis: iso(),
+    viewportBounds: { minX: 0, minY: -50, maxX: 500, maxY: 50 },
+  })
+
+  expect(batch.nodeStrokeRuns.size).toBeGreaterThan(0)
+  expect(batch.nodeStrokeRuns.size).toBeLessThan(graph.nodes.length / 2)
+})
+
+// Draw calls per frame, which is what the Canvas2D renderer's cost tracks --
+// and unlike wall-clock they are deterministic, so they can be asserted exactly.
+// The renderer batches everything drawn with one paint into one path, so the
+// count is a function of how many distinct colours and weights the drawing
+// uses and not of how many nodes it has. It used to be 12.6 per node, with a
+// fill per mesh triangle; see agent-docs/GRAPH_SCALE_AND_LOD.md.
+function countDrawCalls(batch: ReturnType<typeof buildGeometry>) {
+  const { canvas, strokes, fills } = recordingCanvas()
+  const renderer = new Canvas2DRenderer(canvas)
+  renderer.uploadGeometry(batch)
+  renderer.updateTransform({
+    scaleX: 1,
+    scaleY: 1,
+    translateX: 0,
+    translateY: 0,
+    dpr: 1,
+  })
+  renderer.render([1, 1, 1, 1])
+  return { strokes: strokes.length, fills: fills.length }
+}
+
+function uniformBatch(bubbleCount: number) {
+  const { gfa } = generateBubbleGFA(bubbleCount)
+  const graph = convertGFAToGraph(parseGFA(gfa), 'stress')
+  return buildGeometry({
+    nodePositions: syntheticPositions(graph.nodes),
+    graph,
+    nodeById: new Map(graph.nodes.map(n => [n.id, n])),
+    colorScheme: 'uniform',
+    contigThickness: 10,
+    connectorThickness: 4,
+    drawPaths: false,
+    axis: iso(),
+  })
+}
+
+test('draw calls per frame do not grow with the graph', () => {
+  const small = countDrawCalls(uniformBatch(100))
+  const large = countDrawCalls(uniformBatch(500))
+  // one paint each for the edges, the nodes and the arrowheads
+  expect(small).toEqual({ strokes: 2, fills: 1 })
+  expect(large).toEqual(small)
+})