jbrowse-plugin-graphgenomeviewer 1.0.0 → 3.0.3

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

@@ -0,0 +1,212 @@
+import { orderedLayout, referenceOrder } from './orderedLayout'
+import { ROW_HEIGHT_PX } from './rowSpacing'
+import { parseGFA } from '../../gfa-core/index'
+import { convertGFAToGraph } from '../gfa/gfaConverter'
+
+// chr1 runs v1->v2->v3->v4; two single-segment alleles, a1 (foo) and a2 (bar),
+// each replace v3 between the same anchors, so they share a layer and have to
+// take different lanes. The file lists the L-lines in reference direction.
+const BUBBLE = `S\tv1\tAAAAA\tLN:i:5\tSN:Z:chr1\tSO:i:0\tSR:i:0
+S\tv2\tCCC\tLN:i:3\tSN:Z:chr1\tSO:i:5\tSR:i:0
+S\tv3\tGG\tLN:i:2\tSN:Z:chr1\tSO:i:8\tSR:i:0
+S\tv4\tTTTTTTT\tLN:i:7\tSN:Z:chr1\tSO:i:10\tSR:i:0
+S\ta1\tAC\tLN:i:2\tSN:Z:foo\tSO:i:8\tSR:i:1
+S\ta2\tT\tLN:i:1\tSN:Z:bar\tSO:i:8\tSR:i:2
+L\tv1\t+\tv2\t+\t0M
+L\tv2\t+\tv3\t+\t0M
+L\tv3\t+\tv4\t+\t0M
+L\tv2\t+\ta1\t+\t0M
+L\ta1\t+\tv4\t+\t0M
+L\tv2\t+\ta2\t+\t0M
+L\ta2\t+\tv4\t+\t0M`
+
+const BACKBONE = ['v1+', 'v2+', 'v3+', 'v4+']
+
+function graphOf(gfa: string) {
+  return convertGFAToGraph(parseGFA(gfa))
+}
+
+function layout(gfa: string) {
+  return orderedLayout(graphOf(gfa))!.nodePositions
+}
+
+const centre = (seg: { x: number }[]) => (seg[0]!.x + seg.at(-1)!.x) / 2
+
+test('backbone x strictly increases in reference order', () => {
+  const pos = layout(BUBBLE)
+  const xs = BACKBONE.map(id => centre(pos[id]!))
+  for (let i = 1; i < xs.length; i++) {
+    expect(xs[i]!).toBeGreaterThan(xs[i - 1]!)
+  }
+})
+
+test('no two nodes share a layer and a lane', () => {
+  const pos = layout(BUBBLE)
+  const cells = Object.values(pos).map(seg => `${centre(seg)},${seg[0]!.y}`)
+  expect(new Set(cells).size).toBe(cells.length)
+})
+
+test('the backbone holds lane 0 and nothing else does', () => {
+  const pos = layout(BUBBLE)
+  for (const id of BACKBONE) {
+    expect(pos[id]!.every(p => p.y === 0)).toBe(true)
+  }
+  expect(pos['a1+']![0]!.y).not.toBe(0)
+  expect(pos['a2+']![0]!.y).not.toBe(0)
+})
+
+test('every edge runs left to right', () => {
+  const graph = graphOf(BUBBLE)
+  const pos = orderedLayout(graph)!.nodePositions
+  for (const { from, to } of graph.edges) {
+    expect(centre(pos[from]!)).toBeLessThan(centre(pos[to]!))
+  }
+})
+
+test("a bubble's two alleles share a layer on different lanes", () => {
+  const pos = layout(BUBBLE)
+  const a1 = pos['a1+']!
+  const a2 = pos['a2+']!
+  expect(centre(a1)).toBe(centre(a2))
+  expect(a1[0]!.y).not.toBe(a2[0]!.y)
+  // both one or more lane pitches off the reference line
+  expect(Math.abs(a1[0]!.y) % ROW_HEIGHT_PX).toBe(0)
+  expect(Math.abs(a2[0]!.y)).toBeGreaterThanOrEqual(ROW_HEIGHT_PX)
+})
+
+test('an allele sits between its anchors, not under one of them', () => {
+  const pos = layout(BUBBLE)
+  expect(centre(pos['a1+']!)).toBeGreaterThan(centre(pos['v2+']!))
+  expect(centre(pos['a1+']!)).toBeLessThan(centre(pos['v4+']!))
+})
+
+test('a node is a two-point polyline as wide as the log of its bp', () => {
+  const pos = layout(BUBBLE)
+  const seg = pos['v4+']!
+  expect(seg).toHaveLength(2)
+  expect(seg[1]!.x - seg[0]!.x).toBeCloseTo(10 + 8 * Math.log2(8), 5)
+})
+
+test('x is order, and y a lane pitch in screen px', () => {
+  const result = orderedLayout(graphOf(BUBBLE))!
+  expect(result.referenceAxis).toBe(false)
+  expect(result.pixelRows).toBe(true)
+  expect(result.rowLabels).toBeUndefined()
+  expect(result.alleleDeletions).toBeUndefined()
+})
+
+test('a graph without a backbone gets no ordered layout', () => {
+  const plain = `S\t1\tACGT
+S\t2\tGGCC
+L\t1\t+\t2\t+\t0M`
+  expect(orderedLayout(graphOf(plain))).toBeUndefined()
+})
+
+test('the same graph always gets the same drawing', () => {
+  const graph = graphOf(BUBBLE)
+  expect(orderedLayout(graph)).toEqual(orderedLayout(graph))
+  expect(referenceOrder(graph)).toEqual(referenceOrder(graphOf(BUBBLE)))
+})
+
+test('reference order is backbone by offset, alleles just past their anchor', () => {
+  expect(referenceOrder(graphOf(BUBBLE))).toEqual([
+    'v1+',
+    'v2+',
+    'a1+',
+    'a2+',
+    'v3+',
+    'v4+',
+  ])
+})
+
+// r1 r2 r3 r4 along chr1 at 0, 1, 2, 3, a base apart as a base-level graph's
+// backbone is, with whatever `extra` hangs off it.
+function baseLevel(extra: string[]) {
+  return graphOf(
+    [
+      ...[0, 1, 2, 3].map(
+        i => `S\tr${i + 1}\tA\tLN:i:1\tSN:Z:chr1\tSO:i:${i}\tSR:i:0`,
+      ),
+      ...[1, 2, 3].map(i => `L\tr${i}\t+\tr${i + 1}\t+\t0M`),
+      ...extra,
+    ].join('\n'),
+  )
+}
+
+const off = (name: string) => `S\t${name}\tA\tLN:i:1\tSN:Z:alt\tSO:i:0\tSR:i:1`
+const link = (a: string, b: string) => `L\t${a}\t+\t${b}\t+\t0M`
+
+// The search from the backbone meets itself in the middle of x1..x4, so x3 and
+// x4 are claimed from r4. Sorted after it, their links into r4 turned round.
+test('both halves of a multi-node allele sort between its anchors', () => {
+  const chain = ['r1', 'x1', 'x2', 'x3', 'x4', 'r4']
+  const graph = baseLevel([
+    ...['x1', 'x2', 'x3', 'x4'].map(off),
+    ...chain.slice(1).map((n, i) => link(chain[i]!, n)),
+  ])
+  const order = referenceOrder(graph)
+  const places = chain.map(n => order.indexOf(`${n}+`))
+  expect(places).toEqual([...places].sort((a, b) => a - b))
+})
+
+// Six nodes off r1, whose next backbone node is a base away. Nudged half a bp
+// per step, the chain's keys walked past r2, r3 and r4.
+test('a long allele stays beside its anchor however close the next node is', () => {
+  const names = ['y1', 'y2', 'y3', 'y4', 'y5', 'y6']
+  const graph = baseLevel([
+    ...names.map(off),
+    link('r1', 'y1'),
+    ...names.slice(1).map((n, i) => link(names[i]!, n)),
+  ])
+  expect(referenceOrder(graph)).toEqual([
+    'r1+',
+    ...names.map(n => `${n}+`),
+    'r2+',
+    'r3+',
+    'r4+',
+  ])
+})
+
+// t1 and t2 are claimed from r4, and the left reaches them only at t1. t2 is a
+// dead end of the search that the left never reached, so steps from r4 say
+// nothing about where it lies: sorted first, as the far half of a chain is, it
+// would have nothing before it. The run stays after its anchor.
+test('a run with a dead end the left never reached stays after its anchor', () => {
+  const graph = baseLevel([
+    ...['s1', 't1', 't2'].map(off),
+    link('r1', 's1'),
+    link('s1', 't1'),
+    link('t1', 'r4'),
+    link('t1', 't2'),
+  ])
+  const order = referenceOrder(graph)
+  const at = (name: string) => order.indexOf(`${name}+`)
+  expect(at('t1')).toBeGreaterThan(at('r4'))
+  expect(at('t2')).toBeGreaterThan(at('t1'))
+})
+
+// A walk says where its nodes lie. w2 links only to r4, so the links alone put
+// it after r4; the walk enters it from w1, off r1.
+const WALKED = [
+  ...['w1', 'w2'].map(off),
+  link('r1', 'w1'),
+  link('w2', 'r4'),
+  'W\tref\t0\tchr1\t0\t4\t>r1>r2>r3>r4',
+]
+
+test('a walk places the nodes it visits after the node it came from', () => {
+  const graph = baseLevel([...WALKED, 'W\thap\t1\tctg\t0\t4\t>r1>w1>w2>r4'])
+  expect(referenceOrder(graph)).toEqual([
+    'r1+',
+    'w1+',
+    'w2+',
+    'r2+',
+    'r3+',
+    'r4+',
+  ])
+})
+
+test('a walk on the reverse strand is read end-first', () => {
+  const graph = baseLevel([...WALKED, 'W\thap\t1\tctg\t0\t4\t<r4<w2<w1<r1'])
+  expect(referenceOrder(graph).slice(0, 3)).toEqual(['r1+', 'w1+', 'w2+'])
+})

package/src/GraphGenomeView/layout/orderedLayout.ts

@@ -0,0 +1,396 @@
+import { ROW_HEIGHT_PX } from './rowSpacing'
+import { isBackbone } from '../anchoredNodes'
+
+import type { AnchoredNode } from '../anchoredNodes'
+import type { Graph, GraphNode, LayoutResult, NodeSegment } from '../types'
+
+// Reference-ordered layered layout: x is reference ORDER, not bp. Backbone
+// segments take increasing layers by stable offset, every other node the layer
+// between the anchors it hangs off, and a node is as wide as the log of its bp,
+// so a SNP allele gets the same room as a 10 kb segment and a bubble reads as a
+// lens rather than a bar under a line. y is a lane in screen px with the
+// reference pinned at lane 0 (docs/layout-experiments.md, experiment 3).
+
+const GUTTER = 12
+const LANE_PX = ROW_HEIGHT_PX
+
+function nodeWidth(node: GraphNode) {
+  return 10 + 8 * Math.log2(1 + node.length)
+}
+
+function compare<T extends string | number>(a: T, b: T) {
+  return a < b ? -1 : a > b ? 1 : 0
+}
+
+// Where a node sorts: `at` is the rank of a placed node, the backbone and what
+// the walks visit, and a node the search claims sorts before or after the one
+// that claimed it, by its steps from it. A tuple rather than an offset nudged
+// per step: on a base-level graph the backbone nodes are a bp apart, and a
+// chain a few nodes long nudged its keys past the ones that follow.
+interface OrderKey {
+  at: number
+  side: -1 | 0 | 1
+  hops: number
+}
+
+function compareKeys(a: OrderKey, b: OrderKey) {
+  return (
+    compare(a.at, b.at) || compare(a.side, b.side) || compare(a.hops, b.hops)
+  )
+}
+
+const UNREACHED: OrderKey = { at: Infinity, side: 0, hops: 0 }
+
+// Every node id in reference order: backbone by stable offset, every other node
+// beside a backbone node (orderKeys), nodes nothing reaches last. Name breaks
+// ties, so the order is a strict total order and the same graph always gets
+// the same one.
+export function referenceOrder(graph: Graph) {
+  const byId = new Map(graph.nodes.map(n => [n.id, n]))
+  const key = orderKeys(graph)
+  return graph.nodes
+    .map(n => n.id)
+    .sort(
+      (a, b) =>
+        compareKeys(key.get(a) ?? UNREACHED, key.get(b) ?? UNREACHED) ||
+        compare(byId.get(a)!.name, byId.get(b)!.name) ||
+        compare(a, b),
+    )
+}
+
+// A walk states where its nodes lie, which the links alone do not. Starting
+// from the backbone in offset order, each node a walk visits for the first time
+// goes into the order immediately after the node that walk came from, and the
+// nodes a walk visits before it meets a placed one go immediately before it.
+//
+// That keeps every true boundary. A walk's step joins two nodes on the same
+// side of a node every haplotype crosses once, unless one of them is that
+// node, so by induction the nodes between two such boundaries stay one
+// unbroken stretch of the order and no link among them reaches across. On the
+// eight-haplotype KIV-2 cut (15,808 nodes) the walks imply 28 bubbles and this
+// derives those 28, with 5 of 65,776 walk steps against the order. Placing
+// every node by the links alone derived 21, with 23,308 steps against it.
+//
+// A walk on the reverse strand is read end-first.
+function placeByWalks(graph: Graph, backbone: AnchoredNode[]) {
+  const isNode = new Set(graph.nodes.map(n => n.id))
+  const startOf = new Map(backbone.map(n => [n.id, n.stable.start]))
+  const next = new Map<string, string | undefined>()
+  const prev = new Map<string, string | undefined>()
+  backbone.forEach((n, i) => {
+    prev.set(n.id, backbone[i - 1]?.id)
+    next.set(n.id, backbone[i + 1]?.id)
+  })
+  let head = backbone[0]?.id
+  const insertAfter = (at: string, id: string) => {
+    const after = next.get(at)
+    next.set(at, id)
+    prev.set(id, at)
+    next.set(id, after)
+    if (after !== undefined) {
+      prev.set(after, id)
+    }
+  }
+  const insertBefore = (at: string, id: string) => {
+    const before = prev.get(at)
+    if (before === undefined) {
+      head = id
+      prev.set(id, undefined)
+      next.set(id, at)
+      prev.set(at, id)
+    } else {
+      insertAfter(before, id)
+    }
+  }
+
+  for (const path of graph.paths ?? []) {
+    let rising = 0
+    let falling = 0
+    let last: number | undefined
+    for (const id of path.nodeIds) {
+      const start = startOf.get(id)
+      if (start !== undefined) {
+        if (last !== undefined && start !== last) {
+          if (start > last) {
+            rising++
+          } else {
+            falling++
+          }
+        }
+        last = start
+      }
+    }
+    const ids = falling > rising ? [...path.nodeIds].reverse() : path.nodeIds
+    let from: string | undefined
+    const leading = new Set<string>()
+    for (const id of ids) {
+      if (next.has(id)) {
+        if (from === undefined) {
+          for (const lead of leading) {
+            insertBefore(id, lead)
+          }
+        }
+        from = id
+      } else if (isNode.has(id)) {
+        if (from === undefined) {
+          leading.add(id)
+        } else {
+          insertAfter(from, id)
+          from = id
+        }
+      }
+    }
+  }
+
+  const placed: string[] = []
+  for (let id = head; id !== undefined; id = next.get(id)) {
+    placed.push(id)
+  }
+  return placed
+}
+
+// The nodes no walk visits, which is every off-reference node of a graph with
+// no walks: each goes beside the nearest placed node that reaches it (BFS over
+// the links as undirected, seeded in order so a tie goes left).
+//
+// That search meets itself in the middle of an allele, so the far half of a
+// chain A>X1>X2>B is claimed from B, its RIGHT anchor. Placed after B, as every
+// claimed node once was, X2 sorted past the node it leads into, its link was
+// turned round, and the insertion stopped being a bubble. So a run of nodes
+// claimed from one placed node lies BEFORE it, farthest node first, when it is
+// such a far half: it touches nothing right of that node, and every dead end of
+// the search inside it is a place the search from the left arrived. Steps are
+// a position only along a chain. In a tangle the farthest node is a dead end
+// with nothing before it, and sorted first its links to its real neighbours
+// sweep across every boundary between, so any other run stays after.
+function placeBySearch(
+  adjacent: Map<string, string[]>,
+  key: Map<string, OrderKey>,
+) {
+  const queue = [...key.entries()]
+    .sort(([a, ka], [b, kb]) => compareKeys(ka, kb) || compare(a, b))
+    .map(([id]) => id)
+  const placed = queue.length
+  // the queue grows while the loop walks it, which for-of follows
+  for (const id of queue) {
+    const from = key.get(id)!
+    for (const nb of adjacent.get(id) ?? []) {
+      if (!key.has(nb)) {
+        key.set(nb, { at: from.at, side: 1, hops: from.hops + 1 })
+        queue.push(nb)
+      }
+    }
+  }
+
+  const searched = new Set(queue.slice(placed))
+  const sided = new Set<string>()
+  for (const seed of searched) {
+    if (sided.has(seed)) {
+      continue
+    }
+    const { at } = key.get(seed)!
+    const run = [seed]
+    sided.add(seed)
+    let farHalf = true
+    for (const id of run) {
+      const { hops } = key.get(id)!
+      let deadEnd = true
+      let touchesLeft = false
+      for (const nb of adjacent.get(id) ?? []) {
+        const other = key.get(nb)!
+        if (other.at === at && searched.has(nb)) {
+          deadEnd &&= other.hops <= hops
+          if (!sided.has(nb)) {
+            sided.add(nb)
+            run.push(nb)
+          }
+        } else if (other.at !== at) {
+          touchesLeft ||= other.at < at
+          farHalf &&= other.at < at
+        }
+      }
+      farHalf &&= !deadEnd || touchesLeft
+    }
+    if (farHalf) {
+      for (const id of run) {
+        const k = key.get(id)!
+        key.set(id, { ...k, side: -1, hops: -k.hops })
+      }
+    }
+  }
+}
+
+function orderKeys(graph: Graph) {
+  const ids = new Set(graph.nodes.map(n => n.id))
+  const adjacent = new Map<string, string[]>()
+  for (const e of graph.edges) {
+    if (!ids.has(e.from) || !ids.has(e.to)) {
+      continue
+    }
+    ;(adjacent.get(e.from) ?? adjacent.set(e.from, []).get(e.from)!).push(e.to)
+    ;(adjacent.get(e.to) ?? adjacent.set(e.to, []).get(e.to)!).push(e.from)
+  }
+  const backbone = graph.nodes
+    .filter(isBackbone)
+    .sort(
+      (a, b) =>
+        compare(a.stable.start, b.stable.start) || compare(a.name, b.name),
+    )
+  const key = new Map<string, OrderKey>()
+  placeByWalks(graph, backbone).forEach((id, rank) => {
+    key.set(id, { at: rank, side: 0, hops: 0 })
+  })
+  placeBySearch(adjacent, key)
+  return key
+}
+
+export interface LayeredGraph {
+  layers: string[][]
+  layerOf: Map<string, number>
+  // predecessors in layer order, for the y sweep
+  preds: Map<string, string[]>
+}
+
+// The layered DAG the ordered layout draws and the bubble decomposition reads
+// (bubbles/bubblesFromGraph.ts), from one function so the two cannot disagree
+// about which nodes share a layer.
+export function layerGraph(graph: Graph): LayeredGraph {
+  const byId = new Map(graph.nodes.map(n => [n.id, n]))
+  const order = referenceOrder(graph)
+  const key = new Map(order.map((id, i) => [id, i]))
+  const isRef = (id: string) => isBackbone(byId.get(id)!)
+
+  // Every edge directed from lower reference key to higher, so the graph is
+  // acyclic by construction and no cycle-removal heuristic can misplace the
+  // reference.
+  const preds = new Map<string, string[]>(order.map(id => [id, []]))
+  const succs = new Map<string, string[]>(order.map(id => [id, []]))
+  const link = (a: string, b: string) => {
+    preds.get(b)!.push(a)
+    succs.get(a)!.push(b)
+  }
+  for (const e of graph.edges) {
+    if (e.from === e.to || !key.has(e.from) || !key.has(e.to)) {
+      continue
+    }
+    if (key.get(e.from)! < key.get(e.to)!) {
+      link(e.from, e.to)
+    } else {
+      link(e.to, e.from)
+    }
+  }
+  // The backbone chained by virtual edges, so the reference stays monotone even
+  // where adjacent segments are not linked inside the cut.
+  const backbone = order.filter(isRef)
+  for (let i = 1; i < backbone.length; i++) {
+    link(backbone[i - 1]!, backbone[i]!)
+  }
+
+  // Longest-path layering; the key order is a topological order of this DAG.
+  const layerOf = new Map<string, number>()
+  for (const id of order) {
+    let l = 0
+    for (const p of preds.get(id)!) {
+      l = Math.max(l, layerOf.get(p)! + 1)
+    }
+    layerOf.set(id, l)
+  }
+  // Then each allele slides right to centre between the layer its predecessors
+  // force and the one its successors allow, so a short allele sits in the
+  // middle of its bubble rather than hugging the left anchor.
+  for (let i = order.length - 1; i >= 0; i--) {
+    const id = order[i]!
+    const s = succs.get(id)!
+    if (isRef(id) || s.length === 0) {
+      continue
+    }
+    let minSucc = Infinity
+    for (const t of s) {
+      minSucc = Math.min(minSucc, layerOf.get(t)!)
+    }
+    const lo = layerOf.get(id)!
+    const hi = Math.max(lo, minSucc - 1)
+    layerOf.set(id, Math.floor((lo + hi) / 2))
+  }
+
+  const layers: string[][] = []
+  for (const id of order) {
+    ;(layers[layerOf.get(id)!] ??= []).push(id)
+  }
+  return { layers, layerOf, preds }
+}
+
+export function orderedLayout(graph: Graph): LayoutResult | undefined {
+  if (!graph.nodes.some(isBackbone)) {
+    return undefined
+  }
+  const byId = new Map(graph.nodes.map(n => [n.id, n]))
+  const isRef = (id: string) => isBackbone(byId.get(id)!)
+  const { layers, layerOf: layer, preds } = layerGraph(graph)
+
+  const layerWidth = layers.map(ids => {
+    let w = 0
+    for (const id of ids) {
+      w = Math.max(w, nodeWidth(byId.get(id)!))
+    }
+    return w
+  })
+  const layerX: number[] = []
+  let x = 0
+  for (let l = 0; l < layers.length; l++) {
+    layerX[l] = x
+    x += layerWidth[l]! + GUTTER
+  }
+
+  // y: sweep the layers left to right, each allele at the barycenter of its
+  // placed predecessors, then at the nearest FREE lane to it. Lane 0 is the
+  // reference line and stays reserved even in a layer with no backbone node,
+  // or an allele between two backbone segments reads as reference.
+  const y = new Map<string, number>()
+  for (const ids of layers) {
+    const free: { id: string; ideal: number }[] = []
+    for (const id of ids) {
+      if (isRef(id)) {
+        y.set(id, 0)
+        continue
+      }
+      const placed = preds.get(id)!.filter(p => y.has(p))
+      let ideal = 0
+      for (const p of placed) {
+        ideal += y.get(p)! / placed.length
+      }
+      // a node straight off the backbone wants to leave it, not sit on it
+      free.push({ id, ideal: ideal === 0 ? LANE_PX : ideal })
+    }
+    free.sort((a, b) => a.ideal - b.ideal)
+    const taken = new Set([0])
+    for (const { id, ideal } of free) {
+      let lane = Math.round(ideal / LANE_PX)
+      if (lane === 0) {
+        lane = ideal >= 0 ? 1 : -1
+      }
+      for (let d = 1; taken.has(lane); d++) {
+        if (!taken.has(lane + d)) {
+          lane += d
+        } else if (!taken.has(lane - d)) {
+          lane -= d
+        }
+      }
+      taken.add(lane)
+      y.set(id, lane * LANE_PX)
+    }
+  }
+
+  const nodePositions: Record<string, NodeSegment[]> = {}
+  for (const n of graph.nodes) {
+    const l = layer.get(n.id)!
+    const w = nodeWidth(n)
+    const cx = layerX[l]! + layerWidth[l]! / 2
+    const ny = y.get(n.id)!
+    nodePositions[n.id] = [
+      { x: cx - w / 2, y: ny },
+      { x: cx + w / 2, y: ny },
+    ]
+  }
+  return { nodePositions, referenceAxis: false, pixelRows: true }
+}