jbrowse-plugin-graphgenomeviewer 3.0.4 → 3.1.0

package/src/GraphGenomeView/follow.ts

@@ -0,0 +1,129 @@
+import type { SubgraphRegion } from '../launchSubgraph/launchSubgraphView'
+
+// The members of a LinearGenomeView the follow reads and drives. Structural,
+// because this plugin takes no runtime dependency on the LGV plugin (see
+// hoverSync/index.tsx).
+export interface FollowedBlock {
+  refName: string
+  assemblyName: string
+  start: number
+  end: number
+  offsetPx: number
+  reversed?: boolean
+  displayedRegionIndex?: number
+}
+
+export interface FollowedView {
+  id: string
+  initialized: boolean
+  bpPerPx: number
+  offsetPx: number
+  width: number
+  displayedRegions: readonly { start: number; end: number }[]
+  dynamicBlocks: { contentBlocks: readonly FollowedBlock[] }
+  coarseDynamicBlocks: readonly FollowedBlock[]
+  horizontalScroll: (distance: number) => number
+  zoomTo: (bpPerPx: number, offset?: number) => number
+}
+
+export function isFollowable(view: unknown): view is FollowedView {
+  if (typeof view !== 'object' || view === null) {
+    return false
+  }
+  const v = view as Record<string, unknown>
+  return (
+    typeof v.horizontalScroll === 'function' &&
+    typeof v.zoomTo === 'function' &&
+    'coarseDynamicBlocks' in v &&
+    'dynamicBlocks' in v
+  )
+}
+
+// launchSubgraphView's widestBlock, restated rather than imported: that module
+// imports the model, which imports this.
+function widest(blocks: readonly FollowedBlock[]) {
+  return blocks.reduce<FollowedBlock | undefined>(
+    (best, b) => (best && best.end - best.start >= b.end - b.start ? best : b),
+    undefined,
+  )
+}
+
+export interface FollowWindow {
+  refName: string
+  assemblyName: string
+  start: number
+  end: number
+  bpPerPx: number
+  // the view's width in bp, which the margin is sized by: a block at a contig
+  // end is clipped, the zoom is not
+  span: number
+  regionStart: number
+  regionEnd: number
+}
+
+// x is reference bp on an anchored layout, so the graph shows what the linear
+// view shows when one bp is as many px in both and the cut's refName sits at
+// the same screen x. Undefined when the linear view shows no block of that
+// refName, which is a re-cut's job rather than the frame's.
+export function followFrame(view: FollowedView, region: SubgraphRegion) {
+  const block = widest(
+    view.dynamicBlocks.contentBlocks.filter(
+      b =>
+        b.refName === region.refName && b.assemblyName === region.assemblyName,
+    ),
+  )
+  const { bpPerPx } = view
+  return block && bpPerPx > 0
+    ? {
+        scale: 1 / bpPerPx,
+        translateX: block.offsetPx - view.offsetPx - block.start / bpPerPx,
+      }
+    : undefined
+}
+
+// Read off the LIVE blocks even when the coarse ones woke the caller: those
+// name where the window was half a second ago (SyntenyFollow/CLAUDE.md).
+export function followWindow(view: FollowedView): FollowWindow | undefined {
+  const block = widest(view.dynamicBlocks.contentBlocks)
+  const displayed =
+    block?.displayedRegionIndex === undefined
+      ? undefined
+      : view.displayedRegions[block.displayedRegionIndex]
+  return block && view.bpPerPx > 0
+    ? {
+        refName: block.refName,
+        assemblyName: block.assemblyName,
+        start: block.start,
+        end: block.end,
+        bpPerPx: view.bpPerPx,
+        span: view.bpPerPx * view.width,
+        regionStart: displayed?.start ?? block.start,
+        regionEnd: displayed?.end ?? block.end,
+      }
+    : undefined
+}
+
+// The window plus one window-width each side, clamped to the displayed
+// region, with the margins narrowed until the whole cut fits under `capBp`.
+export function followCut(window: FollowWindow, capBp: number): SubgraphRegion {
+  const visible = window.end - window.start
+  const margin = Math.max(0, Math.min(window.span, (capBp - visible) / 2))
+  return {
+    refName: window.refName,
+    assemblyName: window.assemblyName,
+    start: Math.max(window.regionStart, Math.floor(window.start - margin)),
+    end: Math.min(window.regionEnd, Math.ceil(window.end + margin)),
+  }
+}
+
+export function cutHolds(
+  cut: SubgraphRegion | undefined,
+  window: FollowWindow,
+) {
+  return (
+    cut?.refName === window.refName &&
+    cut.assemblyName === window.assemblyName &&
+    cut.start <= window.start &&
+    window.end <= cut.end
+  )
+}

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

@@ -34,6 +34,22 @@ test('rows are the backbone plus one per contributing assembly', () => {
   ])
 })
 
+// A follow re-cuts as the linear view pans, and a stack re-sorted per window
+// moves every row under the reader. Handed the rows on screen, the layout keeps
+// those in their order, drops one the window no longer holds, and puts a sample
+// new to the window below them.
+test('the rows on screen keep their order, and a new sample goes below', () => {
+  const graph = ecoliGraph()
+  const [first, second, third] = sampleRowLayout(graph)!.sampleRows!
+  const { sampleRows, rowLabels } = sampleRowLayout(graph, undefined, [
+    'HG00099',
+    third!,
+    second!,
+  ])!
+  expect(sampleRows).toEqual([third, second, first])
+  expect(rowLabels!.slice(1).map(r => r.label)).toEqual(sampleRows)
+})
+
 // Alphabetical put HG00099 above HG00280 for no reason a reader could see, so a
 // row's neighbours said nothing. Ordering by contributed sequence reads the way
 // a sorted pileup does — most divergent at the top, and how far down the stack

package/src/GraphGenomeView/layout/sampleRowLayout.ts

@@ -55,11 +55,14 @@ import type { Graph, LayoutResult, RowLabel } from '../types'
 // What that costs is comparing one window against another — the order is a fact
 // about the window, so a sample is not in the same place in two of them. That is
 // the case §8's "a row set cannot be requested" is for, and an explicit sample
-// list is the right answer to it rather than an order nobody can read.
+// list is the right answer to it rather than an order nobody can read. A
+// follow's re-cut is the exception it can answer already: `keep` is the rows on
+// screen, those samples hold their order, and a sample new to the window goes
+// below them by content.
 //
 // Name breaks ties, so the order is still deterministic and a pan that changes
 // nothing about the content reshuffles nothing.
-function contributingSamples(graph: Graph) {
+function contributingSamples(graph: Graph, keep: readonly string[]) {
   const carried = new Map<string, number>()
   for (const node of graph.nodes) {
     if (isOffReference(node)) {
@@ -67,17 +70,22 @@ function contributingSamples(graph: Graph) {
       carried.set(sample, (carried.get(sample) ?? 0) + node.length)
     }
   }
+  const held = new Map(keep.map((sample, row) => [sample, row]))
   return [...carried.keys()].sort(
-    (a, b) => carried.get(b)! - carried.get(a)! || a.localeCompare(b),
+    (a, b) =>
+      (held.get(a) ?? Infinity) - (held.get(b) ?? Infinity) ||
+      carried.get(b)! - carried.get(a)! ||
+      a.localeCompare(b),
   )
 }
 
 export function sampleRowLayout(
   graph: Graph,
   region?: { start: number; end: number },
+  keep: readonly string[] = [],
 ): LayoutResult | undefined {
   const backbone = backboneNodes(graph)
-  const samples = contributingSamples(graph)
+  const samples = contributingSamples(graph, keep)
   if (backbone.length === 0 || samples.length === 0) {
     return undefined
   }
@@ -127,6 +135,7 @@ export function sampleRowLayout(
   return {
     nodePositions,
     rowLabels,
+    sampleRows: samples,
     referenceAxis: true,
     pixelRows: true,
     alleleDeletions,

package/src/GraphGenomeView/layoutModes.ts

@@ -28,10 +28,12 @@ export interface LayoutMode {
   // 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).
+  // (referenceSpan). `keepRows` is the sample rows on screen, which only the
+  // sample-row layout reads (LayoutResult.sampleRows).
   run: (
     graph: Graph,
     region?: { start: number; end: number },
+    keepRows?: readonly string[],
   ) => 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