Phase 5: Unsupported options in existing user-facing functions

[suraj-ranganath]

🤖

Phase 5: Unsupported Options In Existing User-Facing Functions

Summary

Close option-level gaps in functions EEGPrep already exposes to users. This phase should reduce surprising NotImplementedError paths and make existing GUI/API/console workflows feel complete.

Start after Phase 2 and Phase 4 APIs are stable. Merge after both to avoid duplicate work.

Scope

Review and close useful unsupported options in:

• pop_erpimage
• pop_comperp
• pop_editset
• pop_export
• pop_epoch filename-backed data path
• pop_eegfilt legacy behavior only if not stale
• pop_runica documented algorithm/options gaps only where maintainable
• headplot, coregister, and clean_asr missing options where they are real workflows

Do not fake external-toolbox behavior. If a path cannot work standalone, provide a clear limitation and matrix classification.

Acceptance Criteria

• Unsupported EEGLAB options are reduced to only explicit, documented non-goals.
• User-facing help Markdown explains supported options and limitations.
• GUI-reachable paths keep EEGPrepSession, eegprep-console, LASTCOM, ALLCOM, and visible GUI state synchronized.
• Tests cover sample data, invalid options, history replay, cancel/error paths, and MATLAB parity where deterministic.
• GUI changes include side-by-side visual parity attachments.
• Matrix rows touched by this phase are updated.

Verification

Run focused tests for each touched function, relevant console workspace tests, GUI visual parity captures for dialogs, then:

• uv run --no-sync ruff check .
• uv run --no-sync ruff format --check .
• uv run --no-sync ty check
• non-slow pytest as risk requires

/goal Prompt

/goal Close unsupported-option gaps in existing EEGPrep user-facing functions. Use EEGLAB source as behavior reference, implement only maintainable and user-relevant options, preserve GUI plus eegprep-console synchronization, add help/docs/tests/parity evidence, update the parity matrix, and classify any remaining unsupported options explicitly.

[claude]

🤖 Plan:

• Read AGENTS.md, fix-issue, pull-request skills
• Actionability check — Phase 5 epic (multi-module, >>100 LOC, design work)
• Duplicate-work preflight — no open PRs touching these modules; depends on Phase 2: File format and channel-location long tail #133 (Phase 2) and Phase 4: Time-frequency internals and legacy time-frequency entry points #135 (Phase 4), both still OPEN with no PR
• Inventory current unsupported options per target function (see Research)
• Located parity matrix source: .notes/eeglab-migration-gap-audit.md §3 (lines 113-144)
• Posted Research + Proposed Approach (no PR — scope exceeds fix-issue threshold and Phase 5 is gated on Phase 2/4)

Research

This is a Phase 5 epic spanning ten user-facing functions with explicit NotImplementedError paths or partial coverage; total touched LOC will be well over 100 and crosses popfunc/, sigprocfunc/, and plugins/clean_rawdata/. The parent epic #131 gates Phase 5 on Phase 2 (#133) and Phase 4 (#135) APIs being stable — both are still OPEN with no PR, so starting now risks duplicate work on imports/IO and time-frequency primitives that this phase calls. Per repo policy on >100-line / multi-module issues, this comment is the analysis hand-off; a human should approve scope before implementation.

Current NotImplementedError inventory (rg -n NotImplementedError):

• pop_export.py#L25 — expr filtering
• pop_editset.py#L239,L258,L273-274,L401-403 — chanlocs file/workspace exprs, ICA-matrix file paths, data file/workspace exprs, history serialization for mappings and chanloc structs
• pop_erpimage.py#L314-348 — event sort/window/align, phase sort, ITC/coherence overlays, spectrum inset, baseline-amp limits, plotamps (amplitude image), nosort/noplot toggles, free-form others kwargs
• pop_comperp.py#L241-267 — significance highlighting (alpha), addstd/addall/substd/suball/diffstd/diffall, disabling addavg/subavg/diffavg
• pop_epoch.py#L184 — filename-backed EEG["data"]
• pop_eegfilt.py#L59-62 — legacy FFT path (directs to pop_eegfiltnew)
• pop_runica.py#L388-391 — jader, sobi, fastica, etc.
• headplot.py#L138-140 — plotmeshonly preview, setup with original unprojected locations
• coregister.py#L325-327 — methods other than traditional/globalrescale
• clean_asr.py#L77 — useriemannian Riemannian ASR; also maxmem chunking is documented as unimplemented at L69

Relevant code

• .notes/eeglab-migration-gap-audit.md §3 — authoritative scope list (lines 113-144)
• src/eegprep/eeglab/functions/popfunc/ — MATLAB parity oracle for each function
• src/eegprep/resources/help/ — existing help files for all ten targets are already present and will need updates

Proposed Approach

Treat Phase 5 as one branch (feature/phase-5-unsupported-options) targeting feature/eeglab-core-parity-completion with one PR per logical group below, merged sequentially. Each group should: (1) port the EEGLAB option semantics, (2) add or remove the corresponding NotImplementedError, (3) update resources/help/<name>.md, (4) add focused tests including history-replay and the parity-matrix row update, (5) for GUI-reachable dialogs add side-by-side visual parity captures. Do not attempt all ten at once — review burden and review-rework risk is too high.

Suggested PR slicing (rough LOC budget shown for sizing only):

1. Small mechanical wins (~250 LOC). pop_export expr evaluator (numpy-expression sandbox over channels/components), clean_asr maxmem chunking, pop_epoch filename-backed EEG.data (delegates to pop_loadset's data load path — requires Phase 2 mmap-style data path to be stable).
2. pop_editset completion (~400 LOC). Implement data file/workspace exprs as pop_importdata delegation, ICA-matrix paths via existing loaders, and history serializers for mapping/chanloc structs. Update pop_editset.md; add console-replay test.
3. pop_comperp plotting variants (~350 LOC). Add addstd/substd/diffstd shaded bands, addall/suball/diffall per-trace overlays, optional *avg disabling, and alpha significance via paired t-tests against the time grid. Visual parity capture required.
4. pop_erpimage sort/overlay completion (~700 LOC, may need its own sub-split). Event-field/type/window sorting, alignment, phase sort (Hilbert/FFT band-power on a user channel), ITC overlay (depends on Phase 4 newtimef internals — block until Phase 4: Time-frequency internals and legacy time-frequency entry points #135 lands), spectrum inset, baseline-amp limits, plotamps image mode. Visual parity capture per option.
5. Algorithm long tail (classify, do not implement blindly). pop_runica (jader/sobi/fastica), coregister (non-traditional/globalrescale), headplot (plotmeshonly), clean_asr (Riemannian): for each, decide port-vs-classify in the parity matrix with rationale (external-toolbox dep, niche workflow, no upstream Python equivalent). Only port the ones with a clear standalone Python path. Update the gap-audit doc and help Markdown to state the classification explicitly per AGENTS.md "explicit, documented non-goals."
6. pop_eegfilt legacy FFT — keep as redirect to pop_eegfiltnew (audit calls it stale); classify, do not port.

Open questions for the maintainer before implementation begins:

1. Is Phase 5 actually unblocked? Phase 2 (Phase 2: File format and channel-location long tail #133) and Phase 4 (Phase 4: Time-frequency internals and legacy time-frequency entry points #135) are still OPEN. pop_erpimage ITC overlay needs Phase 4; pop_epoch file-backed data needs Phase 2 IO. Confirm we should wait, or scope Phase 5 around only the non-dependent items first.
2. For group 5 (algorithm long tail), are jader/sobi/fastica required? They have no standalone Python equivalent with EEGLAB parity guarantees. The cleanest move is to classify as "non-goal" in the parity matrix and surface a clear message in pop_runica's GUI, matching the EEGLAB behavior catalogue.
3. Riemannian ASR — pyriemann exists but ports are non-trivial. Port or classify?
4. Is one Phase 5 branch with sub-PRs acceptable, or one PR per group directly to feature/eeglab-core-parity-completion?
5. The parity matrix location — is .notes/eeglab-migration-gap-audit.md the matrix to update, or is there a separate machine-readable matrix produced by Phase 1 (Phase 1: Parity matrix, staleness triage, and porting contracts #132)?

Not opening a PR. Awaiting maintainer review of slicing and the open questions before starting implementation.

[suraj-ranganath]

🤖 Resolved by the work now included in PR #152. Closing this constituent phase/follow-up issue now; parent epic #131 remains open until the epic PR merges.