@gmod/bam 8.5.1 → 8.6.0

package/src/record.ts

@@ -1,9 +1,15 @@
 import { CIGAR_REF_SKIP, CIGAR_SOFT_CLIP } from './cigar.ts'
 import Constants from './constants.ts'
+import { forEachMismatchNumeric } from './mismatches.ts'
+import { referenceCovers } from './reference.ts'
+import { SEQRET_CODES, SEQRET_DECODER } from './seqAlphabet.ts'
 
-const SEQRET = '=ACMGRSVTWYHKDBN'
-const SEQRET_DECODER = SEQRET.split('')
-const SEQRET_CODES = Uint8Array.from(SEQRET, c => c.charCodeAt(0))
+import type {
+  Mismatch,
+  MismatchCallback,
+  MismatchOptions,
+} from './mismatches.ts'
+import type { PackedReference } from './reference.ts'
 
 // Both bases of a SEQ byte, precomputed for all 256 bytes so decoding advances a
 // byte at a time. Two forms because `seq` has two strategies (see below): packed
@@ -371,6 +377,7 @@ export default class BamRecord {
   private _cachedNumericCigar?: NumericCigar
   private _cachedNUMERIC_MD?: Uint8Array | null
   private _cachedSeqStart?: number
+  private _reference?: PackedReference
 
   // Positional rather than an options object, because every argument is
   // unpacked into a field immediately and nothing keeps the wrapper. The
@@ -938,6 +945,91 @@ export default class BamRecord {
     }
   }
 
+  /**
+   * Bind reference bases for this read to resolve its substitutions against,
+   * for a read with no MD tag. `BamFile` calls this for you when it was given a
+   * `fetchReferenceSequence`; call it yourself when you have the bases from
+   * somewhere else.
+   *
+   * **`ref` must cover the whole read**, and this throws if it does not. The
+   * reason is that records are cached and shared between queries (ADR 0006), so
+   * a binding that varied by query would make one query's reads answer out of
+   * another's region. A region covering the read is the same data whichever
+   * query fetched it, so binding it is safe; a partial one is not, and the
+   * per-call `forEachMismatch(cb, {ref})` is where that belongs.
+   */
+  setReference(ref: PackedReference | undefined) {
+    if (ref !== undefined && !referenceCovers(ref, this.start, this.end)) {
+      throw new Error(
+        `reference region ${ref.start}-${ref.start + ref.length} does not cover the record at ${this.start}-${this.end}. Records are shared between queries, so only a region covering the whole read can be bound to one; pass a partial region per call instead, as forEachMismatch(cb, {ref})`,
+      )
+    }
+    this._reference = ref
+  }
+
+  /** the region {@link setReference} bound, if any */
+  get reference() {
+    return this._reference
+  }
+
+  /**
+   * Report each difference between this read and the reference —
+   * substitutions, insertions, deletions, reference skips and clips — without
+   * allocating an object per difference. This is the intended way to read a
+   * record's differences; deriving them from `CIGAR` and `MD` yourself takes
+   * rather more of the format to interpret correctly (see {@link Mismatch}).
+   *
+   * Substitutions come from the MD tag when the read has one, and otherwise
+   * from comparing SEQ against reference bases — which have to come from
+   * {@link setReference}, `opts.ref`, or the file's `fetchReferenceSequence`.
+   * With neither MD nor reference, indels and clips are still reported in full
+   * and substitutions are not reported at all: nothing in the record says where
+   * they are.
+   *
+   * @param callback called as
+   *   `(code, refPos, length, bases, qual, refBaseCode, clipLength)`
+   * @param opts optional reference window to restrict to, and an optional
+   *   per-call reference region; see {@link MismatchOptions}
+   */
+  forEachMismatch(callback: MismatchCallback, opts?: MismatchOptions) {
+    forEachMismatchNumeric(
+      this.NUMERIC_CIGAR,
+      this.NUMERIC_SEQ,
+      this.seq_length,
+      this.NUMERIC_MD,
+      this.qual,
+      opts?.ref ?? this._reference,
+      this.start,
+      opts?.start ?? Number.NEGATIVE_INFINITY,
+      opts?.end ?? Number.POSITIVE_INFINITY,
+      callback,
+    )
+  }
+
+  /**
+   * The same differences {@link forEachMismatch} reports, as an array of
+   * {@link Mismatch} objects. Convenient; allocates one object per difference,
+   * so the callback form is the one to reach for on a hot path.
+   */
+  getMismatches(opts?: MismatchOptions) {
+    const out: Mismatch[] = []
+    this.forEachMismatch(
+      (code, refPos, length, bases, qual, refBaseCode, clipLength) => {
+        out.push({
+          code,
+          refPos,
+          length,
+          bases,
+          qual,
+          refBaseCode,
+          clipLength,
+        })
+      },
+      opts,
+    )
+    return out
+  }
+
   // Most public BamRecord fields are getters on the prototype, so
   // Object.keys(this) wouldn't include them — JSON.stringify needs an explicit
   // list. Returns the meaningful BAM-spec fields. Return type is widened so

package/src/reference.ts

@@ -0,0 +1,87 @@
+import { SEQRET } from './seqAlphabet.ts'
+
+/**
+ * A region of reference sequence in BAM's own 4-bit alphabet, so the mismatch
+ * walk can compare it against a read's already-packed `NUMERIC_SEQ` a byte —
+ * two bases — at a time, instead of unpacking a nibble and reading a string
+ * character per base. Only the rare byte that differs gets unpacked.
+ *
+ * Two packings, because a read's sequence parity and its reference parity need
+ * not agree: `even[i]` holds region bases (2i, 2i+1), `odd[i]` holds
+ * (2i-1, 2i). The walk picks whichever lines the reference pair up with the
+ * read's byte boundary. Together they cost one byte per base, the same as the
+ * region string they replace.
+ *
+ * Build one with {@link packReference}, per region rather than per read: a
+ * pileup's reads all resolve against the same region, and packing is the only
+ * per-base pass in the whole walk.
+ */
+export interface PackedReference {
+  /** 0-based reference coordinate of the first base */
+  start: number
+  /** length in bases, i.e. of the string this was packed from */
+  length: number
+  even: Uint8Array
+  odd: Uint8Array
+}
+
+// ASCII -> 4-bit code, case-insensitive. Anything outside the alphabet reads as
+// N, which mismatches every concrete base — what an unrecognized character does
+// when the comparison is done in ASCII.
+const NIBBLE_FROM_CHAR = new Uint8Array(256).fill(15)
+for (let i = 0; i < 16; i++) {
+  NIBBLE_FROM_CHAR[SEQRET.charCodeAt(i)] = i
+  NIBBLE_FROM_CHAR[SEQRET.charCodeAt(i) | 0x20] = i
+}
+
+/**
+ * The 4-bit codes back to ASCII, for reporting a mismatch's reference base.
+ * Always the uppercase spelling: packing is case-insensitive, so a soft-masked
+ * reference reports `A` where the raw string would have said `a`.
+ */
+export const CHAR_CODE_FROM_NIBBLE = new Uint8Array(16)
+for (let i = 0; i < 16; i++) {
+  CHAR_CODE_FROM_NIBBLE[i] = SEQRET.charCodeAt(i)
+}
+
+/**
+ * Pack a region of reference sequence for {@link PackedReference}.
+ *
+ * @param seq the reference bases, case-insensitive
+ * @param start the 0-based reference coordinate `seq[0]` sits at
+ */
+export function packReference(seq: string, start = 0): PackedReference {
+  const n = seq.length
+  const even = new Uint8Array((n >> 1) + 1)
+  const odd = new Uint8Array((n >> 1) + 1)
+  for (let i = 0; i < n; i++) {
+    const code = seq.charCodeAt(i)
+    const nibble = code < 256 ? NIBBLE_FROM_CHAR[code]! : 15
+    if (i & 1) {
+      even[i >> 1]! |= nibble
+      odd[(i + 1) >> 1] = nibble << 4
+    } else {
+      even[i >> 1] = nibble << 4
+      odd[i >> 1]! |= nibble
+    }
+  }
+  return { start, length: n, even, odd }
+}
+
+/**
+ * The single reference base at region-relative index `i`, for the ends of an
+ * odd-length run. Callers bound `i` to the region themselves — reading past the
+ * end would report a base the region does not have.
+ */
+export function referenceNibble(ref: PackedReference, i: number) {
+  return (ref.even[i >> 1]! >> ((1 - (i & 1)) << 2)) & 0xf
+}
+
+/** whether `ref` covers every base of the 0-based half-open span [start, end) */
+export function referenceCovers(
+  ref: PackedReference,
+  start: number,
+  end: number,
+) {
+  return ref.start <= start && ref.start + ref.length >= end
+}

package/src/seqAlphabet.ts

@@ -0,0 +1,10 @@
+// BAM's 4-bit sequence alphabet (SAM spec §4.2, `seq`): nibble value -> base.
+//
+// Shared rather than duplicated because three modules need it for three
+// different shapes — `record.ts` builds pair/quad tables on top of it to decode
+// whole reads, `reference.ts` inverts it to pack a reference the same way, and
+// `mismatches.ts` reads single bases out of it — and a copy that drifted would
+// silently mis-decode one of them.
+export const SEQRET = '=ACMGRSVTWYHKDBN'
+export const SEQRET_DECODER = SEQRET.split('')
+export const SEQRET_CODES = Uint8Array.from(SEQRET, c => c.charCodeAt(0))