README.md

---
license: bsd-3-clause
base_model: braindecode/cbramod-pretrained
tags:
- coreml
- eeg
- bci
- motor-imagery
- ios
- macos
- visionos
language:
- en
---

# CBraMod-MI-CoreML

**Zero-calibration motor-imagery decoder for 14-channel consumer EEG (EMOTIV EPOC X montage), running natively on Apple silicon. Subject-grouped estimate on unseen users: 78.4% left/right accuracy with no calibration trials.**

This is CBraMod fine-tuned end-to-end for left/right-hand motor imagery on all 109 PhysioNet EEGBCI subjects, exported to Core ML as a single classifier. Unlike embedding-based deployments, it needs **no per-subject head**: preprocessed EEG in, left/right probabilities out.

## The two-zone window (read this — it is the model's contract)

The input window is **[1.0, 4.5] s after imagery onset** — deliberately covering both the sustained-imagery zone *and* the post-imagery beta rebound. Our profiling showed the rebound period is anti-correlated under sweet-spot-trained decoders (it reverses the linear decision) but is the single most informative zone when trained on directly; the two-zone window is what lifts unseen-user accuracy from 0.717 to 0.784. Feeding a different window degrades the model to that extent.

| Item | Value |
|---|---|
| Model | `CBraModMI.mlpackage` (fp32 `mlprogram`) |
| Input | `eeg` — `float32 [1, 14, 1000]` |
| Output | `logits` — `float32 [1, 2]` = [left, right] (apply softmax) |
| Window | 3.5 s starting 1.0 s after imagery onset, source 256 Hz (896 samples) |
| Preprocessing | average reference over the 14 channels → global z-score of the window → resample to 200 Hz (polyphase) → zero-pad to 1000 samples |
| Channels (order matters) | AF3, F7, F3, FC5, T7, P7, O1, O2, P8, T8, FC6, F4, F8, AF4 |
| Also included | `cbramod_mi_wide.safetensors` (the fine-tuned PyTorch weights), `training_meta.json`, `parity.json` |

## Honest evaluation

All numbers are **subject-grouped** (GroupKFold 5 on 109 subjects: the evaluated model never saw any window from the tested user) with pre-registered hyperparameters; the published checkpoint is the same recipe trained on all 109.

- **0.784 ± 0.132** mean unseen-user accuracy; 56/109 users ≥ 80%, 25/109 ≥ 90%.
- +14.7 points over the best frozen-feature decoder *with* per-user calibration (paired p = 7×10⁻²⁰).
- **Bounds, stated plainly:** the identical recipe does not lift fists-vs-feet decoding (0.567 — the montage lacks midline-central coverage), and transfer across *recording setups* degrades: frozen-feature priors lost ~3 points crossing to a different amplifier/protocol (Cho2017), and the same should be expected here. This model is trained on research-grade recordings channel-subset to the EPOC X montage; true dry-electrode performance is unvalidated until live-headset data exists.
- The model is **cue-paced by design**: it decodes a window anchored to a known imagery onset (an app prompt). It is not an asynchronous/self-paced decoder — our pseudo-online study showed free-running decoding fails on this paradigm regardless of decoder.

## Core ML parity

Converted with `torch.export` + `run_decompositions({})` (fp32; `torch.jit.trace` fails on CBraMod's criss-cross reshapes — see the conversion notes in [CBraMod-CoreML-Apple](https://huggingface.co/oraculumai/CBraMod-CoreML-Apple)). Gates on real EEG windows vs PyTorch: logits rel-L2, 100% decision agreement, softmax max-abs-diff — results in `parity.json`.

## Usage

```python
import numpy as np
import coremltools as ct
from huggingface_hub import snapshot_download

# local_dir is required: Core ML cannot resolve the default HF cache's symlinks
repo = snapshot_download("oraculumai/CBraMod-MI-CoreML", local_dir="CBraMod-MI-CoreML")
model = ct.models.MLModel(f"{repo}/CBraModMI.mlpackage")

# window: [1.0, 4.5]s post-onset, 14ch x 896 @ 256 Hz, avg-ref + z-scored,
# then resampled to 200 Hz and zero-padded to 1000 samples:
logits = model.predict({"eeg": window_1x14x1000})["logits"]  # [1, 2] = [left, right]
```

Python helper with the exact preprocessing: `oraculum.cbramod.CBraModMIClassifier` in <https://github.com/nschlaepfer/oraculum-gpt-mk1>.

## Provenance & credit

- **Base model:** CBraMod (Wang et al., ICLR 2025, BSD-3-Clause) via [`braindecode/cbramod-pretrained`](https://huggingface.co/braindecode/cbramod-pretrained).
- **Fine-tuning data:** PhysioNet EEGBCI (Schalk et al. 2004; Goldberger et al. 2000) — 109 subjects, motor-imagery runs, 14-channel subset. Please cite both when using this model.
- **Method & evaluation:** the accompanying study (repository above) documents the two-zone window discovery, the fine-tuning recipe, and every control.

Research artifact — not a medical device; not validated for clinical use.