edf2csv 0.3.3 → 0.3.5

package/CHANGELOG.md

@@ -3,6 +3,85 @@
 Notable changes to edf2csv. Versions follow [semantic versioning](https://semver.org); while the
 major version is 0, a minor bump may contain breaking changes.
 
+## 0.3.5
+
+### The cross-check now covers BDF and annotations
+
+0.3.4 made the pyEDFlib comparison a command, but it only read `.edf` files carrying signal
+data. That left out the two places a reader is most likely to be quietly wrong.
+
+**24-bit BDF.** A BDF sample is three bytes, and the sign has to be extended by hand. A value
+that comes out unsigned is not obviously wrong to look at: it is a large positive number where
+a large negative one belongs, which is exactly the kind of mistake that survives review. A
+quarter of the generated recordings are now BDF over BioSemi's own digital range, with both
+extremes present in every one.
+
+**Annotations.** Half the recordings now carry EDF+ or BDF+ events, including one with no
+duration and one whose duration is zero, and `annotations.csv` is compared against pyEDFlib's
+own reading of the TALs — onset, duration and text. The two disagree on one point by design:
+pyEDFlib reports a missing duration as `-1.0` where edf2csv leaves the cell empty, a duration
+nobody recorded not being a duration of minus one second. That difference is expected and
+treated as agreement.
+
+```
+Compared 16,943 sample values and 120 annotations across 75 recordings.
+Every value agreed.
+```
+
+Both halves were confirmed capable of failing before being trusted: a one-part-in-a-million
+error in the gain, and a one-millisecond shift in every annotation onset. Each exits 1 and
+names the sample.
+
+Writing the recordings turned up a fault in the generator rather than in the tool. A record's
+timekeeping TAL states where that record begins, which is its index times the record duration —
+it was writing the index. Recordings whose records are not one second long were therefore
+internally inconsistent, and pyEDFlib rejected precisely those rather than reading them wrongly,
+which is a good argument for comparing against something strict.
+
+No behaviour of the tool changed in this release.
+
+## 0.3.4
+
+### Added: `npm run crossvalidate`, the pyEDFlib comparison as something you can run
+
+The README and the correctness page have both said the arithmetic is checked against an
+independent implementation. That was true, and it was done by hand, which meant nothing
+rechecked it when the code changed. It is now a command:
+
+```bash
+pip install pyedflib
+npm run crossvalidate
+```
+
+```
+Compared 12,559 sample values across 77 recordings.
+Every value agreed.
+```
+
+Why another implementation rather than another test: the digital-to-physical mapping is four
+numbers out of the header and one multiply. It is easy to get subtly wrong and nearly
+impossible to catch by reading, and a test written next to the code tends to encode the same
+misunderstanding the code has. pyEDFlib was written by other people from the same
+specification.
+
+The recordings it generates are deliberately not the test fixtures. Those target what real
+files get wrong, and pyEDFlib declines several of them — a truncated file, a header whose
+digital range is a single point. These are the opposite: ordinary well-formed recordings
+across a wide spread of calibrations, digital spans from `-1..1` to `-32768..32767` against
+physical spans from `0.0001` to `99999`, which puts the gain anywhere from about 1e-9 to 1e5.
+Both ends of the digital range appear in every one, because those are the two points the
+header actually calibrates and where two derivations of the same mapping differ most.
+
+The comparison runs at `--decimals 20` so that what is compared is two computations of a value
+rather than one of them against its printed form. The first attempt used 12, where a reading
+near 1e-5 keeps only seven significant digits and the rounding was larger than the
+disagreement being looked for.
+
+It is opt-in and not part of `npm test`, which stays dependency-free. Without pyEDFlib
+installed it says so and exits 0 rather than reporting a pass it did not earn. Putting a
+one-part-in-a-million error into the gain makes it exit 1 and name the sample, which is how
+it was confirmed to be capable of failing at all.
+
 ## 0.3.3
 
 ### Fixed: a mistyped channel position converted a different channel

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "edf2csv",
-  "version": "0.3.3",
+  "version": "0.3.5",
   "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",
@@ -60,7 +60,8 @@
     "fixtures": "node test/fixtures/generate.mjs",
     "test": "npm run build && npm run fixtures && node --test test/*.test.js",
     "typecheck": "tsc -p tsconfig.json --noEmit",
-    "prepublishOnly": "npm run clean && npm run build && npm test"
+    "prepublishOnly": "npm run clean && npm run build && npm test",
+    "crossvalidate": "npm run build && node test/crossvalidate/generate.mjs && python3 test/crossvalidate/compare.py"
   },
   "devDependencies": {
     "@types/node": "^22.10.0",