edf2csv 0.8.75 → 0.8.77

package/dist/edf/annotations.js

@@ -64,6 +64,30 @@ export function decodeRecordAnnotations(bytes, recordIndex, carriesTimekeeping =
     if (!ArrayBuffer.isView(bytes)) {
         throw new OptionError(`bytes must be one record's annotation channel, got ${describeValue(bytes)}.`);
     }
+    /*
+      And the second argument, which this function does not read — it writes it.
+  
+      `recordIndex` is copied onto every `Annotation` this call produces, and `Annotation`
+      declares it a number. Nothing checked that it was one, so whatever was passed came back
+      out in the event list:
+  
+          decodeRecordAnnotations(bytes, 'x').annotations[0].recordIndex   // 'x'
+          decodeRecordAnnotations(bytes).annotations[0].recordIndex        // absent
+  
+      The second is the ordinary mistake, since the page shows this called as
+      `decodeRecordAnnotations(bytes, recordIndex)` beside `annotationBytes(batch, recordOffset,
+      signal)` and the two take their record different ways. It produces events with the field
+      missing altogether, which `record_index` in annotations.csv is written from, and which a
+      caller joining events back to records reads as a record of `undefined`.
+  
+      A whole non-negative number, like the record bounds `readRecords` and `sampleAt` take:
+      records are counted from zero, and this one is a position in the file rather than in a
+      batch, so there is no upper bound to hold it to here.
+    */
+    if (!Number.isInteger(recordIndex) || recordIndex < 0) {
+        throw new OptionError(`recordIndex must be the record's whole-number position in the file, got ` +
+            `${describeValue(recordIndex)}. It is written onto every annotation this returns.`);
+    }
     const annotations = [];
     let recordStart = null;
     let isFirstTal = true;

package/dist/edf/annotations.js.map

@@ -1 +1 @@
-{"version":3,"file":"annotations.js","sourceRoot":"","sources":["../../src/edf/annotations.ts"],"names":[],"mappings":"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","sourcesContent":["/**\n * EDF+ annotation (TAL) decoding.\n *\n * The annotations channel stores UTF-8 text in place of samples. Its bytes are a\n * run of Time-stamped Annotation Lists, each terminated by a NUL, with the rest\n * of the channel NUL-padded:\n *\n *   +<onset>[<0x15><duration>]<0x14><text><0x14>...<0x00>\n *\n * The first TAL of every data record carries that record's start time; that is how an EDF+D\n * file states where each record actually sits in time. It may carry event text after that,\n * which the specification allows and writers use, so an unreadable one costs a position and\n * whatever events went with it — see `malformedTimekeepingWithText`.\n *\n *   +1.25<0x15>0.5<0x14>Seizure onset<0x14><0x00>\n */\n\nimport { decodeText } from './bytes.js';\n// Crossing into convert/ as header.ts and reader.ts already do: the check belongs to the call.\nimport { OptionError, describeValue } from '../convert/options.js';\n\nconst SEP_TEXT = 0x14; // separates onset/duration from text, and text from text\nconst SEP_DURATION = 0x15; // separates onset from duration\nconst TAL_END = 0x00;\n\nconst TEXT_SEP_CHAR = String.fromCharCode(SEP_TEXT);\nconst DURATION_SEP_CHAR = String.fromCharCode(SEP_DURATION);\n\n/**\n * What EDF+ allows a TAL duration to look like, which is less than `Number()` allows.\n *\n * The header parser's DECIMAL_FIELD makes this argument at length and lists where the same\n * mistake had already been fixed: `#0x2` reaching channel 2 through `--channels`,\n * `--decimals 0o5` writing five places, `--jobs 0x10` running sixteen, a physical maximum of\n * `0x64` setting a whole calibration to 100. The annotation duration is the one field it did\n * not reach. `+1<0x15>0x10<0x14>Seizure` was exported with a duration_s of 16 — sixteen\n * seconds no writer wrote, in a column the documentation defines as the length the file\n * stated, exit 0 and no diagnostic. `0b11` is three the same way.\n *\n * A duration this cannot read is already a thing the parser knows how to say: the field is\n * left empty, counted, and reported. Sending these there costs nothing and states the truth,\n * which is that the file wrote something that is not a number of seconds.\n */\nconst DECIMAL_DURATION = /^[+-]?(?:\\d+(?:\\.\\d*)?|\\.\\d+)(?:[eE][+-]?\\d+)?$/u;\n\nexport interface Annotation {\n  /** Seconds from the start of the recording. */\n  onset: number;\n  /**\n   * Seconds, or null when the TAL stated no duration that could be read.\n   *\n   * Null covers two cases the file distinguishes and this field does not: a TAL that omitted\n   * the duration, and a TAL that stated one which is not a number. They are told apart by\n   * `unreadableDurations`, which is what raises the warning; the value itself has nowhere\n   * honest to put \"the file said `abc`\".\n   */\n  duration: number | null;\n  text: string;\n  /** Index of the data record this annotation was stored in. */\n  recordIndex: number;\n  /**\n   * True when the file stated a duration that could not be read.\n   *\n   * `duration` is null either way, which is the ambiguity the counts beside it exist to\n   * flag — and those counts were of the whole file while `annotations.csv` is filtered to\n   * the requested window. A conversion of one second of a recording warned that \"1\n   * annotation states a duration that is not a number, so its duration_s cell is empty\"\n   * about an event two seconds outside it, and failed `--strict` for it. Carrying the fact\n   * on the event lets the count be taken where the window has already been applied.\n   */\n  durationUnreadable?: boolean;\n}\n\nexport interface DecodedRecordAnnotations {\n  /** Record start time in seconds, from the leading timekeeping TAL. */\n  recordStart: number | null;\n  annotations: Annotation[];\n  /** Non-empty chunks that were not valid TALs, so the caller can report them. */\n  malformed: number;\n  /** Unreadable TALs in first position, which carry a record's start time, not an event. */\n  malformedTimekeeping: number;\n  /**\n   * How many of those also carried event text, and so lost events as well as a position.\n   *\n   * A TAL in first position holds the record's start time, and may hold events after it — the\n   * specification allows both in the one entry, and writers use it. When such a TAL cannot be\n   * parsed, both are gone, and counting it only as lost timekeeping let the warning beside it\n   * say \"No event was lost\" over a conversion that had just dropped four of them.\n   *\n   * Counted rather than inferred, because the sentence has to be right in the ordinary case\n   * too: a bare timekeeping TAL really does lose no event, and that is nearly all of them.\n   */\n  malformedTimekeepingWithText: number;\n  /**\n   * Events kept whose stated duration could not be read.\n   *\n   * Counted apart again, for the same reason the two above are: the entry was exported and\n   * nothing about it is missing except the one field, so calling it an entry that \"could not\n   * be exported\" describes a loss that did not happen and hides the one that did.\n   */\n  unreadableDurations: number;\n  /**\n   * Events kept whose stated duration is a readable number below zero.\n   *\n   * Separate from the count above because the value survives: it is written to the CSV as\n   * the file gave it, and what is wrong with it is arithmetic rather than parsing.\n   */\n  negativeDurations: number;\n}\n\n/**\n * Decode one data record's annotation bytes.\n *\n * Malformed TALs are skipped rather than thrown, because a single bad annotation\n * should not cost the user an entire conversion. The count of skipped chunks is\n * returned so the caller can tell the user rather than losing them in silence.\n */\nexport function decodeRecordAnnotations(\n  bytes: Uint8Array,\n  recordIndex: number,\n  carriesTimekeeping = true,\n): DecodedRecordAnnotations {\n  /*\n    The bytes, checked before anything is read out of them.\n\n    The api page offers this function on its own — \"For decoding annotation bytes yourself,\n    `decodeRecordAnnotations(bytes, recordIndex)` handles one record's worth of the channel\" —\n    so it is reached by a caller holding a slice they cut themselves. Hand it anything but a\n    typed array and the loop below reported the shape of its own local:\n\n        decodeRecordAnnotations(Buffer.from(text).toString(), 0)\n        TypeError: bytes.subarray is not a function\n\n    which names a variable inside this function and a method the caller never called. The\n    same `OptionError` the two path-taking exports raise, for the reason given there: the call\n    is what is wrong, not the recording.\n  */\n  if (!ArrayBuffer.isView(bytes)) {\n    throw new OptionError(\n      `bytes must be one record's annotation channel, got ${describeValue(bytes)}.`,\n    );\n  }\n  const annotations: Annotation[] = [];\n  let recordStart: number | null = null;\n  let isFirstTal = true;\n  let malformed = 0;\n  let malformedTimekeeping = 0;\n  let malformedTimekeepingWithText = 0;\n  let unreadableDurations = 0;\n  let negativeDurations = 0;\n\n  let start = 0;\n  for (let i = 0; i <= bytes.length; i++) {\n    if (i !== bytes.length && bytes[i] !== TAL_END) continue;\n\n    if (i > start) {\n      const chunk = bytes.subarray(start, i);\n      /*\n        Padding is not a lost annotation.\n\n        The spec pads the slot with NUL, which the loop above already skips because it is what\n        separates one TAL from the next. Writers pad with spaces instead, and a run of spaces\n        after the last TAL is a non-empty chunk — so a file holding one perfectly readable\n        event, exported in full, was told \"2 annotation entries were unreadable and could not\n        be exported\", one per record. Nothing was lost. Under --strict that is a failed run\n        over the whitespace at the end of a slot.\n\n        Only whitespace. A chunk of anything else that does not parse is a real loss and is\n        still counted, which is the case this warning exists for.\n      */\n      if (chunk.every(isPaddingByte)) {\n        start = i + 1;\n        continue;\n      }\n      const parsed = parseTal(chunk, recordIndex);\n\n      // The timekeeping TAL is the one in first POSITION, whether or not it decodes.\n      // Clearing this flag only on a successful parse meant that an unreadable first TAL\n      // promoted the next ordinary annotation to timekeeping, and its onset silently\n      // became the record's start time — shifting every sample in that record. Leaving\n      // recordStart null instead is what the caller already handles, with a fallback\n      // timestamp and an ANNOTATION_DECODE_FAILED warning naming the record.\n      /*\n        Only one annotation channel carries a record's start time.\n\n        This flagged the first TAL of *every* annotation channel as timekeeping. In a second\n        channel the first TAL is an ordinary event — so when one failed to parse, the event\n        was dropped and counted as a lost timekeeping entry, which produced the warning\n        \"3 data records carry a timekeeping annotation that could not be read\" followed by\n        \"No event was lost\". Three events had been lost, and the timekeeping in that file was\n        perfectly readable. Both sentences false, about the same three records.\n      */\n      const isTimekeeping = isFirstTal && carriesTimekeeping;\n      isFirstTal = false;\n\n      if (parsed) {\n        if (isTimekeeping) recordStart = parsed.onset;\n        for (const annotation of parsed.annotations) annotations.push(annotation);\n        unreadableDurations += parsed.unreadableDurations;\n        negativeDurations += parsed.negativeDurations;\n      } else {\n        /*\n          Counted apart from the events, because losing one is a different loss.\n\n          A timekeeping TAL is never exported — it says where the record sits, not what\n          happened — so counting it among the entries that \"could not be exported\" both\n          overstated what was lost from annotations.csv and said nothing about the thing that\n          actually went missing, which is a record's position in time. A file with one\n          unreadable timekeeping TAL and three perfectly good events reported \"1 annotation\n          entry was unreadable and could not be exported\" while exporting all three.\n\n          The other direction is just as wrong. A first-position TAL may carry events after\n          the start time, and when one of those cannot be parsed the events go with it — so\n          counting it only as lost timekeeping produced the opposite false sentence: \"No event\n          was lost\", printed over a run whose annotations.csv had gone from six rows to two.\n          It is one entry that could not be exported and one record with no position, and it\n          is counted as both.\n        */\n        if (isTimekeeping) {\n          malformedTimekeeping++;\n          if (carriesAnnotationText(chunk)) {\n            malformedTimekeepingWithText++;\n            malformed++;\n          }\n        } else malformed++;\n      }\n    }\n    start = i + 1;\n  }\n\n  return {\n    recordStart,\n    annotations,\n    malformed,\n    malformedTimekeeping,\n    malformedTimekeepingWithText,\n    unreadableDurations,\n    negativeDurations,\n  };\n}\n\ninterface ParsedTal {\n  onset: number;\n  annotations: Annotation[];\n  /** How many of those annotations carry a duration the file stated and this could not read. */\n  unreadableDurations: number;\n  /** How many carry a duration that read as a number below zero. */\n  negativeDurations: number;\n}\n\n/**\n * Whether a TAL that could not be parsed still carried event text.\n *\n * A TAL is `onset[<0x15>duration]<0x14>text<0x14>...`, so anything other than padding after\n * the first 0x14 is a description the file meant to export. Read from the raw chunk, since by\n * the time this is asked the parse has already failed and there is no structure to consult.\n */\nfunction carriesAnnotationText(chunk: Uint8Array): boolean {\n  let afterSeparator = false;\n  for (const byte of chunk) {\n    if (byte === 0x14) {\n      afterSeparator = true;\n      continue;\n    }\n    if (afterSeparator && !isPaddingByte(byte)) return true;\n  }\n  return false;\n}\n\n/** Space, tab, CR, LF or NUL — what a writer fills the rest of the slot with. */\nfunction isPaddingByte(byte: number): boolean {\n  return byte === 0x20 || byte === 0x09 || byte === 0x0d || byte === 0x0a || byte === 0x00;\n}\n\nfunction parseTal(chunk: Uint8Array, recordIndex: number): ParsedTal | null {\n  // The onset must be explicitly signed; anything else is not a TAL.\n  const first = chunk[0];\n  if (first !== 0x2b /* + */ && first !== 0x2d /* - */) return null;\n\n  const text = decodeText(chunk);\n  const parts = text.split(TEXT_SEP_CHAR);\n  const head = parts[0] ?? '';\n\n  let onsetText = head;\n  let durationText: string | null = null;\n  const durationSep = head.indexOf(DURATION_SEP_CHAR);\n  if (durationSep >= 0) {\n    onsetText = head.slice(0, durationSep);\n    durationText = head.slice(durationSep + 1);\n  }\n\n  const onset = Number(onsetText);\n  if (!Number.isFinite(onset)) return null;\n\n  /*\n    A duration the file stated and this could not read is not the same as no duration.\n\n    Both came out as `null` and so as an empty `duration_s` cell, which the documentation\n    defines as meaning the file gave no duration — so an event whose duration was written as\n    `abc` was exported as an event with no duration, indistinguishable from one beside it\n    that genuinely had none, and nothing anywhere said a field had been dropped. The onset is\n    already held to this standard: one that is not a number costs the whole TAL and is\n    reported. A duration is one field of an otherwise readable event, so the event is kept —\n    but it is counted, and the run says so.\n  */\n  /*\n    Fill in the field is an absent duration, not a zero.\n\n    `Number` reads a run of whitespace as 0 — the rule that makes `Number('')` zero, one step\n    along — so a TAL whose duration field held nothing but the writer's padding was exported\n    with a `duration_s` of `0`, byte-identical to the event beside it whose file really did\n    say `0`. An instantaneous event is a claim about the recording, and no writer made it;\n    inventing it is the one thing this tool does not do, and it did so in silence, exit 0.\n\n    The empty field this condition already declines is the same field without the fill in it,\n    so padding takes the same answer: the file stated no duration. `trim` empties exactly the\n    strings `Number` would otherwise have swallowed into a zero, so `  2.5  ` still reads as\n    2.5 and `abc` is still counted as unreadable below.\n  */\n  let duration: number | null = null;\n  let durationUnreadable = false;\n  if (durationText !== null && durationText.trim() !== '') {\n    const stated = durationText.trim();\n    const d = DECIMAL_DURATION.test(stated) ? Number(stated) : NaN;\n    if (Number.isFinite(d)) duration = d;\n    else durationUnreadable = true;\n  }\n\n  /*\n    A duration is a length of time, and a length below zero is not one.\n\n    The value is kept and written as the file gave it — inventing a zero, or dropping it to\n    an empty cell, would put a number in annotations.csv that no writer wrote, which is the\n    one thing this tool does not do. But it is reported, because everything downstream\n    quietly does the wrong thing with it: the recipe this documentation gives for the samples\n    an event covers is `onset_s + duration_s`, which for a duration of -3 ends three seconds\n    before the event starts and selects nothing at all, with no error anywhere.\n  */\n  const durationNegative = duration !== null && duration < 0;\n\n  const annotations: Annotation[] = [];\n  for (const raw of parts.slice(1)) {\n    /*\n      A trailing separator yields an empty segment; a timekeeping TAL is all empty.\n\n      Whitespace counts as empty here, which it did not, and the padding at the end of the\n      slot became an event. The chunk loop above already refuses to call a run of spaces a\n      lost annotation — but it only sees chunks between NULs, and a writer that leaves its\n      last TAL unterminated puts the fill *inside* the chunk, after the final 0x14. Split on\n      that separator it is a text segment like any other, and \" \" is not \"\".\n\n      A file holding two events exported four rows: `0.5,,Lights off,0` and `0.5,,   ,0`,\n      twice, sharing the real event's onset, with annotations_written and the run summary\n      agreeing with the inflated number and nothing warned. An event whose description is\n      genuinely nothing but spaces cannot be told from fill, and inventing rows out of fill\n      is the worse of the two answers.\n    */\n    if ([...raw].every((c) => isPaddingByte(c.charCodeAt(0)))) continue;\n    annotations.push({\n      onset,\n      duration,\n      text: raw,\n      recordIndex,\n      ...(durationUnreadable ? { durationUnreadable: true } : {}),\n    });\n  }\n\n  // Per event rather than per TAL: one TAL may carry several texts, and each becomes a row\n  // of annotations.csv with the same cell in it.\n  return {\n    onset,\n    annotations,\n    unreadableDurations: durationUnreadable ? annotations.length : 0,\n    negativeDurations: durationNegative ? annotations.length : 0,\n  };\n}\n\nexport { SEP_TEXT, SEP_DURATION, TAL_END };\n"]}
+{"version":3,"file":"annotations.js","sourceRoot":"","sources":["../../src/edf/annotations.ts"],"names":[],"mappings":"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","sourcesContent":["/**\n * EDF+ annotation (TAL) decoding.\n *\n * The annotations channel stores UTF-8 text in place of samples. Its bytes are a\n * run of Time-stamped Annotation Lists, each terminated by a NUL, with the rest\n * of the channel NUL-padded:\n *\n *   +<onset>[<0x15><duration>]<0x14><text><0x14>...<0x00>\n *\n * The first TAL of every data record carries that record's start time; that is how an EDF+D\n * file states where each record actually sits in time. It may carry event text after that,\n * which the specification allows and writers use, so an unreadable one costs a position and\n * whatever events went with it — see `malformedTimekeepingWithText`.\n *\n *   +1.25<0x15>0.5<0x14>Seizure onset<0x14><0x00>\n */\n\nimport { decodeText } from './bytes.js';\n// Crossing into convert/ as header.ts and reader.ts already do: the check belongs to the call.\nimport { OptionError, describeValue } from '../convert/options.js';\n\nconst SEP_TEXT = 0x14; // separates onset/duration from text, and text from text\nconst SEP_DURATION = 0x15; // separates onset from duration\nconst TAL_END = 0x00;\n\nconst TEXT_SEP_CHAR = String.fromCharCode(SEP_TEXT);\nconst DURATION_SEP_CHAR = String.fromCharCode(SEP_DURATION);\n\n/**\n * What EDF+ allows a TAL duration to look like, which is less than `Number()` allows.\n *\n * The header parser's DECIMAL_FIELD makes this argument at length and lists where the same\n * mistake had already been fixed: `#0x2` reaching channel 2 through `--channels`,\n * `--decimals 0o5` writing five places, `--jobs 0x10` running sixteen, a physical maximum of\n * `0x64` setting a whole calibration to 100. The annotation duration is the one field it did\n * not reach. `+1<0x15>0x10<0x14>Seizure` was exported with a duration_s of 16 — sixteen\n * seconds no writer wrote, in a column the documentation defines as the length the file\n * stated, exit 0 and no diagnostic. `0b11` is three the same way.\n *\n * A duration this cannot read is already a thing the parser knows how to say: the field is\n * left empty, counted, and reported. Sending these there costs nothing and states the truth,\n * which is that the file wrote something that is not a number of seconds.\n */\nconst DECIMAL_DURATION = /^[+-]?(?:\\d+(?:\\.\\d*)?|\\.\\d+)(?:[eE][+-]?\\d+)?$/u;\n\nexport interface Annotation {\n  /** Seconds from the start of the recording. */\n  onset: number;\n  /**\n   * Seconds, or null when the TAL stated no duration that could be read.\n   *\n   * Null covers two cases the file distinguishes and this field does not: a TAL that omitted\n   * the duration, and a TAL that stated one which is not a number. They are told apart by\n   * `unreadableDurations`, which is what raises the warning; the value itself has nowhere\n   * honest to put \"the file said `abc`\".\n   */\n  duration: number | null;\n  text: string;\n  /** Index of the data record this annotation was stored in. */\n  recordIndex: number;\n  /**\n   * True when the file stated a duration that could not be read.\n   *\n   * `duration` is null either way, which is the ambiguity the counts beside it exist to\n   * flag — and those counts were of the whole file while `annotations.csv` is filtered to\n   * the requested window. A conversion of one second of a recording warned that \"1\n   * annotation states a duration that is not a number, so its duration_s cell is empty\"\n   * about an event two seconds outside it, and failed `--strict` for it. Carrying the fact\n   * on the event lets the count be taken where the window has already been applied.\n   */\n  durationUnreadable?: boolean;\n}\n\nexport interface DecodedRecordAnnotations {\n  /** Record start time in seconds, from the leading timekeeping TAL. */\n  recordStart: number | null;\n  annotations: Annotation[];\n  /** Non-empty chunks that were not valid TALs, so the caller can report them. */\n  malformed: number;\n  /** Unreadable TALs in first position, which carry a record's start time, not an event. */\n  malformedTimekeeping: number;\n  /**\n   * How many of those also carried event text, and so lost events as well as a position.\n   *\n   * A TAL in first position holds the record's start time, and may hold events after it — the\n   * specification allows both in the one entry, and writers use it. When such a TAL cannot be\n   * parsed, both are gone, and counting it only as lost timekeeping let the warning beside it\n   * say \"No event was lost\" over a conversion that had just dropped four of them.\n   *\n   * Counted rather than inferred, because the sentence has to be right in the ordinary case\n   * too: a bare timekeeping TAL really does lose no event, and that is nearly all of them.\n   */\n  malformedTimekeepingWithText: number;\n  /**\n   * Events kept whose stated duration could not be read.\n   *\n   * Counted apart again, for the same reason the two above are: the entry was exported and\n   * nothing about it is missing except the one field, so calling it an entry that \"could not\n   * be exported\" describes a loss that did not happen and hides the one that did.\n   */\n  unreadableDurations: number;\n  /**\n   * Events kept whose stated duration is a readable number below zero.\n   *\n   * Separate from the count above because the value survives: it is written to the CSV as\n   * the file gave it, and what is wrong with it is arithmetic rather than parsing.\n   */\n  negativeDurations: number;\n}\n\n/**\n * Decode one data record's annotation bytes.\n *\n * Malformed TALs are skipped rather than thrown, because a single bad annotation\n * should not cost the user an entire conversion. The count of skipped chunks is\n * returned so the caller can tell the user rather than losing them in silence.\n */\nexport function decodeRecordAnnotations(\n  bytes: Uint8Array,\n  recordIndex: number,\n  carriesTimekeeping = true,\n): DecodedRecordAnnotations {\n  /*\n    The bytes, checked before anything is read out of them.\n\n    The api page offers this function on its own — \"For decoding annotation bytes yourself,\n    `decodeRecordAnnotations(bytes, recordIndex)` handles one record's worth of the channel\" —\n    so it is reached by a caller holding a slice they cut themselves. Hand it anything but a\n    typed array and the loop below reported the shape of its own local:\n\n        decodeRecordAnnotations(Buffer.from(text).toString(), 0)\n        TypeError: bytes.subarray is not a function\n\n    which names a variable inside this function and a method the caller never called. The\n    same `OptionError` the two path-taking exports raise, for the reason given there: the call\n    is what is wrong, not the recording.\n  */\n  if (!ArrayBuffer.isView(bytes)) {\n    throw new OptionError(\n      `bytes must be one record's annotation channel, got ${describeValue(bytes)}.`,\n    );\n  }\n  /*\n    And the second argument, which this function does not read — it writes it.\n\n    `recordIndex` is copied onto every `Annotation` this call produces, and `Annotation`\n    declares it a number. Nothing checked that it was one, so whatever was passed came back\n    out in the event list:\n\n        decodeRecordAnnotations(bytes, 'x').annotations[0].recordIndex   // 'x'\n        decodeRecordAnnotations(bytes).annotations[0].recordIndex        // absent\n\n    The second is the ordinary mistake, since the page shows this called as\n    `decodeRecordAnnotations(bytes, recordIndex)` beside `annotationBytes(batch, recordOffset,\n    signal)` and the two take their record different ways. It produces events with the field\n    missing altogether, which `record_index` in annotations.csv is written from, and which a\n    caller joining events back to records reads as a record of `undefined`.\n\n    A whole non-negative number, like the record bounds `readRecords` and `sampleAt` take:\n    records are counted from zero, and this one is a position in the file rather than in a\n    batch, so there is no upper bound to hold it to here.\n  */\n  if (!Number.isInteger(recordIndex) || recordIndex < 0) {\n    throw new OptionError(\n      `recordIndex must be the record's whole-number position in the file, got ` +\n        `${describeValue(recordIndex)}. It is written onto every annotation this returns.`,\n    );\n  }\n  const annotations: Annotation[] = [];\n  let recordStart: number | null = null;\n  let isFirstTal = true;\n  let malformed = 0;\n  let malformedTimekeeping = 0;\n  let malformedTimekeepingWithText = 0;\n  let unreadableDurations = 0;\n  let negativeDurations = 0;\n\n  let start = 0;\n  for (let i = 0; i <= bytes.length; i++) {\n    if (i !== bytes.length && bytes[i] !== TAL_END) continue;\n\n    if (i > start) {\n      const chunk = bytes.subarray(start, i);\n      /*\n        Padding is not a lost annotation.\n\n        The spec pads the slot with NUL, which the loop above already skips because it is what\n        separates one TAL from the next. Writers pad with spaces instead, and a run of spaces\n        after the last TAL is a non-empty chunk — so a file holding one perfectly readable\n        event, exported in full, was told \"2 annotation entries were unreadable and could not\n        be exported\", one per record. Nothing was lost. Under --strict that is a failed run\n        over the whitespace at the end of a slot.\n\n        Only whitespace. A chunk of anything else that does not parse is a real loss and is\n        still counted, which is the case this warning exists for.\n      */\n      if (chunk.every(isPaddingByte)) {\n        start = i + 1;\n        continue;\n      }\n      const parsed = parseTal(chunk, recordIndex);\n\n      // The timekeeping TAL is the one in first POSITION, whether or not it decodes.\n      // Clearing this flag only on a successful parse meant that an unreadable first TAL\n      // promoted the next ordinary annotation to timekeeping, and its onset silently\n      // became the record's start time — shifting every sample in that record. Leaving\n      // recordStart null instead is what the caller already handles, with a fallback\n      // timestamp and an ANNOTATION_DECODE_FAILED warning naming the record.\n      /*\n        Only one annotation channel carries a record's start time.\n\n        This flagged the first TAL of *every* annotation channel as timekeeping. In a second\n        channel the first TAL is an ordinary event — so when one failed to parse, the event\n        was dropped and counted as a lost timekeeping entry, which produced the warning\n        \"3 data records carry a timekeeping annotation that could not be read\" followed by\n        \"No event was lost\". Three events had been lost, and the timekeeping in that file was\n        perfectly readable. Both sentences false, about the same three records.\n      */\n      const isTimekeeping = isFirstTal && carriesTimekeeping;\n      isFirstTal = false;\n\n      if (parsed) {\n        if (isTimekeeping) recordStart = parsed.onset;\n        for (const annotation of parsed.annotations) annotations.push(annotation);\n        unreadableDurations += parsed.unreadableDurations;\n        negativeDurations += parsed.negativeDurations;\n      } else {\n        /*\n          Counted apart from the events, because losing one is a different loss.\n\n          A timekeeping TAL is never exported — it says where the record sits, not what\n          happened — so counting it among the entries that \"could not be exported\" both\n          overstated what was lost from annotations.csv and said nothing about the thing that\n          actually went missing, which is a record's position in time. A file with one\n          unreadable timekeeping TAL and three perfectly good events reported \"1 annotation\n          entry was unreadable and could not be exported\" while exporting all three.\n\n          The other direction is just as wrong. A first-position TAL may carry events after\n          the start time, and when one of those cannot be parsed the events go with it — so\n          counting it only as lost timekeeping produced the opposite false sentence: \"No event\n          was lost\", printed over a run whose annotations.csv had gone from six rows to two.\n          It is one entry that could not be exported and one record with no position, and it\n          is counted as both.\n        */\n        if (isTimekeeping) {\n          malformedTimekeeping++;\n          if (carriesAnnotationText(chunk)) {\n            malformedTimekeepingWithText++;\n            malformed++;\n          }\n        } else malformed++;\n      }\n    }\n    start = i + 1;\n  }\n\n  return {\n    recordStart,\n    annotations,\n    malformed,\n    malformedTimekeeping,\n    malformedTimekeepingWithText,\n    unreadableDurations,\n    negativeDurations,\n  };\n}\n\ninterface ParsedTal {\n  onset: number;\n  annotations: Annotation[];\n  /** How many of those annotations carry a duration the file stated and this could not read. */\n  unreadableDurations: number;\n  /** How many carry a duration that read as a number below zero. */\n  negativeDurations: number;\n}\n\n/**\n * Whether a TAL that could not be parsed still carried event text.\n *\n * A TAL is `onset[<0x15>duration]<0x14>text<0x14>...`, so anything other than padding after\n * the first 0x14 is a description the file meant to export. Read from the raw chunk, since by\n * the time this is asked the parse has already failed and there is no structure to consult.\n */\nfunction carriesAnnotationText(chunk: Uint8Array): boolean {\n  let afterSeparator = false;\n  for (const byte of chunk) {\n    if (byte === 0x14) {\n      afterSeparator = true;\n      continue;\n    }\n    if (afterSeparator && !isPaddingByte(byte)) return true;\n  }\n  return false;\n}\n\n/** Space, tab, CR, LF or NUL — what a writer fills the rest of the slot with. */\nfunction isPaddingByte(byte: number): boolean {\n  return byte === 0x20 || byte === 0x09 || byte === 0x0d || byte === 0x0a || byte === 0x00;\n}\n\nfunction parseTal(chunk: Uint8Array, recordIndex: number): ParsedTal | null {\n  // The onset must be explicitly signed; anything else is not a TAL.\n  const first = chunk[0];\n  if (first !== 0x2b /* + */ && first !== 0x2d /* - */) return null;\n\n  const text = decodeText(chunk);\n  const parts = text.split(TEXT_SEP_CHAR);\n  const head = parts[0] ?? '';\n\n  let onsetText = head;\n  let durationText: string | null = null;\n  const durationSep = head.indexOf(DURATION_SEP_CHAR);\n  if (durationSep >= 0) {\n    onsetText = head.slice(0, durationSep);\n    durationText = head.slice(durationSep + 1);\n  }\n\n  const onset = Number(onsetText);\n  if (!Number.isFinite(onset)) return null;\n\n  /*\n    A duration the file stated and this could not read is not the same as no duration.\n\n    Both came out as `null` and so as an empty `duration_s` cell, which the documentation\n    defines as meaning the file gave no duration — so an event whose duration was written as\n    `abc` was exported as an event with no duration, indistinguishable from one beside it\n    that genuinely had none, and nothing anywhere said a field had been dropped. The onset is\n    already held to this standard: one that is not a number costs the whole TAL and is\n    reported. A duration is one field of an otherwise readable event, so the event is kept —\n    but it is counted, and the run says so.\n  */\n  /*\n    Fill in the field is an absent duration, not a zero.\n\n    `Number` reads a run of whitespace as 0 — the rule that makes `Number('')` zero, one step\n    along — so a TAL whose duration field held nothing but the writer's padding was exported\n    with a `duration_s` of `0`, byte-identical to the event beside it whose file really did\n    say `0`. An instantaneous event is a claim about the recording, and no writer made it;\n    inventing it is the one thing this tool does not do, and it did so in silence, exit 0.\n\n    The empty field this condition already declines is the same field without the fill in it,\n    so padding takes the same answer: the file stated no duration. `trim` empties exactly the\n    strings `Number` would otherwise have swallowed into a zero, so `  2.5  ` still reads as\n    2.5 and `abc` is still counted as unreadable below.\n  */\n  let duration: number | null = null;\n  let durationUnreadable = false;\n  if (durationText !== null && durationText.trim() !== '') {\n    const stated = durationText.trim();\n    const d = DECIMAL_DURATION.test(stated) ? Number(stated) : NaN;\n    if (Number.isFinite(d)) duration = d;\n    else durationUnreadable = true;\n  }\n\n  /*\n    A duration is a length of time, and a length below zero is not one.\n\n    The value is kept and written as the file gave it — inventing a zero, or dropping it to\n    an empty cell, would put a number in annotations.csv that no writer wrote, which is the\n    one thing this tool does not do. But it is reported, because everything downstream\n    quietly does the wrong thing with it: the recipe this documentation gives for the samples\n    an event covers is `onset_s + duration_s`, which for a duration of -3 ends three seconds\n    before the event starts and selects nothing at all, with no error anywhere.\n  */\n  const durationNegative = duration !== null && duration < 0;\n\n  const annotations: Annotation[] = [];\n  for (const raw of parts.slice(1)) {\n    /*\n      A trailing separator yields an empty segment; a timekeeping TAL is all empty.\n\n      Whitespace counts as empty here, which it did not, and the padding at the end of the\n      slot became an event. The chunk loop above already refuses to call a run of spaces a\n      lost annotation — but it only sees chunks between NULs, and a writer that leaves its\n      last TAL unterminated puts the fill *inside* the chunk, after the final 0x14. Split on\n      that separator it is a text segment like any other, and \" \" is not \"\".\n\n      A file holding two events exported four rows: `0.5,,Lights off,0` and `0.5,,   ,0`,\n      twice, sharing the real event's onset, with annotations_written and the run summary\n      agreeing with the inflated number and nothing warned. An event whose description is\n      genuinely nothing but spaces cannot be told from fill, and inventing rows out of fill\n      is the worse of the two answers.\n    */\n    if ([...raw].every((c) => isPaddingByte(c.charCodeAt(0)))) continue;\n    annotations.push({\n      onset,\n      duration,\n      text: raw,\n      recordIndex,\n      ...(durationUnreadable ? { durationUnreadable: true } : {}),\n    });\n  }\n\n  // Per event rather than per TAL: one TAL may carry several texts, and each becomes a row\n  // of annotations.csv with the same cell in it.\n  return {\n    onset,\n    annotations,\n    unreadableDurations: durationUnreadable ? annotations.length : 0,\n    negativeDurations: durationNegative ? annotations.length : 0,\n  };\n}\n\nexport { SEP_TEXT, SEP_DURATION, TAL_END };\n"]}

package/dist/edf/scale.js

@@ -26,6 +26,32 @@
 import { OptionError, describeValue } from '../convert/options.js';
 /** The four header fields this reads, in the order a message should name them. */
 const CALIBRATION = ['digitalMin', 'digitalMax', 'physicalMin', 'physicalMax'];
+/**
+ * The four calibration numbers, confirmed to be on the thing that was passed.
+ *
+ * Written for `makeScaler` in 0.8.61 and shared since 0.8.76, when the two functions beside
+ * it turned out to read the same four fields off the same argument and ask nothing of it.
+ * Both answer rather than refuse:
+ *
+ *     quantizationStep({})     // 0     — the step of a channel whose header contradicts itself
+ *     decimalsForSignal(42)    // 3     — the precision an ordinary EEG channel gets
+ *
+ * `undefined - undefined` is `NaN`, `NaN === 0` is false, and the division that follows gives
+ * `NaN`; `quantizationStep` returns it as a step, and `decimalsForSignal` reads a step that is
+ * not a positive number as "this channel has none to derive from" and falls back to three
+ * places. Both of those are real answers for real channels — a zero digital span is what
+ * `DEGENERATE_DIGITAL_RANGE` reports, and three places is what most EEG gets — so a caller
+ * holding the wrong object gets a number they have no way to doubt.
+ */
+function assertCalibration(signal) {
+    if (typeof signal !== 'object' || signal === null) {
+        throw new OptionError(`signal must be a channel from a header, got ${describeValue(signal)}.`);
+    }
+    const missing = CALIBRATION.find((name) => typeof signal[name] !== 'number');
+    if (missing !== undefined) {
+        throw new OptionError(`signal.${missing} must be a number, got ${describeValue(signal[missing])}.`);
+    }
+}
 export function makeScaler(signal) {
     /*
       The argument, checked like the arguments of the other exported functions.
@@ -42,13 +68,7 @@ export function makeScaler(signal) {
       the wrong object. The diagnostic that normally accompanies it, DEGENERATE_DIGITAL_RANGE,
       comes from the header parser and is not raised here at all.
     */
-    if (typeof signal !== 'object' || signal === null) {
-        throw new OptionError(`signal must be a channel from a header, got ${describeValue(signal)}.`);
-    }
-    const missing = CALIBRATION.find((name) => typeof signal[name] !== 'number');
-    if (missing !== undefined) {
-        throw new OptionError(`signal.${missing} must be a number, got ${describeValue(signal[missing])}.`);
-    }
+    assertCalibration(signal);
     const { digitalMin, digitalMax, physicalMin, physicalMax } = signal;
     // A zero digital span leaves the mapping undefined — the header contradicts itself,
     // so there is no physical value for any sample on this channel.
@@ -102,6 +122,9 @@ export function makeScaler(signal) {
  * Used to choose a decimal precision that preserves every distinct sample value.
  */
 export function quantizationStep(signal) {
+    // See `assertCalibration`: without it `quantizationStep({})` answered 0, which is the step
+    // of a channel whose header contradicts itself.
+    assertCalibration(signal);
     const digitalSpan = signal.digitalMax - signal.digitalMin;
     if (digitalSpan === 0)
         return 0;

package/dist/edf/scale.js.map

@@ -1 +1 @@
-{"version":3,"file":"scale.js","sourceRoot":"","sources":["../../src/edf/scale.ts"],"names":[],"mappings":"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","sourcesContent":["/**\n * Digital-to-physical conversion.\n *\n * EDF defines the mapping by two calibration points, (digitalMin -> physicalMin)\n * and (digitalMax -> physicalMax), which the specification writes as:\n *\n *   gain     = (physicalMax - physicalMin) / (digitalMax - digitalMin)\n *   physical = (digital - digitalMin) * gain + physicalMin\n *\n * That form is evaluated here in EDFlib's algebraically equivalent arrangement:\n *\n *   offset   = physicalMax / gain - digitalMax\n *   physical = gain * (offset + digital)\n *\n * The rearrangement is not cosmetic. Written the first way, a channel spanning\n * +/-800 uV computes a value near 800 and then subtracts 800, and the cancellation\n * throws away low-order bits: digital 0 yields 0.19536019536019467 when the exact\n * value is 0.19536019536019536. EDFlib's form keeps the intermediate small\n * (offset + digital = 0.5 here) and returns the correctly rounded result.\n *\n * Both properties matter. The values are as accurate as a double can express, and\n * they are bit-identical to pyEDFlib and EDFbrowser, which share EDFlib's arithmetic,\n * so the test suite can assert exact equality against a reference implementation\n * rather than settling for a tolerance.\n */\n\nimport type { EdfSignal } from './header.js';\nimport { OptionError, describeValue } from '../convert/options.js';\n\nexport type Scaler = (digital: number) => number;\n\n/** The four header fields this reads, in the order a message should name them. */\nconst CALIBRATION = ['digitalMin', 'digitalMax', 'physicalMin', 'physicalMax'] as const;\n\nexport function makeScaler(signal: EdfSignal): Scaler {\n  /*\n    The argument, checked like the arguments of the other exported functions.\n\n    Every branch below reads four numbers off `signal`, and the first of them — the one that\n    catches a header contradicting itself — is `digitalMax === digitalMin`. On an object that\n    has neither, that comparison is `undefined === undefined`, which is true. So\n    `makeScaler({})` came back as a working function returning NaN for every sample, which is\n    exactly what a real channel with a zero digital span returns.\n\n    A caller cannot tell the two apart. The api page recommends this function for reading\n    physical units out of a file, and the empty column it produces is documented as meaning\n    \"the header contradicts itself\" — a sentence about the recording, over a call that passed\n    the wrong object. The diagnostic that normally accompanies it, DEGENERATE_DIGITAL_RANGE,\n    comes from the header parser and is not raised here at all.\n  */\n  if (typeof signal !== 'object' || signal === null) {\n    throw new OptionError(`signal must be a channel from a header, got ${describeValue(signal)}.`);\n  }\n  const missing = CALIBRATION.find((name) => typeof signal[name] !== 'number');\n  if (missing !== undefined) {\n    throw new OptionError(\n      `signal.${missing} must be a number, got ${describeValue(signal[missing])}.`,\n    );\n  }\n  const { digitalMin, digitalMax, physicalMin, physicalMax } = signal;\n\n  // A zero digital span leaves the mapping undefined — the header contradicts itself,\n  // so there is no physical value for any sample on this channel.\n  //\n  // NaN rather than a stand-in number. Writing the physical minimum produces a column\n  // of plausible readings (\"-100.000\" repeated) that is indistinguishable from a real\n  // flat recording once the CSV is opened somewhere else, which is exactly the kind of\n  // invented data this tool exists to avoid. NaN carries through to an empty CSV cell\n  // and reads back as NaN in pandas, matching how a missing annotation duration is\n  // already written. DEGENERATE_DIGITAL_RANGE is raised alongside it.\n  if (digitalMax === digitalMin) return () => NaN;\n\n  const gain = (physicalMax - physicalMin) / (digitalMax - digitalMin);\n\n  /*\n    A flat physical range makes every sample the same value, and would divide by zero in the\n    offset below. That mapping is defined, so its constant is written.\n\n    A gain of zero does not always mean flat, and this could not tell the difference. A range\n    of -1e-320 to 1e-320 is not flat — it is 65,536 distinct physical values — but the gain\n    is 2e-320/65535, which is smaller than the smallest subnormal double and underflows to\n    +0. Every distinct sample then took `physicalMin`, so eight codes spanning -16,000 to\n    +12,000 came out as one repeated number, with no diagnostic anywhere and `--strict`\n    exiting 0. At 1e-319, one power of ten away, the same file raises VALUE_RESOLUTION.\n\n    That is the same situation as the overflow below it, which this codebase already reasoned\n    about and answered: the span cannot be represented, so there is no mapping, so the cells\n    are left empty rather than filled with a value the header cannot justify. Underflow only\n    got the flat-range treatment because `gain === 0` is what both look like from here.\n  */\n  if (gain === 0) return physicalMax === physicalMin ? (): number => physicalMin : (): number => NaN;\n\n  // A non-finite gain is a different thing: the physical span overflowed a double, so\n  // there is no mapping at all. Returning physicalMin filled the column with one enormous\n  // constant — every distinct sample rendered as the same 300-digit number — and raised\n  // nothing. NaN takes the same route as a degenerate digital range: empty cells, plus\n  // UNUSABLE_PHYSICAL_RANGE from the header parser.\n  if (!Number.isFinite(gain)) return () => NaN;\n\n  // Deriving the offset divides by the gain. For every realistic calibration that is\n  // both safe and more accurate, but an absurd header (a huge physical range over a\n  // near-zero gain) could overflow it, so fall back to the specification's own\n  // arrangement rather than emitting Infinity.\n  const offset = physicalMax / gain - digitalMax;\n  if (!Number.isFinite(offset)) {\n    return (digital: number): number => (digital - digitalMin) * gain + physicalMin;\n  }\n\n  return (digital: number): number => gain * (offset + digital);\n}\n\n/**\n * Smallest physical step this channel can express — one digital unit.\n * Used to choose a decimal precision that preserves every distinct sample value.\n */\nexport function quantizationStep(signal: EdfSignal): number {\n  const digitalSpan = signal.digitalMax - signal.digitalMin;\n  if (digitalSpan === 0) return 0;\n  return Math.abs((signal.physicalMax - signal.physicalMin) / digitalSpan);\n}\n\n/**\n * The most `toFixed` accepts. 101 is a RangeError, so this is the ceiling, not a taste.\n *\n * It used to be 20, on the stated grounds that 20 was what `toFixed` allowed. It is not,\n * and the gap was not academic: a magnetometer channel spanning ±1e-16 T over a 16-bit\n * converter has a step of 3.05e-21 and needs 23 places. Clamped to 20, every value landed\n * on a 1e-20 grid — about three digital codes to a printed value — so 69% of the samples\n * could not be recovered, the conversion exited 0, and nothing said a word. The channel\n * type the old comment named as the reason for the ceiling was the one it broke.\n */\nconst MAX_DERIVED_DECIMALS = 100;\n\n/**\n * Places this channel needs before any ceiling, or null when it has no step to derive one from.\n *\n * One expression, because two functions depend on agreeing about it. `decimalsForSignal`\n * computed `Math.ceil(-Math.log10(step)) + 2` and clamped it; `decimalsAreClamped` computed the\n * same thing again and compared it to the same ceiling. Two copies of one formula whose only\n * job is to give the same answer — change either `+ 2` and they part company at the boundary,\n * so a channel whose precision really was capped is reported as not capped, VALUE_RESOLUTION is\n * not raised, and its codes print indistinguishable in silence. Which is the exact thing that\n * warning exists to say.\n */\nfunction decimalsNeeded(signal: EdfSignal): number | null {\n  const step = quantizationStep(signal);\n  if (!(step > 0) || !Number.isFinite(step)) return null;\n  return Math.ceil(-Math.log10(step)) + 2;\n}\n\n/**\n * Decimal places needed so that two adjacent digital codes never round to the same\n * string. Two places past the quantization step keep rounding error far below the\n * resolution the hardware actually recorded, without padding the file with digits\n * that carry no information.\n *\n * Ordinary channels land at three or four: a ±800 µV channel over 12 bits steps by\n * 0.39 µV and needs three. The ceiling is only reached by calibrations whose step is\n * below 1e-98, which an 8-character physical bound can still express — `1e-99` is five\n * characters. Those get VALUE_RESOLUTION rather than silence.\n */\nexport function decimalsForSignal(signal: EdfSignal, max = MAX_DERIVED_DECIMALS): number {\n  const needed = decimalsNeeded(signal);\n  if (needed === null) return 3;\n  return Math.min(max, Math.max(0, needed));\n}\n\n/**\n * Whether this channel's step is finer than any precision the tool can print.\n *\n * Asked of the ceiling, not of the precision in use. `--decimals 2` on a channel needing 3\n * is a trade the caller made knowingly and is not this warning's business — 0.5.10 fixed a\n * version of this that fired on every ordinary EEG at `--decimals 2` and made\n * `--decimals 2 --strict` impossible. But it fixed it by asking \"did the caller choose the\n * precision\", which suppressed the real case too: at `--decimals 20` a channel stepping by\n * 1e-106 printed every one of its codes as `0.00000000000000000000`, in silence.\n *\n * The question is whether anything the tool can print would separate consecutive codes. When\n * the answer is no, that is a ceiling nobody chose, and it holds whatever `--decimals` says.\n */\nexport function decimalsAreClamped(signal: EdfSignal): boolean {\n  const needed = decimalsNeeded(signal);\n  return needed !== null && needed > MAX_DERIVED_DECIMALS;\n}\n"]}
+{"version":3,"file":"scale.js","sourceRoot":"","sources":["../../src/edf/scale.ts"],"names":[],"mappings":"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","sourcesContent":["/**\n * Digital-to-physical conversion.\n *\n * EDF defines the mapping by two calibration points, (digitalMin -> physicalMin)\n * and (digitalMax -> physicalMax), which the specification writes as:\n *\n *   gain     = (physicalMax - physicalMin) / (digitalMax - digitalMin)\n *   physical = (digital - digitalMin) * gain + physicalMin\n *\n * That form is evaluated here in EDFlib's algebraically equivalent arrangement:\n *\n *   offset   = physicalMax / gain - digitalMax\n *   physical = gain * (offset + digital)\n *\n * The rearrangement is not cosmetic. Written the first way, a channel spanning\n * +/-800 uV computes a value near 800 and then subtracts 800, and the cancellation\n * throws away low-order bits: digital 0 yields 0.19536019536019467 when the exact\n * value is 0.19536019536019536. EDFlib's form keeps the intermediate small\n * (offset + digital = 0.5 here) and returns the correctly rounded result.\n *\n * Both properties matter. The values are as accurate as a double can express, and\n * they are bit-identical to pyEDFlib and EDFbrowser, which share EDFlib's arithmetic,\n * so the test suite can assert exact equality against a reference implementation\n * rather than settling for a tolerance.\n */\n\nimport type { EdfSignal } from './header.js';\nimport { OptionError, describeValue } from '../convert/options.js';\n\nexport type Scaler = (digital: number) => number;\n\n/** The four header fields this reads, in the order a message should name them. */\nconst CALIBRATION = ['digitalMin', 'digitalMax', 'physicalMin', 'physicalMax'] as const;\n\n/**\n * The four calibration numbers, confirmed to be on the thing that was passed.\n *\n * Written for `makeScaler` in 0.8.61 and shared since 0.8.76, when the two functions beside\n * it turned out to read the same four fields off the same argument and ask nothing of it.\n * Both answer rather than refuse:\n *\n *     quantizationStep({})     // 0     — the step of a channel whose header contradicts itself\n *     decimalsForSignal(42)    // 3     — the precision an ordinary EEG channel gets\n *\n * `undefined - undefined` is `NaN`, `NaN === 0` is false, and the division that follows gives\n * `NaN`; `quantizationStep` returns it as a step, and `decimalsForSignal` reads a step that is\n * not a positive number as \"this channel has none to derive from\" and falls back to three\n * places. Both of those are real answers for real channels — a zero digital span is what\n * `DEGENERATE_DIGITAL_RANGE` reports, and three places is what most EEG gets — so a caller\n * holding the wrong object gets a number they have no way to doubt.\n */\nfunction assertCalibration(signal: EdfSignal): void {\n  if (typeof signal !== 'object' || signal === null) {\n    throw new OptionError(`signal must be a channel from a header, got ${describeValue(signal)}.`);\n  }\n  const missing = CALIBRATION.find((name) => typeof signal[name] !== 'number');\n  if (missing !== undefined) {\n    throw new OptionError(\n      `signal.${missing} must be a number, got ${describeValue(signal[missing])}.`,\n    );\n  }\n}\n\nexport function makeScaler(signal: EdfSignal): Scaler {\n  /*\n    The argument, checked like the arguments of the other exported functions.\n\n    Every branch below reads four numbers off `signal`, and the first of them — the one that\n    catches a header contradicting itself — is `digitalMax === digitalMin`. On an object that\n    has neither, that comparison is `undefined === undefined`, which is true. So\n    `makeScaler({})` came back as a working function returning NaN for every sample, which is\n    exactly what a real channel with a zero digital span returns.\n\n    A caller cannot tell the two apart. The api page recommends this function for reading\n    physical units out of a file, and the empty column it produces is documented as meaning\n    \"the header contradicts itself\" — a sentence about the recording, over a call that passed\n    the wrong object. The diagnostic that normally accompanies it, DEGENERATE_DIGITAL_RANGE,\n    comes from the header parser and is not raised here at all.\n  */\n  assertCalibration(signal);\n  const { digitalMin, digitalMax, physicalMin, physicalMax } = signal;\n\n  // A zero digital span leaves the mapping undefined — the header contradicts itself,\n  // so there is no physical value for any sample on this channel.\n  //\n  // NaN rather than a stand-in number. Writing the physical minimum produces a column\n  // of plausible readings (\"-100.000\" repeated) that is indistinguishable from a real\n  // flat recording once the CSV is opened somewhere else, which is exactly the kind of\n  // invented data this tool exists to avoid. NaN carries through to an empty CSV cell\n  // and reads back as NaN in pandas, matching how a missing annotation duration is\n  // already written. DEGENERATE_DIGITAL_RANGE is raised alongside it.\n  if (digitalMax === digitalMin) return () => NaN;\n\n  const gain = (physicalMax - physicalMin) / (digitalMax - digitalMin);\n\n  /*\n    A flat physical range makes every sample the same value, and would divide by zero in the\n    offset below. That mapping is defined, so its constant is written.\n\n    A gain of zero does not always mean flat, and this could not tell the difference. A range\n    of -1e-320 to 1e-320 is not flat — it is 65,536 distinct physical values — but the gain\n    is 2e-320/65535, which is smaller than the smallest subnormal double and underflows to\n    +0. Every distinct sample then took `physicalMin`, so eight codes spanning -16,000 to\n    +12,000 came out as one repeated number, with no diagnostic anywhere and `--strict`\n    exiting 0. At 1e-319, one power of ten away, the same file raises VALUE_RESOLUTION.\n\n    That is the same situation as the overflow below it, which this codebase already reasoned\n    about and answered: the span cannot be represented, so there is no mapping, so the cells\n    are left empty rather than filled with a value the header cannot justify. Underflow only\n    got the flat-range treatment because `gain === 0` is what both look like from here.\n  */\n  if (gain === 0) return physicalMax === physicalMin ? (): number => physicalMin : (): number => NaN;\n\n  // A non-finite gain is a different thing: the physical span overflowed a double, so\n  // there is no mapping at all. Returning physicalMin filled the column with one enormous\n  // constant — every distinct sample rendered as the same 300-digit number — and raised\n  // nothing. NaN takes the same route as a degenerate digital range: empty cells, plus\n  // UNUSABLE_PHYSICAL_RANGE from the header parser.\n  if (!Number.isFinite(gain)) return () => NaN;\n\n  // Deriving the offset divides by the gain. For every realistic calibration that is\n  // both safe and more accurate, but an absurd header (a huge physical range over a\n  // near-zero gain) could overflow it, so fall back to the specification's own\n  // arrangement rather than emitting Infinity.\n  const offset = physicalMax / gain - digitalMax;\n  if (!Number.isFinite(offset)) {\n    return (digital: number): number => (digital - digitalMin) * gain + physicalMin;\n  }\n\n  return (digital: number): number => gain * (offset + digital);\n}\n\n/**\n * Smallest physical step this channel can express — one digital unit.\n * Used to choose a decimal precision that preserves every distinct sample value.\n */\nexport function quantizationStep(signal: EdfSignal): number {\n  // See `assertCalibration`: without it `quantizationStep({})` answered 0, which is the step\n  // of a channel whose header contradicts itself.\n  assertCalibration(signal);\n  const digitalSpan = signal.digitalMax - signal.digitalMin;\n  if (digitalSpan === 0) return 0;\n  return Math.abs((signal.physicalMax - signal.physicalMin) / digitalSpan);\n}\n\n/**\n * The most `toFixed` accepts. 101 is a RangeError, so this is the ceiling, not a taste.\n *\n * It used to be 20, on the stated grounds that 20 was what `toFixed` allowed. It is not,\n * and the gap was not academic: a magnetometer channel spanning ±1e-16 T over a 16-bit\n * converter has a step of 3.05e-21 and needs 23 places. Clamped to 20, every value landed\n * on a 1e-20 grid — about three digital codes to a printed value — so 69% of the samples\n * could not be recovered, the conversion exited 0, and nothing said a word. The channel\n * type the old comment named as the reason for the ceiling was the one it broke.\n */\nconst MAX_DERIVED_DECIMALS = 100;\n\n/**\n * Places this channel needs before any ceiling, or null when it has no step to derive one from.\n *\n * One expression, because two functions depend on agreeing about it. `decimalsForSignal`\n * computed `Math.ceil(-Math.log10(step)) + 2` and clamped it; `decimalsAreClamped` computed the\n * same thing again and compared it to the same ceiling. Two copies of one formula whose only\n * job is to give the same answer — change either `+ 2` and they part company at the boundary,\n * so a channel whose precision really was capped is reported as not capped, VALUE_RESOLUTION is\n * not raised, and its codes print indistinguishable in silence. Which is the exact thing that\n * warning exists to say.\n */\nfunction decimalsNeeded(signal: EdfSignal): number | null {\n  const step = quantizationStep(signal);\n  if (!(step > 0) || !Number.isFinite(step)) return null;\n  return Math.ceil(-Math.log10(step)) + 2;\n}\n\n/**\n * Decimal places needed so that two adjacent digital codes never round to the same\n * string. Two places past the quantization step keep rounding error far below the\n * resolution the hardware actually recorded, without padding the file with digits\n * that carry no information.\n *\n * Ordinary channels land at three or four: a ±800 µV channel over 12 bits steps by\n * 0.39 µV and needs three. The ceiling is only reached by calibrations whose step is\n * below 1e-98, which an 8-character physical bound can still express — `1e-99` is five\n * characters. Those get VALUE_RESOLUTION rather than silence.\n */\nexport function decimalsForSignal(signal: EdfSignal, max = MAX_DERIVED_DECIMALS): number {\n  const needed = decimalsNeeded(signal);\n  if (needed === null) return 3;\n  return Math.min(max, Math.max(0, needed));\n}\n\n/**\n * Whether this channel's step is finer than any precision the tool can print.\n *\n * Asked of the ceiling, not of the precision in use. `--decimals 2` on a channel needing 3\n * is a trade the caller made knowingly and is not this warning's business — 0.5.10 fixed a\n * version of this that fired on every ordinary EEG at `--decimals 2` and made\n * `--decimals 2 --strict` impossible. But it fixed it by asking \"did the caller choose the\n * precision\", which suppressed the real case too: at `--decimals 20` a channel stepping by\n * 1e-106 printed every one of its codes as `0.00000000000000000000`, in silence.\n *\n * The question is whether anything the tool can print would separate consecutive codes. When\n * the answer is no, that is a ceiling nobody chose, and it holds whatever `--decimals` says.\n */\nexport function decimalsAreClamped(signal: EdfSignal): boolean {\n  const needed = decimalsNeeded(signal);\n  return needed !== null && needed > MAX_DERIVED_DECIMALS;\n}\n"]}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "edf2csv",
-  "version": "0.8.75",
+  "version": "0.8.77",
   "description": "Convert EDF, EDF+ and BDF biosignal recordings (European Data Format) to CSV from the command line. Local, streaming, and never resamples or alters units.",
   "keywords": [
     "edf",