# Daybreak Decoder Studio

A beginner-friendly EEG workspace with a complete local example, preparation
instructions, quality checks, method comparison, result interpretation and exports.
The default example uses individually calibrated CSP + LDA, selected on validation
recordings before final testing. A simple training-majority baseline and bandpower
LDA comparison run on the same held-out trials. Original Braindecode EEGNet and
ShallowFBCSPNet checkpoints remain available as a separate legacy diagnostic.
Hosted conversation uses GPT-5.6 Luna when the site API is active; explicitly labeled
guided help works without it. Local WebLLM generation is experimental, outside the
default workflow, and has not been verified on the available test hardware.

## What works in the website

- Run three fixed methods on 120 measured PhysioNet EEG trials across eight people;
  calculate accuracy, balanced accuracy, confusion matrices and per-trial results.
- Inspect participant variation and descriptive uncertainty alongside the comparison.
- Export measured results and reproducible next steps as JSON and CSV.
- Ask hosted AI or guided help about the actual reported results. AI does not decode EEG.
- Import `experiment.json` produced by the included custom training workflow.
- EEG inference is local. Visitors do not need an API key. Training is done in Python, not on
  the website. Direct EDF/CSV upload and arbitrary channel montages are not supported.

## Main example: fixed validation and final test

PhysioNet EEGMMIDB v1.0.0 participants S002–S009 were fixed before evaluation. Each
person's model fit run 4 (120 training trials total), then run 8 supplied 120
validation trials. The shared default was frozen as CSP + LDA from validation
mean participant balanced accuracy: 62.17%, versus 58.82% for bandpower and 50.00%
for the training-majority rule. All methods were refitted on runs 4+8 (240 training
trials, including the earlier validation trials), then evaluated once on untouched
run 12 (120 final trials). There are 360 unique trials, not 480.

CSP achieved 72/120 correct (60.0%). The fitted training-majority rule achieved
62/120 (51.7%). CSP mean participant balanced accuracy was 59.60%, descriptive
95% participant t interval 51.70–67.50%. This is same-person, later-run decoding,
not a new-person or new-day generalization claim. All participants and all eligible
trials are included. See `DEMO_EVALUATION.md` for every method, person, uncertainty
assumption, unfavorable comparison and legacy checkpoint audit.

See `DEMO_PROTOCOL.md` for the fixed preprocessing and method specifications;
`demo-selection.json` records the frozen validation choice. `demo-manifest.json`
contains trial counts, all source EDF hashes, exact versions and complete metrics.
`demo-models.json` stores fitted filters and linear coefficients; `demo-data.json`
stores only the normalized held-out example arrays. The browser recomputes scores
from the arrays, then computes metrics from those scores; stored accuracy is not
substituted for inference.

Reproduce on Python 3.12, CPU only (no GPU or deep-learning install needed):

```sh
python -m venv .venv
# Activate .venv using your operating system's activation command.
python -m pip install -r requirements-demo.txt
python train_demo.py --stage select --output . --cache ./physionet-cache
python train_demo.py --stage final --output . --cache ./physionet-cache
node --test demo-inference.test.mjs
```

This downloads 24 public EDF recordings, approximately 62 MB, without credentials.
Run selection first; do not adjust the protocol after looking at final results.
The reproducibility check compares all 360 method/trial decisions against Python
scores to within 1e-7. Export rounding is included in both calculations.

## Legacy S001 deep-model diagnostic

PhysioNet EEG Motor Movement/Imagery Dataset v1.0.0, subject S001. Runs 4 and 8
train; run 12 tests. Labels T1/T2 in these runs are left/right fist motor imagery.
Retain C3, Cz, C4; filter each recording independently with a 4–38 Hz order-4
Butterworth zero-phase IIR; resample to 128 Hz. Epoch 0.5–3.5 s after cue (384 samples).
Fit channel mean and standard deviation on training runs only. Train both models
for a fixed 60 epochs with Adam, learning rate 0.001, batch size 8, seed 42. No
hyperparameter or checkpoint selection uses the test run. Test inputs are rounded
to 6 decimals before numerical parity checks and browser export.

This is a small teaching experiment with a single participant, not a benchmark
or evidence of generalization to other people, days, devices, or tasks. Runs from
one participant can still share confounds. Repeated inspection or choosing models
based on this test set turns it into development data. Softmax scores are not
calibrated confidence. No clinical use or free-form thought reading is supported.
The manifest records exact versions, hashes, training settings, test counts,
computed metrics, and numerical PyTorch/ONNX agreement. The browser recalculates
metrics from model outputs; it does not display the stored accuracy as a run.

## Run locally

Unzip, then `python -m http.server 8080` in the `decoder-studio` directory and open
http://localhost:8080 . Use a modern browser with WebAssembly. Optional AI needs
WebGPU, enough GPU memory, and Internet access for the initial ~1 GB download.
Open the included notebook for a guided explanation of training your own model.

## Reproduce the legacy deep checkpoints

Use Python 3.12 in a virtual environment:

```sh
python -m venv .venv
# Activate .venv using your operating system's activation command.
python -m pip install torch==2.11.0 torchaudio==2.11.0 --index-url https://download.pytorch.org/whl/cpu
python -m pip install -r requirements.txt
python train_export.py --output . --cache ./physionet-cache
```

Use a platform with compatible wheels for this PyTorch/torchaudio pair; the current
Windows ARM64 scientific environment did not have these packages. For macOS, use the matching
pair from the standard package index. This legacy reproduction
downloads only three public EDF recordings, about 8 MB total. No credentials needed.

## Bring your own EEG

1. Prepare consented, de-identified EEG with MNE in Python. Keep only C3, Cz, C4 in
   that order. Filter each recording independently at 4–38 Hz and resample to 128 Hz.
   Construct 3-second, non-overlapping, labeled task epochs. Store samples in microvolts.
2. Save an NPZ with `X` float32 `[trials, 3, 384]`, `y` integer `[trials]` (0 or 1),
   and `groups` string `[trials]` recording-session IDs. Use a separate session
   for testing; do not randomly split windows from the same recording.
3. `python train_custom.py epochs.npz --test-group session_3 --class-0 Left --class-1 Right`
4. Import the resulting `experiment.json` using “Import a trained experiment.”
5. Run decoding and inspect the result. Both the uploaded model and test EEG stay
   in memory in this browser tab. Closing the tab clears them. The exporter fits
   normalization only on training groups and checks PyTorch/ONNX numerical parity.

At least 20 training trials and 2–300 test trials are required, with both labels
in each split. These are file-format safeguards, not adequate scientific sample
size recommendations. A bundle must be under 12 MB. Import bundles from trusted
sources: they contain an ONNX model evaluated by ONNX Runtime. Do not put names,
participant identifiers, or other sensitive metadata in the bundle.

## Hosted AI

When connected, the hosted assistant is available without a model download. Sending
a question shares that question, up to four recent messages, and a small numerical
result summary with OpenAI through the site server. Raw EEG/model files stay on
your device. Avoid sensitive participant information in chat. The server requests
store:false; OpenAI may still retain abuse-monitoring data under its API policy.

The site enforces a $20 monthly estimated model-use allowance with reservations
for concurrent requests, plus 20 attempts per browser/day and 3/minute. A signed
30-day cookie identifies a browser; resetting cookies does not reset the global
allowance. A pseudonymous cost ledger stores no chat text or EEG. When a limit is
reached or the service is unavailable, guided help stays available.
The standalone source download has no hosted API backend; use guided help.

## Experimental local AI and privacy

Qwen2.5-1.5B-Instruct-q4f32_1-MLC (Apache-2.0 upstream weights) runs in a browser
worker via WebLLM 0.2.88 on compatible hardware. On November 10, 2026, the local
preview loaded the model and generated a complete reply on one tested device.
That reply incorrectly defined balanced accuracy as averaging TP, TN, FP and FN.
The correct binary definition is the mean of the two class recalls. The prompt
now supplies that definition, but this change has not validated answer quality
or reliability. Use measured results and curated guided explanations as references.
Local AI remains experimental, optional and outside the default journey;
capability detection and download/runtime failures retain hosted/guided help.
Explicitly enable it before downloading. JavaScript is
loaded from jsDelivr; model files come from Hugging Face and MLC. These providers
receive ordinary asset-download requests/IP information. In Local AI mode, chat text, uploaded EEG, and results are not sent to an inference server. No chat or data is persisted by
this app; WebLLM may cache model assets in browser storage. Clear site data through
your browser to remove model caches. The assistant sees only summary metrics, not
EEG arrays, and cannot execute commands or edit the experiment. Its answers may be
wrong. Computed results are shown in distinct cards. Without WebGPU or a successful
model download, use hosted AI when connected or the labeled curated walkthrough.

## Sources and licenses

- Braindecode 2.0.0, BSD-3-Clause: https://braindecode.org/stable/index.html
  and https://github.com/braindecode/braindecode . Included BSD notice.
- EEGNet: Lawhern et al. (2018), J Neural Eng 15 056013,
  https://doi.org/10.1088/1741-2552/aace8c .
- ShallowFBCSPNet: Schirrmeister et al. (2017), Human Brain Mapping 38:5391–5420,
  https://doi.org/10.1002/hbm.23730 .
- Schalk, G. (2009), EEG Motor Movement/Imagery Dataset v1.0.0, PhysioNet,
  https://doi.org/10.13026/C28G6P . Data and derived test epochs are made available
  under the Open Data Commons Attribution License v1.0:
  https://opendatacommons.org/licenses/by/1-0/ . Dataset source:
  https://physionet.org/content/eegmmidb/1.0.0/ .
- Original data publication: Schalk, McFarland, Hinterberger, Birbaumer & Wolpaw
  (2004), BCI2000, IEEE Trans Biomed Eng 51(6):1034–1043,
  https://doi.org/10.1109/TBME.2004.827072 .
- PhysioNet: Pollard et al. (2026), Nature Health,
  https://doi.org/10.1038/s44360-026-00096-z .
- ONNX Runtime Web 1.31.1, MIT: https://onnxruntime.ai/ . Included MIT notice.
- WebLLM 0.2.88, Apache-2.0: https://webllm.mlc.ai/ .
- Qwen2.5 1.5B Instruct: https://huggingface.co/Qwen/Qwen2.5-1.5B-Instruct .

Daybreak application code and training/export scripts: MIT, see LICENSE.
Third-party software and data retain their separate licenses. Daybreak is not
endorsed by the model or dataset authors. Source/protocol checked November 10, 2026.