@gmod/gbz-base 2.2.0 → 2.4.0

package/src/subgraph.ts

@@ -11,6 +11,7 @@ import {
   isReverse,
   nodeId,
   nodeOrientation,
+  pathEndsAreCanonical,
   pathIsCanonical,
 } from './gbwt/node.ts'
 import { gfaHeaderLines, sha256Hex, subgraphName } from './graphName.ts'
@@ -54,7 +55,7 @@ export interface PathIdentity {
 
 interface PathInfo {
   path: number[]
-  positions: Pos[]
+  offsets: number[]
   len: number
   weight: number | undefined
   identity: PathIdentity | undefined
@@ -114,6 +115,24 @@ export interface SubgraphOptions {
   signal?: AbortSignal | undefined
 }
 
+export class SubgraphLimitError extends Error {
+  override name = 'SubgraphLimitError'
+  readonly limit: number
+  readonly windowBp: number | undefined
+  readonly walkedBp: number | undefined
+
+  constructor(limit: number, walk?: { windowBp: number; walkedBp: number }) {
+    super(
+      walk === undefined
+        ? `Subgraph size limit of ${limit} nodes exceeded`
+        : `Subgraph size limit of ${limit} nodes exceeded ${walk.walkedBp} bp into a ${walk.windowBp} bp window`,
+    )
+    this.limit = limit
+    this.windowBp = walk?.windowBp
+    this.walkedBp = walk?.walkedBp
+  }
+}
+
 function sideBefore(
   a: [number, number, NodeSide],
   b: [number, number, NodeSide],
@@ -178,26 +197,198 @@ function posKey(pos: Pos) {
   return `${pos.node}:${pos.offset}`
 }
 
+interface FragmentAlignment {
+  strand: '+' | '-'
+  refStart: number
+  refEnd: number
+  edits: Edit[]
+  weight: number | undefined
+  path: number[]
+  start: Pos
+  identity:
+    | {
+        pathHandle: number
+        name: PathName
+        hapStart: number
+        hapEnd: number
+        walkForward: boolean
+      }
+    | undefined
+}
+
+function joinable(a: FragmentAlignment, b: FragmentAlignment) {
+  const insertion = b.identity!.hapStart - a.identity!.hapEnd
+  const deletion =
+    a.strand === '+' ? b.refStart - a.refEnd : a.refStart - b.refEnd
+  return a.strand === b.strand && insertion >= 0 && deletion >= 0
+    ? { insertion, deletion }
+    : undefined
+}
+
+function joinPair(
+  a: FragmentAlignment,
+  b: FragmentAlignment,
+  gap: { insertion: number; deletion: number },
+): FragmentAlignment {
+  const [left, right] = a.strand === '+' ? [a, b] : [b, a]
+  const edits = left.edits.map(([op, len]): Edit => [op, len])
+  appendGap(edits, gap.insertion, gap.deletion)
+  for (const [op, len] of right.edits) {
+    appendEdit(edits, op, len)
+  }
+  const walkForward = a.identity!.walkForward
+  const [first, second] = walkForward ? [a, b] : [b, a]
+  return {
+    strand: a.strand,
+    refStart: left.refStart,
+    refEnd: right.refEnd,
+    edits,
+    weight: undefined,
+    path: [...first.path, ...second.path],
+    start: first.start,
+    identity: {
+      pathHandle: a.identity!.pathHandle,
+      name: a.identity!.name,
+      hapStart: a.identity!.hapStart,
+      hapEnd: b.identity!.hapEnd,
+      walkForward,
+    },
+  }
+}
+
+function joinSiblings(fragments: FragmentAlignment[]) {
+  if (fragments.some(f => f.weight !== undefined)) {
+    return fragments
+  }
+  const byPath = new Map<number, number[]>()
+  fragments.forEach((fragment, index) => {
+    if (fragment.identity) {
+      const siblings = byPath.get(fragment.identity.pathHandle)
+      if (siblings) {
+        siblings.push(index)
+      } else {
+        byPath.set(fragment.identity.pathHandle, [index])
+      }
+    }
+  })
+  const joined = new Map<number, FragmentAlignment>()
+  const consumed = new Set<number>()
+  for (const siblings of byPath.values()) {
+    siblings.sort(
+      (x, y) =>
+        fragments[x]!.identity!.hapStart - fragments[y]!.identity!.hapStart,
+    )
+    let head = siblings[0]!
+    let current = fragments[head]!
+    for (const index of siblings.slice(1)) {
+      const next = fragments[index]!
+      const gap = joinable(current, next)
+      if (gap) {
+        current = joinPair(current, next, gap)
+        consumed.add(index)
+      } else {
+        joined.set(head, current)
+        head = index
+        current = next
+      }
+    }
+    joined.set(head, current)
+  }
+  return fragments.flatMap((fragment, index) =>
+    consumed.has(index) ? [] : [joined.get(index) ?? fragment],
+  )
+}
+
+function pathPosition(info: PathInfo, k: number): Pos {
+  return { node: info.path[k]!, offset: info.offsets[k]! }
+}
+
+const SCAN_GAP = 4096
+
+function handleRuns(sortedHandles: number[]) {
+  const runs: [number, number][] = []
+  for (const handle of sortedHandles) {
+    const last = runs[runs.length - 1]
+    if (last && handle - last[1] <= SCAN_GAP) {
+      last[1] = handle
+    } else {
+      runs.push([handle, handle])
+    }
+  }
+  return runs
+}
+
 interface Anchor {
   pathHandle: number
   orientation: Orientation
   base: number
 }
 
+export type ChainEnd =
+  | 'in-fragment sample'
+  | 'identified sibling'
+  | 'out-of-window sample'
+  | 'bound'
+  | 'endmarker'
+  | 'cycle'
+
+export interface ChainRecord {
+  fragments: number
+  steps: number
+  seeks: number
+  reentries: number
+  twinLandings: number
+  end: ChainEnd
+  pathHandle: number | undefined
+}
+
+export interface IdentificationStats {
+  interval: number
+  scans: [number, number][]
+  windowSamples: number
+  fragmentLengths: number[]
+  companionSeeks: number
+  companionMisses: number
+  graphLookups: number
+  graphFetches: number
+  chains: ChainRecord[]
+}
+
+interface SubgraphStats {
+  orderedAlignments: number
+  lcsAlignments: number
+  identificationSteps: number
+  identificationFetches: number
+  identification: IdentificationStats
+}
+
 export class Subgraph {
   private records = new Map<number, GbzRecord>()
   private paths: PathInfo[] = []
+  private twinStarts = new Set<string>()
   private refId: number | undefined
   private refPath: PathName | undefined
   private refHandle: number | undefined
   private refInterval: [number, number] | undefined
   private refIndexCache: Map<number, number[]> | undefined
   private refPrefixCache: number[] | undefined
-  readonly stats = {
+  private walkedBp: number | undefined
+  readonly stats: SubgraphStats = {
     orderedAlignments: 0,
     lcsAlignments: 0,
     identificationSteps: 0,
     identificationFetches: 0,
+    identification: {
+      interval: 0,
+      scans: [],
+      windowSamples: 0,
+      fragmentLengths: [],
+      companionSeeks: 0,
+      companionMisses: 0,
+      graphLookups: 0,
+      graphFetches: 0,
+      chains: [],
+    },
   }
 
   private db: GBZBase
@@ -251,7 +442,7 @@ export class Subgraph {
   private async addNode(id: number) {
     this.signal?.throwIfAborted()
     if (this.limit !== undefined && this.nodeCount >= this.limit) {
-      throw new Error(`Subgraph size limit of ${this.limit} nodes exceeded`)
+      throw new SubgraphLimitError(this.limit)
     }
     const forward = await this.db.getRecord(encodeNode(id, 'forward'))
     const reverse = await this.db.getRecord(encodeNode(id, 'reverse'))
@@ -270,6 +461,7 @@ export class Subgraph {
 
   private clearPaths() {
     this.paths = []
+    this.twinStarts.clear()
     this.refId = undefined
     this.refPath = undefined
     this.refHandle = undefined
@@ -350,10 +542,44 @@ export class Subgraph {
     return this.insertContext(active, context)
   }
 
+  async prefetchReferenceWalk(reference: ReferencePath, len: number) {
+    const last = await this.db.indexedPosition(
+      reference.handle,
+      reference.position.seqOffset + len,
+    )
+    if (last) {
+      const a = reference.position.handle
+      const b = last.pos.node
+      await this.db.prefetchRecords(Math.min(a, b), Math.max(a, b) + 1)
+    }
+  }
+
   async aroundInterval(start: PathPosition, len: number, context: number) {
     if (len === 0) {
       throw new Error('Interval length must be greater than 0')
     }
+    this.walkedBp = 0
+    try {
+      return await this.walkInterval(start, len, context)
+    } catch (error) {
+      throw error instanceof SubgraphLimitError && error.windowBp === undefined
+        ? new SubgraphLimitError(error.limit, {
+            windowBp: len,
+            walkedBp: this.walkedBp,
+          })
+        : error
+    }
+  }
+
+  get referenceWalkedBp() {
+    return this.walkedBp
+  }
+
+  private async walkInterval(
+    start: PathPosition,
+    len: number,
+    context: number,
+  ) {
     let pos: Pos = { node: start.handle, offset: start.gbwtOffset }
     let offset = start.nodeOffset
     let remaining = len
@@ -361,6 +587,7 @@ export class Subgraph {
     for (;;) {
       const id = nodeId(pos.node)
       const orientation = nodeOrientation(pos.node)
+      this.walkedBp = len - remaining
       await this.ensureNode(id)
       const record = this.record(pos.node)
       if (offset >= record.sequenceLen) {
@@ -389,6 +616,7 @@ export class Subgraph {
       offset = 0
       remaining -= distanceToNext
     }
+    this.walkedBp = len
     return this.insertContext(active, context)
   }
 
@@ -602,69 +830,133 @@ export class Subgraph {
     this.refPath = reference?.name
     this.refHandle = reference?.handle
     const handles = this.sortedHandles()
-    const successors = new Map<
-      number,
-      { nodes: Int32Array; offsets: Int32Array; hasPredecessor: Uint8Array }
-    >()
-    for (const handle of handles) {
-      const { nodes, offsets } = this.record(handle).gbwt().decompressArrays()
-      successors.set(handle, {
-        nodes,
+    const count = handles.length
+    const indexOf = new Map<number, number>()
+    handles.forEach((handle, i) => indexOf.set(handle, i))
+    const nextIndex: Int32Array[] = []
+    const nextOffset: Int32Array[] = []
+    const hasPredecessor: Uint8Array[] = []
+    const seqLen = new Int32Array(count)
+    for (let i = 0; i < count; i++) {
+      const record = this.record(handles[i]!)
+      const { nodes, offsets } = record.gbwt().decompressArrays()
+      seqLen[i] = record.sequenceLen
+      nextIndex.push(nodes)
+      nextOffset.push(offsets)
+      hasPredecessor.push(new Uint8Array(nodes.length))
+    }
+    for (let i = 0; i < count; i++) {
+      const nodes = nextIndex[i]!
+      const offsets = nextOffset[i]!
+      for (let k = 0; k < nodes.length; k++) {
+        const j = indexOf.get(nodes[k]!)
+        if (j === undefined) {
+          nodes[k] = -1
+        } else {
+          nodes[k] = j
+          hasPredecessor[j]![offsets[k]!] = 1
+        }
+      }
+    }
+    const refIndex =
+      refPos === undefined ? undefined : indexOf.get(refPos.handle)
+    const refGbwtOffset = refPos?.gbwtOffset
+    let refOffset: number | undefined
+    const walk = (i: number, offset: number, path: number[] | undefined) => {
+      const offsets: number[] = []
+      let steps = 0
+      let len = 0
+      let refAt = -1
+      let cur = i
+      let off = offset
+      for (;;) {
+        if (cur === refIndex && off === refGbwtOffset) {
+          refAt = steps
+        }
+        if (path) {
+          path.push(handles[cur]!)
+          offsets.push(off)
+        }
+        steps += 1
+        len += seqLen[cur]!
+        const next = nextIndex[cur]![off]!
+        if (next < 0) {
+          break
+        }
+        off = nextOffset[cur]![off]!
+        cur = next
+      }
+      return { offsets, len, refAt, last: cur }
+    }
+    const keep = (
+      path: number[],
+      offsets: number[],
+      len: number,
+      refAt: number,
+    ) => {
+      if (refAt >= 0) {
+        this.refId = this.paths.length
+        refOffset = refAt
+      }
+      this.paths.push({
+        path,
         offsets,
-        hasPredecessor: new Uint8Array(nodes.length),
+        len,
+        weight: undefined,
+        identity: undefined,
       })
     }
-    for (const handle of handles) {
-      const { nodes, offsets } = successors.get(handle)!
-      for (let i = 0; i < nodes.length; i++) {
-        const entry = successors.get(nodes[i]!)
-        if (entry) {
-          entry.hasPredecessor[offsets[i]!] = 1
+    const twinsExpected = new Int32Array(count)
+    const refMayStartReversed =
+      refIndex !== undefined && isReverse(handles[refIndex]!)
+    for (let i = 0; i < count; i++) {
+      const first = handles[i]!
+      if (!isReverse(first)) {
+        const starts = hasPredecessor[i]!
+        for (let offset = 0; offset < starts.length; offset++) {
+          if (starts[offset] === 0) {
+            const path: number[] = []
+            const { offsets, len, refAt, last } = walk(i, offset, path)
+            const lastHandle = handles[last]!
+            if (refAt >= 0 || pathEndsAreCanonical(first, lastHandle)) {
+              keep(path, offsets, len, refAt)
+              if (!isReverse(lastHandle)) {
+                const twinRecord = indexOf.get(flipNode(lastHandle))!
+                twinsExpected[twinRecord] = twinsExpected[twinRecord]! + 1
+              }
+            } else {
+              this.twinStarts.add(posKey({ node: first, offset }))
+            }
+          }
         }
       }
     }
-    let refOffset: number | undefined
-    for (const handle of handles) {
-      const entries = successors.get(handle)!
-      for (let offset = 0; offset < entries.nodes.length; offset++) {
-        if (entries.hasPredecessor[offset] === 0) {
-          let currNode: number | undefined = handle
-          let currOffset = offset
-          let isRef = false
-          const path: number[] = []
-          const positions: Pos[] = []
-          let len = 0
-          while (currNode !== undefined) {
+    for (let i = 0; i < count; i++) {
+      const first = handles[i]!
+      if (isReverse(first)) {
+        const starts = hasPredecessor[i]!
+        let startCount = 0
+        for (const flag of starts) {
+          if (flag === 0) {
+            startCount += 1
+          }
+        }
+        const allTwins = !refMayStartReversed && startCount === twinsExpected[i]
+        for (let offset = 0; offset < starts.length; offset++) {
+          if (starts[offset] === 0) {
+            const bare = allTwins ? undefined : walk(i, offset, undefined)
             if (
-              currNode === refPos?.handle &&
-              currOffset === refPos.gbwtOffset
+              bare &&
+              (bare.refAt >= 0 ||
+                pathEndsAreCanonical(first, handles[bare.last]))
             ) {
-              this.refId = this.paths.length
-              refOffset = path.length
-              isRef = true
-            }
-            path.push(currNode)
-            positions.push({ node: currNode, offset: currOffset })
-            len += this.record(currNode).sequenceLen
-            const step = successors.get(currNode)!
-            const nextNode: number = step.nodes[currOffset]!
-            const nextOffset: number = step.offsets[currOffset]!
-            if (nextNode !== ENDMARKER && successors.has(nextNode)) {
-              currNode = nextNode
-              currOffset = nextOffset
+              const path: number[] = []
+              const { offsets, len, refAt } = walk(i, offset, path)
+              keep(path, offsets, len, refAt)
             } else {
-              currNode = undefined
+              this.twinStarts.add(posKey({ node: first, offset }))
             }
           }
-          if (isRef || pathIsCanonical(path)) {
-            this.paths.push({
-              path,
-              positions,
-              len,
-              weight: undefined,
-              identity: undefined,
-            })
-          }
         }
       }
     }
@@ -720,6 +1012,33 @@ export class Subgraph {
     this.refId = refId
   }
 
+  // Narrows an identified subgraph to the reference walk and the named walks
+  // `wanted` accepts, and drops every node only the discarded walks visited,
+  // so a cut for a chosen set draws that set's private sequence and nothing
+  // else's. Unresolved walks are discarded with the rest.
+  keepHaplotypes(wanted: (name: PathName) => boolean) {
+    const refInfo =
+      this.refId === undefined ? undefined : this.paths[this.refId]
+    const kept = this.paths.filter(
+      (info, index) =>
+        index === this.refId ||
+        (info.identity !== undefined && wanted(info.identity.name)),
+    )
+    const visited = new Set<number>()
+    for (const info of kept) {
+      for (const handle of info.path) {
+        visited.add(nodeId(handle))
+      }
+    }
+    for (const handle of [...this.records.keys()]) {
+      if (!visited.has(nodeId(handle))) {
+        this.records.delete(handle)
+      }
+    }
+    this.paths = kept
+    this.refId = refInfo === undefined ? undefined : kept.indexOf(refInfo)
+  }
+
   async identifyPaths() {
     if (!this.db.hasHaplotypeIndex) {
       throw new Error(
@@ -727,35 +1046,65 @@ export class Subgraph {
       )
     }
     const interval = (await this.db.haplotypeSampleInterval()) ?? 4096
-    const handles = this.sortedHandles()
-    const minHandle = handles[0]
-    const maxHandle = handles[handles.length - 1]
-    if (minHandle === undefined || maxHandle === undefined) {
+    const runs = handleRuns(this.sortedHandles())
+    if (runs.length === 0) {
       return
     }
     const samples = new Map<string, HaplotypeSample>()
-    for (const sample of await this.db.haplotypeSamplesInRange(
-      minHandle,
-      maxHandle,
-    )) {
-      samples.set(posKey(sample), sample)
+    for (const [first, last] of runs) {
+      for (const sample of await this.db.haplotypeSamplesInRange(first, last)) {
+        samples.set(posKey(sample), sample)
+      }
+    }
+    const scanned = (handle: number) => {
+      let lo = 0
+      let hi = runs.length - 1
+      while (lo < hi) {
+        const mid = (lo + hi + 1) >> 1
+        if (runs[mid]![0] <= handle) {
+          lo = mid
+        } else {
+          hi = mid - 1
+        }
+      }
+      const run = runs[lo]!
+      return run[0] <= handle && handle <= run[1]
     }
     const starts = new Map<string, number>()
     this.paths.forEach((info, index) => {
-      const first = info.positions[0]
-      if (first && index !== this.refId) {
-        starts.set(posKey(first), index)
+      if (info.path.length > 0 && index !== this.refId) {
+        starts.set(posKey(pathPosition(info, 0)), index)
       }
     })
-    const recordAt = this.recordReader(() => {
+    const identification = this.stats.identification
+    identification.interval = interval
+    identification.scans = runs
+    identification.windowSamples = samples.size
+    this.paths.forEach((info, index) => {
+      if (index !== this.refId) {
+        identification.fragmentLengths.push(info.len)
+      }
+    })
+    const readRecord = this.recordReader(() => {
       this.stats.identificationFetches += 1
+      identification.graphFetches += 1
     })
-    const sampleAt = async (pos: Pos) => {
-      if (pos.node >= minHandle && pos.node <= maxHandle) {
+    const recordAt = (handle: number) => {
+      identification.graphLookups += 1
+      return readRecord(handle)
+    }
+    const sampleAt = async (pos: Pos, chain: ChainRecord) => {
+      if (scanned(pos.node)) {
         return samples.get(posKey(pos))
       }
       this.stats.identificationFetches += 1
-      return this.db.haplotypeSampleAt(pos.node, pos.offset)
+      identification.companionSeeks += 1
+      chain.seeks += 1
+      const sample = await this.db.haplotypeSampleAt(pos.node, pos.offset)
+      if (!sample) {
+        identification.companionMisses += 1
+      }
+      return sample
     }
     const names = new Map<number, PathName>()
     const nameOf = async (pathHandle: number) => {
@@ -809,6 +1158,16 @@ export class Subgraph {
       }
       const chain: { index: number; startBp: number }[] = []
       const visited = new Set<number>()
+      const record: ChainRecord = {
+        fragments: 0,
+        steps: 0,
+        seeks: 0,
+        reentries: 0,
+        twinLandings: 0,
+        end: 'endmarker',
+        pathHandle: undefined,
+      }
+      identification.chains.push(record)
       let anchor: Anchor | undefined
       let counter = 0
       let current: number | undefined = start
@@ -817,13 +1176,16 @@ export class Subgraph {
         this.signal?.throwIfAborted()
         if (current !== undefined) {
           if (visited.has(current)) {
+            record.end = 'cycle'
             break
           }
           visited.add(current)
           const info = this.paths[current]!
           chain.push({ index: current, startBp: counter })
+          record.fragments += 1
           let bp = counter
-          for (const position of info.positions) {
+          for (let k = 0; k < info.path.length; k++) {
+            const position = pathPosition(info, k)
             const sample = samples.get(posKey(position))
             const nodeLen = this.record(position.node).sequenceLen
             if (sample) {
@@ -834,42 +1196,56 @@ export class Subgraph {
           }
           counter += info.len
           if (anchor) {
+            record.end = 'in-fragment sample'
             break
           }
-          const last = info.positions[info.positions.length - 1]!
+          const last = pathPosition(info, info.path.length - 1)
           pos = this.record(last.node).gbwt().lf(last.offset)
           current = undefined
         }
         if (pos === undefined || pos.node === ENDMARKER) {
+          record.end = 'endmarker'
           break
         }
-        const known = starts.get(posKey(pos))
+        const key = posKey(pos)
+        const known = starts.get(key)
         if (known !== undefined) {
           const identity = this.paths[known]!.identity
           if (identity) {
             anchor = anchorFromIdentity(identity, counter)
+            record.end = 'identified sibling'
             break
           }
           current = known
           continue
         }
-        const sample = await sampleAt(pos)
-        const record = await recordAt(pos.node)
+        if (this.records.has(pos.node)) {
+          record.reentries += 1
+        }
+        if (this.twinStarts.has(key)) {
+          record.twinLandings += 1
+        }
+        const sample = await sampleAt(pos, record)
+        const node = await recordAt(pos.node)
         if (sample) {
-          anchor = anchorFromSample(sample, counter, record.sequenceLen)
+          anchor = anchorFromSample(sample, counter, node.sequenceLen)
+          record.end = 'out-of-window sample'
           break
         }
         this.stats.identificationSteps += 1
+        record.steps += 1
         if (
           counter - (chain[chain.length - 1] as { startBp: number }).startBp >
-          4 * interval + 4 * record.sequenceLen
+          4 * interval + 4 * node.sequenceLen
         ) {
+          record.end = 'bound'
           break
         }
-        counter += record.sequenceLen
-        pos = record.gbwt().lf(pos.offset)
+        counter += node.sequenceLen
+        pos = node.gbwt().lf(pos.offset)
       }
       if (anchor) {
+        record.pathHandle = anchor.pathHandle
         const name = await nameOf(anchor.pathHandle)
         for (const { index, startBp } of chain) {
           const info = this.paths[index]!
@@ -1020,28 +1396,7 @@ export class Subgraph {
       suffix = refLen - prefix
     }
     appendEdit(edits, 'M', prefix)
-    const pathMiddle = pathLen - prefix - suffix
-    const refMiddle = refLen - prefix - suffix
-    if (pathMiddle === 0) {
-      appendEdit(edits, 'D', refMiddle)
-    } else if (refMiddle === 0) {
-      appendEdit(edits, 'I', pathMiddle)
-    } else {
-      const mismatch = Math.min(pathMiddle, refMiddle)
-      const mismatchIndel =
-        4 * mismatch +
-        gapPenalty(pathMiddle - mismatch) +
-        gapPenalty(refMiddle - mismatch)
-      const insertionDeletion = gapPenalty(pathMiddle) + gapPenalty(refMiddle)
-      if (mismatchIndel <= insertionDeletion) {
-        appendEdit(edits, 'M', mismatch)
-        appendEdit(edits, 'I', pathMiddle - mismatch)
-        appendEdit(edits, 'D', refMiddle - mismatch)
-      } else {
-        appendEdit(edits, 'I', pathMiddle)
-        appendEdit(edits, 'D', refMiddle)
-      }
-    }
+    appendGap(edits, pathLen - prefix - suffix, refLen - prefix - suffix)
     appendEdit(edits, 'M', suffix)
   }
 
@@ -1067,22 +1422,37 @@ export class Subgraph {
       ordered ??
       weightedLcs(path, ref, handle => this.record(handle).sequenceLen)[0]
     const edits: Edit[] = []
+    const refPrefix = this.refPrefix(ref)
+    const alignGap = (
+      pathFrom: number,
+      pathTo: number,
+      refFrom: number,
+      refTo: number,
+    ) => {
+      if (pathFrom === pathTo) {
+        appendEdit(edits, 'D', refPrefix[refTo]! - refPrefix[refFrom]!)
+      } else if (refFrom === refTo) {
+        appendEdit(edits, 'I', this.pathLen(path.slice(pathFrom, pathTo)))
+      } else {
+        this.align(
+          path.slice(pathFrom, pathTo),
+          ref.slice(refFrom, refTo),
+          edits,
+        )
+      }
+    }
     let matched = 0
     let pathOffset = 0
     let refOffset = 0
     for (const [nextPath, nextRef] of lcs) {
-      this.align(
-        path.slice(pathOffset, nextPath),
-        ref.slice(refOffset, nextRef),
-        edits,
-      )
+      alignGap(pathOffset, nextPath, refOffset, nextRef)
       const nodeLen = this.record(path[nextPath]!).sequenceLen
       appendEdit(edits, 'M', nodeLen)
       matched += nodeLen
       pathOffset = nextPath + 1
       refOffset = nextRef + 1
     }
-    this.align(path.slice(pathOffset), ref.slice(refOffset), edits)
+    alignGap(pathOffset, path.length, refOffset, ref.length)
     return { edits, matched }
   }
 
@@ -1132,7 +1502,7 @@ export class Subgraph {
     }
     const ref = this.paths[this.refId]!.path
     const refTotal = this.refPrefix(ref)[ref.length]!
-    const result: HaplotypeAlignment[] = []
+    const fragments: FragmentAlignment[] = []
     this.paths.forEach((info, index) => {
       if (index === this.refId) {
         return
@@ -1154,38 +1524,44 @@ export class Subgraph {
       const alongReference = identity
         ? (identity.orientation === 'forward') !== flipped
         : !flipped
-      const span: AlignmentSpan = {
+      fragments.push({
         strand: alongReference ? '+' : '-',
         refStart: reference.start + leading,
         refEnd: reference.start + refTotal - trailing,
-        cigar: edits
-          .slice(first, last)
-          .map(([op, len]) => `${len}${op}`)
-          .join(''),
+        edits: edits.slice(first, last),
         weight: info.weight,
         path: info.path,
-        start: info.positions[0]!,
-      }
-      if (identity) {
-        const hapStart = identity.name.fragment + identity.hapStart
-        const hapEnd = identity.name.fragment + identity.hapEnd
-        result.push({
-          ...span,
-          resolved: true,
-          name: identity.name,
-          label: formatPathName(
-            { ...identity.name, fragment: hapStart },
-            hapEnd,
-          ),
-          pathHandle: identity.pathHandle,
-          hapStart,
-          hapEnd,
-        })
-      } else {
-        result.push({ ...span, resolved: false })
-      }
+        start: pathPosition(info, 0),
+        identity:
+          identity === undefined
+            ? undefined
+            : {
+                pathHandle: identity.pathHandle,
+                name: identity.name,
+                hapStart: identity.name.fragment + identity.hapStart,
+                hapEnd: identity.name.fragment + identity.hapEnd,
+                walkForward: identity.orientation === 'forward',
+              },
+      })
+    })
+    return joinSiblings(fragments).map(fragment => {
+      const { edits, identity, ...rest } = fragment
+      const span: AlignmentSpan = { ...rest, cigar: cigarOf(edits) }
+      return identity
+        ? {
+            ...span,
+            resolved: true,
+            name: identity.name,
+            label: formatPathName(
+              { ...identity.name, fragment: identity.hapStart },
+              identity.hapEnd,
+            ),
+            pathHandle: identity.pathHandle,
+            hapStart: identity.hapStart,
+            hapEnd: identity.hapEnd,
+          }
+        : { ...span, resolved: false }
     })
-    return result
   }
 
   private canonicalEdges(id: number) {
@@ -1254,11 +1630,12 @@ export class Subgraph {
     }
     const walk = (
       info: PathInfo,
+      identity: PathIdentity | undefined,
       name: PathName,
       end: number,
       cigarString: string | undefined,
     ) => {
-      const steps = info.path
+      const steps = haplotypeOrderedPath(info, identity)
         .map(handle => `${isReverse(handle) ? '<' : '>'}${nodeId(handle)}`)
         .join('')
       const weight = info.weight === undefined ? '' : `\tWT:i:${info.weight}`
@@ -1270,6 +1647,7 @@ export class Subgraph {
       lines.push(
         walk(
           this.paths[this.refId]!,
+          undefined,
           {
             ...this.refPath,
             fragment: this.refPath.fragment + this.refInterval[0],
@@ -1288,6 +1666,7 @@ export class Subgraph {
           resolved
             ? walk(
                 info,
+                resolved,
                 {
                   ...resolved.name,
                   fragment: resolved.name.fragment + resolved.hapStart,
@@ -1297,6 +1676,7 @@ export class Subgraph {
               )
             : walk(
                 info,
+                undefined,
                 { sample: 'unknown', contig, haplotype, fragment: 0 },
                 info.len,
                 cigarString,
@@ -1341,6 +1721,7 @@ export class Subgraph {
       paths.push(
         jsonPath(
           info,
+          undefined,
           formatPathName(name, this.refPath.fragment + this.refInterval[1]),
           undefined,
         ),
@@ -1365,7 +1746,12 @@ export class Subgraph {
             info.len,
           )
       paths.push(
-        jsonPath(info, name, cigar ? this.alignToRef(index) : undefined),
+        jsonPath(
+          info,
+          resolved,
+          name,
+          cigar ? this.alignToRef(index) : undefined,
+        ),
       )
       haplotype += 1
     })
@@ -1373,8 +1759,23 @@ export class Subgraph {
   }
 }
 
+// A named walk lists its steps in the haplotype's own direction, as the W line
+// spec and the start..end coordinates beside it require. extractPaths keeps
+// whichever twin of a walk is canonical, which is a property of the handles
+// and not of the haplotype, so the kept walk runs against the haplotype for
+// about half of them; identification records which.
+function haplotypeOrderedPath(
+  info: PathInfo,
+  identity: PathIdentity | undefined,
+) {
+  return identity?.orientation === 'reverse'
+    ? info.path.map(handle => flipNode(handle)).reverse()
+    : info.path
+}
+
 function jsonPath(
   info: PathInfo,
+  identity: PathIdentity | undefined,
   name: string,
   cigar: string | undefined,
 ): SubgraphPath {
@@ -1382,7 +1783,7 @@ function jsonPath(
     name,
     ...(info.weight === undefined ? {} : { weight: info.weight }),
     ...(cigar === undefined ? {} : { cigar }),
-    path: info.path.map(handle => ({
+    path: haplotypeOrderedPath(info, identity).map(handle => ({
       id: String(nodeId(handle)),
       is_reverse: isReverse(handle),
     })),
@@ -1416,3 +1817,30 @@ function appendEdit(edits: Edit[], op: EditOp, len: number) {
 function gapPenalty(len: number) {
   return len === 0 ? 0 : 6 + (len - 1)
 }
+
+function appendGap(edits: Edit[], pathMiddle: number, refMiddle: number) {
+  if (pathMiddle === 0) {
+    appendEdit(edits, 'D', refMiddle)
+  } else if (refMiddle === 0) {
+    appendEdit(edits, 'I', pathMiddle)
+  } else {
+    const mismatch = Math.min(pathMiddle, refMiddle)
+    const mismatchIndel =
+      4 * mismatch +
+      gapPenalty(pathMiddle - mismatch) +
+      gapPenalty(refMiddle - mismatch)
+    const insertionDeletion = gapPenalty(pathMiddle) + gapPenalty(refMiddle)
+    if (mismatchIndel <= insertionDeletion) {
+      appendEdit(edits, 'M', mismatch)
+      appendEdit(edits, 'I', pathMiddle - mismatch)
+      appendEdit(edits, 'D', refMiddle - mismatch)
+    } else {
+      appendEdit(edits, 'I', pathMiddle)
+      appendEdit(edits, 'D', refMiddle)
+    }
+  }
+}
+
+function cigarOf(edits: Edit[]) {
+  return edits.map(([op, len]) => `${len}${op}`).join('')
+}