@gmod/bam 7.8.1 → 7.9.0

package/src/util.ts

@@ -29,6 +29,16 @@ export interface BaseOpts {
   onProgress?: (bytesDownloaded: number, totalBytes?: number) => void
 }
 
+/**
+ * Merge and order the chunks a query resolved to.
+ *
+ * Takes ownership of `chunks`: with no `lowest` to pre-filter against it sorts
+ * the array IN PLACE rather than copying. Every caller builds a fresh array to
+ * hand over, which is what makes that safe — passing something you still hold,
+ * or anything reachable from the index's per-refId cache, would reorder it
+ * underneath you. (The Chunk objects themselves are never mutated; a merged
+ * span produces a new instance.)
+ */
 export function optimizeChunks(chunks: Chunk[], lowest?: OffsetCoords) {
   const n = chunks.length
   if (n === 0) {
@@ -74,6 +84,14 @@ export function optimizeChunks(chunks: Chunk[], lowest?: OffsetCoords) {
     const chunkMaxBlock = chunk.maxv.blockPosition
     // Merge if chunks are close enough: small gap between them, and the
     // combined span is bounded so we don't grow a single chunk indefinitely.
+    //
+    // Both constants were swept before being left alone — see ADR 0011.
+    // Dropping merging entirely, on the theory that a caller with a coalescing
+    // range cache makes it redundant, is much worse: a bare consumer goes from
+    // 6 reads to 95-378 on the same queries AND downloads MORE, because every
+    // small chunk pays its own tail padding where a merged one amortizes it.
+    // Raising the gap is worse too, partly because it blunts the early stop in
+    // _fetchChunkFeatures. Records are identical either way; only the I/O moves.
     if (
       chunkMinBlock - lastMaxBlock < 65000 &&
       chunkMaxBlock - lastMinBlock < 5000000
@@ -177,19 +195,14 @@ export function clampChunkEnds(
   if (chunks.length === 0) {
     return
   }
-  // A plain array, sized once and filled by index. Not a Float64Array: this
-  // runs once per reference, and an assembly with tens of thousands of unplaced
-  // scaffolds (cho.bam.bai has 28751 references) pays the allocation that many
-  // times over, where each individual boundary list is a handful of entries.
-  // The small-allocation cost dominates the faster typed sort by a wide margin
-  // at that shape. Filling by index still avoids the intermediate array that
-  // mapping the linear index to block positions used to build.
-  // Pre-sized and filled by index. Measured against both alternatives on five
-  // real .bai shapes (min of 21, interleaved, sign-stable over 3 runs):
-  // building with push instead is 5-8% slower here, and a Float64Array is
-  // faster to sort but allocates per reference, which costs 1.7x on an
-  // assembly with 28751 scaffolds. Filling by index also avoids the
-  // intermediate array that mapping the linear index used to build.
+  // A plain array, pre-sized and filled by index. Measured against both
+  // alternatives on five real .bai shapes (min of 21, interleaved, sign-stable
+  // over 3 runs): building with push instead is 5-8% slower, and a
+  // Float64Array is faster to sort but allocates per reference, which costs
+  // 1.7x on an assembly with tens of thousands of unplaced scaffolds
+  // (cho.bam.bai has 28751 references, each with a handful of boundaries).
+  // Filling by index also avoids the intermediate array that mapping the
+  // linear index to block positions used to build.
   const boundaries = new Array<number>(
     extraBoundaries.length + chunks.length * 2,
   )
@@ -361,10 +374,23 @@ interface Positioned {
   end: number
 }
 
+// The end htslib's bam_endpos() reports: a record consuming no reference —
+// an unmapped mate placed at its mate's coordinate, or an empty CIGAR — still
+// covers one base rather than none, so it can be found by a query on the base
+// it sits at.
+function endpos(r: Positioned) {
+  return r.end > r.start ? r.end : r.start + 1
+}
+
 // Append records overlapping [min, max) on `chrId` into `out` (or a fresh
 // array if omitted). Records are assumed coordinate-sorted (by ref_id, then
 // start), so we stop scanning once we pass `max` within `chrId` or move past
 // `chrId` entirely. Returns the populated array.
+//
+// `end` is exclusive, so overlap is `end > min`, not `end >= min`: a read
+// finishing exactly where the query begins shares no base with it. samtools
+// agrees — `samtools view f.bam chr:124001-124300` omits a 150M read at
+// 1-based POS 123851, which ends at 124000.
 export function appendInRange<T extends Positioned>(
   records: T[],
   chrId: number,
@@ -377,7 +403,7 @@ export function appendInRange<T extends Positioned>(
     if (r.ref_id === chrId) {
       if (r.start >= max) {
         break
-      } else if (r.end >= min) {
+      } else if (endpos(r) > min) {
         out.push(r)
       }
     } else if (r.ref_id > chrId) {