edfcore 0.1.0

package/src/decode/digital.ts

@@ -0,0 +1,258 @@
+/**
+ * De-interleaving and sign extension.
+ *
+ * Layer 3. Sole owner of turning record bytes into sample values: the 2- and 3-byte two's
+ * complement expressions exist here and nowhere else in edfcore.
+ *
+ * Bitwise operators appear in this file and are correct here — a sample is 16 or 24 bits, so
+ * `|` and `<<` are exact on it. They are never applied to an OFFSET: a data offset in a
+ * multi-gigabyte BDF routinely exceeds 2^31, where every bitwise operator silently wraps it
+ * negative. Every offset below is plain arithmetic, exact to 2^53.
+ */
+
+import { DEFAULT_MAX_MATERIALIZE_BYTES } from '../constants.js';
+import { EdfBudgetError, EdfChannelNotFoundError, EdfRangeError } from '../errors.js';
+import type { EdfHeader, EdfSignal, RecordRange } from '../types.js';
+
+const BYTES_PER_INT32 = 4;
+
+/**
+ * The allocation ceiling for a decode that has to allocate.
+ *
+ * A trailing optional argument on functions whose signature is otherwise fixed by the public
+ * API, so passing nothing keeps the documented call shape and the 256 MiB default.
+ */
+export interface MaterializeOptions {
+  readonly maxMaterializeBytes?: number;
+}
+
+export interface DecodedDigital {
+  readonly digital: Int32Array;
+  /**
+   * Samples outside the DECLARED digital range, counted in the same pass that decodes them so
+   * `EdfChunkSignal.outOfDigitalRangeCount` costs nothing. edfcore never clamps: a non-zero
+   * count means the declared range is wrong, not that the samples are.
+   */
+  readonly outOfDigitalRangeCount: number;
+}
+
+/** Hoisted out of the two decode loops so neither reloads a property per sample. */
+interface DeinterleavePlan {
+  readonly recordCount: number;
+  readonly recordByteLength: number;
+  readonly recordByteOffset: number;
+  readonly samplesPerRecord: number;
+  readonly digitalLow: number;
+  readonly digitalHigh: number;
+}
+
+function assertWithinBudget(
+  requiredBytes: number,
+  what: string,
+  options: MaterializeOptions | undefined,
+): void {
+  const budgetBytes = options?.maxMaterializeBytes ?? DEFAULT_MAX_MATERIALIZE_BYTES;
+  if (requiredBytes <= budgetBytes) return;
+  throw new EdfBudgetError(
+    `Decoding ${what} needs a ${requiredBytes}-byte array, above the ${budgetBytes}-byte ` +
+      'maxMaterializeBytes budget, so the allocation was refused before it was attempted. ' +
+      'Next: decode fewer records per call, reuse an `out` array, or raise ' +
+      'options.maxMaterializeBytes.',
+    { requiredBytes, budgetBytes },
+  );
+}
+
+function signalAt(header: EdfHeader, signalIndex: number): EdfSignal {
+  const signal = header.signals[signalIndex];
+  if (signal !== undefined) return signal;
+  throw new EdfChannelNotFoundError(
+    `signalIndex ${signalIndex} is not one of the ${header.signals.length} signals in this ` +
+      'header. Next: pass an index taken from header.signals, or resolve one with ' +
+      'getSignal(header, label).',
+    { selector: signalIndex, availableLabels: header.signals.map((s) => s.label) },
+  );
+}
+
+/**
+ * `recordBytes` must be exactly the requested records and nothing else.
+ *
+ * Both halves matter. The range check catches a caller asking for records the file does not
+ * have; the length check catches a buffer that does not start where `records.start` says it
+ * does — which is unrecoverable rather than merely wrong, because nothing in the bytes
+ * identifies which record they came from.
+ */
+function assertRecordRange(header: EdfHeader, recordBytes: Uint8Array, records: RecordRange): void {
+  const available: RecordRange = { start: 0, count: header.recordCount };
+  const startValid = Number.isSafeInteger(records.start) && records.start >= 0;
+  const countValid = Number.isSafeInteger(records.count) && records.count >= 0;
+  if (!startValid || !countValid || records.start + records.count > header.recordCount) {
+    throw new EdfRangeError(
+      `records { start: ${records.start}, count: ${records.count} } is not inside the ` +
+        `${header.recordCount} data records this file contains. Next: clamp the range against ` +
+        'header.recordCount before decoding.',
+      { requested: records, available },
+    );
+  }
+
+  const expectedBytes = records.count * header.recordByteLength;
+  if (recordBytes.length === expectedBytes) return;
+  const wholeRecords =
+    header.recordByteLength > 0 ? Math.floor(recordBytes.length / header.recordByteLength) : 0;
+  throw new EdfRangeError(
+    `recordBytes is ${recordBytes.length} bytes, but ${records.count} records of ` +
+      `${header.recordByteLength} bytes each are exactly ${expectedBytes}. decodeDigital ` +
+      'cannot tell which record a differently sized buffer begins at, so it will not guess. ' +
+      'Next: pass the buffer returned by readRecordBytes(source, header, records) unmodified.',
+    { requested: records, available: { start: records.start, count: wholeRecords } },
+  );
+}
+
+/**
+ * A plain `RangeError`, deliberately not `EdfRangeError`: a signal block that overflows its own
+ * record means the header's offset arithmetic is inconsistent with its record size, which is an
+ * edfcore bug or a hand-built header — never the caller asking for something reasonable.
+ */
+function assertSignalFitsRecord(header: EdfHeader, signal: EdfSignal, blockBytes: number): void {
+  if (signal.recordByteOffset + blockBytes <= header.recordByteLength) return;
+  throw new RangeError(
+    `signal ${signal.index} occupies bytes [${signal.recordByteOffset}, ` +
+      `${signal.recordByteOffset + blockBytes}) of a ${header.recordByteLength}-byte record, ` +
+      'which does not fit. The header this was called with is internally inconsistent.',
+  );
+}
+
+/**
+ * The destination for `sampleCount` samples: `out` when it is large enough, otherwise a fresh
+ * array checked against the budget first.
+ *
+ * A longer `out` is narrowed with `subarray`, which shares its memory — the zero-allocation
+ * path survives — while keeping `result.length` equal to the true sample count, so no caller
+ * can mistake spare capacity for data.
+ */
+function resolveOut(
+  out: Int32Array | undefined,
+  sampleCount: number,
+  options: MaterializeOptions | undefined,
+): Int32Array {
+  if (out === undefined) {
+    assertWithinBudget(sampleCount * BYTES_PER_INT32, `${sampleCount} digital samples`, options);
+    return new Int32Array(sampleCount);
+  }
+  if (out.length < sampleCount) {
+    throw new RangeError(
+      `out holds ${out.length} samples but this decode produces ${sampleCount}. Next: size the ` +
+        'reused array to records.count * signal.samplesPerRecord, or omit it and let ' +
+        'decodeDigital allocate.',
+    );
+  }
+  return out.length === sampleCount ? out : out.subarray(0, sampleCount);
+}
+
+/** EDF: little-endian 16-bit two's complement. Returns the out-of-declared-range count. */
+function decodeInt16(bytes: Uint8Array, out: Int32Array, plan: DeinterleavePlan): number {
+  const { recordCount, recordByteLength, recordByteOffset, samplesPerRecord } = plan;
+  const low = plan.digitalLow;
+  const high = plan.digitalHigh;
+  let outOfRange = 0;
+  let write = 0;
+  for (let r = 0; r < recordCount; r++) {
+    const base = r * recordByteLength + recordByteOffset;
+    for (let k = 0; k < samplesPerRecord; k++) {
+      const p = base + k * 2;
+      // In bounds by construction: assertRecordRange pinned bytes.length to
+      // recordCount * recordByteLength, and assertSignalFitsRecord pinned this block inside a
+      // record. A per-sample undefined check would cost more than the decode itself.
+      // biome-ignore lint/style/noNonNullAssertion: bounds are established above.
+      let value = bytes[p]! | (bytes[p + 1]! << 8);
+      if (value & 0x8000) value -= 0x10000;
+      if (value < low || value > high) outOfRange++;
+      out[write] = value;
+      write++;
+    }
+  }
+  return outOfRange;
+}
+
+/** BDF: little-endian 24-bit two's complement, sign-extended from bit 23. */
+function decodeInt24(bytes: Uint8Array, out: Int32Array, plan: DeinterleavePlan): number {
+  const { recordCount, recordByteLength, recordByteOffset, samplesPerRecord } = plan;
+  const low = plan.digitalLow;
+  const high = plan.digitalHigh;
+  let outOfRange = 0;
+  let write = 0;
+  for (let r = 0; r < recordCount; r++) {
+    const base = r * recordByteLength + recordByteOffset;
+    for (let k = 0; k < samplesPerRecord; k++) {
+      const p = base + k * 3;
+      // biome-ignore lint/style/noNonNullAssertion: see decodeInt16.
+      let value = bytes[p]! | (bytes[p + 1]! << 8) | (bytes[p + 2]! << 16);
+      if (value & 0x800000) value -= 0x1000000;
+      if (value < low || value > high) outOfRange++;
+      out[write] = value;
+      write++;
+    }
+  }
+  return outOfRange;
+}
+
+/**
+ * Decode one signal out of a record range, with the out-of-declared-range tally.
+ *
+ * The count compares against `min`/`max` of the DECLARED digital minimum and maximum rather
+ * than against the pair as written: an inverted declaration (`digitalMinimum > digitalMaximum`)
+ * would otherwise report every sample in the file as out of range, which tells the caller
+ * nothing about the samples.
+ */
+export function decodeDigitalCounted(
+  header: EdfHeader,
+  recordBytes: Uint8Array,
+  records: RecordRange,
+  signalIndex: number,
+  out?: Int32Array,
+  options?: MaterializeOptions,
+): DecodedDigital {
+  const signal = signalAt(header, signalIndex);
+  assertRecordRange(header, recordBytes, records);
+
+  const bytesPerSample = header.bytesPerSample;
+  const samplesPerRecord = signal.samplesPerRecord;
+  assertSignalFitsRecord(header, signal, samplesPerRecord * bytesPerSample);
+
+  const sampleCount = records.count * samplesPerRecord;
+  const digital = resolveOut(out, sampleCount, options);
+  const plan: DeinterleavePlan = {
+    recordCount: records.count,
+    recordByteLength: header.recordByteLength,
+    // `records.start` located the bytes; inside the buffer record 0 is at offset 0.
+    recordByteOffset: signal.recordByteOffset,
+    samplesPerRecord,
+    digitalLow: Math.min(signal.digitalMinimum, signal.digitalMaximum),
+    digitalHigh: Math.max(signal.digitalMinimum, signal.digitalMaximum),
+  };
+
+  const outOfDigitalRangeCount =
+    bytesPerSample === 2
+      ? decodeInt16(recordBytes, digital, plan)
+      : decodeInt24(recordBytes, digital, plan);
+
+  return { digital, outOfDigitalRangeCount };
+}
+
+/**
+ * `recordBytes` must be exactly `records.count * header.recordByteLength` bytes and must begin
+ * at record `records.start`; anything else throws `EdfRangeError`. `out` is reused when
+ * supplied and long enough.
+ *
+ * The out-of-range tally reaches callers through `EdfChunkSignal.outOfDigitalRangeCount` — it is the same single
+ * pass, so a caller never needs a second one to produce it.
+ */
+export function decodeDigital(
+  header: EdfHeader,
+  recordBytes: Uint8Array,
+  records: RecordRange,
+  signalIndex: number,
+  out?: Int32Array,
+  options?: MaterializeOptions,
+): Int32Array {
+  return decodeDigitalCounted(header, recordBytes, records, signalIndex, out, options).digital;
+}

package/src/decode/physical.ts

@@ -0,0 +1,235 @@
+/**
+ * Digital counts to physical units.
+ *
+ * Layer 3. Sole owner of the scaling expression. The expression is PINNED — see `toPhysical`
+ * before changing anything in this file.
+ *
+ * Also home to `clampToDigitalRange`, which is a cross-validation tool and never part of a
+ * read: EDFlib clamps silently when it loads samples, edfcore does not, and reproducing that
+ * behaviour has to be something a caller asks for explicitly.
+ */
+
+import { DEFAULT_MAX_MATERIALIZE_BYTES } from '../constants.js';
+import { EdfBudgetError, EdfScalingError } from '../errors.js';
+import type { EdfDiagnosticCode, EdfSignal } from '../types.js';
+import type { MaterializeOptions } from './digital.js';
+
+export type { MaterializeOptions } from './digital.js';
+
+const BYTES_PER_FLOAT64 = 8;
+const BYTES_PER_INT32 = 4;
+
+/** The physical dimension that marks a log-compressed channel (EDFlib `edffloat.html`). */
+const LOG_TRANSFORMED_DIMENSION = 'Filtered';
+
+interface ScalingFailure {
+  readonly code: EdfDiagnosticCode;
+  /** Completes the sentence `signal 7 "EMG Chin" ...`. */
+  readonly reason: string;
+  readonly specReference: string | undefined;
+}
+
+function assertWithinBudget(
+  requiredBytes: number,
+  what: string,
+  options: MaterializeOptions | undefined,
+): void {
+  const budgetBytes = options?.maxMaterializeBytes ?? DEFAULT_MAX_MATERIALIZE_BYTES;
+  if (requiredBytes <= budgetBytes) return;
+  throw new EdfBudgetError(
+    `Producing ${what} needs a ${requiredBytes}-byte array, above the ${budgetBytes}-byte ` +
+      'maxMaterializeBytes budget, so the allocation was refused before it was attempted. ' +
+      'Next: convert fewer samples per call, reuse an `out` array, or raise ' +
+      'options.maxMaterializeBytes.',
+    { requiredBytes, budgetBytes },
+  );
+}
+
+/**
+ * Why `signal.scale` is `undefined`, re-derived from the signal itself.
+ *
+ * The header records the matching diagnostic at parse time, but a bare `EdfSignal` does not
+ * carry it, and `toPhysical` takes a signal. These four tests are the same ones `header/scale.ts`
+ * applies, IN THE SAME ORDER — a signal can fail two of them at once, and the order is what
+ * decides which cause is named, so the code reported here is the code the header reported.
+ * `buildScale` owns that order; this function follows it. A signal that fails none
+ * of them yet still has no scale gets `SCALE_UNAVAILABLE` rather than the nearest-looking code:
+ * naming the wrong cause is worse than admitting the cause is not on hand.
+ */
+function describeScalingFailure(signal: EdfSignal): ScalingFailure {
+  const digitalSpec =
+    'EDF+ additional specification 5: "Digital maximum must be larger than Digital minimum"';
+  if (signal.digitalMinimum === signal.digitalMaximum) {
+    return {
+      code: 'DEGENERATE_DIGITAL_RANGE',
+      reason:
+        `declares digitalMinimum == digitalMaximum == ${signal.digitalMinimum}, which makes ` +
+        'the gain a division by zero',
+      specReference: digitalSpec,
+    };
+  }
+  if (signal.physicalMinimum === signal.physicalMaximum) {
+    return {
+      code: 'DEGENERATE_PHYSICAL_RANGE',
+      reason:
+        `declares physicalMinimum == physicalMaximum == ${signal.physicalMinimum}, so every ` +
+        'sample would map to that one value',
+      specReference: undefined,
+    };
+  }
+  if (signal.digitalMinimum > signal.digitalMaximum) {
+    return {
+      code: 'INVERTED_DIGITAL_RANGE',
+      reason:
+        `declares digitalMinimum ${signal.digitalMinimum} above digitalMaximum ` +
+        `${signal.digitalMaximum}, and edfcore will not guess which one the writer meant`,
+      specReference: digitalSpec,
+    };
+  }
+  if (signal.physicalDimension.trim() === LOG_TRANSFORMED_DIMENSION) {
+    return {
+      code: 'LOG_TRANSFORMED_CHANNEL',
+      reason:
+        `has physical dimension "${LOG_TRANSFORMED_DIMENSION}", so its values are ` +
+        'log-compressed and the linear formula would be wrong by orders of magnitude',
+      specReference: 'EDFlib edffloat.html',
+    };
+  }
+  return {
+    code: 'SCALE_UNAVAILABLE',
+    reason: 'has no usable scale, and the header recorded the reason rather than the signal',
+    specReference: undefined,
+  };
+}
+
+function scalingError(signal: EdfSignal): EdfScalingError {
+  const failure = describeScalingFailure(signal);
+  const message =
+    `[${failure.code}] signal ${signal.index} "${signal.label}" ${failure.reason}, so ` +
+    'physical units are undefined for it. Raw fields: digital minimum ' +
+    `"${signal.raw.digitalMinimum}", digital maximum "${signal.raw.digitalMaximum}", ` +
+    `physical minimum "${signal.raw.physicalMinimum}", physical maximum ` +
+    `"${signal.raw.physicalMaximum}", physical dimension "${signal.raw.physicalDimension}". ` +
+    (failure.specReference === undefined ? '' : `${failure.specReference}. `) +
+    'Next: decodeDigital() still works on this signal; edfcore will not invent a gain.';
+  return new EdfScalingError(message, {
+    code: failure.code,
+    signalIndex: signal.index,
+    label: signal.label,
+  });
+}
+
+/**
+ * Float64 by contract, never Float32.
+ *
+ * Float32 carries 24 significand bits, so a 24-bit BDF sample scaled into it loses about a
+ * quarter of a quantisation step — a rounding error a quarter the size of the smallest real
+ * difference the hardware can express.
+ */
+function resolveFloat64Out(
+  out: Float64Array | undefined,
+  length: number,
+  options: MaterializeOptions | undefined,
+): Float64Array {
+  if (out === undefined) {
+    assertWithinBudget(length * BYTES_PER_FLOAT64, `${length} physical samples`, options);
+    return new Float64Array(length);
+  }
+  if (out.length < length) {
+    throw new RangeError(
+      `out holds ${out.length} samples but this conversion produces ${length}. Next: size the ` +
+        'reused array to digital.length, or omit it and let toPhysical allocate.',
+    );
+  }
+  // A longer `out` is narrowed to a view over its own memory, so reuse still allocates no
+  // samples while `result.length` stays equal to the real sample count.
+  return out.length === length ? out : out.subarray(0, length);
+}
+
+function resolveInt32Out(
+  out: Int32Array | undefined,
+  length: number,
+  options: MaterializeOptions | undefined,
+): Int32Array {
+  if (out === undefined) {
+    assertWithinBudget(length * BYTES_PER_INT32, `${length} clamped samples`, options);
+    return new Int32Array(length);
+  }
+  if (out.length < length) {
+    throw new RangeError(
+      `out holds ${out.length} samples but this clamp produces ${length}. Next: size the ` +
+        'reused array to digital.length, or omit it and let clampToDigitalRange allocate.',
+    );
+  }
+  return out.length === length ? out : out.subarray(0, length);
+}
+
+/**
+ * `physical = bitValue * (offset + digital)`, in float64 throughout.
+ *
+ * THIS EXPRESSION IS PINNED AND MUST NOT BE "SIMPLIFIED". It is numerically worse than
+ * `physicalMinimum + (digital - digitalMinimum) * gain`, and that is not an accident: it is
+ * EDFlib's exact form, kept verbatim so edfcore reproduces pyEDFlib/EDFlib float64 output
+ * bit for bit. The two forms disagree by up to ~9.3e-10 LSB — ten orders of magnitude below
+ * the quantisation floor, and on asymmetric ranges they differ on nearly half the samples by
+ * one ULP. Rewriting this line breaks the golden-value tests, and rightly so.
+ *
+ * Throws `EdfScalingError` when `signal.scale` is `undefined`. edfcore never fabricates a gain,
+ * and `decodeDigital` keeps working on such a signal.
+ */
+export function toPhysical(
+  signal: EdfSignal,
+  digital: ArrayLike<number>,
+  out?: Float64Array,
+  options?: MaterializeOptions,
+): Float64Array {
+  const scale = signal.scale;
+  if (scale === undefined) throw scalingError(signal);
+
+  const length = digital.length;
+  const physical = resolveFloat64Out(out, length, options);
+  const bitValue = scale.bitValue;
+  const offset = scale.offset;
+  for (let i = 0; i < length; i++) {
+    // biome-ignore lint/style/noNonNullAssertion: i < digital.length, per the ArrayLike contract.
+    physical[i] = bitValue * (offset + digital[i]!);
+  }
+  return physical;
+}
+
+/**
+ * Clamp to the declared digital range. POST-HOC ONLY — nothing on the read path calls this.
+ *
+ * It exists to reproduce a clamping consumer (EDFlib clamps silently on read; edfcore does not)
+ * when cross-validating against one. Clamping to `[min(digMin, digMax), max(digMin, digMax)]`
+ * rather than to `[digMin, digMax]` matters for an inverted declaration, where the naive bounds
+ * are empty and collapse every sample onto a single value.
+ */
+export function clampToDigitalRange(
+  signal: EdfSignal,
+  digital: Int32Array,
+  out?: Int32Array,
+  options?: MaterializeOptions,
+): Int32Array {
+  const low = Math.min(signal.digitalMinimum, signal.digitalMaximum);
+  const high = Math.max(signal.digitalMinimum, signal.digitalMaximum);
+  if (!Number.isFinite(low) || !Number.isFinite(high)) {
+    // Every comparison against a NaN bound is false, so proceeding would return the input
+    // unchanged while claiming to have clamped it.
+    throw new RangeError(
+      `signal ${signal.index} "${signal.label}" declares digital minimum ` +
+        `"${signal.raw.digitalMinimum}" and digital maximum "${signal.raw.digitalMaximum}", ` +
+        'which do not both parse as numbers, so there is no range to clamp to. Next: read ' +
+        'header.diagnostics for this signal.',
+    );
+  }
+
+  const length = digital.length;
+  const clamped = resolveInt32Out(out, length, options);
+  for (let i = 0; i < length; i++) {
+    // biome-ignore lint/style/noNonNullAssertion: i < digital.length.
+    const value = digital[i]!;
+    clamped[i] = value < low ? low : value > high ? high : value;
+  }
+  return clamped;
+}