@jbrowse/modifications-utils 4.1.14

package/LICENSE

@@ -0,0 +1,201 @@
+                                 Apache License
+                           Version 2.0, January 2004
+                        http://www.apache.org/licenses/
+
+   TERMS AND CONDITIONS FOR USE, REPRODUCTION, AND DISTRIBUTION
+
+   1. Definitions.
+
+      "License" shall mean the terms and conditions for use, reproduction,
+      and distribution as defined by Sections 1 through 9 of this document.
+
+      "Licensor" shall mean the copyright owner or entity authorized by
+      the copyright owner that is granting the License.
+
+      "Legal Entity" shall mean the union of the acting entity and all
+      other entities that control, are controlled by, or are under common
+      control with that entity. For the purposes of this definition,
+      "control" means (i) the power, direct or indirect, to cause the
+      direction or management of such entity, whether by contract or
+      otherwise, or (ii) ownership of fifty percent (50%) or more of the
+      outstanding shares, or (iii) beneficial ownership of such entity.
+
+      "You" (or "Your") shall mean an individual or Legal Entity
+      exercising permissions granted by this License.
+
+      "Source" form shall mean the preferred form for making modifications,
+      including but not limited to software source code, documentation
+      source, and configuration files.
+
+      "Object" form shall mean any form resulting from mechanical
+      transformation or translation of a Source form, including but
+      not limited to compiled object code, generated documentation,
+      and conversions to other media types.
+
+      "Work" shall mean the work of authorship, whether in Source or
+      Object form, made available under the License, as indicated by a
+      copyright notice that is included in or attached to the work
+      (an example is provided in the Appendix below).
+
+      "Derivative Works" shall mean any work, whether in Source or Object
+      form, that is based on (or derived from) the Work and for which the
+      editorial revisions, annotations, elaborations, or other modifications
+      represent, as a whole, an original work of authorship. For the purposes
+      of this License, Derivative Works shall not include works that remain
+      separable from, or merely link (or bind by name) to the interfaces of,
+      the Work and Derivative Works thereof.
+
+      "Contribution" shall mean any work of authorship, including
+      the original version of the Work and any modifications or additions
+      to that Work or Derivative Works thereof, that is intentionally
+      submitted to Licensor for inclusion in the Work by the copyright owner
+      or by an individual or Legal Entity authorized to submit on behalf of
+      the copyright owner. For the purposes of this definition, "submitted"
+      means any form of electronic, verbal, or written communication sent
+      to the Licensor or its representatives, including but not limited to
+      communication on electronic mailing lists, source code control systems,
+      and issue tracking systems that are managed by, or on behalf of, the
+      Licensor for the purpose of discussing and improving the Work, but
+      excluding communication that is conspicuously marked or otherwise
+      designated in writing by the copyright owner as "Not a Contribution."
+
+      "Contributor" shall mean Licensor and any individual or Legal Entity
+      on behalf of whom a Contribution has been received by Licensor and
+      subsequently incorporated within the Work.
+
+   2. Grant of Copyright License. Subject to the terms and conditions of
+      this License, each Contributor hereby grants to You a perpetual,
+      worldwide, non-exclusive, no-charge, royalty-free, irrevocable
+      copyright license to reproduce, prepare Derivative Works of,
+      publicly display, publicly perform, sublicense, and distribute the
+      Work and such Derivative Works in Source or Object form.
+
+   3. Grant of Patent License. Subject to the terms and conditions of
+      this License, each Contributor hereby grants to You a perpetual,
+      worldwide, non-exclusive, no-charge, royalty-free, irrevocable
+      (except as stated in this section) patent license to make, have made,
+      use, offer to sell, sell, import, and otherwise transfer the Work,
+      where such license applies only to those patent claims licensable
+      by such Contributor that are necessarily infringed by their
+      Contribution(s) alone or by combination of their Contribution(s)
+      with the Work to which such Contribution(s) was submitted. If You
+      institute patent litigation against any entity (including a
+      cross-claim or counterclaim in a lawsuit) alleging that the Work
+      or a Contribution incorporated within the Work constitutes direct
+      or contributory patent infringement, then any patent licenses
+      granted to You under this License for that Work shall terminate
+      as of the date such litigation is filed.
+
+   4. Redistribution. You may reproduce and distribute copies of the
+      Work or Derivative Works thereof in any medium, with or without
+      modifications, and in Source or Object form, provided that You
+      meet the following conditions:
+
+      (a) You must give any other recipients of the Work or
+          Derivative Works a copy of this License; and
+
+      (b) You must cause any modified files to carry prominent notices
+          stating that You changed the files; and
+
+      (c) You must retain, in the Source form of any Derivative Works
+          that You distribute, all copyright, patent, trademark, and
+          attribution notices from the Source form of the Work,
+          excluding those notices that do not pertain to any part of
+          the Derivative Works; and
+
+      (d) If the Work includes a "NOTICE" text file as part of its
+          distribution, then any Derivative Works that You distribute must
+          include a readable copy of the attribution notices contained
+          within such NOTICE file, excluding those notices that do not
+          pertain to any part of the Derivative Works, in at least one
+          of the following places: within a NOTICE text file distributed
+          as part of the Derivative Works; within the Source form or
+          documentation, if provided along with the Derivative Works; or,
+          within a display generated by the Derivative Works, if and
+          wherever such third-party notices normally appear. The contents
+          of the NOTICE file are for informational purposes only and
+          do not modify the License. You may add Your own attribution
+          notices within Derivative Works that You distribute, alongside
+          or as an addendum to the NOTICE text from the Work, provided
+          that such additional attribution notices cannot be construed
+          as modifying the License.
+
+      You may add Your own copyright statement to Your modifications and
+      may provide additional or different license terms and conditions
+      for use, reproduction, or distribution of Your modifications, or
+      for any such Derivative Works as a whole, provided Your use,
+      reproduction, and distribution of the Work otherwise complies with
+      the conditions stated in this License.
+
+   5. Submission of Contributions. Unless You explicitly state otherwise,
+      any Contribution intentionally submitted for inclusion in the Work
+      by You to the Licensor shall be under the terms and conditions of
+      this License, without any additional terms or conditions.
+      Notwithstanding the above, nothing herein shall supersede or modify
+      the terms of any separate license agreement you may have executed
+      with Licensor regarding such Contributions.
+
+   6. Trademarks. This License does not grant permission to use the trade
+      names, trademarks, service marks, or product names of the Licensor,
+      except as required for reasonable and customary use in describing the
+      origin of the Work and reproducing the content of the NOTICE file.
+
+   7. Disclaimer of Warranty. Unless required by applicable law or
+      agreed to in writing, Licensor provides the Work (and each
+      Contributor provides its Contributions) on an "AS IS" BASIS,
+      WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or
+      implied, including, without limitation, any warranties or conditions
+      of TITLE, NON-INFRINGEMENT, MERCHANTABILITY, or FITNESS FOR A
+      PARTICULAR PURPOSE. You are solely responsible for determining the
+      appropriateness of using or redistributing the Work and assume any
+      risks associated with Your exercise of permissions under this License.
+
+   8. Limitation of Liability. In no event and under no legal theory,
+      whether in tort (including negligence), contract, or otherwise,
+      unless required by applicable law (such as deliberate and grossly
+      negligent acts) or agreed to in writing, shall any Contributor be
+      liable to You for damages, including any direct, indirect, special,
+      incidental, or consequential damages of any character arising as a
+      result of this License or out of the use or inability to use the
+      Work (including but not limited to damages for loss of goodwill,
+      work stoppage, computer failure or malfunction, or any and all
+      other commercial damages or losses), even if such Contributor
+      has been advised of the possibility of such damages.
+
+   9. Accepting Warranty or Additional Liability. While redistributing
+      the Work or Derivative Works thereof, You may choose to offer,
+      and charge a fee for, acceptance of support, warranty, indemnity,
+      or other liability obligations and/or rights consistent with this
+      License. However, in accepting such obligations, You may act only
+      on Your own behalf and on Your sole responsibility, not on behalf
+      of any other Contributor, and only if You agree to indemnify,
+      defend, and hold each Contributor harmless for any liability
+      incurred by, or claims asserted against, such Contributor by reason
+      of your accepting any such warranty or additional liability.
+
+   END OF TERMS AND CONDITIONS
+
+   APPENDIX: How to apply the Apache License to your work.
+
+      To apply the Apache License to your work, attach the following
+      boilerplate notice, with the fields enclosed by brackets "[]"
+      replaced with your own identifying information. (Don't include
+      the brackets!)  The text should be enclosed in the appropriate
+      comment syntax for the file format. We also recommend that a
+      file or class name and description of purpose be included on the
+      same "printed page" as the copyright notice for easier
+      identification within third-party archives.
+
+   Copyright [2020] [Evolutionary Software Foundation]
+
+   Licensed under the Apache License, Version 2.0 (the "License");
+   you may not use this file except in compliance with the License.
+   You may obtain a copy of the License at
+
+       http://www.apache.org/licenses/LICENSE-2.0
+
+   Unless required by applicable law or agreed to in writing, software
+   distributed under the License is distributed on an "AS IS" BASIS,
+   WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+   See the License for the specific language governing permissions and
+   limitations under the License.

package/README.md

@@ -0,0 +1,192 @@
+# @jbrowse/modifications-utils
+
+Pure MM/ML base-modification tag parsers (methylation, etc.)
+
+<!-- API_DOCS_START -->
+
+## API
+
+Auto-generated from `#api` JSDoc tags in this package. Do not edit by hand.
+
+### getMethBins
+
+Bins per-read base modifications and their probabilities onto reference
+positions, returning typed arrays for methylated/unmethylated calls. Only
+cytosines in `context` are considered (default CpG); plants also use CHG/CHH.
+
+```js
+// type signature
+({…}: ParsedModData, context?: CytosineContext) => { methBins: number[]; hydroxyMethBins: number[]; methProbs: number[]; hydroxyMethProbs: number[]; }
+```
+
+[Source code](https://github.com/GMOD/jbrowse-components/blob/main/packages/modifications-utils/src/getMethBins.ts)
+
+### getModPositions
+
+Parse MM tag to extract modification positions on the read sequence.
+
+```js
+// type signature
+(mm: string, fseq: string, fstrand: number) => ModWithPositions[]
+```
+
+[Source code](https://github.com/GMOD/jbrowse-components/blob/main/packages/modifications-utils/src/getModPositions.ts)
+
+### getModProbabilities
+
+Reads the ML tag from a feature and returns per-call modification probabilities
+scaled to 0..1.
+
+```js
+// type signature
+(feature: Feature) => number[] | undefined
+```
+
+[Source code](https://github.com/GMOD/jbrowse-components/blob/main/packages/modifications-utils/src/getModProbabilities.ts)
+
+### getModProbabilityBytes
+
+The ML tag as its raw 0..255 bytes, without the scaling `getModProbabilities`
+applies.
+
+The byte is a LOSSLESS stand-in for the probability — every value on this path
+is exactly `(N + 0.5) / 256` — and it is monotonic in it, so anything that only
+compares probabilities (picking the most likely call at a position, testing a
+threshold) can work in bytes and divide once, at the end, for the few calls that
+survive. A caller that needs the numbers themselves still wants
+`getModProbabilities`.
+
+```js
+// type signature
+(feature: Feature) => ArrayLike<number> | undefined
+```
+
+[Source code](https://github.com/GMOD/jbrowse-components/blob/main/packages/modifications-utils/src/getModProbabilities.ts)
+
+### getModTypes
+
+The modification types an MM tag declares, from its headers alone.
+
+`getModPositions` answers this too, but on the way to placing every call: it
+walks the delta list against the read sequence, which is the expensive half and
+is only needed to DRAW marks. Anything that just wants to know what is in the
+file — which types to offer in a menu, whether a track carries modifications at
+all — wants this instead, and pays neither the walk nor the sequence decode that
+feeds it.
+
+```js
+// type signature
+(mm: string) => ModTypeHeader[]
+```
+
+[Source code](https://github.com/GMOD/jbrowse-components/blob/main/packages/modifications-utils/src/getModTypes.ts)
+
+### getTag
+
+Read a single tag by name, using the feature's targeted tag accessor when it has
+one (BAM) and the full tags object otherwise (CRAM/synteny).
+
+```js
+// type signature
+(feature: Feature, tag: string) => unknown
+```
+
+[Source code](https://github.com/GMOD/jbrowse-components/blob/main/packages/modifications-utils/src/getTagAlt.ts)
+
+### getTagAlt
+
+Read a tag by its canonical name, falling back to a lowercase-suffixed alias
+(e.g. MM/Mm, ML/Ml) as emitted by some aligners.
+
+Prefers the feature's own one-pass alias lookup when it has one. The plain
+`getTag(tag) ?? getTag(alt)` form walks the record's whole tag block TWICE
+whenever neither name is present — which is every read in a file without base
+modifications, and this is called per read on every render. On jb2bench's
+1000x.shortread that pair of walks was 12.9% of the whole BAM query, more than
+the CIGAR/SEQ/MD reads the pileup actually uses.
+
+```js
+// type signature
+(feature: Feature, tag: string, alt: string) => unknown
+```
+
+[Source code](https://github.com/GMOD/jbrowse-components/blob/main/packages/modifications-utils/src/getTagAlt.ts)
+
+### isMethylationFillType
+
+The modification types the methylation walk below paints — 5mC and 5hmC, the
+pair that compete for one cytosine.
+
+Stated once because two functions have to agree on it and they are in different
+packages: this walk claims those types, and `extractModifications` has to skip
+exactly them in the fill view so a cytosine gets one mark rather than two. A
+second spelling would either double-paint or, as it did, drop every OTHER type
+the read declares.
+
+```js
+// type signature
+(type: string) => type is "h" | "m"
+```
+
+[Source code](https://github.com/GMOD/jbrowse-components/blob/main/packages/modifications-utils/src/getMethBins.ts)
+
+### matchesCytosineContext
+
+Whether the cytosine at read position `pos` sits in the given context.
+
+The pattern is defined on the template (the strand the C is on), read 5'->3'.
+For forward reads the stored sequence IS the template, so we read forward from
+`pos`. getModPositions works reverse-strand reads in stored-sequence space,
+where the template runs backwards and complemented, so we read backwards from
+`pos` and complement each base before matching.
+
+**Char codes, not characters, and that is the whole shape of this function.**
+Folding case with `& ~0x20` on the code and comparing numbers keeps a probe to
+arithmetic, where lower-casing the character and the pattern base beside it is
+two string operations per base. It is asked at that volume: the fill-unmarked
+methylation walk asks up to twice for every aligned base of every read
+(getMethBins), and bisulfite asks at every candidate cytosine. What it is worth
+in the phase it sits in — which is not what it is worth on its own — is
+`plugins/alignments/benches/modFillView.bench.ts`.
+
+`charCodeAt` past either end of the string is NaN and `NaN & ~0x20` is 0 — an
+index no pattern base equals and the complement table holds -1 at — so the walk
+runs off the read as a non-match with no bounds test of its own.
+`features/modCoverage/readBaseCounts.ts` folds case the same way and says so.
+
+```js
+// type signature
+(seq: string, pos: number, isReverse: boolean, context: CytosineContext) => boolean
+```
+
+[Source code](https://github.com/GMOD/jbrowse-components/blob/main/packages/modifications-utils/src/cytosineContext.ts)
+
+### modProbAt
+
+Returns the probability value from the flat ML array for a modification's
+position. `idx` is the position's index within the mod's stored `positions`
+array; we recover its MM-tag order (reverse-strand reads store positions in
+descending order) and step into ML by `probStart + mmOrder * probStride`.
+`probStride` is >1 for combined codes (e.g. 'C+mh'), where ML values are
+interleaved per position.
+
+```js
+// type signature
+(probabilities: number[] | undefined, probStart: number, probStride: number, isReverse: boolean, idx: number, posLen: number) => number
+```
+
+[Source code](https://github.com/GMOD/jbrowse-components/blob/main/packages/modifications-utils/src/getModProbabilities.ts)
+
+### parseModHeader
+
+Parses one MM-tag modification header (e.g. `C+m`) into its base, strand, type
+string, and modification code.
+
+```js
+// type signature
+(basemod: string, fullmod: string) => { base: string; strand: string; typestr: string; mod: string; }
+```
+
+[Source code](https://github.com/GMOD/jbrowse-components/blob/main/packages/modifications-utils/src/consts.ts)
+
+<!-- API_DOCS_END -->

package/esm/consts.d.ts

@@ -0,0 +1,12 @@
+export declare const modificationRegex: RegExp;
+/**
+ * #api
+ * Parses one MM-tag modification header (e.g. `C+m`) into its base, strand,
+ * type string, and modification code.
+ */
+export declare function parseModHeader(basemod: string, fullmod: string): {
+    base: string;
+    strand: string;
+    typestr: string;
+    mod: string;
+};

package/esm/consts.js

@@ -0,0 +1,42 @@
+// Regex for MM:Z tag format based on SAM/BAM spec (hts-specs):
+// Spec: ([ACGTUN][-+]([a-z]+|[0-9]+)[.?]?(,[0-9]+)*;)*
+//
+// Our implementation diverges intentionally from the spec:
+// 1. Capture strand as group 2: ([-+]) instead of [-+]
+//    - Needed to extract strand info for downstream processing
+// 2. Accept uppercase single letters: ([a-z]+|[A-Z]|[0-9]+) instead of ([a-z]+|[0-9]+)
+//    - The spec PROSE defines uppercase ambiguity codes A/C/G/T/U and N (an
+//      unspecified modification of the respective canonical base), but the
+//      spec's own grammar regex omits them — a known inconsistency in the spec.
+//    - Ambiguity codes are always a single uppercase letter (never multi-char
+//      or mixed with lowercase), hence [A-Z] rather than [A-Z]+.
+// 3. Capture modifier flag as group 4: ([.?]?) instead of non-capturing
+//    - Per spec: '?' = modification status of skipped bases is unknown
+//    - Per spec: '.' or absent = skipped bases should be assumed low probability of modification
+//    - We capture this to support correct interpretation of skipped positions
+// 4. Don't match delta values or semicolon
+//    - We extract just the base modification header (e.g., "C+m?" from "C+m?,2,1;")
+//    - Caller splits by ";" and "," to get this header before passing to regex
+//
+// Real-world examples with modifier flags:
+//   C+m   → skipped bases = low probability modification (default)
+//   C+m.  → skipped bases = low probability modification (explicit)
+//   C+m?  → skipped bases = unknown modification status
+export const modificationRegex = /([ACGTUN])([-+])([a-z]+|[A-Z]|[0-9]+)([.?]?)/;
+/**
+ * #api
+ * Parses one MM-tag modification header (e.g. `C+m`) into its base, strand,
+ * type string, and modification code.
+ */
+export function parseModHeader(basemod, fullmod) {
+    const matches = modificationRegex.exec(basemod);
+    if (!matches) {
+        throw new Error(`bad format for MM tag: "${fullmod}"`);
+    }
+    return {
+        base: matches[1],
+        strand: matches[2],
+        typestr: matches[3],
+        mod: matches[4] !== '' ? matches[4] : '.',
+    };
+}

package/esm/cytosineContext.d.ts

@@ -0,0 +1,26 @@
+export type CytosineContext = 'CG' | 'CHG' | 'CHH' | 'all';
+/**
+ * #api
+ * Whether the cytosine at read position `pos` sits in the given context.
+ *
+ * The pattern is defined on the template (the strand the C is on), read 5'->3'.
+ * For forward reads the stored sequence IS the template, so we read forward from
+ * `pos`. getModPositions works reverse-strand reads in stored-sequence space,
+ * where the template runs backwards and complemented, so we read backwards from
+ * `pos` and complement each base before matching.
+ *
+ * **Char codes, not characters, and that is the whole shape of this function.**
+ * Folding case with `& ~0x20` on the code and comparing numbers keeps a probe
+ * to arithmetic, where lower-casing the character and the pattern base beside
+ * it is two string operations per base. It is asked at that volume: the
+ * fill-unmarked methylation walk asks up to twice for every aligned base of
+ * every read (getMethBins), and bisulfite asks at every candidate cytosine.
+ * What it is worth in the phase it sits in — which is not what it is worth on
+ * its own — is `plugins/alignments/benches/modFillView.bench.ts`.
+ *
+ * `charCodeAt` past either end of the string is NaN and `NaN & ~0x20` is 0 — an
+ * index no pattern base equals and the complement table holds -1 at — so the
+ * walk runs off the read as a non-match with no bounds test of its own.
+ * `features/modCoverage/readBaseCounts.ts` folds case the same way and says so.
+ */
+export declare function matchesCytosineContext(seq: string, pos: number, isReverse: boolean, context: CytosineContext): boolean;

package/esm/cytosineContext.js

@@ -0,0 +1,62 @@
+const A = 65;
+const C = 67;
+const G = 71;
+const T = 84;
+// The IUPAC A/C/T ambiguity code, which is what the H of CHG/CHH is.
+const H = 72;
+// Template-strand base pattern per context, 5'->3', as upper-case char codes.
+// 'all' constrains only the cytosine itself.
+const CONTEXT_PATTERN = {
+    CG: Uint8Array.of(C, G),
+    CHG: Uint8Array.of(C, H, G),
+    CHH: Uint8Array.of(C, H, H),
+    all: Uint8Array.of(C),
+};
+const COMPLEMENT_CODE = new Int16Array(128).fill(-1);
+COMPLEMENT_CODE[A] = T;
+COMPLEMENT_CODE[T] = A;
+COMPLEMENT_CODE[C] = G;
+COMPLEMENT_CODE[G] = C;
+/**
+ * #api
+ * Whether the cytosine at read position `pos` sits in the given context.
+ *
+ * The pattern is defined on the template (the strand the C is on), read 5'->3'.
+ * For forward reads the stored sequence IS the template, so we read forward from
+ * `pos`. getModPositions works reverse-strand reads in stored-sequence space,
+ * where the template runs backwards and complemented, so we read backwards from
+ * `pos` and complement each base before matching.
+ *
+ * **Char codes, not characters, and that is the whole shape of this function.**
+ * Folding case with `& ~0x20` on the code and comparing numbers keeps a probe
+ * to arithmetic, where lower-casing the character and the pattern base beside
+ * it is two string operations per base. It is asked at that volume: the
+ * fill-unmarked methylation walk asks up to twice for every aligned base of
+ * every read (getMethBins), and bisulfite asks at every candidate cytosine.
+ * What it is worth in the phase it sits in — which is not what it is worth on
+ * its own — is `plugins/alignments/benches/modFillView.bench.ts`.
+ *
+ * `charCodeAt` past either end of the string is NaN and `NaN & ~0x20` is 0 — an
+ * index no pattern base equals and the complement table holds -1 at — so the
+ * walk runs off the read as a non-match with no bounds test of its own.
+ * `features/modCoverage/readBaseCounts.ts` folds case the same way and says so.
+ */
+export function matchesCytosineContext(seq, pos, isReverse, context) {
+    const pattern = CONTEXT_PATTERN[context];
+    for (let i = 0, len = pattern.length; i < len; i++) {
+        const code = seq.charCodeAt(isReverse ? pos - i : pos + i) & ~0x20;
+        // A non-ASCII sequence character folds to something past the complement
+        // table rather than into it, and matches no pattern base either way.
+        if (code > 127) {
+            return false;
+        }
+        const actual = isReverse ? COMPLEMENT_CODE[code] : code;
+        const expected = pattern[i];
+        if (expected === H
+            ? actual !== A && actual !== C && actual !== T
+            : actual !== expected) {
+            return false;
+        }
+    }
+    return true;
+}

package/esm/detectSimplexModifications.d.ts

@@ -0,0 +1,21 @@
+import type { ModificationType } from './types.ts';
+type ModificationTypeList = readonly ModificationType[];
+/**
+ * Which modification types were basecalled on only ONE strand ("simplex") vs
+ * both ("duplex"). The MM tag reports each mod against a strand, e.g. `C+m` (5mC
+ * on the read's strand) or `G-m` (5mC on the opposite strand, reading as a G).
+ * A type on '+' with no '-' partner anywhere → simplex; both present → duplex.
+ *
+ * Callers use this to pick the modification-coverage denominator (see
+ * calculateModificationCounts): duplex counts every read with the base, simplex
+ * only reads on the examined strand, else the modified fraction is understated.
+ *
+ * Run over the WHOLE dataset, not one read: simplex-ness is a protocol property,
+ * shared by all reads, and a single read can lack the '-' call just by covering
+ * no eligible base — a per-read check would misclassify duplex data as simplex.
+ *
+ * Mirrors IGV: AlignmentDataManager builds the set globally,
+ * BaseModificationCoverageRenderer uses it for the detectable count.
+ */
+export declare function detectSimplexModifications(modifications: ModificationTypeList): ReadonlySet<string>;
+export {};

package/esm/detectSimplexModifications.js

@@ -0,0 +1,34 @@
+/**
+ * Which modification types were basecalled on only ONE strand ("simplex") vs
+ * both ("duplex"). The MM tag reports each mod against a strand, e.g. `C+m` (5mC
+ * on the read's strand) or `G-m` (5mC on the opposite strand, reading as a G).
+ * A type on '+' with no '-' partner anywhere → simplex; both present → duplex.
+ *
+ * Callers use this to pick the modification-coverage denominator (see
+ * calculateModificationCounts): duplex counts every read with the base, simplex
+ * only reads on the examined strand, else the modified fraction is understated.
+ *
+ * Run over the WHOLE dataset, not one read: simplex-ness is a protocol property,
+ * shared by all reads, and a single read can lack the '-' call just by covering
+ * no eligible base — a per-read check would misclassify duplex data as simplex.
+ *
+ * Mirrors IGV: AlignmentDataManager builds the set globally,
+ * BaseModificationCoverageRenderer uses it for the detectable count.
+ */
+export function detectSimplexModifications(modifications) {
+    // types seen on the '-' strand anywhere → those are duplex
+    const minusTypes = new Set();
+    for (const { strand, type } of modifications) {
+        if (strand === '-') {
+            minusTypes.add(type);
+        }
+    }
+    // a '+' type with no '-' partner was only examined on one strand → simplex
+    const simplex = new Set();
+    for (const { strand, type } of modifications) {
+        if (strand === '+' && !minusTypes.has(type)) {
+            simplex.add(type);
+        }
+    }
+    return simplex;
+}

package/esm/forEachModRefPos.d.ts

@@ -0,0 +1,2 @@
+import type { ModWithPositions } from './getModPositions.ts';
+export declare function forEachModRefPos(modifications: readonly ModWithPositions[], probabilities: number[] | undefined, cigarOps: ArrayLike<number>, isReverse: boolean, cb: (mod: ModWithPositions, ref: number, idx: number, prob: number) => void): void;

package/esm/forEachModRefPos.js

@@ -0,0 +1,15 @@
+import { getNextRefPos } from '@jbrowse/cigar-utils';
+import { modProbAt } from './getModProbabilities.js';
+// Walk every modification's read-sequence positions, mapping each to its
+// reference position via the CIGAR and recovering its ML probability. The
+// ML-array offset (probStart/probStride) is precomputed per modification by
+// getModPositions, so this no longer tracks a running index by hand.
+export function forEachModRefPos(modifications, probabilities, cigarOps, isReverse, cb) {
+    for (const mod of modifications) {
+        const { positions, probStart, probStride } = mod;
+        getNextRefPos(cigarOps, positions, (ref, idx) => {
+            const prob = modProbAt(probabilities, probStart, probStride, isReverse, idx, positions.length);
+            cb(mod, ref, idx, prob);
+        });
+    }
+}

package/esm/getMethBins.d.ts

@@ -0,0 +1,34 @@
+import type { CytosineContext } from './cytosineContext.ts';
+import type { ModWithPositions } from './getModPositions.ts';
+export interface ParsedModData {
+    modifications: ModWithPositions[];
+    probabilities: number[] | undefined;
+    cigarOps: ArrayLike<number>;
+    seq: string;
+    fstrand: -1 | 0 | 1;
+    flen: number;
+}
+/**
+ * #api
+ * The modification types the methylation walk below paints — 5mC and 5hmC, the
+ * pair that compete for one cytosine.
+ *
+ * Stated once because two functions have to agree on it and they are in
+ * different packages: this walk claims those types, and
+ * `extractModifications` has to skip exactly them in the fill view so a
+ * cytosine gets one mark rather than two. A second spelling would either
+ * double-paint or, as it did, drop every OTHER type the read declares.
+ */
+export declare function isMethylationFillType(type: string): type is "h" | "m";
+/**
+ * #api
+ * Bins per-read base modifications and their probabilities onto reference
+ * positions, returning typed arrays for methylated/unmethylated calls. Only
+ * cytosines in `context` are considered (default CpG); plants also use CHG/CHH.
+ */
+export declare function getMethBins({ modifications, probabilities, cigarOps, seq, fstrand, flen }: ParsedModData, context?: CytosineContext): {
+    methBins: number[];
+    hydroxyMethBins: number[];
+    methProbs: number[];
+    hydroxyMethProbs: number[];
+};

package/esm/getMethBins.js

@@ -0,0 +1,92 @@
+import { CIGAR_D, CIGAR_EQ, CIGAR_I, CIGAR_M, CIGAR_N, CIGAR_S, CIGAR_X, } from '@jbrowse/cigar-utils';
+import { matchesCytosineContext } from './cytosineContext.js';
+import { forEachModRefPos } from './forEachModRefPos.js';
+/**
+ * #api
+ * The modification types the methylation walk below paints — 5mC and 5hmC, the
+ * pair that compete for one cytosine.
+ *
+ * Stated once because two functions have to agree on it and they are in
+ * different packages: this walk claims those types, and
+ * `extractModifications` has to skip exactly them in the fill view so a
+ * cytosine gets one mark rather than two. A second spelling would either
+ * double-paint or, as it did, drop every OTHER type the read declares.
+ */
+export function isMethylationFillType(type) {
+    return type === 'm' || type === 'h';
+}
+/**
+ * #api
+ * Bins per-read base modifications and their probabilities onto reference
+ * positions, returning typed arrays for methylated/unmethylated calls. Only
+ * cytosines in `context` are considered (default CpG); plants also use CHG/CHH.
+ */
+export function getMethBins({ modifications, probabilities, cigarOps, seq, fstrand, flen }, context = 'CG') {
+    const isReverse = fstrand === -1;
+    const methBins = [];
+    const hydroxyMethBins = [];
+    const methProbs = [];
+    const hydroxyMethProbs = [];
+    forEachModRefPos(modifications, probabilities, cigarOps, isReverse, ({ type, strand, positions }, ref, idx, prob) => {
+        const isMeth = isMethylationFillType(type);
+        if (isMeth &&
+            ref >= 0 &&
+            ref < flen &&
+            matchesCytosineContext(seq, positions[idx], isReverse !== (strand === '-'), context)) {
+            if (type === 'm') {
+                methBins[ref] = 1;
+                methProbs[ref] = prob;
+            }
+            else {
+                hydroxyMethBins[ref] = 1;
+                hydroxyMethProbs[ref] = prob;
+            }
+        }
+    });
+    // Only fill undetected sites as unmethylated when the read actually carries a
+    // 5mC ('m') call. A read with only e.g. 6mA modifications never assayed
+    // methylation, so inventing unmethylated cytosines for it would be wrong.
+    // Additionally, per SAMtags the '?' flag means the status of bases not listed
+    // in the MM tag is unknown, so we must NOT assume them unmethylated; only the
+    // '.'/absent flag (low probability for skipped bases) lets us fill them in.
+    const methMods = modifications.filter(m => m.type === 'm');
+    const fillUnmethylated = methMods.length > 0 && !methMods.some(m => m.unknownSkip);
+    // A '-' MM group assays the cytosines of the strand OPPOSITE the read, so a
+    // both-strand modBAM ('C+m;G-m') has its uncalled sites in both directions.
+    const fillForward = methMods.some(m => isReverse === (m.strand === '-'));
+    const fillReverse = methMods.some(m => isReverse !== (m.strand === '-'));
+    // Scan the full read sequence for every cytosine in `context` and mark any not
+    // already detected from the MM tag as unmethylated (prob=0).
+    if (fillUnmethylated) {
+        let readPos = 0;
+        let refPos = 0;
+        for (let i = 0, l = cigarOps.length; i < l; i++) {
+            const packed = cigarOps[i];
+            const len = packed >>> 4;
+            const op = packed & 0xf;
+            if (op === CIGAR_S || op === CIGAR_I) {
+                readPos += len;
+            }
+            else if (op === CIGAR_D || op === CIGAR_N) {
+                refPos += len;
+            }
+            else if (op === CIGAR_M || op === CIGAR_X || op === CIGAR_EQ) {
+                for (let j = 0; j < len; j++) {
+                    const rp = readPos + j;
+                    const rf = refPos + j;
+                    if (rf >= 0 &&
+                        rf < flen &&
+                        !methBins[rf] &&
+                        ((fillForward && matchesCytosineContext(seq, rp, false, context)) ||
+                            (fillReverse && matchesCytosineContext(seq, rp, true, context)))) {
+                        methBins[rf] = 1;
+                        methProbs[rf] = 0;
+                    }
+                }
+                readPos += len;
+                refPos += len;
+            }
+        }
+    }
+    return { methBins, hydroxyMethBins, methProbs, hydroxyMethProbs };
+}

package/esm/getModPositions.d.ts

@@ -0,0 +1,19 @@
+export interface ModWithPositions {
+    type: string;
+    base: string;
+    strand: string;
+    unknownSkip: boolean;
+    positions: number[];
+    probStart: number;
+    probStride: number;
+}
+/**
+ * #api
+ * Parse MM tag to extract modification positions on the read sequence.
+ *
+ * @param mm - MM tag string (e.g., "C+m,2,2,1;A+a,0,3")
+ * @param fseq - Read sequence
+ * @param fstrand - Read strand (-1, 0, or 1)
+ * @returns Array of modification objects with positions
+ */
+export declare function getModPositions(mm: string, fseq: string, fstrand: number): ModWithPositions[];

package/esm/getModPositions.js

@@ -0,0 +1,211 @@
+import { parseModHeader } from './consts.js';
+import { isSingleModType } from './getModTypes.js';
+const COMPLEMENT_CODE = {
+    65: 84, // A->T
+    84: 65, // T->A
+    67: 71, // C->G
+    71: 67, // G->C
+    78: 78, // N->N
+};
+/**
+ * #api
+ * Parse MM tag to extract modification positions on the read sequence.
+ *
+ * @param mm - MM tag string (e.g., "C+m,2,2,1;A+a,0,3")
+ * @param fseq - Read sequence
+ * @param fstrand - Read strand (-1, 0, or 1)
+ * @returns Array of modification objects with positions
+ */
+export function getModPositions(mm, fseq, fstrand) {
+    const seqLength = fseq.length;
+    const isRev = fstrand === -1;
+    const mods = mm.split(';');
+    const result = [];
+    // Running offset into the flat ML probabilities array. Each group consumes
+    // (numPositions * numTypes) values, interleaved per position.
+    let mlBase = 0;
+    // Groups already walked, so a later group calling the same positions can reuse
+    // the array instead of walking the sequence again for it. Dorado's 5mCG_5hmCG
+    // model emits `C+h?;C+m?` — two groups, one canonical base, identical delta
+    // lists — so on real ONT output this drops one of every three sequence walks.
+    //
+    // The key is what the walk below READS: the canonical base and the delta list
+    // (`fseq` and `fstrand` are per read, not per group). It also carries the MM
+    // strand, which the walk does not currently read — deliberately stronger than
+    // needed, so the test cannot go quietly wrong if the walk ever becomes
+    // strand-aware.
+    //
+    // Parallel arrays rather than a Map: a read carries one to four groups, so a
+    // linear scan of char compares beats hashing a multi-kilobyte delta string,
+    // and they are allocated on the first walk so a single-group read builds none.
+    // `benches/sameBaseMerge.bench.ts` prices the whole test at inside the control
+    // on every fixture where it cannot fire, including one where every compare is
+    // forced to run to its final byte and then fail.
+    let seenKeys;
+    let seenDeltas;
+    let seenPositions;
+    for (const mod of mods) {
+        if (mod === '') {
+            continue;
+        }
+        const split = mod.split(',');
+        const basemod = split[0];
+        const { base, strand, typestr, mod: skipFlag, } = parseModHeader(basemod, mod);
+        const unknownSkip = skipFlag === '?';
+        // typestr can be multi-char lowercase e.g. 'mh' (5mC + 5hmC at same
+        // positions) or a ChEBI code e.g. '16061'. The rule is `isSingleModType`,
+        // shared with `getModTypes` so the two cannot disagree about what a tag
+        // declares.
+        const isSingleType = isSingleModType(typestr);
+        const nTypes = isSingleType ? 1 : typestr.length;
+        // ONE walk per GROUP, not per type. Every type in a combined code is called
+        // at the same positions — only probStart differs — so the walk below and the
+        // array it fills are shared, and the entries pushed after it point at the
+        // same array. `C+mh` used to walk the read sequence twice and allocate two
+        // identical arrays; `benches/modCombinedCode.bench.ts` (in the alignments
+        // plugin, where the fixture lives) prices that at **2.07x** on a synthesized
+        // `C+mh`, and at **1.16x** even on a single-type tag, where nothing is
+        // deduplicated and the win is the per-group closure this loop replaced.
+        //
+        // A combined code is the RARER of the two shapes this deduplicates, though.
+        // The reuse test below is the common one — see `seenKeys`.
+        //
+        // this logic based on parse_mm.pl from hts-specs
+        const splitLength = split.length;
+        const nPositions = splitLength - 1;
+        // Everything after the header — `,2,2,1`. V8 slices a long string in O(1),
+        // and the compare rejects on length before it reads a byte.
+        const deltas = mod.slice(basemod.length);
+        const key = base + strand;
+        let positions;
+        if (seenKeys !== undefined) {
+            for (let s = 0, n = seenKeys.length; s < n; s++) {
+                if (seenKeys[s] === key && seenDeltas[s] === deltas) {
+                    positions = seenPositions[s];
+                    break;
+                }
+            }
+        }
+        if (positions === undefined) {
+            const isN = base === 'N';
+            let currPos = 0;
+            // An MM tag may declare more calls of a base than the read has left. When
+            // that happens the walk has nowhere to put them, and every emitted value
+            // still has to be a valid index into the read — `getMethBins` indexes the
+            // sequence with these, and the CIGAR walk requires them ascending, so a
+            // position outside the read is read as a real one somewhere wrong rather
+            // than dropped. So the exhausted case clamps to the nearest valid index
+            // and stays there.
+            const endClamp = isRev ? 0 : Math.max(0, seqLength - 1);
+            // Pre-allocate and fill backwards on reverse strand to avoid a final
+            // reverse(). Forward stays a growing literal on purpose: filling
+            // `new Array(n)` leaves holey elements, and this array is read in the
+            // CIGAR walk's inner loop.
+            positions = isRev ? new Array(nPositions) : [];
+            let writeIndex = isRev ? nPositions - 1 : 0;
+            if (isRev) {
+                // Avoid revcom(fseq) by reading fseq from the back and complementing the
+                // expected char-code.
+                const baseCode = base.charCodeAt(0);
+                const targetCode = COMPLEMENT_CODE[baseCode] ?? baseCode;
+                for (let i = 1; i < splitLength; i++) {
+                    if (currPos >= seqLength) {
+                        positions[writeIndex--] = endClamp;
+                        continue;
+                    }
+                    let delta = +split[i];
+                    do {
+                        if (isN ||
+                            fseq.charCodeAt(seqLength - 1 - currPos) === targetCode) {
+                            delta--;
+                        }
+                        currPos++;
+                    } while (delta >= 0 && currPos < seqLength);
+                    positions[writeIndex--] = seqLength - currPos;
+                }
+            }
+            else {
+                // **Forward jumps, reverse steps, and the asymmetry is measured rather
+                // than assumed.** `indexOf` for a single character is a native scan, so
+                // finding the (delta+1)-th occurrence is delta+1 searches instead of one
+                // step per base — 1.560x on the sparse fixture and 1.247x on the dense
+                // one, parse phase, in `benches/mmDeltaJump.bench.ts`.
+                //
+                // `lastIndexOf` is NOT the mirror image: the same change on reverse
+                // reads measures **0.786x**, i.e. materially slower than stepping, so
+                // reverse keeps the loop above. Applying it to both, which is the
+                // obvious version, nets 1.054x where branching on strand nets 1.263x.
+                for (let i = 1; i < splitLength; i++) {
+                    const delta = +split[i];
+                    let at = -1;
+                    if (isN) {
+                        // 'N' matches every base, so the (delta+1)-th is delta ahead and
+                        // there is nothing to search for.
+                        at = currPos + delta;
+                        if (at >= seqLength) {
+                            at = -1;
+                        }
+                    }
+                    else {
+                        for (let k = 0; k <= delta; k++) {
+                            at = fseq.indexOf(base, currPos);
+                            if (at < 0) {
+                                break;
+                            }
+                            currPos = at + 1;
+                        }
+                    }
+                    if (at < 0) {
+                        currPos = seqLength;
+                        positions[writeIndex++] = endClamp;
+                    }
+                    else {
+                        currPos = at + 1;
+                        positions[writeIndex++] = at;
+                    }
+                }
+            }
+            if (seenKeys === undefined) {
+                seenKeys = [key];
+                seenDeltas = [deltas];
+                seenPositions = [positions];
+            }
+            else {
+                seenKeys.push(key);
+                seenDeltas.push(deltas);
+                seenPositions.push(positions);
+            }
+        }
+        if (isSingleType) {
+            result.push({
+                type: typestr,
+                base,
+                strand,
+                unknownSkip,
+                positions,
+                probStart: mlBase,
+                probStride: 1,
+            });
+        }
+        else {
+            // Multi-char lowercase: each character is a separate type
+            for (let j = 0, len = typestr.length; j < len; j++) {
+                result.push({
+                    type: typestr[j],
+                    base,
+                    strand,
+                    unknownSkip,
+                    positions,
+                    probStart: mlBase + j,
+                    probStride: nTypes,
+                });
+            }
+        }
+        // Unaffected by the reuse above. Two separate groups' ML values are
+        // consecutive, not interleaved, so each group consumes its own
+        // nPositions * nTypes whether or not it walked for them — which is why
+        // sharing the array leaves probStart/probStride alone.
+        mlBase += nPositions * nTypes;
+    }
+    return result;
+}

package/esm/getModProbabilities.d.ts

@@ -0,0 +1,30 @@
+import type { Feature } from '@jbrowse/core/util';
+/**
+ * #api
+ * Returns the probability value from the flat ML array for a modification's
+ * position. `idx` is the position's index within the mod's stored `positions`
+ * array; we recover its MM-tag order (reverse-strand reads store positions in
+ * descending order) and step into ML by `probStart + mmOrder * probStride`.
+ * `probStride` is >1 for combined codes (e.g. 'C+mh'), where ML values are
+ * interleaved per position.
+ */
+export declare function modProbAt(probabilities: number[] | undefined, probStart: number, probStride: number, isReverse: boolean, idx: number, posLen: number): number;
+/**
+ * #api
+ * Reads the ML tag from a feature and returns per-call modification
+ * probabilities scaled to 0..1.
+ */
+export declare function getModProbabilities(feature: Feature): number[] | undefined;
+/**
+ * #api
+ * The ML tag as its raw 0..255 bytes, without the scaling `getModProbabilities`
+ * applies.
+ *
+ * The byte is a LOSSLESS stand-in for the probability — every value on this
+ * path is exactly `(N + 0.5) / 256` — and it is monotonic in it, so anything
+ * that only compares probabilities (picking the most likely call at a
+ * position, testing a threshold) can work in bytes and divide once, at the end,
+ * for the few calls that survive. A caller that needs the numbers themselves
+ * still wants `getModProbabilities`.
+ */
+export declare function getModProbabilityBytes(feature: Feature): ArrayLike<number> | undefined;

package/esm/getModProbabilities.js

@@ -0,0 +1,63 @@
+import { getTagAlt } from './getTagAlt.js';
+/**
+ * #api
+ * Returns the probability value from the flat ML array for a modification's
+ * position. `idx` is the position's index within the mod's stored `positions`
+ * array; we recover its MM-tag order (reverse-strand reads store positions in
+ * descending order) and step into ML by `probStart + mmOrder * probStride`.
+ * `probStride` is >1 for combined codes (e.g. 'C+mh'), where ML values are
+ * interleaved per position.
+ */
+export function modProbAt(probabilities, probStart, probStride, isReverse, idx, posLen) {
+    const mmOrder = isReverse ? posLen - 1 - idx : idx;
+    return probabilities?.[probStart + mmOrder * probStride] ?? 0;
+}
+/**
+ * #api
+ * Reads the ML tag from a feature and returns per-call modification
+ * probabilities scaled to 0..1.
+ */
+export function getModProbabilities(feature) {
+    // ML is an 8-bit scaled probability. Per SAMtags, integer N covers the
+    // continuous range N/256..(N+1)/256, so the representative value is the
+    // midpoint (N + 0.5) / 256.
+    const ml = getTagAlt(feature, 'ML', 'Ml');
+    if (ml === undefined) {
+        return undefined;
+    }
+    // BAM returns ML:B:C as a Uint8Array; mapping with TypedArray.prototype.map
+    // would coerce each float result back to a uint8 (truncating every value to
+    // 0). Array.from(values, fn) always produces a plain number[]. A string ML
+    // (htsget/SAM text) is split on commas first.
+    const values = typeof ml === 'string' ? ml.split(',') : ml;
+    return Array.from(values, v => (+v + 0.5) / 256);
+}
+/**
+ * #api
+ * The ML tag as its raw 0..255 bytes, without the scaling `getModProbabilities`
+ * applies.
+ *
+ * The byte is a LOSSLESS stand-in for the probability — every value on this
+ * path is exactly `(N + 0.5) / 256` — and it is monotonic in it, so anything
+ * that only compares probabilities (picking the most likely call at a
+ * position, testing a threshold) can work in bytes and divide once, at the end,
+ * for the few calls that survive. A caller that needs the numbers themselves
+ * still wants `getModProbabilities`.
+ */
+export function getModProbabilityBytes(feature) {
+    const ml = getTagAlt(feature, 'ML', 'Ml');
+    if (ml === undefined) {
+        return undefined;
+    }
+    if (typeof ml !== 'string') {
+        return ml;
+    }
+    // htsget/SAM text gives a comma-separated string; parse it once into bytes
+    // rather than making every read of it coerce.
+    const parts = ml.split(',');
+    const out = new Uint8Array(parts.length);
+    for (let i = 0; i < parts.length; i++) {
+        out[i] = +parts[i];
+    }
+    return out;
+}

package/esm/getModTypes.d.ts

@@ -0,0 +1,31 @@
+/**
+ * How one MM header's type string splits into modification types.
+ *
+ * A multi-character LOWERCASE type string is a combined code — `C+mh` is 5mC
+ * and 5hmC called at the same positions — so each character is its own type. A
+ * single character, or anything starting outside a-z (a ChEBI number like
+ * `C+16061`, an uppercase ambiguity code like `C+C`), is one type whole.
+ *
+ * Stated once because `getModPositions` and `getModTypes` both have to split
+ * the same way: the second exists to answer "which types are here" without the
+ * first's work, and a disagreement would show as a modification the menu offers
+ * and the display cannot draw.
+ */
+export declare function isSingleModType(typestr: string): boolean;
+export interface ModTypeHeader {
+    type: string;
+    base: string;
+    strand: string;
+}
+/**
+ * #api
+ * The modification types an MM tag declares, from its headers alone.
+ *
+ * `getModPositions` answers this too, but on the way to placing every call: it
+ * walks the delta list against the read sequence, which is the expensive half
+ * and is only needed to DRAW marks. Anything that just wants to know what is in
+ * the file — which types to offer in a menu, whether a track carries
+ * modifications at all — wants this instead, and pays neither the walk nor the
+ * sequence decode that feeds it.
+ */
+export declare function getModTypes(mm: string): ModTypeHeader[];

package/esm/getModTypes.js

@@ -0,0 +1,48 @@
+import { parseModHeader } from './consts.js';
+/**
+ * How one MM header's type string splits into modification types.
+ *
+ * A multi-character LOWERCASE type string is a combined code — `C+mh` is 5mC
+ * and 5hmC called at the same positions — so each character is its own type. A
+ * single character, or anything starting outside a-z (a ChEBI number like
+ * `C+16061`, an uppercase ambiguity code like `C+C`), is one type whole.
+ *
+ * Stated once because `getModPositions` and `getModTypes` both have to split
+ * the same way: the second exists to answer "which types are here" without the
+ * first's work, and a disagreement would show as a modification the menu offers
+ * and the display cannot draw.
+ */
+export function isSingleModType(typestr) {
+    return typestr.charCodeAt(0) < 97 || typestr.length === 1;
+}
+/**
+ * #api
+ * The modification types an MM tag declares, from its headers alone.
+ *
+ * `getModPositions` answers this too, but on the way to placing every call: it
+ * walks the delta list against the read sequence, which is the expensive half
+ * and is only needed to DRAW marks. Anything that just wants to know what is in
+ * the file — which types to offer in a menu, whether a track carries
+ * modifications at all — wants this instead, and pays neither the walk nor the
+ * sequence decode that feeds it.
+ */
+export function getModTypes(mm) {
+    const out = [];
+    for (const group of mm.split(';')) {
+        if (group === '') {
+            continue;
+        }
+        const comma = group.indexOf(',');
+        const basemod = comma === -1 ? group : group.slice(0, comma);
+        const { base, strand, typestr } = parseModHeader(basemod, group);
+        if (isSingleModType(typestr)) {
+            out.push({ type: typestr, base, strand });
+        }
+        else {
+            for (let i = 0, l = typestr.length; i < l; i++) {
+                out.push({ type: typestr[i], base, strand });
+            }
+        }
+    }
+    return out;
+}

package/esm/getTagAlt.d.ts

@@ -0,0 +1,20 @@
+import type { Feature } from '@jbrowse/core/util';
+/**
+ * #api
+ * Read a single tag by name, using the feature's targeted tag accessor when it
+ * has one (BAM) and the full tags object otherwise (CRAM/synteny).
+ */
+export declare function getTag(feature: Feature, tag: string): unknown;
+/**
+ * #api
+ * Read a tag by its canonical name, falling back to a lowercase-suffixed alias
+ * (e.g. MM/Mm, ML/Ml) as emitted by some aligners.
+ *
+ * Prefers the feature's own one-pass alias lookup when it has one. The plain
+ * `getTag(tag) ?? getTag(alt)` form walks the record's whole tag block TWICE
+ * whenever neither name is present — which is every read in a file without base
+ * modifications, and this is called per read on every render. On jb2bench's
+ * 1000x.shortread that pair of walks was 12.9% of the whole BAM query, more
+ * than the CIGAR/SEQ/MD reads the pileup actually uses.
+ */
+export declare function getTagAlt(feature: Feature, tag: string, alt: string): unknown;

package/esm/getTagAlt.js

@@ -0,0 +1,31 @@
+/**
+ * #api
+ * Read a single tag by name, using the feature's targeted tag accessor when it
+ * has one (BAM) and the full tags object otherwise (CRAM/synteny).
+ */
+export function getTag(feature, tag) {
+    const getter = feature.getTag;
+    if (getter) {
+        return getter.call(feature, tag);
+    }
+    return feature.get('tags')?.[tag];
+}
+/**
+ * #api
+ * Read a tag by its canonical name, falling back to a lowercase-suffixed alias
+ * (e.g. MM/Mm, ML/Ml) as emitted by some aligners.
+ *
+ * Prefers the feature's own one-pass alias lookup when it has one. The plain
+ * `getTag(tag) ?? getTag(alt)` form walks the record's whole tag block TWICE
+ * whenever neither name is present — which is every read in a file without base
+ * modifications, and this is called per read on every render. On jb2bench's
+ * 1000x.shortread that pair of walks was 12.9% of the whole BAM query, more
+ * than the CIGAR/SEQ/MD reads the pileup actually uses.
+ */
+export function getTagAlt(feature, tag, alt) {
+    const both = feature.getTagAlt;
+    if (both) {
+        return both.call(feature, tag, alt);
+    }
+    return getTag(feature, tag) ?? getTag(feature, alt);
+}

package/esm/index.d.ts

@@ -0,0 +1,14 @@
+export { modificationRegex, parseModHeader } from './consts.ts';
+export { matchesCytosineContext } from './cytosineContext.ts';
+export type { CytosineContext } from './cytosineContext.ts';
+export { detectSimplexModifications } from './detectSimplexModifications.ts';
+export { forEachModRefPos } from './forEachModRefPos.ts';
+export { getMethBins, isMethylationFillType } from './getMethBins.ts';
+export type { ParsedModData } from './getMethBins.ts';
+export { getModPositions } from './getModPositions.ts';
+export type { ModWithPositions } from './getModPositions.ts';
+export { getModTypes, isSingleModType } from './getModTypes.ts';
+export type { ModTypeHeader } from './getModTypes.ts';
+export { getModProbabilities, getModProbabilityBytes, modProbAt, } from './getModProbabilities.ts';
+export { getTag, getTagAlt } from './getTagAlt.ts';
+export type { ModificationType } from './types.ts';

package/esm/index.js

@@ -0,0 +1,9 @@
+export { modificationRegex, parseModHeader } from './consts.js';
+export { matchesCytosineContext } from './cytosineContext.js';
+export { detectSimplexModifications } from './detectSimplexModifications.js';
+export { forEachModRefPos } from './forEachModRefPos.js';
+export { getMethBins, isMethylationFillType } from './getMethBins.js';
+export { getModPositions } from './getModPositions.js';
+export { getModTypes, isSingleModType } from './getModTypes.js';
+export { getModProbabilities, getModProbabilityBytes, modProbAt, } from './getModProbabilities.js';
+export { getTag, getTagAlt } from './getTagAlt.js';

package/esm/types.d.ts

@@ -0,0 +1,5 @@
+export interface ModificationType {
+    type: string;
+    base: string;
+    strand: string;
+}

package/esm/types.js

@@ -0,0 +1 @@
+export {};

package/package.json

@@ -0,0 +1,46 @@
+{
+  "name": "@jbrowse/modifications-utils",
+  "version": "4.1.14",
+  "type": "module",
+  "description": "Pure MM/ML base-modification tag parsers (methylation, etc.)",
+  "keywords": [
+    "jbrowse",
+    "jbrowse2",
+    "modifications",
+    "methylation",
+    "sam",
+    "bam"
+  ],
+  "license": "Apache-2.0",
+  "homepage": "https://jbrowse.org",
+  "bugs": "https://github.com/GMOD/jbrowse-components/issues",
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/GMOD/jbrowse-components.git",
+    "directory": "packages/modifications-utils"
+  },
+  "author": "JBrowse Team",
+  "main": "esm/index.js",
+  "files": [
+    "esm"
+  ],
+  "dependencies": {
+    "@jbrowse/cigar-utils": "^4.1.14",
+    "@jbrowse/core": "^4.3.0"
+  },
+  "publishConfig": {
+    "access": "public"
+  },
+  "sideEffects": false,
+  "scripts": {
+    "build:esm": "node ../../node_modules/typescript7/bin/tsc --build tsconfig.build.esm.json",
+    "build": "pnpm build:esm",
+    "test": "cd ../..; jest --passWithNoTests packages/modifications-utils",
+    "clean": "rimraf esm *.tsbuildinfo",
+    "prebuild": "pnpm clean"
+  },
+  "types": "esm/index.d.ts",
+  "exports": {
+    ".": "./esm/index.js"
+  }
+}