Epic: eegprep in the browser (Pyodide) with a small ONNX ICLabel

[neuromechanist]

@arnodelorme requesting your approval on scope. Sub-issues are filed and listed below; scope corrections found while grounding the plan against the code are flagged in a comment.

Why

NEMAR's assistant will write and run eegprep code in the user's browser under Pyodide, with nothing computed server-side (nemarOrg/nemar-cli#1292, ADR 0049; design note OpenScience-Collective/osa#351). eegprep's algorithms are already pure Python. What blocks a browser install is a set of declared dependencies with no WebAssembly build, and ICLabel being torch-only. A small ONNX ICLabel also makes the classifier deployable anywhere, with or without Python.

Phases

Epic branch: epic/324-pyodide-browser. Phase PRs target that branch; the final epic PR targets develop.

Phase	Issue	Depends on
1. Move oct2py, psutil, pyedflib out of the base install	#374	none
2. Pyodide harness, CI, and the ICA benchmark gate	#375	1
3. Route runica matmuls through scipy BLAS under Emscripten	#376	2
4. Export ICLabel to ONNX and add the native onnxruntime backend	#377	none
5. Browser ICLabel via ONNX Runtime Web with an await-able entry point	#378	2, 4
6. Quantize ICLabel to int8 with a committed parity report	#379	4

Two streams run in parallel: the dependency and BLAS stream is 1 then 2 then 3, and the ICLabel stream is 4 then 5 and 6. Phase 4 can start immediately alongside phase 1.

Phase 2 is a go/no-go gate. It produces the numbers that decide whether picard keeps its advantage in the browser and whether the BLAS routing in phase 3 is worth a code change.

Parity definition

On a fixed held-out set of real independent components from public NEMAR datasets:

• Top-1 label agreement with the float32 reference at or above 95 percent.
• Keep or reject decision agreement under eegprep's thresholds at or above 99 percent.
• Per-class agreement reported, so rare classes are not averaged away.

Out of scope

Feature extraction, input normalization, and softmax stay float. No numerical change anywhere else. No server-side execution.

Decisions

1. Scope and extras names. Pending your approval. Extras are [eeglab] for oct2py and [sys] for psutil; [formats] is an open question because nothing imports pyedflib (see Phase 1: Move oct2py, psutil, and pyedflib out of the base install #374).
2. Browser default ICA: picard, with runica available. Recorded. Phase 2's benchmark can overturn this if picard's iteration advantage does not survive a single WebAssembly thread.
3. int8 ships as the default artifact everywhere, native and browser. Recorded. One artifact, one set of numbers to validate. This makes phase 6's parity report the thing that earns the default for every user, not just browser users.

[neuromechanist]

🤖 Grounded the plan against the code before filing sub-issues. Five findings change the scope as written.

1. pyedflib is unused. Zero imports anywhere in src/. It appears only in pyproject.toml and uv.lock. EDF already goes through mne and neo.rawio.edfrawio (plugins/EEG_BIDS/raw.py:79). So this is a deletion, not a move, and a [formats] extra that installs a package eegprep never calls would be misleading. Flagged as an open question on #374 rather than decided unilaterally.

2. oct2py is the dominant blocker, and not because of its own wheel. It is pure Python. Its tree is oct2py -> octave-kernel -> ipykernel, which pulls in pyzmq (needs cffi), debugpy, psutil, and tornado. Moving oct2py alone removes four C-extension packages from the base install, and psutil is therefore both a direct dependency and a transitive one.

3. greenlet is not a blocker, so pybids can stay. Worth recording because it looks like one. uv.lock shows sqlalchemy declaring greenlet under a platform_machine marker listing AMD64, WIN32, aarch64, amd64, ppc64le, win32, x86_64. Pyodide reports wasm32, so it self-excludes. Everything else in the base set is either in the Pyodide distribution or is a pure-Python wheel micropip can fetch.

4. The BLAS helper cannot cover picard. The epic specifies "one matmul helper ... used by runica and eeg_picard". That does not survive contact with the code: picard's hot matmuls are np.dot calls inside the third-party package (picard/_core_picard.py:84,163,206,207, picard/_tools.py:70,71,84,86). eeg_picard.py itself has two cheap post-processing matmuls at :63 and :65, and routing those changes nothing measurable. Monkeypatching numpy or vendoring picard are both ruled out by AGENTS.md, so the realistic options are to accept numpy's fallback and document it, or to go upstream to python-picard.

This matters because decision 2 makes picard the browser default, which puts picard's unoptimized inner loop on the critical path for the whole epic. That is why phase 2 is now a benchmark gate ahead of phase 3 rather than a bullet inside it.

Separately, runica's existing _matmul helper (runica.py:33) exists to suppress Accelerate floating-point warnings, not to route BLAS, and the hot loops bypass it with a bare @ at lines 684, 692, 718, 721, 871, 882, 1014, 1021, 1042, 1044, 1175, 1184. Phase 3 is partly about making that helper cover the hot path at all.

5. The browser ICLabel path needs an API decision, so it is its own phase. ONNX Runtime Web is asynchronous, while iclabel() and pop_iclabel() are synchronous and reachable from both the GUI menus and eegprep-console. How the await-able entry point reaches users without forking the pop_* surface, and what the synchronous path does under Emscripten, is a design question rather than an implementation detail. Split out as #378 with the options to be posted there before implementation.

Also noted for #377: swapping netICL.mat for iclabel.onnx touches pyproject.toml package data, tests/test_public_api_examples.py:73 and :144, resources/help/pop_iclabel.md:25, and tools/iclabel/iclabel_net_load_py_measures.py:22.

Net effect on the plan: five bullets became six phases, the benchmark moved ahead of the BLAS work as a gate, and the browser ICLabel runtime split from the ONNX export.

[neuromechanist]

🤖 Phase 2 CI acceptance evidence is complete: run 35245625332 passed, including the Pyodide harness, smoke test, benchmark, comparison, pre-commit, Ruff/ty, and Python platform matrix.

The threading boundary is now explicit: one runica or Picard ICA solve is single-threaded (thread_count=1). Web Workers or a bounded worker pool are for independent jobs; Phase 2 does not split one iterative solve across workers.

CI benchmark results for the fixed 64 x 15000 input:

• runica: native 467.274 s, Pyodide 680.509 s; both reached 512 iterations without convergence.
• Picard: native 9.972 s, Pyodide 109.049 s; both reached 511 iterations without convergence.
• Pyodide BLAS speedups over NumPy @: activation float64 1.76x, activation float32 0.81x, weight update float64 2.20x, weight update float32 1.62x.

Decisions: picard_browser_default_retained=false; phase3_recommended=false, because the Phase 3 gate requires at least 1.2x for every tested shape and dtype. Phase 2 is therefore validated as a harness/benchmark phase, with no browser ICA default promotion and no Phase 3 BLAS follow-on recommended by this gate.

[neuromechanist]

MATLAB/EEGPrep ICLabel parity update

I ran a controlled comparison using the same MATLAB R2025b ICA decomposition and MATLAB-generated ICLabel feature tensors.

The focused figures attached below cover the six components where replacing only EEGPrep’s PSD features caused top-1 label changes: ICs 1, 12, 18, 26, 27, and 30. The PSD figure compares MATLAB vs EEGPrep and shows the EEGPrep − MATLAB residual; the topomap figure is included as a visual control.

Findings:

• EEGPrep’s float32 model on MATLAB’s exact feature tensors matched MATLAB ICLabel on 32/32 components.
• The new int8 model preserved 32/32 top-1 labels and 32/32 keep/reject decisions.
• Replacing only PSD features changed 6/32 top-1 labels; replacing only topography or autocorrelation changed none.
• The average-reference data matrix itself matches MATLAB exactly, but EEGPrep’s post-rereference ICA state does not: post-reref icaact differs by up to approximately 31.5 and PSD is reduced across the spectrum.
• This localizes the remaining issue to the pop_reref/ICA activation update path, not the ICLabel model or quantization.

This is a diagnostic update; no fix is claimed yet. Next work should align EEGPrep’s post-rereference ICA activation handling with EEGLAB before rerunning the MATLAB parity gate.

[neuromechanist]

🤖 @arnodelorme The browser epic is ready for your review: final epic PR #386.

All six phase PRs are merged into epic/324-pyodide-browser, including the final Phase 3 merge (#385). The full project:pr-review-toolkit integration review found no actionable findings across code, tests, errors, comments/docs, types, and simplification. CI evidence includes the Pyodide smoke test, browser ICLabel parity, ICA benchmark, and Python platform matrix.

The final PR targets develop and remains open for your merge decision; we did not merge the epic into develop or main. Remaining bounded risks are the external MATLAB/EEGLAB parity gate and the intentionally false universal all-dtypes BLAS gate.

[neuromechanist]

🤖 Review status correction: the requested five-agent fresh-context panel found actionable blockers on the final epic PR #386. The earlier inline no-findings note should not be treated as final. The main blocker is stale async ICLabel result commits when session data changes during inference; the live documentation job also fails because it installs torch without the separate iclabel/onnxruntime extra. Additional runtime/package provenance and quantization-gate follow-ups are recorded on the PR.

PR #386 remains open and intentionally unmerged to develop/main pending fixes and rerun checks. The Codex review-fanout workflow gap is tracked in research-skills #97. @arnodelorme

[neuromechanist]

Cross-repo context, since this epic is one of four tracks in a larger piece of work: the map now lives at .context/epic_browser_compute_state.md in nemarOrg/nemar-cli (nemarOrg/nemar-cli#1459).

Two things in it bear on this epic directly:

• ADR 0069 decides that the browser runtime is its own distribution, eegprep-lean, published from this repository, and that eegprep itself stays whole with its default install unchanged. The dependency-trimming plan that mne is a base dependency, but eegprep is its peer rather than its consumer #395 was heading toward is closed; mne is a base dependency, but eegprep is its peer rather than its consumer #395 carries the reasoning and the measurement that killed it.
• The map notes an open question this epic has not yet been asked: where the ICLabel work meets the lean runtime. Phases 5 and 6 are building browser ICLabel on their own track, and ADR 0069 has not been applied to them.

PR #386 remains deliberately held, per the earlier decision not to merge it until something actually needs it.