Skip to content

sleep-edf: declare and apply microvolt input scaling (v0.2) - #58

Merged
GTC2333 merged 1 commit into
mainfrom
fix/sleep-edf-input-unit
Aug 11, 2026
Merged

sleep-edf: declare and apply microvolt input scaling (v0.2)#58
GTC2333 merged 1 commit into
mainfrom
fix/sleep-edf-input-unit

Conversation

@bondingelectron

Copy link
Copy Markdown
Collaborator

Summary

  • scale epochs to microvolts in load_subject_recording (×1e6, float32), matching the academic convention for EEG (MOABB / braindecode expose µV-scale arrays) and the bciciv-2a v0.2 precedent — keeps input units consistent across the bench
  • declare "input_unit": "microvolts" in the prompt's frozen preprocessing dict and note µV in the input shape contract
  • add 4 preprocessing contract unit tests (label mapping incl. stage 3+4 → N3 merge, V→µV scaling, interface constants, training hyperparameters) and wire them into the required CI matrix
  • document the unit in both READMEs and bump the breaking task version from 0.1 to 0.2

Background

The scorer returned MNE's SI-unit (volt) arrays while the prompt's self-contained preprocessing dict said nothing about units, and the shape contract exemplified inputs with torch.randn (unit scale). This is not a correctness bug — the scorer trains and tests on the same pipeline, so scores stay fair and reproducible — but amplitude-sensitive architectures (fixed-eps log-power, unnormalized saturating nonlinearities) behave differently at 1e-5 scale, and an agent inspecting the raw EDFs with non-MNE tooling sees µV (the EDF physical unit), which contradicts what the scorer actually feeds the model.

Validation

  • 4 new contract tests pass; bciciv-2a contract tests still pass (5/5)
  • Real-data smoke on pinned subject-0 recording: (841, 1, 3000) float32, label distribution 188/58/250/220/125 (W/N1/N2/N3/REM) unchanged, std = 22.88 µV (was 2.29e-5 V), abs max 192 µV
  • bp-bench validate sleep-edf, docs smoke, and the 208-test Node suite all pass

Score compatibility

This is a breaking scorer change. Scores produced with sleep-edf v0.1 should not be mixed with v0.2 scores. For normalization-based architectures the difference is expected to be within run-to-run noise; amplitude-sensitive architectures benefit materially.

The scorer returned MNE's SI-unit (volt) arrays while the prompt's
preprocessing contract said nothing about units, and the shape contract
exemplified inputs with torch.randn (unit scale). The academic
convention for EEG is microvolts (MOABB / braindecode expose µV-scale
arrays), and bciciv-2a v0.2 already adopted µV — keep the bench
consistent.

- scale epochs to microvolts in load_subject_recording (x1e6, float32)
- declare "input_unit": "microvolts" in the prompt preprocessing dict
  and note µV in the input shape contract
- bump task version 0.1 -> 0.2 (breaking: scores not comparable to v0.1)
- add preprocessing contract unit tests (label mapping, µV scaling,
  interface constants, training hyperparameters) and wire them into the
  validate workflow, mirroring bciciv-2a v0.2
- document the unit in both READMEs

Co-Authored-By: Claude Opus 4.8 <noreply@anthropic.com>
@bondingelectron
bondingelectron requested a review from a team as a code owner August 11, 2026 08:32

@GTC2333 GTC2333 left a comment

Copy link
Copy Markdown
Collaborator

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Verified the V→µV conversion on the pinned Sleep-EDF data: epoch shape and labels remain unchanged, while amplitudes scale exactly as intended. The four new preprocessing-contract tests and all required CI checks pass. Approved for merge. Non-blocking follow-up: please align the task README header from Version 0.1 to 0.2 and explicitly note that v0.1/v0.2 scores are not comparable.

@GTC2333
GTC2333 merged commit 29ff007 into main Aug 11, 2026
12 checks passed
@GTC2333
GTC2333 deleted the fix/sleep-edf-input-unit branch August 11, 2026 08:56
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

2 participants