@fishka/seqio 0.3.0 → 0.4.0

package/README.md

@@ -4,7 +4,7 @@ Sequencing I/O — parsers and writers for bioinformatics file formats.
 
 Currently supports:
 
-- **ABIF** (`.ab1` / `.abi`) — chromatogram traces produced by ABI Sanger / fragment analysis instruments. Lossless round-trip, browser- and Node-compatible.
+- **ABIF** (`.ab1` / `.abi`) — chromatogram traces produced by ABI Sanger / fragment analysis instruments. Meaning-lossless round-trip (every entry preserved), browser- and Node-compatible.
 - **FASTA / FASTQ / .qual** — text writers (Phred+33), pure and format-agnostic.
 
 Planned: SCF; FASTA/FASTQ reading.
@@ -25,10 +25,12 @@ import { parseAbif } from '@fishka/seqio/abif';
 
 const result = parseAbif(uint8ArrayOrArrayBuffer, 'sample.ab1');
 
-result.baseCalls?.sequence; // "ACGT..."
+result.baseCalls?.sequence; // "ACGT..." (preferred/called version, upper-cased)
 result.baseCalls?.confidences; // [40, 38, 41, ...]
 result.baseCalls?.positions; // [13, 25, 38, ...] sample-point peaks
-result.chromatogram.basecalled.A; // raw int16 trace for the A channel
+result.baseCallVariants; // every PBAS version present: [{ version, role: 'called'|'edited', ... }]
+result.chromatogram.data9To12.A; // A-channel int16 trace of the DATA9..12 block
+result.chromatogram.data1To4.A; // A-channel int16 trace of the DATA1..4 block
 result.metadata.sampleName; // SMPL tag
 result.metadata.samplingRate; // SPAC tag (falls back to PLOC-derived spacing)
 ```
@@ -68,7 +70,10 @@ if (hasUsableQuality(qualities)) {
 ## Features
 
 - Browser- and Node-compatible (Uint8Array + DataView, no Node Buffer dependency).
-- Lossless round-trip: every directory entry preserved as raw payload.
+- Meaning-lossless round-trip: every directory entry preserved as a raw payload, so
+  `readAbif(writeAbif(f))` reproduces the same entries. The output is not byte-for-byte
+  identical to the input (payloads are repacked, `dataSize` normalized, MacBinary/padding
+  dropped); a byte-exact layout-preserving writer is a possible future opt-in.
 - MacBinary preamble support.
 - BioPython-compatible declared-vs-computed dataSize clamp.
 - PLOC read/written as unsigned int16 (preserves traces > 32k scans).

package/dist/abif/index.d.mts

@@ -7,10 +7,35 @@
 interface AbifFile {
     /** ABIF version, e.g. 101 for v1.01. */
     version: number;
+    /** The root directory (tdir) header, exactly as read — including any directory padding it declares. */
+    tdir: AbifDirectory;
     /** Directory entries in the original on-disk order. */
     entries: AbifEntry[];
     /** MacBinary preamble offset (128 if present, 0 otherwise). Preserved for diagnostics. */
     macBinaryOffset: number;
+    /**
+     * The 128-byte MacBinary preamble, verbatim — present only when {@link macBinaryOffset} is 128.
+     * Exposed so a raw reader can reproduce the wrapper, not just note that it existed.
+     */
+    macBinaryHeader?: Uint8Array;
+    /**
+     * Reserved header bytes [34..127] (94 bytes), verbatim. Usually zeros; exposed so a raw reader
+     * keeps the entire 128-byte header, not just magic/version/tdir.
+     */
+    headerReserved: Uint8Array;
+    /**
+     * Physical byte ranges not covered by the header, directory, or any entry payload — orphaned
+     * blocks left by editing tools, trailing padding, etc. Empty for a tightly-packed file. Exposed
+     * so a raw reader accounts for every byte; the chromatogram never depends on these.
+     */
+    unreferencedRanges: AbifByteRange[];
+}
+/** A contiguous run of file bytes at an absolute offset — used for {@link AbifFile.unreferencedRanges}. */
+interface AbifByteRange {
+    /** Absolute offset from the start of the file (includes any MacBinary preamble). */
+    offset: number;
+    /** The bytes in this range, verbatim. `bytes.length` is the range length. */
+    bytes: Uint8Array;
 }
 interface AbifEntry {
     /** 4-character tag name, e.g. "DATA", "PBAS". */
@@ -23,12 +48,72 @@ interface AbifEntry {
     elementType: number;
     /** Bytes per element. */
     elementSize: number;
-    /** Number of elements. */
+    /** Number of elements (reconciled: clamped to what the payload holds). */
     elementCount: number;
-    /** Raw payload bytes (length === elementCount * elementSize). */
+    /**
+     * Raw payload bytes. Length === the on-disk `dataSize` (the authoritative field), which for
+     * user/opaque types may differ from `elementCount * elementSize`.
+     */
     payload: Uint8Array;
     /** Opaque dataHandle field, usually 0. Preserved for round-trip. */
     dataHandle: number;
+    /**
+     * The directory fields exactly as they were on disk — present only when this entry was read from a
+     * file (absent for entries synthesized by setters/writeAbif). Lets consumers inspect the real record
+     * without our reconciliation.
+     */
+    raw?: AbifEntryRaw;
+}
+/** A directory entry's on-disk fields, verbatim, before any reconciliation applied by {@link readAbif}. */
+interface AbifEntryRaw {
+    /** `elementCount` (numElements) as written on disk. */
+    elementCount: number;
+    /** `dataSize` field as written on disk, in bytes. */
+    dataSize: number;
+    /** External payload offset relative to the ABIF start, or -1 when the payload is inline. */
+    dataOffset: number;
+    /** Whether the payload was stored inline (declared dataSize ≤ 4). */
+    inline: boolean;
+    /**
+     * The 4 raw bytes of the dataOffset/data slot, verbatim. For an external entry these are the
+     * big-endian offset; for an inline entry they are the value bytes plus any padding/stale bytes
+     * beyond `dataSize` — exposed so a raw reader loses no structure.
+     */
+    dataOffsetBytes: Uint8Array;
+}
+/**
+ * The root directory (`tdir`) header — the header's own directory entry, describing the directory
+ * block. Its fields are exposed like any other raw entry so a raw reader never loses them, even when
+ * `rawEntryCount` desyncs from `dataSize`.
+ */
+interface AbifDirectory {
+    /** Effective number of entries actually read — equals `entries.length`. */
+    entryCount: number;
+    /** tdir `numElements` verbatim, before reconciliation; the authoritative on-disk entry count. */
+    rawEntryCount: number;
+    /** tdir `elementType` (1023). */
+    elementType: number;
+    /** tdir `tagNumber` (usually 1). */
+    tagNumber: number;
+    /** Bytes per directory entry (always 28). */
+    entrySize: number;
+    /**
+     * Directory block size in bytes, from the tdir `dataSize` field. May exceed `entryCount * 28`
+     * when the file carries directory padding / extra bytes.
+     */
+    dataSize: number;
+    /** File offset (relative to the ABIF start) where the directory block begins. */
+    dataOffset: number;
+    /** The 4 raw bytes of the tdir's dataOffset field, verbatim. */
+    dataOffsetBytes: Uint8Array;
+    /** tdir `dataHandle` field, usually 0. */
+    dataHandle: number;
+    /**
+     * The raw directory-padding bytes: everything from the end of the last entry to the end of the
+     * directory block (`dataSize - entryCount*28`). Usually zeros; exposed so a raw reader keeps the
+     * whole directory structure, not just the entries.
+     */
+    paddingBytes: Uint8Array;
 }
 interface ChannelSignals {
     A: number[];
@@ -36,6 +121,8 @@ interface ChannelSignals {
     G: number[];
     T: number[];
 }
+/** Spec-defined role of a DATA<n> tag — see {@link dataChannelRole}. */
+type AbifDataChannelRole = 'trace' | 'telemetry' | 'other';
 /** Per-base chromatogram view. */
 interface Chromatogram {
     /** Per-base peak position in sample points (from PLOC). */
@@ -47,7 +134,39 @@ interface Chromatogram {
     /** Average peak spacing (samples per base), from SPAC. */
     samplingRate?: number;
 }
-/** Basecalls extracted from PBAS/PCON/PLOC under the chosen version. */
+/**
+ * One basecall version exactly as the file stores it. ABIF numbers the
+ * PBAS/PCON/PLOC tags by version, and the spec fixes what each number means:
+ *
+ *   - version 2 (`role: 'called'`) — the sequence as produced by the basecaller.
+ *   - version 1 (`role: 'edited'`) — the sequence after user hand-editing.
+ *   - any other version (`role: 'unknown'`) — the spec only defines 1 and 2, so
+ *     a vendor/future PBAS3+ is surfaced without a claimed role.
+ *
+ * A file may carry either or both, and the two can differ in content and even in
+ * length (edits insert/delete bases). {@link parseAbif} exposes every version it
+ * finds via {@link ParsedAbif.baseCallVariants} — picking which one to show or
+ * export is the consumer's call, not the parser's.
+ */
+type AbifBaseCallRole = 'called' | 'edited' | 'unknown';
+interface AbifBaseCallVariant {
+    /** Tag number of the PBAS/PCON/PLOC this variant came from (1, 2, or a vendor number). */
+    version: number;
+    /** Spec-defined role by tag number: 2 = basecaller-called, 1 = user-edited, else unknown. */
+    role: AbifBaseCallRole;
+    /** Bases from PBAS<version> as stored — case preserved, trailing NULs stripped, not normalized. */
+    sequence: string;
+    /** Per-base Q-scores from PCON<version>; `[]` when that version has no PCON. */
+    confidences: number[];
+    /** Per-base peak positions (sample indices) from PLOC<version>; `[]` when absent. */
+    positions: number[];
+}
+/**
+ * Convenience pointer to the preferred basecall version — the called one (PBAS2)
+ * when present, else whatever single version the file has. This is a spec-role
+ * choice (called over edited), not a quality judgement; see
+ * {@link ParsedAbif.baseCallVariants} for every version the file actually carries.
+ */
 interface AbifBaseCalls {
     /** Called bases (uppercase). */
     sequence: string;
@@ -68,34 +187,37 @@ interface AbifMetadata {
     runDate?: string;
     runTime?: string;
     samplingRate?: number;
+    /**
+     * Value of the RevC1 flag: whether the file declares its sequence already
+     * reverse-complemented. undefined when the tag is absent. Reported as-is — the
+     * consumer decides what to do with it.
+     */
+    reverseComplemented?: boolean;
     comments: string[];
 }
 /**
- * Full chromatogram bundle: all DATA channels, plus FWO_-aware A/C/G/T views.
- *
- * The two block views are named after their on-disk tag number ranges. Their
- * semantic content varies by instrument:
- *
- *   - DATA1..4  — on modern KB-basecaller-aware instruments (3130, 3500,
- *                  3730) these are POST-PROCESSED traces (mobility-corrected,
- *                  baseline-subtracted, color-separated). Basecallers operate
- *                  on these. On older simpler instruments DATA1..4 IS the raw
- *                  fluorescence.
- *   - DATA9..12 — RAW fluorescence on instruments that produce both blocks.
- *                  Absent on instruments that only write DATA1..8.
- *
- * Use {@link hasProcessedTraces} (data9To12 present) to detect whether
- * DATA1..4 has already been processed and bypass your own baseline/color
- * steps accordingly.
+ * All DATA channels plus FWO_-aware A/C/G/T views of the two dye-trace blocks.
+ *
+ * The block views are named after their on-disk tag ranges — nothing more. Which
+ * block is "raw" and which is "analyzed / processed" is an instrument-and-tool
+ * convention that the ABIF file does NOT state, so this parser refuses to label
+ * it. The consumer that needs to tell them apart has the primitives to decide:
+ * the per-block sample counts (channel lengths) and the basecall peak positions
+ * ({@link AbifBaseCalls.positions}); e.g. positions that overflow one block's
+ * length can only belong to the other.
+ *
+ * Per the ABIF spec, DATA5..8 are instrument telemetry (voltage / current / power
+ * / temperature), NOT dye traces — see {@link dataChannelRole}. They live in
+ * {@link dataChannels} but are excluded from the A/C/G/T views.
  */
 interface AbifChromatogramBundle {
     /** FWO_ value (e.g. "GATC"). */
     baseOrder: string;
-    /** All DATA tags by tagNumber → trace. */
+    /** All DATA tags by tagNumber → trace (dye traces AND telemetry). */
     dataChannels: Record<number, number[]>;
-    /** DATA1..4 mapped to A/C/G/T by FWO_. Post-processed on newer instruments, raw on older. */
+    /** DATA1..4 mapped to A/C/G/T by FWO_. */
     data1To4: ChannelSignals;
-    /** DATA9..12 mapped to A/C/G/T by FWO_. Raw fluorescence; absent on older instruments. */
+    /** DATA9..12 mapped to A/C/G/T by FWO_; empty when the file has no 9..12 block. */
     data9To12: ChannelSignals;
 }
 /** Rich result from {@link parseAbif} — everything the typical viewer needs. */
@@ -107,7 +229,10 @@ interface ParsedAbif {
     dirEntryCount: number;
     metadata: AbifMetadata;
     chromatogram: AbifChromatogramBundle;
+    /** Preferred basecall version (called over edited); convenience over {@link baseCallVariants}. */
     baseCalls?: AbifBaseCalls;
+    /** Every basecall version the file carries (called and/or edited), in version order. */
+    baseCallVariants: AbifBaseCallVariant[];
     /** All directory entries with their decoded payloads (best-effort by type). */
     entries: AbifDirEntry[];
 }
@@ -119,9 +244,15 @@ interface AbifDirEntry {
     elementType: number;
     elementTypeName: string;
     elementSize: number;
+    /** Reconciled element count (clamped to the declared dataSize when it was smaller). */
     elementCount: number;
+    /** `numElements` exactly as written on disk, before reconciliation. */
+    rawElementCount: number;
+    /** `dataSize` as written on disk, in bytes (not recomputed). */
     dataSize: number;
+    /** External payload offset relative to the ABIF start, or -1 when the payload is inline. */
     dataOffset: number;
+    /** Whether the payload was stored inline (declared dataSize ≤ 4). */
     inline: boolean;
     decoded: AbifDecodedValue;
     preview: string;
@@ -184,12 +315,14 @@ declare function tagNameFromInt32(n: number): string;
  *     8   2    elementType    (int16)
  *    10   2    elementSize    (int16)
  *    12   4    elementCount   (int32)
- *    16   4    dataSize       (int32; total payload bytes; spec says count*size)
+ *    16   4    dataSize       (int32; total payload bytes — authoritative; for
+ *                              well-formed entries equals count*size, but user/
+ *                              opaque types may differ, so we read by dataSize)
  *    20   4    dataOffset     (int32) OR inline data if dataSize <= 4
  *    24   4    dataHandle     (int32; usually 0)
  *
- * Inline rule (per ABIF spec): when count*size <= 4 the payload bytes are
- * stored directly in the dataOffset field (left-aligned, padded to 4 bytes).
+ * Inline rule (per ABIF spec): when the declared dataSize <= 4 the payload bytes
+ * are stored directly in the dataOffset field (left-aligned, padded to 4 bytes).
  *
  * MacBinary preamble: some ABIF files (older Mac-origin) start with a 128-byte
  * MacBinary header before the actual ABIF magic. We detect and skip it.
@@ -198,7 +331,13 @@ declare function tagNameFromInt32(n: number): string;
 declare const HEADER_SIZE = 128;
 declare const ENTRY_SIZE = 28;
 /**
- * Parse an ABIF file from raw bytes.
+ * Parse an ABIF file from raw bytes into its verbatim directory structure.
+ *
+ * This is the RAW source of truth: it reads the tdir header and every entry as
+ * stored — real dataSize, dataOffset, numElements (see `entry.raw`), the 4 inline
+ * bytes, and the tdir/directory metadata — and interprets nothing. For a
+ * high-level, opinionated view (typed channels, basecalls, metadata) layer
+ * {@link parseAbif} on top.
  *
  * Accepts Uint8Array (works in Node and the browser). Node's Buffer extends
  * Uint8Array, so `readAbif(buffer)` and `readAbif(new Uint8Array(arrayBuffer))`
@@ -212,14 +351,13 @@ declare function readAbif(bytes: Uint8Array): AbifFile;
  * Serialize an AbifFile back to a Uint8Array.
  *
  * Layout produced: header (128 B) + directory (N*28 B) + payload block.
- * External payloads are packed tightly in entry order. Inline payloads
- * (count*size <= 4) live entirely inside their directory entry.
- *
- * The output is not bit-identical to the input if the original had a different
- * physical layout (e.g. payloads before directory), but the *meaning*
- * round-trips: readAbif(writeAbif(f)) reproduces the same entries structurally.
+ * External payloads are packed tightly in entry order. Payloads <= 4 bytes are
+ * stored inline inside their directory entry.
  *
- * MacBinary preamble is not preserved by writeAbif.
+ * Meaning-lossless, not byte-exact: the payload bytes, tag fields and dataSize
+ * (= payload length) round-trip, but physical layout does not — payloads are
+ * repacked, directory/header padding and any MacBinary preamble are dropped. A
+ * byte-exact layout-preserving mode is a possible future opt-in.
  */
 declare function writeAbif(file: AbifFile): Uint8Array;
 /** Find an entry by name+number, or undefined. */
@@ -254,33 +392,46 @@ declare function getDataChannel(file: AbifFile, n: number): Int16Array | undefin
  */
 declare function getFwo(file: AbifFile): string;
 /**
- * True when the file carries BOTH DATA1..4 and DATA9..12. Newer ABI-style
- * instruments produce both: DATA1..4 is post-processed (mobility-corrected,
- * baseline-subtracted, color-separated) and DATA9..12 is raw fluorescence.
- * Older instruments produce only DATA1..4 (which IS the raw signal).
- *
- * Callers that re-process traces (basecallers) should detect this and bypass
- * their own baseline-subtraction / color-matrix steps when DATA1..4 is
- * already cleaned.
+ * Whether an FWO_ string is a genuine dye order: a permutation of A/C/G/T with all
+ * four bases distinct. `"GATC"` passes; `"AAAA"` (regex-valid but degenerate) does
+ * not — mapping four channels through it would collapse them onto one base.
  */
-declare function hasProcessedTraces(file: AbifFile): boolean;
+declare function isFwoPermutation(fwo: string): boolean;
 /**
- * Map from base letter ("A"|"C"|"G"|"T") to the DATA tag number that holds
- * its RAW fluorescence channel.
+ * Fact: the file carries a second dye-trace block, DATA9..12 (all four tags), in
+ * addition to DATA1..4. Reports presence only — it does NOT say which block is
+ * raw and which is analyzed/processed; that convention isn't stored in the file.
+ */
+declare function hasData9To12Block(file: AbifFile): boolean;
+/**
+ * Spec-defined role of a DATA<n> tag, limited to the numbers the ABIF spec names:
  *
- * ABIF stores up to 12 DATA tags. KB-basecaller-aware instruments (3130, 3500,
- * ...) use DATA1..4 for processed traces and DATA9..12 for raw. Older / simpler
- * instruments produce only DATA1..8 where DATA1..4 ARE the raw traces.
+ *   - `'trace'`     — dye-signal channels: DATA1..4 (raw dyes 1-4), DATA9..12
+ *                     (analyzed dyes 1-4), and the two optional 5th-dye blocks
+ *                     DATA105 (raw dye 5) and DATA205 (analyzed dye 5).
+ *   - `'telemetry'` — DATA5..8: instrument run telemetry (voltage, current,
+ *                     power, temperature), one value per scan — NOT dye signal.
+ *   - `'other'`     — any other DATA number. The spec does not enumerate higher
+ *                     extra-dye tags (106/206/…), so we don't claim a role for them.
  *
- * This helper always returns the DATA1..4 mapping (the convention used by
- * basecallers operating on raw signal). Use {@link hasProcessedTraces} to
- * detect whether DATA1..4 has been pre-processed and bypass baseline/color
- * steps accordingly.
+ * A fact from the ABIF specification, not an inference about content.
+ */
+declare function dataChannelRole(n: number): AbifDataChannelRole;
+/**
+ * Whether the file declares its sequence already reverse-complemented, from the
+ * RevC1 flag (int16, non-zero = true). undefined when RevC1 is absent. Reported
+ * as-is; the consumer decides how to act on it.
+ */
+declare function getReverseComplemented(file: AbifFile): boolean | undefined;
+/**
+ * Map from base letter ("A"|"C"|"G"|"T") to the DATA1..4 tag number that holds
+ * its channel, using the dye order declared by FWO_. If FWO_="GATC" then
+ * G→1, A→2, T→3, C→4.
  *
- * The dye-to-channel order within each block is given by FWO_. If
- * FWO_="GATC" then G→1, A→2, T→3, C→4.
+ * This follows the file's own FWO_ declaration for the DATA1..4 block; it makes
+ * no claim about whether that block is raw or processed.
  */
-declare function getRawChannelMap(file: AbifFile): Record<'A' | 'C' | 'G' | 'T', number>;
+declare function getChannelMap(file: AbifFile): Record<'A' | 'C' | 'G' | 'T', number>;
 /** Get PBAS sequence (prefer PBAS2 over PBAS1). undefined if neither present. */
 declare function getSequence(file: AbifFile): string | undefined;
 /**
@@ -374,6 +525,12 @@ declare function ensureRawDataChannels(file: AbifFile): void;
  * Parse an ABIF file into a high-level view: metadata, channels, basecalls,
  * and decoded directory entries.
  *
+ * This is the INTERPRETING layer — it makes convenience choices (FWO_ → "GATC"
+ * fallback, derived samplingRate, preferred/upper-cased PBAS2 baseCalls). It is
+ * not the raw structural truth: for that use {@link readAbif}, which reads the
+ * directory verbatim (raw dataSize/offset/counts, tdir, inline bytes) and makes
+ * no interpretation. `parseAbif` builds on top of it.
+ *
  * Accepts ArrayBuffer or Uint8Array (Buffer in Node works too — it extends
  * Uint8Array). The `fileName` argument is informational only; it's preserved
  * in the result.
@@ -384,4 +541,4 @@ declare function hasSignals(s: ChannelSignals): boolean;
 /** Length of the longest channel in a ChannelSignals bundle. */
 declare function channelMaxLength(s: ChannelSignals): number;
 
-export { type AbifBaseCalls, type AbifChromatogramBundle, type AbifDecodedValue, type AbifDirEntry, type AbifEntry, type AbifFile, type AbifMetadata, type ChannelSignals, type Chromatogram, ENTRY_SIZE, HEADER_SIZE, type ParsedAbif, averagePeakSpacing, channelMaxLength, ensureRawDataChannels, findEntries, findEntry, getConfidences, getDataChannel, getFwo, getPositions, getRawChannelMap, getSamplingRate, getSequence, hasProcessedTraces, hasSignals, parseAbif, readAbif, setAveragePeakSpacing, setConfidences, setPositions, setSequence, tagNameFromInt32, upsertEntry, writeAbif };
+export { type AbifBaseCallRole, type AbifBaseCallVariant, type AbifBaseCalls, type AbifByteRange, type AbifChromatogramBundle, type AbifDataChannelRole, type AbifDecodedValue, type AbifDirEntry, type AbifDirectory, type AbifEntry, type AbifEntryRaw, type AbifFile, type AbifMetadata, type ChannelSignals, type Chromatogram, ENTRY_SIZE, HEADER_SIZE, type ParsedAbif, averagePeakSpacing, channelMaxLength, dataChannelRole, ensureRawDataChannels, findEntries, findEntry, getChannelMap, getConfidences, getDataChannel, getFwo, getPositions, getReverseComplemented, getSamplingRate, getSequence, hasData9To12Block, hasSignals, isFwoPermutation, parseAbif, readAbif, setAveragePeakSpacing, setConfidences, setPositions, setSequence, tagNameFromInt32, upsertEntry, writeAbif };