jbrowse-plugin-graphgenomeviewer 6.1.4 → 6.2.0

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "jbrowse-plugin-graphgenomeviewer",
-  "version": "6.1.4",
+  "version": "6.2.0",
   "description": "JBrowse 2 graph genome (pangenome) view: rGFA reference-anchored layouts, the Bandage force-directed engine, and haplotype lanes read from a gbz-base database",
   "license": "GPL-3.0-or-later",
   "repository": {
@@ -26,7 +26,7 @@
   "private": false,
   "dependencies": {
     "@gmod/bgzf-filehandle": "^6.7.0",
-    "@gmod/gbz-base": "^7.0.0",
+    "@gmod/gbz-base": "^7.1.0",
     "@gmod/tabix": "^3.9.1",
     "@gmod/tubemap-core": "^0.1.0",
     "@jbrowse/cigar-utils": "5.0.0-beta.11",

package/src/GbzBaseSyntenyAdapter/GbzBaseSyntenyAdapter.test.ts

@@ -15,6 +15,7 @@ import Adapter, {
   PairTargetError,
   laneAssemblyName,
   resolveReferenceSample,
+  widestWalkGap,
 } from './GbzBaseSyntenyAdapter.ts'
 import configSchema from './configSchema.ts'
 import GbzBaseSyntenyAdapterF from './index.ts'
@@ -518,7 +519,7 @@ test('the adapter type declares that a window of its anchor answers any lane pai
   pluginManager.createPluggableElements()
   expect(
     pluginManager.getAdapterType('GbzBaseSyntenyAdapter').adapterCapabilities,
-  ).toContain('lanePairsOnAnchor')
+  ).toEqual(expect.arrayContaining(['lanePairsOnAnchor', 'lanePairBatches']))
 })
 
 // HG00673#1's insertion is 16 bp longer than HG01361#2's, so that pair holds
@@ -692,6 +693,82 @@ test('a lane pair walks only its two lanes', async () => {
   cut.mockRestore()
 })
 
+test('a batch of lane pairs answers each pair what it answers alone, from one cut', async () => {
+  const adapter = anchoredAdapter()
+  const pairs = [
+    { queryAssemblyName: 'HG01361#2', targetAssemblyName: 'HG02145#2' },
+    { queryAssemblyName: 'HG02145#2', targetAssemblyName: 'HG00673#1' },
+    { queryAssemblyName: 'HG00673#1', targetAssemblyName: 'HG00438#1' },
+  ]
+  const alone = await Promise.all(
+    pairs.map(async p =>
+      (await feats(adapter, insertionWindow, p)).map(f => f.toJSON()),
+    ),
+  )
+  const { db } = await (
+    adapter as unknown as {
+      graph: () => Promise<{ db: { getSubgraphs: unknown } }>
+    }
+  ).graph()
+  const cut = vi.spyOn(db, 'getSubgraphs')
+  const batch = await feats(adapter, insertionWindow, { lanePairs: pairs })
+  expect(cut).toHaveBeenCalledTimes(1)
+  cut.mockRestore()
+  pairs.forEach((p, i) => {
+    expect(alone[i]!.length).toBeGreaterThan(0)
+    expect(
+      batch
+        .filter(
+          f =>
+            f.get('assemblyName') === p.queryAssemblyName &&
+            mateOf(f).assemblyName === p.targetAssemblyName,
+        )
+        .map(f => f.toJSON()),
+    ).toEqual(alone[i])
+  })
+})
+
+test('a kept walk in two pieces is the gap a pair cut widens its context for', () => {
+  const name = (sample: string, haplotype: number, contig = 'c') => ({
+    sample,
+    haplotype,
+    contig,
+    fragment: 0,
+  })
+  const subgraph = (
+    spans: { name: ReturnType<typeof name>; start: number; end: number }[],
+  ) => ({ walkSpans: () => spans }) as unknown as Subgraph
+  const kept = new Set(['A#1', 'B#1'])
+  expect(
+    widestWalkGap(
+      [
+        subgraph([
+          { name: name('A', 1), start: 0, end: 100 },
+          { name: name('A', 1), start: 54_100, end: 60_000 },
+          { name: name('B', 1), start: 0, end: 500 },
+          { name: name('B', 1), start: 2500, end: 3000 },
+          { name: name('C', 1), start: 0, end: 10 },
+          { name: name('C', 1), start: 90_000, end: 90_010 },
+        ]),
+      ],
+      kept,
+    ),
+  ).toBe(54_000)
+  expect(
+    widestWalkGap(
+      [
+        subgraph([
+          { name: name('A', 1), start: 0, end: 100 },
+          { name: name('A', 1), start: 500_000, end: 500_100 },
+          { name: name('B', 1, 'c1'), start: 0, end: 100 },
+          { name: name('B', 1, 'c2'), start: 5000, end: 5100 },
+        ]),
+      ],
+      kept,
+    ),
+  ).toBe(0)
+})
+
 test('lane pair ids are the same across two fetches of one window', async () => {
   const adapter = anchoredAdapter()
   const ids = async () =>

package/src/GbzBaseSyntenyAdapter/GbzBaseSyntenyAdapter.ts

@@ -1,4 +1,4 @@
-import { GBZBase } from '@gmod/gbz-base'
+import { GBZBase, SubgraphLimitError } from '@gmod/gbz-base'
 import {
   NodeLimitError,
   cutWindowGFA,
@@ -34,6 +34,7 @@ import type {
   PairAlignment,
   PathName,
   PathQuery,
+  Subgraph,
 } from '@gmod/gbz-base'
 import type { BaseOptions } from '@jbrowse/core/data_adapters/BaseAdapter'
 import type { Feature, SimpleFeatureSerialized } from '@jbrowse/core/util'
@@ -91,6 +92,16 @@ export interface GbzHeaderLane {
 export interface GbzFeatureOptions extends ComparativeOptions {
   haplotypes?: string[]
   queryAssemblyName?: string
+  lanePairs?: LanePair[]
+}
+
+/**
+ * Two lanes aligned to each other inside an anchor window: records on the
+ * query lane's contigs, with the target lane's walk as the mate
+ */
+export interface LanePair {
+  queryAssemblyName: string
+  targetAssemblyName: string
 }
 
 export class PairTargetError extends Error {
@@ -103,6 +114,16 @@ export class PairTargetError extends Error {
   }
 }
 
+function onePair(
+  queryAssemblyName: string,
+  targetAssemblyName: string | undefined,
+): LanePair {
+  if (targetAssemblyName === undefined) {
+    throw new PairTargetError(queryAssemblyName)
+  }
+  return { queryAssemblyName, targetAssemblyName }
+}
+
 export class HaplotypeWindowError extends Error {
   override name = 'HaplotypeWindowError'
 
@@ -213,6 +234,39 @@ export function pairFeature({
   })
 }
 
+// The longest detour a pair cut widens its context to take in
+const BRIDGE_MAX_BP = 120_000
+
+/**
+ * The widest gap, up to `BRIDGE_MAX_BP`, between two pieces of one kept walk:
+ * a haplotype that left the cut's nodes for sequence the reference lacks and
+ * came back. Two kept haplotypes that share that sequence only align across it
+ * once its nodes are in the cut.
+ */
+export function widestWalkGap(subgraphs: Subgraph[], kept: Set<string>) {
+  const byPath = new Map<string, [number, number][]>()
+  for (const subgraph of subgraphs) {
+    for (const { name, start, end } of subgraph.walkSpans()) {
+      const prefix = haplotypePrefix(name)
+      if (kept.has(prefix)) {
+        const key = `${prefix}#${name.contig}`
+        byPath.set(key, [...(byPath.get(key) ?? []), [start, end]])
+      }
+    }
+  }
+  let widest = 0
+  for (const spans of byPath.values()) {
+    spans.sort((a, b) => a[0] - b[0])
+    for (let i = 1; i < spans.length; i++) {
+      const gap = spans[i]![0] - spans[i - 1]![1]
+      if (gap > 0 && gap <= BRIDGE_MAX_BP) {
+        widest = Math.max(widest, gap)
+      }
+    }
+  }
+  return widest
+}
+
 // A window past the node limit fails as a zoom-in notice naming a span that
 // fits
 function zoomInNotice(error: unknown, what: string) {
@@ -495,71 +549,93 @@ export default class GbzBaseSyntenyAdapter extends ComparativeAdapterBase<GbzBas
   }
 
   /**
-   * The two lanes' walks cut out of the anchor window alone, and each walk
-   * of the query lane aligned to each walk of the target lane on the nodes
-   * both visit, with no base compared. The records sit on the query lane's
-   * contigs, the lane the display draws on top.
+   * Each pair's two lanes cut out of the anchor window alone, all pairs in one
+   * cut, and each walk of a pair's query lane aligned to each walk of its
+   * target lane on the nodes both visit, with no base compared. A pair's
+   * records sit on its query lane's contigs, the lane the display draws on top.
    *
    * Whether the index has anchor rows changes only how fast gbz-base finds
    * the walks: both routes cut the same pieces.
    */
   private async pairFeatures(
     region: Region,
-    queryAssemblyName: string,
+    pairs: LanePair[],
     opts: GbzFeatureOptions,
   ) {
-    const { targetAssemblyName } = opts
-    if (targetAssemblyName === undefined) {
-      throw new PairTargetError(queryAssemblyName)
-    }
     const { db } = await this.graph(opts)
     const { refName, start, end } = region
-    const featureSide = await this.laneHaplotypes(queryAssemblyName, opts)
-    const mateSide = await this.laneHaplotypes(targetAssemblyName, opts)
-    const kept = [...featureSide, ...mateSide]
+    const sides = await Promise.all(
+      pairs.map(async pair => ({
+        pair,
+        featureSide: await this.laneHaplotypes(pair.queryAssemblyName, opts),
+        mateSide: await this.laneHaplotypes(pair.targetAssemblyName, opts),
+      })),
+    )
+    const answerable = sides.filter(
+      ({ featureSide, mateSide }) =>
+        featureSide.length > 0 && mateSide.length > 0,
+    )
+    const kept = new Set(
+      answerable.flatMap(({ featureSide, mateSide }) =>
+        [...featureSide, ...mateSide].map(haplotypePrefix),
+      ),
+    )
     const query = await this.referenceQuery(refName, opts)
     const nodeLimit: number = this.getConf('nodeLimit')
-    const cut = (path: PathQuery) =>
-      db
-        .getSubgraphs({
-          path,
-          start,
-          end,
-          context: this.getConf('context'),
-          snarls: this.getConf('subgraphSnarls'),
-          haplotypes: 'all',
-          limit: nodeLimit,
-          signal: opts.signal,
-          keep: name =>
-            kept.some(
-              haplotype =>
-                haplotype.sample === name.sample &&
-                haplotype.haplotype === name.haplotype,
-            ),
-        })
-        .catch((error: unknown) => {
-          throw nodeLimitError(error, nodeLimit, end - start) ?? error
-        })
+    const baseContext: number = this.getConf('context')
+    const [first] = pairs
+    const cut = (path: PathQuery, context: number) =>
+      db.getSubgraphs({
+        path,
+        start,
+        end,
+        context,
+        snarls: this.getConf('subgraphSnarls'),
+        haplotypes: 'all',
+        limit: nodeLimit,
+        signal: opts.signal,
+        keep: name => kept.has(haplotypePrefix(name)),
+      })
+    // a cut past the node limit for the wider context keeps the first one
+    const bridged = async (path: PathQuery) => {
+      const subgraphs = await cut(path, baseContext).catch((error: unknown) => {
+        throw nodeLimitError(error, nodeLimit, end - start) ?? error
+      })
+      const gap = widestWalkGap(subgraphs, kept)
+      const context = Math.ceil(gap / 2) + 2000
+      return gap > 0 && context > baseContext
+        ? cut(path, context).catch((error: unknown) => {
+            if (error instanceof SubgraphLimitError) {
+              return subgraphs
+            }
+            throw error
+          })
+        : subgraphs
+    }
     const subgraphs =
-      query && featureSide.length > 0 && mateSide.length > 0
+      query && first && answerable.length > 0
         ? await updateStatus(
-            `Reading ${queryAssemblyName} against ${targetAssemblyName}`,
+            pairs.length === 1
+              ? `Reading ${first.queryAssemblyName} against ${first.targetAssemblyName}`
+              : `Reading ${pairs.length} lane pairs`,
             opts.statusCallback,
-            () => cut(query),
+            () => bridged(query),
           )
         : []
     return subgraphs.flatMap(subgraph =>
-      featureSide.flatMap(target =>
-        mateSide.flatMap(mate =>
-          subgraph
-            .pairAlignments({ target, query: mate, bases: false })
-            .map(pair =>
-              pairFeature({
-                pair,
-                lane: queryAssemblyName,
-                mateLane: targetAssemblyName,
-              }),
-            ),
+      answerable.flatMap(({ pair, featureSide, mateSide }) =>
+        featureSide.flatMap(target =>
+          mateSide.flatMap(mate =>
+            subgraph
+              .pairAlignments({ target, query: mate, bases: false })
+              .map(alignment =>
+                pairFeature({
+                  pair: alignment,
+                  lane: pair.queryAssemblyName,
+                  mateLane: pair.targetAssemblyName,
+                }),
+              ),
+          ),
         ),
       ),
     )
@@ -574,10 +650,15 @@ export default class GbzBaseSyntenyAdapter extends ComparativeAdapterBase<GbzBas
       // the graph is indexed on its reference alone, so a window on a
       // haplotype lane has no answer: a lane pair is read inside the anchor's
       if (region.assemblyName === anchor) {
-        const features =
-          opts.queryAssemblyName === undefined
+        const features = opts.lanePairs?.length
+          ? await this.pairFeatures(region, opts.lanePairs, opts)
+          : opts.queryAssemblyName === undefined
             ? await this.anchorFeatures(region, opts)
-            : await this.pairFeatures(region, opts.queryAssemblyName, opts)
+            : await this.pairFeatures(
+                region,
+                [onePair(opts.queryAssemblyName, opts.targetAssemblyName)],
+                opts,
+              )
         for (const feature of features) {
           observer.next(feature)
         }

package/src/GbzBaseSyntenyAdapter/index.ts

@@ -17,11 +17,13 @@ export default function GbzBaseSyntenyAdapterF(pluginManager: PluginManager) {
         // adapter and offer its lane picker over the whole graph.
         // lanePairsOnAnchor: a window of the anchor answers any two lanes'
         // alignment to each other, so the display fetches each adjacent pair
-        // rather than composing it through the reference
+        // rather than composing it through the reference.
+        // lanePairBatches: every pair on a window comes from one cut
         adapterCapabilities: [
           'getSubgraph',
           'headerLanes',
           'lanePairsOnAnchor',
+          'lanePairBatches',
         ],
         adapterMetadata: {
           category: 'Synteny adapters',

package/src/version.ts

@@ -1 +1 @@
-export const version = '6.1.4'
+export const version = '6.2.0'