jbrowse-plugin-graphgenomeviewer 1.0.0 → 3.0.3

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

@@ -0,0 +1,110 @@
+import { orientToReference } from './orientToReference'
+
+import type { Graph, NodeSegment } from '../types'
+
+const stable = (start: number, rank: number) => ({
+  refName: rank === 0 ? 'chr1' : 'alt',
+  start,
+  rank,
+})
+
+const graph: Graph = {
+  name: 'g',
+  nodes: [
+    { id: 'b0+', name: 'b0', length: 10, depth: 1, stable: stable(0, 0) },
+    { id: 'b1+', name: 'b1', length: 10, depth: 1, stable: stable(10, 0) },
+    { id: 'b2+', name: 'b2', length: 10, depth: 1, stable: stable(20, 0) },
+    { id: 'b3+', name: 'b3', length: 10, depth: 1, stable: stable(30, 0) },
+    { id: 'a0+', name: 'a0', length: 4, depth: 1, stable: stable(10, 1) },
+  ],
+  edges: [],
+}
+
+const segment = (x: number, y: number): NodeSegment[] => [
+  { x, y },
+  { x: x + 10, y },
+]
+
+// backbone left to right on y = 0, the allele below it
+const oriented: Record<string, NodeSegment[]> = {
+  'b0+': segment(0, 0),
+  'b1+': segment(20, 0),
+  'b2+': segment(40, 0),
+  'b3+': segment(60, 0),
+  'a0+': segment(25, 12),
+}
+
+function transform(
+  positions: Record<string, NodeSegment[]>,
+  angle: number,
+  reflect: boolean,
+  dx: number,
+  dy: number,
+) {
+  const c = Math.cos(angle)
+  const s = Math.sin(angle)
+  return Object.fromEntries(
+    Object.entries(positions).map(([id, segs]) => [
+      id,
+      segs.map(p => {
+        const y = reflect ? -p.y : p.y
+        return { x: c * p.x - s * y + dx, y: s * p.x + c * y + dy }
+      }),
+    ]),
+  )
+}
+
+const mid = (segs: NodeSegment[]) => segs[Math.floor(segs.length / 2)]!
+
+function distance(a: NodeSegment, b: NodeSegment) {
+  return Math.hypot(a.x - b.x, a.y - b.y)
+}
+
+test('a rotated and reflected drawing comes back reading left to right', () => {
+  const scrambled = transform(oriented, 2.3, true, 100, -50)
+  const out = orientToReference(graph, scrambled)
+  const xs = ['b0+', 'b1+', 'b2+', 'b3+'].map(id => mid(out[id]!).x)
+  for (let i = 1; i < xs.length; i++) {
+    expect(xs[i]!).toBeGreaterThan(xs[i - 1]!)
+  }
+  const backboneY = mid(out['b1+']!).y
+  for (const p of out['a0+']!) {
+    expect(p.y).toBeGreaterThan(backboneY)
+  }
+})
+
+test('the transform is rigid: pairwise distances survive', () => {
+  const scrambled = transform(oriented, -1.1, false, -30, 7)
+  const out = orientToReference(graph, scrambled)
+  const ids = Object.keys(oriented)
+  for (const a of ids) {
+    for (const b of ids) {
+      expect(distance(out[a]![0]!, out[b]![1]!)).toBeCloseTo(
+        distance(scrambled[a]![0]!, scrambled[b]![1]!),
+        9,
+      )
+    }
+  }
+})
+
+test('an oriented drawing is returned where it was', () => {
+  const out = orientToReference(graph, oriented)
+  for (const [id, segs] of Object.entries(oriented)) {
+    segs.forEach((p, i) => {
+      expect(out[id]![i]!.x).toBeCloseTo(p.x, 9)
+      expect(out[id]![i]!.y).toBeCloseTo(p.y, 9)
+    })
+  }
+})
+
+test('alleles above the axis are reflected below it', () => {
+  const above = transform(oriented, 0, true, 0, 0)
+  const out = orientToReference(graph, above)
+  expect(mid(out['a0+']!).y).toBeGreaterThan(mid(out['b1+']!).y)
+  expect(mid(out['b3+']!).x).toBeGreaterThan(mid(out['b0+']!).x)
+})
+
+test('fewer than two placed backbone nodes leaves the drawing alone', () => {
+  const positions = { 'b0+': segment(3, 4), 'a0+': segment(9, -2) }
+  expect(orientToReference(graph, positions)).toBe(positions)
+})

package/src/GraphGenomeView/layout/orientToReference.ts

@@ -0,0 +1,79 @@
+import { isBackbone } from '../anchoredNodes'
+
+import type { Graph, NodeSegment } from '../types'
+
+type Positions = Record<string, NodeSegment[]>
+
+// Turn a finished force layout so the reference runs left to right: the
+// rotation that best maps backbone midpoints onto their reference coordinate
+// (a one-dimensional orthogonal Procrustes fit, weighted by segment length),
+// then a reflection so the off-reference mass sits below the axis. A rigid
+// transform, so the drawing FMMM made is unchanged; only its frame moves.
+//
+// About the length-weighted centroid, and translated back, so a drawing that is
+// already oriented comes back where it was rather than recentred on the origin.
+export function orientToReference(graph: Graph, positions: Positions) {
+  const backbone = graph.nodes.filter(
+    node => isBackbone(node) && (positions[node.id]?.length ?? 0) > 0,
+  )
+  if (backbone.length < 2) {
+    return positions
+  }
+  const points = backbone.map(node => {
+    const segments = positions[node.id]!
+    const mid = segments[Math.floor(segments.length / 2)]!
+    return {
+      x: mid.x,
+      y: mid.y,
+      r: node.stable!.start + node.length / 2,
+      w: node.length,
+    }
+  })
+  const weight = points.reduce((sum, p) => sum + p.w, 0)
+  const cx = points.reduce((sum, p) => sum + p.x * p.w, 0) / weight
+  const cy = points.reduce((sum, p) => sum + p.y * p.w, 0) / weight
+  const cr = points.reduce((sum, p) => sum + p.r * p.w, 0) / weight
+  // cross-covariance of (x, y) against (r, 0); only the first row is non-zero
+  let sxr = 0
+  let syr = 0
+  for (const p of points) {
+    sxr += p.w * (p.x - cx) * (p.r - cr)
+    syr += p.w * (p.y - cy) * (p.r - cr)
+  }
+  // the rotation taking the direction (sxr, syr) onto +x
+  const angle = -Math.atan2(syr, sxr)
+  const c = Math.cos(angle)
+  const s = Math.sin(angle)
+
+  const out: Positions = {}
+  for (const [id, segments] of Object.entries(positions)) {
+    out[id] = segments.map(p => {
+      const x = p.x - cx
+      const y = p.y - cy
+      return { x: cx + c * x - s * y, y: cy + s * x + c * y }
+    })
+  }
+
+  let below = 0
+  let above = 0
+  for (const node of graph.nodes) {
+    if (isBackbone(node)) {
+      continue
+    }
+    for (const p of out[node.id] ?? []) {
+      if (p.y > cy) {
+        below++
+      } else {
+        above++
+      }
+    }
+  }
+  if (above > below) {
+    for (const segments of Object.values(out)) {
+      for (const p of segments) {
+        p.y = 2 * cy - p.y
+      }
+    }
+  }
+  return out
+}

package/src/GraphGenomeView/layout/placeOffReference.ts

@@ -0,0 +1,147 @@
+import { projectAlleles } from '../../alleleProjection/projectAlleles'
+import { buildNeighbors } from '../referenceSpan'
+
+import type { AlleleDeletion, Graph, NodeSegment } from '../types'
+
+// Where off-reference segments go on a reference x axis. Shared by the two
+// row-structured layouts, which differ only in what a row means (stable rank
+// vs contributing assembly); how far along the reference a segment reaches is
+// the same question in both, and answering it twice is how they drifted.
+//
+// The rule: a segment occupies the reference its allele replaces, never its own
+// sequence length. x is reference bp — the axis the backbone declares and the
+// linear view beside it is drawn on — so an insertion, which consumes no
+// reference, must not advance along it. Both layouts used to advance by
+// sequence length, which made every off-reference x a false statement about
+// reference position and, on a 1 kb window holding a 100 kb allele, drew 101x
+// the window so that zoom-to-fit rendered the reference at 1% of the frame.
+//
+// Magnitude is the cost. An axis of reference coordinates has no way to state
+// how much sequence an insertion adds, so it is not stated here: it is in the
+// node tooltip, and drawn to scale in the allele-inventory track, where a CIGAR
+// gives the alignments display a channel for length that is not the x axis.
+
+// Reference bp an allele has to skip before the drawing calls it a deletion:
+// the 1 bp floor `deletionEdges` uses, a guard against abutting anchors' zero
+// gap rather than a biological threshold. Whether a small one is drawn is
+// decided by its label's fit in graphLabels.
+const MIN_DELETION_BP = 1
+
+// Floor on an off-reference node's drawn span, as a fraction of the window.
+// Node thickness is a constant number of screen pixels, so a segment on a
+// sub-percent slice of the window draws wider than it is long and reads as a
+// dot on a stalk, and a pure insertion occupies no reference at all. Rank-0
+// nodes keep their exact offsets, so the reference axis is untouched.
+const MIN_ALLELE_SPAN_FRACTION = 0.015
+
+interface PlaceArgs {
+  graph: Graph
+  // the reference interval the drawing is scaled against (referenceSpan)
+  span: number
+  // y for a segment, which is the whole of what the two layouts disagree about
+  rowY: (node: Graph['nodes'][number]) => number
+  // the backbone, already placed at its declared offsets. Mutated in place, and
+  // read for the branch points the unanchored walk below starts from.
+  positions: Record<string, NodeSegment[]>
+}
+
+export function placeOffReference({
+  graph,
+  span,
+  rowY,
+  positions,
+}: PlaceArgs): AlleleDeletion[] {
+  const minSpan = span * MIN_ALLELE_SPAN_FRACTION
+  const alleles = projectAlleles(graph)
+  const byId = new Map(graph.nodes.map(n => [n.id, n]))
+  // Alleles standing in for more reference than they carry. Collected here
+  // rather than derived by the label pass, because the reason they need saying
+  // is the placement done in this function: a run drawn over the reference it
+  // replaces has a width that is not its length, and nothing downstream can
+  // tell that from a node drawn at its own scale. Same measure the deletion
+  // arcs use — reference bp a haplotype does not carry — so the two kinds of
+  // deletion in a drawing are stated in the same units and the same words.
+  const alleleDeletions: AlleleDeletion[] = []
+
+  for (const allele of alleles) {
+    const skipped = allele.refSpan - allele.pathLength
+    if (skipped >= MIN_DELETION_BP) {
+      alleleDeletions.push({ nodeIds: allele.nodeIds, bp: skipped })
+    }
+    const drawn = Math.max(allele.refSpan, minSpan)
+    // A node sits where it sits *within* the allele: its bp offset from the
+    // entry, scaled so the run's longest path fills the reference the allele
+    // replaces. So a bubble path occupies the reference exactly once however
+    // many segments it is built from, and two parallel branches share the x
+    // range rather than queue up after each other — they are alternatives over
+    // the same interval, not consecutive sequence.
+    //
+    // Offsets are measured over the graph rather than over nodeIds' order (see
+    // runOffsets). Concatenating in traversal order put graph neighbours 26 kb
+    // apart on a 27 kb allele, and the edges spanning those gaps crossed as a
+    // long X. A run of all zero-length segments has no distances to scale by;
+    // splitting evenly beats 0/0, which wrote NaN into every position after it.
+    //
+    // Where the floor widens a run past the reference it replaces, the overhang
+    // hangs off the right, so the run can end past the rank-0 segment it
+    // rejoins and its exit edge runs backwards. That is handled where it shows,
+    // in computeEdgeCurves, which sizes each control point by how far the other
+    // endpoint lies along its own tangent — a backwards edge gets a straight
+    // leader rather than the loop that read as a crossed bowtie.
+    const scale = allele.pathLength > 0 ? drawn / allele.pathLength : 0
+    allele.nodeIds.forEach((nodeId, i) => {
+      const node = byId.get(nodeId)
+      if (node) {
+        const offset = allele.nodeOffsets[i]!
+        const even = drawn / allele.nodeIds.length
+        // both ends from the offset rather than start-plus-width, so two nodes
+        // the sweep placed end to end land on exactly the same x instead of on
+        // two roundings of it
+        const at = (bp: number) => allele.start + bp * scale
+        const y = rowY(node)
+        positions[nodeId] = scale
+          ? [
+              { x: at(offset), y },
+              { x: at(offset + node.length), y },
+            ]
+          : [
+              { x: allele.start + i * even, y },
+              { x: allele.start + (i + 1) * even, y },
+            ]
+      }
+    })
+  }
+
+  // A run that reaches the edge of the fetched subgraph has only one backbone
+  // anchor, so no reference span can be stated for it. That is the normal case
+  // at a window boundary, not an error, and dropping it is indistinguishable
+  // from the layout being broken — the sample-rows layout did drop them.
+  //
+  // They get the floor each, chained from wherever they branch: the only honest
+  // claim available is "attaches here and continues past the edge", and a floor
+  // keeps a chain of them bounded by the window instead of by their sequence.
+  // The same undirected adjacency the reference walk builds, from the one
+  // function that builds it. The copy here rebuilt each list with a spread per
+  // edge, which is quadratic in a node's degree and is the shape a collapsed
+  // repeat's hub node is worst at.
+  const neighbors = buildNeighbors(graph)
+  // Read forward while appending, so this is a BFS with an O(1) dequeue rather
+  // than a quadratic shift() over what ends up being every node in the run.
+  const queue = Object.keys(positions)
+  for (const fromId of queue) {
+    const fromEnd = positions[fromId]!.at(-1)!.x
+    for (const nextId of neighbors.get(fromId) ?? []) {
+      const next = byId.get(nextId)
+      if (next && !(nextId in positions)) {
+        const y = rowY(next)
+        positions[nextId] = [
+          { x: fromEnd, y },
+          { x: fromEnd + minSpan, y },
+        ]
+        queue.push(nextId)
+      }
+    }
+  }
+
+  return alleleDeletions
+}

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

@@ -0,0 +1,79 @@
+import { drawnNodeLength, layoutScaling } from './drawnScale'
+import { referenceSeeds, seededNodes } from './referenceSeeds'
+import { parseGFA } from '../../gfa-core/index'
+import { spreadFor } from '../bubbleSpreads'
+import { convertGFAToGraph } from '../gfa/gfaConverter'
+
+// chr1 runs v1->v2->v3->v4; a1 replaces v3 and hangs a2 off itself, which no
+// backbone node touches; lone is linked to nothing. Lengths span 1 bp to 7 kb so
+// a compressing spread moves the spacing by more than rounding.
+const GFA = `S\tv1\t${'A'.repeat(5000)}\tSN:Z:chr1\tSO:i:0\tSR:i:0
+S\tv2\tCCC\tSN:Z:chr1\tSO:i:5000\tSR:i:0
+S\tv3\tGG\tSN:Z:chr1\tSO:i:5003\tSR:i:0
+S\tv4\t${'T'.repeat(7000)}\tSN:Z:chr1\tSO:i:5005\tSR:i:0
+S\ta1\tAC\tSN:Z:foo\tSO:i:8\tSR:i:1
+S\ta2\tT\tSN:Z:bar\tSO:i:8\tSR:i:2
+S\tlone\tGATTACA\tSN:Z:baz\tSO:i:0\tSR:i:1
+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\ta1\t+\ta2\t+\t0M`
+
+const graph = convertGFAToGraph(parseGFA(GFA))
+const BACKBONE = ['v1+', 'v2+', 'v3+', 'v4+']
+
+test('the backbone runs along x, each node one drawn length and one edge on', () => {
+  const scaling = layoutScaling(graph)
+  const seeds = referenceSeeds(graph, scaling)
+  let x = 0
+  for (const id of BACKBONE) {
+    expect(seeds.get(id)).toEqual({ x, y: 0 })
+    const node = graph.nodes.find(n => n.id === id)!
+    x += drawnNodeLength(scaling.opts, node.length) + scaling.opts.edgeLength
+  }
+})
+
+test('an allele sits at its anchor midpoint one lane down, a lane more per step', () => {
+  const scaling = layoutScaling(graph)
+  const seeds = referenceSeeds(graph, scaling)
+  const v2 = graph.nodes.find(n => n.id === 'v2+')!
+  const a1 = graph.nodes.find(n => n.id === 'a1+')!
+  const anchor = seeds.get('v2+')!
+  expect(seeds.get('a1+')).toEqual({
+    x: anchor.x + drawnNodeLength(scaling.opts, v2.length) / 2,
+    y: 30,
+  })
+  expect(seeds.get('a2+')).toEqual({
+    x: seeds.get('a1+')!.x + drawnNodeLength(scaling.opts, a1.length) / 2,
+    y: 60,
+  })
+})
+
+test('a node no backbone reaches goes below everything', () => {
+  const seeds = referenceSeeds(graph, layoutScaling(graph))
+  expect(seeds.get('lone+')).toEqual({ x: 0, y: 90 })
+  expect(seeds.size).toBe(graph.nodes.length)
+})
+
+test('spacing follows the scaled lengths the engine is handed, not bp', () => {
+  const compressed = layoutScaling(graph, spreadFor('compress'))
+  const seeds = referenceSeeds(graph, compressed)
+  const v1 = compressed.nodes.find(n => n.id === 'v1+')!
+  expect(v1.length).not.toBe(5000)
+  expect(seeds.get('v2+')!.x).toBe(
+    drawnNodeLength(compressed.opts, v1.length) + compressed.opts.edgeLength,
+  )
+  const proportional = referenceSeeds(graph, layoutScaling(graph))
+  expect(seeds.get('v2+')!.x).not.toBe(proportional.get('v2+')!.x)
+})
+
+test('seededNodes carries every scaled node with its seed', () => {
+  const scaling = layoutScaling(graph, spreadFor('compress'))
+  const nodes = seededNodes(graph, scaling)
+  expect(nodes.map(n => n.length)).toEqual(scaling.nodes.map(n => n.length))
+  expect(nodes.every(n => Number.isFinite(n.x) && Number.isFinite(n.y))).toBe(
+    true,
+  )
+})

package/src/GraphGenomeView/layout/referenceSeeds.ts

@@ -0,0 +1,89 @@
+import { isBackbone } from '../anchoredNodes'
+import { buildNeighbors } from '../referenceSpan'
+import { drawnNodeLength } from './drawnScale'
+
+import type { LayoutScaling } from './drawnScale'
+import type { Graph, GraphNode } from '../types'
+
+// A node as the engine takes it: an optional `x`/`y` is where FMMM starts the
+// node's chain (`addToOgdfGraph`, graphlayout.cpp).
+export type LayoutNode = GraphNode & { x?: number; y?: number }
+
+export interface Seed {
+  x: number
+  y: number
+}
+
+// y per BFS step off the backbone. FMMM keeps only the coarse shape of these
+// (OGDF applies the initial placement at its coarsest multilevel graph), so
+// the gap needs to say "below the line", not to place a lane.
+const LANE_GAP = 30
+
+// Initial positions for a reference-anchored graph: the backbone end to end
+// along x at drawn length, each off-reference node at the midpoint of the node
+// a BFS from the backbone reached it from, a lane lower per step. Two alleles
+// off one anchor share a seed; FMMM separates them. Nodes no backbone reaches
+// spread along x below everything rather than piling on one point.
+//
+// Lengths come from `scaling.nodes`, not the graph's bp: under a compressing
+// spread a node's `length` crosses the RPC as drawn units times 1000 with a
+// matching `nodeLengthPerMegabase`, and a seed from bp would misplace every
+// chain against the one the engine builds.
+export function referenceSeeds(
+  graph: Graph,
+  scaling: LayoutScaling,
+): Map<string, Seed> {
+  const { opts } = scaling
+  const drawn = new Map(
+    scaling.nodes.map(node => [node.id, drawnNodeLength(opts, node.length)]),
+  )
+  const drawnOf = (id: string) => drawn.get(id) ?? opts.minimumNodeLength
+  const backbone = graph.nodes
+    .filter(isBackbone)
+    .sort((a, b) => a.stable.start - b.stable.start)
+
+  const seeds = new Map<string, Seed>()
+  let x = 0
+  for (const node of backbone) {
+    seeds.set(node.id, { x, y: 0 })
+    x += drawnOf(node.id) + opts.edgeLength
+  }
+
+  const adjacent = buildNeighbors(graph)
+
+  const depth = new Map(backbone.map(node => [node.id, 0]))
+  // for-of over an array that grows as it goes: the iterator reads the live
+  // length, so nodes pushed here are visited
+  const queue = backbone.map(node => node.id)
+  for (const id of queue) {
+    const at = seeds.get(id)!
+    const next = depth.get(id)! + 1
+    for (const neighbour of adjacent.get(id) ?? []) {
+      if (depth.has(neighbour)) {
+        continue
+      }
+      depth.set(neighbour, next)
+      seeds.set(neighbour, { x: at.x + drawnOf(id) / 2, y: LANE_GAP * next })
+      queue.push(neighbour)
+    }
+  }
+
+  let unreached = 0
+  for (const node of graph.nodes) {
+    if (!seeds.has(node.id)) {
+      seeds.set(node.id, {
+        x: (unreached++ * x) / graph.nodes.length,
+        y: LANE_GAP * 3,
+      })
+    }
+  }
+  return seeds
+}
+
+export function seededNodes(
+  graph: Graph,
+  scaling: LayoutScaling,
+): LayoutNode[] {
+  const seeds = referenceSeeds(graph, scaling)
+  return scaling.nodes.map(node => ({ ...node, ...seeds.get(node.id) }))
+}

package/src/GraphGenomeView/layout/rowSpacing.ts

@@ -0,0 +1,5 @@
+// Row pitch of the row layouts, in screen pixels rather than bp: a row holds a
+// 10 px tube and an 11 px label whatever the window spans, so y is never
+// scaled (LayoutResult.pixelRows) and rows past the pane are reached by panning.
+// 20 px is the floor at which labels stop touching.
+export const ROW_HEIGHT_PX = 20