jbrowse-plugin-graphgenomeviewer 1.0.0 → 3.0.3

package/src/GraphGenomeView/subgraphLoad.test.ts

@@ -0,0 +1,245 @@
+import stateModelFactory from './model'
+
+const mockRpcCall = vi.fn()
+const mockSession = {
+  tracks: [] as Record<string, unknown>[],
+  rpcManager: { call: mockRpcCall },
+}
+
+vi.mock('@jbrowse/core/util', () => ({
+  getSession: () => mockSession,
+  isSessionModelWithWidgets: () => false,
+  parseLocString: () => ({}),
+  getEnv: () => ({}),
+  useWidthSetter: () => {},
+  measureText: () => 0,
+  IntervalTree: class {},
+  getSnapshot: () => ({}),
+  applySnapshot: () => {},
+  objectHash: () => '',
+}))
+
+vi.mock(import('@jbrowse/core/configuration'), async importOriginal => ({
+  ...(await importOriginal()),
+  readConfObject: vi.fn(
+    (obj: Record<string, unknown>, key: string) => obj[key],
+  ),
+}))
+
+// pangenome_hprc's segments track once NA20809 haplotype 2 is loaded
+const TRACK = {
+  trackId: 'segments',
+  assemblyNames: ['hg38', 'NA20809.2'],
+  adapter: { type: 'RgfaTabixAdapter' },
+}
+
+// A GRCh38 backbone s1, s3 and one NA20809#2 allele between them, which is what
+// the adapter returns for a window on either assembly.
+const GFA = [
+  'H\tVN:Z:1.0',
+  'S\ts1\t*\tLN:i:1000\tSN:Z:GRCh38#0#chr6\tSO:i:32000000\tSR:i:0',
+  'S\ts3\t*\tLN:i:900\tSN:Z:GRCh38#0#chr6\tSO:i:32001100\tSR:i:0',
+  'S\th1\t*\tLN:i:200\tSN:Z:NA20809#2#CM094351.1\tSO:i:31901000\tSR:i:1',
+  'L\ts1\t+\th1\t+\t0M',
+  'L\th1\t+\ts3\t+\t0M',
+].join('\n')
+
+const ON_HG38 = {
+  refName: 'chr6',
+  assemblyName: 'hg38',
+  start: 32_000_000,
+  end: 32_002_000,
+}
+
+const ON_NA20809 = {
+  refName: 'CM094351.1',
+  assemblyName: 'NA20809.2',
+  start: 31_900_900,
+  end: 31_901_300,
+}
+
+function createView(snapshot: Record<string, unknown> = {}) {
+  return stateModelFactory().create({
+    type: 'GraphGenomeView',
+    layoutMode: 'auto',
+    ...snapshot,
+  } as never)
+}
+
+async function cut(region: typeof ON_HG38, gfa = GFA) {
+  mockRpcCall.mockImplementation((_sid: unknown, method: string) =>
+    method === 'GetSubgraph'
+      ? Promise.resolve(gfa)
+      : Promise.reject(new Error(`Unexpected RPC: ${method}`)),
+  )
+  const model = createView()
+  await model.loadFromTabixSubgraph(TRACK.adapter, region, {
+    trackId: TRACK.trackId,
+  })
+  return model
+}
+
+beforeEach(() => {
+  mockRpcCall.mockReset()
+  mockSession.tracks = [TRACK]
+})
+
+test('a cut on the reference draws', async () => {
+  const model = await cut(ON_HG38)
+  expect(model.error).toBeUndefined()
+  expect(model.nodeCount).toBe(3)
+})
+
+// Framed on NA20809.2's contig, the anchored layouts, the colour ramp and every
+// highlight would put GRCh38 coordinates on CM094351.1.
+test('a cut on another assembly the track names is refused, naming the reference', async () => {
+  const model = await cut(ON_NA20809)
+  expect(String(model.error)).toMatch(/cut on its reference, hg38/)
+  expect(model.hasGraph).toBe(false)
+  expect(mockRpcCall).not.toHaveBeenCalled()
+})
+
+test('a cut that finds no segments is an error, not an empty graph', async () => {
+  const model = await cut(ON_HG38, 'H\tVN:Z:1.0')
+  expect(String(model.error)).toMatch(/No graph segments/)
+  expect(model.hasGraph).toBe(false)
+})
+
+describe('overlapping cuts', () => {
+  const TWO_NODES = [
+    'H\tVN:Z:1.0',
+    'S\ta1\t*\tLN:i:10\tSN:Z:GRCh38#0#chr6\tSO:i:100\tSR:i:0',
+    'S\ta2\t*\tLN:i:10\tSN:Z:GRCh38#0#chr6\tSO:i:110\tSR:i:0',
+    'L\ta1\t+\ta2\t+\t0M',
+  ].join('\n')
+  const THREE_NODES = [
+    'H\tVN:Z:1.0',
+    'S\tb1\t*\tLN:i:10\tSN:Z:GRCh38#0#chr6\tSO:i:100\tSR:i:0',
+    'S\tb2\t*\tLN:i:10\tSN:Z:GRCh38#0#chr6\tSO:i:110\tSR:i:0',
+    'S\tb3\t*\tLN:i:10\tSN:Z:GRCh38#0#chr6\tSO:i:120\tSR:i:0',
+    'L\tb1\t+\tb2\t+\t0M',
+    'L\tb2\t+\tb3\t+\t0M',
+  ].join('\n')
+
+  // Two re-cuts in flight at once, the way two quick changes in the settings
+  // dialog leave them, each answered when the test says.
+  function twoCuts() {
+    const pending: ((gfa: string) => void)[] = []
+    mockRpcCall.mockImplementation((_sid: unknown, method: string) =>
+      method === 'GetSubgraph'
+        ? new Promise<string>(resolve => {
+            pending.push(resolve)
+          })
+        : Promise.reject(new Error(`Unexpected RPC: ${method}`)),
+    )
+    const model = createView({
+      loadedTrackId: TRACK.trackId,
+      loadedRegion: { ...ON_HG38, start: 0, end: 200 },
+    })
+    const first = model.reloadSubgraph()
+    const second = model.reloadSubgraph()
+    return { model, pending, first, second }
+  }
+
+  test('the later cut wins when the earlier one finishes last', async () => {
+    const { model, pending, first, second } = twoCuts()
+    pending[1]!(THREE_NODES)
+    await second
+    pending[0]!(TWO_NODES)
+    await first
+    expect(model.nodeCount).toBe(3)
+  })
+
+  test('the spinner stays up until the live cut lands', async () => {
+    const { model, pending, first, second } = twoCuts()
+    pending[0]!(TWO_NODES)
+    await first
+    expect(model.isLoading).toBe(true)
+    pending[1]!(THREE_NODES)
+    await second
+    expect(model.isLoading).toBe(false)
+    expect(model.nodeCount).toBe(3)
+  })
+})
+
+describe('canceling and retrying', () => {
+  function pendingCuts() {
+    const pending: ((gfa: string) => void)[] = []
+    mockRpcCall.mockImplementation((_sid: unknown, method: string) =>
+      method === 'GetSubgraph'
+        ? new Promise<string>(resolve => {
+            pending.push(resolve)
+          })
+        : Promise.reject(new Error(`Unexpected RPC: ${method}`)),
+    )
+    return pending
+  }
+
+  function cutSignal(index: number) {
+    return (mockRpcCall.mock.calls[index]![2] as { signal: AbortSignal }).signal
+  }
+
+  function launchedView() {
+    return createView({ loadedTrackId: TRACK.trackId, loadedRegion: ON_HG38 })
+  }
+
+  test('canceling a first cut aborts it, and its late answer never lands', async () => {
+    const pending = pendingCuts()
+    const model = launchedView()
+    const load = model.reloadSubgraph()
+    expect(model.canCancelLoad).toBe(true)
+
+    model.cancelLoad()
+    expect(cutSignal(0).aborted).toBe(true)
+    expect(model.isLoading).toBe(false)
+    expect(model.loadCanceled).toBe(true)
+
+    pending[0]!(GFA)
+    await load
+    expect(model.hasGraph).toBe(false)
+    expect(model.error).toBeUndefined()
+  })
+
+  test('retry cuts the same region again', async () => {
+    pendingCuts()
+    const model = launchedView()
+    void model.reloadSubgraph()
+    model.cancelLoad()
+
+    mockRpcCall.mockResolvedValue(GFA)
+    model.retryLoad()
+    expect(model.loadCanceled).toBe(false)
+    await vi.waitFor(() => {
+      expect(model.nodeCount).toBe(3)
+    })
+  })
+
+  test('a newer cut aborts the one it replaces', () => {
+    pendingCuts()
+    const model = launchedView()
+    void model.reloadSubgraph()
+    void model.reloadSubgraph()
+    expect(cutSignal(0).aborted).toBe(true)
+    expect(cutSignal(1).aborted).toBe(false)
+  })
+
+  test('a reload over a drawn graph cannot be canceled', async () => {
+    const model = await cut(ON_HG38)
+    pendingCuts()
+    void model.reloadSubgraph()
+    expect(model.canCancelLoad).toBe(false)
+
+    model.cancelLoad()
+    expect(model.isLoading).toBe(true)
+    expect(model.nodeCount).toBe(3)
+  })
+
+  test('a stored track the session no longer has is reported', async () => {
+    mockSession.tracks = []
+    const model = launchedView()
+    await model.refetchIfNeeded()
+    expect(String(model.error)).toMatch(/"segments", is not in this session/)
+    expect(model.canRetryLoad).toBe(true)
+    expect(mockRpcCall).not.toHaveBeenCalled()
+  })
+})

package/src/GraphGenomeView/types.ts

@@ -0,0 +1,141 @@
+import type { StableCoordinate } from '../gfa-core/index'
+
+export interface GraphNode {
+  id: string
+  name: string
+  length: number
+  depth: number
+  // where this segment sits on a stable sequence: stated per-segment by rGFA's
+  // SN/SO/SR, derived from the P/W lines otherwise (pathAnchoring.ts)
+  stable?: StableCoordinate
+  // every assembly whose P/W record visits this segment, sorted. This is
+  // carriage, and only a path GFA can state it: rGFA's SR is build order, so
+  // there the most a segment says is which assembly first contributed it.
+  samples?: string[]
+}
+
+export interface GraphEdge {
+  from: string
+  to: string
+  // How the link reads each segment, as the file states it: it leaves the END
+  // of `from` read this way and arrives at the START of `to`. `from` and `to`
+  // alone cannot say which side of a node a link is on, and that is the whole
+  // difference between a deletion, a duplication and an inversion. Absent on a
+  // graph built without them.
+  fromStrand?: '+' | '-'
+  toStrand?: '+' | '-'
+  pathIds?: string[]
+}
+
+export interface GraphPath {
+  name: string
+  nodeIds: string[]
+  // set for W records, which state the assembly they walk; P records do not
+  sample?: string
+  haplotype?: number
+  contig?: string
+}
+
+// One P or W record, named the way a coordinate is named: the range suffix
+// `odgi extract` appends (`K12#1#chr:1004500-1004961`) split off into `start`,
+// so `name` is a stable sequence and `start` is where this path begins on it.
+export interface PathOrigin {
+  name: string
+  sample: string
+  start: number
+  // bp the path covers, summed over its steps
+  length: number
+}
+
+// One visit a path makes to one segment. A path may visit the same segment more
+// than once (a collapsed repeat), so this is a list per segment, not a value.
+export interface PathVisit {
+  path: string
+  sample: string
+  // offset on `path`'s own sequence, from walking the path's steps
+  start: number
+  // how this path reads the segment, which is not how another path may read it
+  strand: '+' | '-'
+}
+
+export interface Graph {
+  name: string
+  nodes: GraphNode[]
+  edges: GraphEdge[]
+  paths?: GraphPath[]
+  // The paths that could put this graph on a reference axis, in file order, and
+  // every segment visit they make. Absent for a GFA with no P/W records — an
+  // rGFA, where the segments carry their own coordinates instead.
+  anchorPaths?: PathOrigin[]
+  pathVisits?: Map<string, PathVisit[]>
+  // Where the nodes' `stable` came from. 'tags' is rGFA's SN/SO/SR; 'paths' is
+  // derived, and the only one that can be re-derived against a different
+  // reference path. Absent when nothing anchors the graph at all.
+  anchoredBy?: 'tags' | 'paths'
+  // the path `anchoredBy: 'paths'` put on x
+  referencePath?: string
+}
+
+export interface NodeSegment {
+  x: number
+  y: number
+}
+
+// A row a layout drew, named, in the same graph y coordinates as
+// `nodePositions`. Emitted by the layout that positioned the rows rather than
+// recomputed by the renderer, so a label cannot end up naming a row the layout
+// put somewhere else. Absent for layouts with no row structure (FMMM).
+export interface RowLabel {
+  label: string
+  y: number
+}
+
+// An allele that stands in for MORE reference than it carries sequence, as the
+// row-structured layouts drew it. Those layouts give an off-reference node the
+// slice of reference its allele replaces rather than its own length
+// (placeOffReference), so on this axis a 93 bp segment bridging two backbone
+// anchors 7.1 kb apart is drawn 7.1 kb wide — and labelling it `93 bp`, which is
+// what a node label says everywhere else, describes the sequence while the
+// reader is looking at the reference. It is a deletion, and the drawing already
+// names deletions when they are bare edges; this is the same event with a
+// segment in the middle of it, which `deletionEdges` cannot see.
+//
+// Emitted by the layout, because only the layout knows whether x is reference bp
+// — under FMMM a node IS drawn at its own scale and `93 bp` is the true label.
+export interface AlleleDeletion {
+  // the run's nodes, so a label can be placed over the extent they were drawn at
+  nodeIds: string[]
+  // reference bp the allele does not carry: the span between its anchors less
+  // the longest path through the run. Not `-delta`, which sums a bubble's
+  // parallel branches and so understates what any one haplotype skips.
+  bp: number
+}
+
+export interface LayoutResult {
+  nodePositions: Record<string, NodeSegment[]>
+  rowLabels?: RowLabel[]
+  // Deletions carried by a SEGMENT rather than by a bare edge, which only a
+  // reference-bp layout can state — see AlleleDeletion.
+  alleleDeletions?: AlleleDeletion[]
+  // Set by the layouts whose x is reference bp, so the fit can be taken from
+  // the region the cut was made for rather than from how far the drawing
+  // happens to reach. An allele anchored far outside the window is a fact
+  // about the graph, not a reason to redraw the window at 6% of the frame —
+  // see layoutBounds.
+  referenceAxis?: boolean
+  // Set by the layouts that state y in SCREEN PIXELS rather than in the same
+  // units as x. A row layout's y is a row pitch, which is a property of what a
+  // row has to hold (a tube, a label) and not of the window's span, so the two
+  // axes are no longer one number — see rowSpacing.ts and the model's
+  // scaleX/scaleY. A layout that leaves this unset (FMMM) is isotropic, and
+  // every unit of it is drawn at one scale, exactly as before.
+  //
+  // Separate from `referenceAxis` on purpose: that one says what x MEANS, this
+  // one says what y is MEASURED IN, and a future layout could set either
+  // without the other.
+  pixelRows?: boolean
+  // How far a drawing reaches past its nodes, when an overlay draws rows the
+  // renderer has no node for (walk rows). The fit and the pane height take the
+  // wider of this and the nodes.
+  extent?: { maxX: number; maxY: number }
+}

package/src/GraphGenomeView/util/SpatialIndex.test.ts

@@ -0,0 +1,73 @@
+import { SpatialIndex } from './SpatialIndex'
+
+const positions = {
+  'A+': [
+    { x: 0, y: 0 },
+    { x: 100, y: 0 },
+  ],
+  'B+': [
+    { x: 200, y: 200 },
+    { x: 300, y: 200 },
+  ],
+  'C+': [
+    { x: 0, y: 0 },
+    { x: 0, y: 100 },
+  ],
+}
+
+test('finds nearby segments', () => {
+  const index = new SpatialIndex(positions, 50)
+  const results = index.query(50, 0, 10)
+  const nodeIds = results.map(r => r.nodeId)
+  expect(nodeIds).toContain('A+')
+  expect(nodeIds).not.toContain('B+')
+})
+
+test('finds nothing when far from all segments', () => {
+  const index = new SpatialIndex(positions, 50)
+  const results = index.query(500, 500, 10)
+  expect(results).toHaveLength(0)
+})
+
+test('finds segments near intersection', () => {
+  const index = new SpatialIndex(positions, 50)
+  const results = index.query(0, 0, 10)
+  const nodeIds = new Set(results.map(r => r.nodeId))
+  expect(nodeIds.has('A+')).toBe(true)
+  expect(nodeIds.has('C+')).toBe(true)
+})
+
+test('larger radius finds more candidates', () => {
+  const index = new SpatialIndex(positions, 50)
+  const small = index.query(150, 100, 10)
+  const large = index.query(150, 100, 200)
+  expect(large.length).toBeGreaterThanOrEqual(small.length)
+})
+
+test('deduplicates entries across cells', () => {
+  const index = new SpatialIndex(positions, 10)
+  const results = index.query(50, 0, 20)
+  const keys = results.map(r => `${r.nodeId}:${r.segmentIdx}`)
+  const unique = new Set(keys)
+  expect(keys.length).toBe(unique.size)
+})
+
+// A row layout puts bp on x and a 20 px row pitch on y, so one cell size taken
+// from the two summed is the x size, and applied to y it swallows every row into
+// one cell: the grid stops discriminating on y and each query hands the distance
+// loop every row in the band. HPRC's rGFA is exactly this shape, at ~7 kb a
+// segment.
+test('a row layout is bucketed on both axes, not just on x', () => {
+  const rows: Record<string, { x: number; y: number }[]> = {}
+  for (let row = 0; row < 20; row++) {
+    rows[`r${row}`] = [
+      { x: 0, y: row * 20 },
+      { x: 7000, y: row * 20 },
+    ]
+  }
+  const index = new SpatialIndex(rows)
+
+  // 5 screen px of slack on y, which is a quarter of a row
+  const hits = index.query(3500, 0, 7000 * 0.001, 5)
+  expect(hits.map(h => h.nodeId)).toEqual(['r0'])
+})