@jbrowse/cigar-utils 4.1.14 → 5.0.0-beta.2

package/README.md

@@ -32,6 +32,43 @@ a caller may not have the assembly in hand; pass it when you do.
 
 [Source code](https://github.com/GMOD/jbrowse-components/blob/main/packages/cigar-utils/src/buildReadVsRefFeatures.ts)
 
+### coarseCigarOwnAxis
+
+The coarse CIGAR as a plain CIGAR over the row's own axis, for a walk that
+places mismatches by reference position: a run keeps only its own length, a run
+with no own length is the insertion it amounts to, and one with no mate length
+the deletion. Kept indels are exact, so they land where the fine tier's would.
+
+```js
+// type signature
+(s: string) => string
+```
+
+[Source code](https://github.com/GMOD/jbrowse-components/blob/main/packages/cigar-utils/src/coarseCigar.ts)
+
+### coarsenCigar
+
+Fold a CIGAR into a coarse CIGAR whose straight lines stay within `gap` of the
+alignment's own path. An indel longer than half the gap keeps its letter and
+length (D/N/I); a shorter one is absorbed into the match run around it, and a
+run whose two axes advanced by different amounts is written `<own>:<mate>M`, a
+square run `<n>M`. `=`/`X` count as M. `ownLen`/`mateLen` are the totals each
+axis consumed, for the caller to check against the row's coordinate columns.
+
+The bound: a run is closed before a folded indel would push its running skew
+(own minus mate) past half the gap, and no folded indel is longer than that, so
+inside a run the skew never exceeds half the gap and the line between the run's
+corners is never more than the gap off the path. That is what lets a reader
+interpolate within a run, and it costs a new run only where the two genomes'
+small indels are lopsided.
+
+```js
+// type signature
+(cigar: string, gap: number) => CoarsenedCigar
+```
+
+[Source code](https://github.com/GMOD/jbrowse-components/blob/main/packages/cigar-utils/src/coarseCigar.ts)
+
 ### featurizeSAEntries
 
 featurizeSA over pre-split entries (see splitSA). Lets a caller filter the
@@ -45,6 +82,18 @@ segments — without paying to split and rejoin the tag around the filter.
 
 [Source code](https://github.com/GMOD/jbrowse-components/blob/main/packages/cigar-utils/src/mismatchParser.ts)
 
+### flipCoarseCigar
+
+The coarse CIGAR seen from the other axis on the minus strand: swapped as
+`swapCoarseCigar` does, and in reverse op order. The twin of `flipCigar`.
+
+```js
+// type signature
+(s: string) => string
+```
+
+[Source code](https://github.com/GMOD/jbrowse-components/blob/main/packages/cigar-utils/src/coarseCigar.ts)
+
 ### getLength
 
 Length of the read sequence (sum of all ops except D/N).
@@ -152,6 +201,19 @@ single typed-array code path.
 
 [Source code](https://github.com/GMOD/jbrowse-components/blob/main/packages/cigar-utils/src/mismatchParser.ts)
 
+### parseCoarseCigar
+
+Parse a coarse CIGAR into the packed `(len << 4) | op` form
+`visitCigarRenderedSegments` walks. A square run packs as one `CIGAR_M` word; an
+unequal run as a `CIGAR_RUN` word pair, own axis first.
+
+```js
+// type signature
+(s: string) => Uint32Array<ArrayBuffer>
+```
+
+[Source code](https://github.com/GMOD/jbrowse-components/blob/main/packages/cigar-utils/src/coarseCigar.ts)
+
 ### splitSA
 
 The `;`-separated alignment records of an SA tag, empties dropped — the input
@@ -164,4 +226,17 @@ The `;`-separated alignment records of an SA tag, empties dropped — the input
 
 [Source code](https://github.com/GMOD/jbrowse-components/blob/main/packages/cigar-utils/src/mismatchParser.ts)
 
+### swapCoarseCigar
+
+The coarse CIGAR seen from the other axis on the plus strand: the two lengths of
+every run trade places and D<->I swap, op order untouched. The twin of
+`swapIndelCigar`.
+
+```js
+// type signature
+(s: string) => string
+```
+
+[Source code](https://github.com/GMOD/jbrowse-components/blob/main/packages/cigar-utils/src/coarseCigar.ts)
+
 <!-- API_DOCS_END -->

package/esm/cigarConstants.d.ts

@@ -9,3 +9,4 @@ export declare const CIGAR_EQ = 7;
 export declare const CIGAR_X = 8;
 export declare const CIGAR_M_EQ_MASK = 129;
 export declare const CIGAR_INDEL_MASK = 14;
+export declare const CIGAR_RUN = 9;

package/esm/cigarConstants.js

@@ -13,3 +13,8 @@ export const CIGAR_X = 8;
 export const CIGAR_M_EQ_MASK = 0b10000001; // (1<<0)|(1<<7) = 129
 // Indel ops (I=1, D=2, N=3) — each consumes only one axis (a gap on the other)
 export const CIGAR_INDEL_MASK = 0b00001110; // (1<<1)|(1<<2)|(1<<3) = 14
+// Not a BAM op: a match run whose two axes advance by different lengths, the
+// coarse tier's fold of the small indels between two kept gaps. Packed as two
+// consecutive words, `(ownLen << 4) | CIGAR_RUN` then `(mateLen << 4) |
+// CIGAR_RUN`. Only parseCoarseCigar writes it.
+export const CIGAR_RUN = 9;

package/esm/cigarRenderedSegments.d.ts

@@ -2,7 +2,9 @@
  * Walks pre-parsed (packed int) CIGAR ops in bp-space and fires a callback
  * for each rendered segment. Small indels (width < MIN_INDEL_PX) are merged
  * into surrounding context; tiny M segments (both accumulators advance <
- * bpPerPx) are accumulated before emitting.
+ * bpPerPx) are accumulated before emitting. A `CIGAR_RUN` word pair (the
+ * coarse tier's fold of a run with its small indels) advances each axis by its
+ * own length and is reported as CIGAR_M.
  *
  * Used by synteny and dotplot GPU renderers so both stay in sync.
  * Re-exported via @jbrowse/synteny-core for consistent import paths.

package/esm/cigarRenderedSegments.js

@@ -1,4 +1,4 @@
-import { CIGAR_D, CIGAR_EQ, CIGAR_I, CIGAR_M, CIGAR_N, CIGAR_X, } from './cigarConstants.js';
+import { CIGAR_D, CIGAR_EQ, CIGAR_I, CIGAR_M, CIGAR_N, CIGAR_RUN, CIGAR_X, } from './cigarConstants.js';
 // Indels narrower than this (in pixels) are merged into surrounding match
 // context rather than rendered as separate quads. At 1px an indel resolving to
 // a single pixel still renders — small on-screen detail is intentionally kept.
@@ -12,7 +12,9 @@ const MIN_INDEL_PX = 1;
  * Walks pre-parsed (packed int) CIGAR ops in bp-space and fires a callback
  * for each rendered segment. Small indels (width < MIN_INDEL_PX) are merged
  * into surrounding context; tiny M segments (both accumulators advance <
- * bpPerPx) are accumulated before emitting.
+ * bpPerPx) are accumulated before emitting. A `CIGAR_RUN` word pair (the
+ * coarse tier's fold of a run with its small indels) advances each axis by its
+ * own length and is reported as CIGAR_M.
  *
  * Used by synteny and dotplot GPU renderers so both stay in sync.
  * Re-exported via @jbrowse/synteny-core for consistent import paths.
@@ -34,7 +36,11 @@ export function visitCigarRenderedSegments(cigar, startBp1, startBp2, bpPerPx0,
             segBp1Start = bp1;
             segBp2Start = bp2;
         }
-        if (op === CIGAR_M || op === CIGAR_EQ || op === CIGAR_X) {
+        if (op === CIGAR_RUN) {
+            bp1 += len * rev1;
+            bp2 += (cigar[++j] >>> 4) * rev2;
+        }
+        else if (op === CIGAR_M || op === CIGAR_EQ || op === CIGAR_X) {
             bp1 += len * rev1;
             bp2 += len * rev2;
         }
@@ -60,7 +66,11 @@ export function visitCigarRenderedSegments(cigar, startBp1, startBp2, bpPerPx0,
         else {
             const span1 = Math.abs(bp1 - segBp1Start);
             const span2 = Math.abs(bp2 - segBp2Start);
-            const resolvedOp = span1 > bpPerPx0 || span2 > bpPerPx1 ? op : CIGAR_M;
+            const resolvedOp = span1 > bpPerPx0 || span2 > bpPerPx1
+                ? op === CIGAR_RUN
+                    ? CIGAR_M
+                    : op
+                : CIGAR_M;
             continuingFlag = false;
             callback(resolvedOp, segBp1Start, bp1, segBp2Start, bp2);
         }

package/esm/cigarReorient.js

@@ -1,29 +1,39 @@
+// Both re-orientations keep every byte of the CIGAR and change only which
+// letter an indel wears (and, for the flip, the op order), so each is written
+// straight into a byte buffer the size of its input rather than a string built
+// op by op: 2-3x faster on a multi-kb PAF CIGAR, which make-pif does twice a
+// row and orientAlignment does per fetched row.
+function swapIndelByte(code) {
+    return code === 68 ? 73 : code === 73 ? 68 : code;
+}
 // Reverse a CIGAR's op order and swap insertions<->deletions. Used to view an
 // alignment from the opposite (query<->target) perspective on the reverse
 // strand, where both the direction and the indel sense flip.
 export function flipCigar(cigar) {
-    const ops = [];
-    let len = 0;
-    for (let i = 0, l = cigar.length; i < l; i++) {
-        const c = cigar[i];
-        if (c >= '0' && c <= '9') {
-            len = len * 10 + (c.charCodeAt(0) - 48);
-        }
-        else {
-            ops.push([len, c]);
-            len = 0;
+    const src = new TextEncoder().encode(cigar);
+    const n = src.length;
+    const out = new Uint8Array(n);
+    let pos = n;
+    let start = 0;
+    for (let i = 0; i < n; i++) {
+        const code = src[i];
+        if (code < 48 || code > 57) {
+            pos -= i + 1 - start;
+            for (let k = start, p = pos; k < i; k++, p++) {
+                out[p] = src[k];
+            }
+            out[pos + i - start] = swapIndelByte(code);
+            start = i + 1;
         }
     }
-    let result = '';
-    for (let i = ops.length - 1; i >= 0; i--) {
-        const [l, op] = ops[i];
-        result += l;
-        result += op === 'D' ? 'I' : op === 'I' ? 'D' : op;
-    }
-    return result;
+    return new TextDecoder().decode(out.subarray(pos));
 }
 // Swap insertions<->deletions in place, leaving op order untouched. This is the
 // +-strand query<->target perspective flip, where only the indel sense reverses.
 export function swapIndelCigar(cigar) {
-    return cigar.replaceAll(/[DI]/g, op => (op === 'D' ? 'I' : 'D'));
+    const bytes = new TextEncoder().encode(cigar);
+    for (let i = 0, n = bytes.length; i < n; i++) {
+        bytes[i] = swapIndelByte(bytes[i]);
+    }
+    return new TextDecoder().decode(bytes);
 }

package/esm/coarseCigar.d.ts

@@ -0,0 +1,54 @@
+export interface CoarsenedCigar {
+    ops: string;
+    ownLen: number;
+    mateLen: number;
+    gapCount: number;
+    opCount: number;
+}
+/**
+ * #api
+ * Fold a CIGAR into a coarse CIGAR whose straight lines stay within `gap` of
+ * the alignment's own path. An indel longer than half the gap keeps its letter
+ * and length (D/N/I); a shorter one is absorbed into the match run around it,
+ * and a run whose two axes advanced by different amounts is written
+ * `<own>:<mate>M`, a square run `<n>M`. `=`/`X` count as M. `ownLen`/`mateLen`
+ * are the totals each axis consumed, for the caller to check against the row's
+ * coordinate columns.
+ *
+ * The bound: a run is closed before a folded indel would push its running
+ * skew (own minus mate) past half the gap, and no folded indel is longer than
+ * that, so inside a run the skew never exceeds half the gap and the line
+ * between the run's corners is never more than the gap off the path. That is
+ * what lets a reader interpolate within a run, and it costs a new run only
+ * where the two genomes' small indels are lopsided.
+ */
+export declare function coarsenCigar(cigar: string, gap: number): CoarsenedCigar;
+/**
+ * #api
+ * The coarse CIGAR seen from the other axis on the plus strand: the two lengths
+ * of every run trade places and D<->I swap, op order untouched. The twin of
+ * `swapIndelCigar`.
+ */
+export declare function swapCoarseCigar(s: string): string;
+/**
+ * #api
+ * The coarse CIGAR seen from the other axis on the minus strand: swapped as
+ * `swapCoarseCigar` does, and in reverse op order. The twin of `flipCigar`.
+ */
+export declare function flipCoarseCigar(s: string): string;
+/**
+ * #api
+ * The coarse CIGAR as a plain CIGAR over the row's own axis, for a walk that
+ * places mismatches by reference position: a run keeps only its own length, a
+ * run with no own length is the insertion it amounts to, and one with no mate
+ * length the deletion. Kept indels are exact, so they land where the fine
+ * tier's would.
+ */
+export declare function coarseCigarOwnAxis(s: string): string;
+/**
+ * #api
+ * Parse a coarse CIGAR into the packed `(len << 4) | op` form
+ * `visitCigarRenderedSegments` walks. A square run packs as one `CIGAR_M`
+ * word; an unequal run as a `CIGAR_RUN` word pair, own axis first.
+ */
+export declare function parseCoarseCigar(s: string): Uint32Array<ArrayBuffer>;

package/esm/coarseCigar.js

@@ -0,0 +1,235 @@
+import { CIGAR_D, CIGAR_I, CIGAR_M, CIGAR_N, CIGAR_RUN, } from './cigarConstants.js';
+/**
+ * #api
+ * Fold a CIGAR into a coarse CIGAR whose straight lines stay within `gap` of
+ * the alignment's own path. An indel longer than half the gap keeps its letter
+ * and length (D/N/I); a shorter one is absorbed into the match run around it,
+ * and a run whose two axes advanced by different amounts is written
+ * `<own>:<mate>M`, a square run `<n>M`. `=`/`X` count as M. `ownLen`/`mateLen`
+ * are the totals each axis consumed, for the caller to check against the row's
+ * coordinate columns.
+ *
+ * The bound: a run is closed before a folded indel would push its running
+ * skew (own minus mate) past half the gap, and no folded indel is longer than
+ * that, so inside a run the skew never exceeds half the gap and the line
+ * between the run's corners is never more than the gap off the path. That is
+ * what lets a reader interpolate within a run, and it costs a new run only
+ * where the two genomes' small indels are lopsided.
+ */
+export function coarsenCigar(cigar, gap) {
+    const skewBound = gap / 2;
+    let ops = '';
+    let ownLen = 0;
+    let mateLen = 0;
+    let gapCount = 0;
+    let opCount = 0;
+    let runOwn = 0;
+    let runMate = 0;
+    // a run with nothing on one side is the indel it amounts to, and is written
+    // as one, so a reader never meets a zero-sided run
+    const flushRun = () => {
+        if (runOwn > 0 || runMate > 0) {
+            ops +=
+                runOwn === runMate
+                    ? `${runOwn}M`
+                    : runOwn === 0
+                        ? `${runMate}I`
+                        : runMate === 0
+                            ? `${runOwn}D`
+                            : `${runOwn}:${runMate}M`;
+            opCount++;
+            runOwn = 0;
+            runMate = 0;
+        }
+    };
+    const keep = (len, op) => {
+        flushRun();
+        ops += `${len}${op}`;
+        gapCount++;
+        opCount++;
+    };
+    const fold = (own, mate) => {
+        if (Math.abs(runOwn + own - runMate - mate) > skewBound) {
+            flushRun();
+        }
+        runOwn += own;
+        runMate += mate;
+    };
+    let len = 0;
+    for (let i = 0, l = cigar.length; i < l; i++) {
+        const code = cigar.charCodeAt(i);
+        if (code >= 48 && code <= 57) {
+            len = len * 10 + code - 48;
+        }
+        else {
+            const op = cigar[i];
+            if (op === 'M' || op === '=' || op === 'X') {
+                runOwn += len;
+                runMate += len;
+                ownLen += len;
+                mateLen += len;
+            }
+            else if (op === 'D' || op === 'N') {
+                ownLen += len;
+                if (len > skewBound) {
+                    keep(len, op);
+                }
+                else {
+                    fold(len, 0);
+                }
+            }
+            else if (op === 'I') {
+                mateLen += len;
+                if (len > skewBound) {
+                    keep(len, op);
+                }
+                else {
+                    fold(0, len);
+                }
+            }
+            len = 0;
+        }
+    }
+    flushRun();
+    return { ops, ownLen, mateLen, gapCount, opCount };
+}
+function parseCoarseOps(s) {
+    const out = [];
+    let len = 0;
+    let ownBeforeColon;
+    for (let i = 0, l = s.length; i < l; i++) {
+        const code = s.charCodeAt(i);
+        if (code >= 48 && code <= 57) {
+            len = len * 10 + code - 48;
+        }
+        else if (code === 58) {
+            ownBeforeColon = len;
+            len = 0;
+        }
+        else {
+            // the alphabet is M I D N plus the run; a reader also takes =/X as M and
+            // steps over clips and padding, which a writer never emits
+            const op = s[i];
+            if (op === 'M' || op === '=' || op === 'X') {
+                out.push({
+                    own: ownBeforeColon === undefined ? len : ownBeforeColon,
+                    mate: len,
+                    op: 'M',
+                });
+            }
+            else if (op === 'I') {
+                out.push({ own: 0, mate: len, op });
+            }
+            else if (op === 'D' || op === 'N') {
+                out.push({ own: len, mate: 0, op });
+            }
+            ownBeforeColon = undefined;
+            len = 0;
+        }
+    }
+    return out;
+}
+function serializeCoarseOps(ops) {
+    let s = '';
+    for (const { own, mate, op } of ops) {
+        s +=
+            op === 'M'
+                ? own === mate
+                    ? `${own}M`
+                    : `${own}:${mate}M`
+                : `${op === 'I' ? mate : own}${op}`;
+    }
+    return s;
+}
+// N keeps its axis as well as its letter, matching `swapIndelCigar`, which
+// swaps only D<->I
+function swapAxes({ own, mate, op }) {
+    return op === 'N'
+        ? { own, mate, op }
+        : {
+            own: mate,
+            mate: own,
+            op: op === 'D' ? 'I' : op === 'I' ? 'D' : op,
+        };
+}
+/**
+ * #api
+ * The coarse CIGAR seen from the other axis on the plus strand: the two lengths
+ * of every run trade places and D<->I swap, op order untouched. The twin of
+ * `swapIndelCigar`.
+ */
+export function swapCoarseCigar(s) {
+    return serializeCoarseOps(parseCoarseOps(s).map(swapAxes));
+}
+/**
+ * #api
+ * The coarse CIGAR seen from the other axis on the minus strand: swapped as
+ * `swapCoarseCigar` does, and in reverse op order. The twin of `flipCigar`.
+ */
+export function flipCoarseCigar(s) {
+    return serializeCoarseOps(parseCoarseOps(s).map(swapAxes).reverse());
+}
+/**
+ * #api
+ * The coarse CIGAR as a plain CIGAR over the row's own axis, for a walk that
+ * places mismatches by reference position: a run keeps only its own length, a
+ * run with no own length is the insertion it amounts to, and one with no mate
+ * length the deletion. Kept indels are exact, so they land where the fine
+ * tier's would.
+ */
+export function coarseCigarOwnAxis(s) {
+    let out = '';
+    for (const { own, mate, op } of parseCoarseOps(s)) {
+        out +=
+            op === 'M'
+                ? own === 0
+                    ? `${mate}I`
+                    : mate === 0
+                        ? `${own}D`
+                        : `${own}M`
+                : `${op === 'I' ? mate : own}${op}`;
+    }
+    return out;
+}
+// The packed form keeps 28 bits of length, so a longer op is written as several
+// words that sum to it. A run is split with both axes in proportion.
+const MAX_PACKED_LEN = 2 ** 28 - 1;
+function pushPacked(out, len, code) {
+    for (let rest = len; rest > 0; rest -= MAX_PACKED_LEN) {
+        out.push(((Math.min(rest, MAX_PACKED_LEN) << 4) | code) >>> 0);
+    }
+}
+function pushRun(out, own, mate) {
+    if (own === mate) {
+        pushPacked(out, own, CIGAR_M);
+    }
+    else {
+        const chunks = Math.ceil(Math.max(own, mate) / MAX_PACKED_LEN);
+        for (let i = 0; i < chunks; i++) {
+            const o = Math.floor((own * (i + 1)) / chunks) - Math.floor((own * i) / chunks);
+            const m = Math.floor((mate * (i + 1)) / chunks) - Math.floor((mate * i) / chunks);
+            out.push(((o << 4) | CIGAR_RUN) >>> 0, ((m << 4) | CIGAR_RUN) >>> 0);
+        }
+    }
+}
+/**
+ * #api
+ * Parse a coarse CIGAR into the packed `(len << 4) | op` form
+ * `visitCigarRenderedSegments` walks. A square run packs as one `CIGAR_M`
+ * word; an unequal run as a `CIGAR_RUN` word pair, own axis first.
+ */
+export function parseCoarseCigar(s) {
+    const out = [];
+    for (const { own, mate, op } of parseCoarseOps(s)) {
+        if (op === 'M') {
+            pushRun(out, own, mate);
+        }
+        else if (op === 'I') {
+            pushPacked(out, mate, CIGAR_I);
+        }
+        else {
+            pushPacked(out, own, op === 'N' ? CIGAR_N : CIGAR_D);
+        }
+    }
+    return Uint32Array.from(out);
+}

package/esm/index.d.ts

@@ -1,4 +1,6 @@
-export { CIGAR_D, CIGAR_EQ, CIGAR_H, CIGAR_I, CIGAR_INDEL_MASK, CIGAR_M, CIGAR_M_EQ_MASK, CIGAR_N, CIGAR_P, CIGAR_S, CIGAR_X, } from './cigarConstants.ts';
+export { CIGAR_D, CIGAR_EQ, CIGAR_H, CIGAR_I, CIGAR_INDEL_MASK, CIGAR_M, CIGAR_M_EQ_MASK, CIGAR_N, CIGAR_P, CIGAR_RUN, CIGAR_S, CIGAR_X, } from './cigarConstants.ts';
+export { coarseCigarOwnAxis, coarsenCigar, flipCoarseCigar, parseCoarseCigar, swapCoarseCigar, } from './coarseCigar.ts';
+export type { CoarsenedCigar } from './coarseCigar.ts';
 export { CHAR_FROM_CODE, SEQRET, SEQRET_NUMERIC_DECODER, } from './bamSeqDecoder.ts';
 export { encodeSeqNumeric } from './bamSeqEncoder.ts';
 export { flipCigar, swapIndelCigar } from './cigarReorient.ts';

package/esm/index.js

@@ -1,4 +1,5 @@
-export { CIGAR_D, CIGAR_EQ, CIGAR_H, CIGAR_I, CIGAR_INDEL_MASK, CIGAR_M, CIGAR_M_EQ_MASK, CIGAR_N, CIGAR_P, CIGAR_S, CIGAR_X, } from './cigarConstants.js';
+export { CIGAR_D, CIGAR_EQ, CIGAR_H, CIGAR_I, CIGAR_INDEL_MASK, CIGAR_M, CIGAR_M_EQ_MASK, CIGAR_N, CIGAR_P, CIGAR_RUN, CIGAR_S, CIGAR_X, } from './cigarConstants.js';
+export { coarseCigarOwnAxis, coarsenCigar, flipCoarseCigar, parseCoarseCigar, swapCoarseCigar, } from './coarseCigar.js';
 export { CHAR_FROM_CODE, SEQRET, SEQRET_NUMERIC_DECODER, } from './bamSeqDecoder.js';
 export { encodeSeqNumeric } from './bamSeqEncoder.js';
 // The BAM mismatch walk and its packed reference come from `@gmod/bam`:

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@jbrowse/cigar-utils",
-  "version": "4.1.14",
+  "version": "5.0.0-beta.2",
   "type": "module",
   "description": "Pure CIGAR / MD / mismatch parsers and types — no rendering or framework deps",
   "keywords": [