Epic: Complete EEGPrep standalone EEGLAB parity and documentation

[suraj-ranganath]

🤖 This epic plans the final standalone EEGPrep parity push after PR #152. It is stacked on feature/eeglab-core-parity-completion until #152 merges.

Summary

Complete the remaining non-stale EEGLAB parity work so EEGPrep is a standalone Python application that EEGLAB users can use naturally from GUI, Python API, and eegprep-console. This epic does not reopen the core parity categories already closed by PR #152; instead it targets the still-relevant product surfaces left in .notes/eeglab-migration-gap-audit.md:

• bundled plugin depth: clean_rawdata, firfilt, ICLabel/viewprops, DIPFIT
• external-toolbox-backed user workflows where EEGPrep can provide a tested standalone or optional-dependency path
• large-dataset storage and EEGLAB storedisk/memory semantics
• EEGLAB-style user documentation, tutorials, and Sphinx organization
• final product-level QA across GUI, console, docs, sample data, MATLAB parity, and visual parity

Branching

• Epic branch: feature/eeglab-full-standalone-completion
• Epic branch base: feature/eeglab-core-parity-completion
• Phase PR target: feature/eeglab-full-standalone-completion
• Final epic PR target: origin/develop
• Stacking note: do not merge the final epic PR until PR [Parity] Complete remaining EEGLAB core gaps #152 has merged.

References

• AGENTS.md
• .notes/eeglab-migration-gap-audit.md
• docs/parity/eeglab_core_parity_matrix.json
• .agents/skills/eegprep-feature-development/SKILL.md
• .agents/skills/eeglab-gui-visual-parity/SKILL.md
• .agents/skills/gui-agent-flow-qa/SKILL.md
• .agents/skills/eegprep-project-management/SKILL.md

Audit Result Before Planning

The previous core parity matrix is green:

• 608 rows cover 608 in-scope EEGLAB core functions.
• No remaining port, partial, or unclassified rows for the PR [Parity] Complete remaining EEGLAB core gaps #152 categories.
• Remaining non-stale work is concentrated in product/plugin/runtime/docs areas, not blind same-name helper ports.

Useful remaining surfaces found during this planning pass:

• clean_rawdata: Riemannian ASR processing depth, vis_artifacts, user-visible progress/diagnostic parity, Manopt-backed behavior decisions.
• firfilt: order calculators, filter reports, split/boundary helpers, minimum-phase/window helpers, and frequency-response plotting.
• DIPFIT: source-localization internals, manual/batch workflows, atlas/head-coordinate helpers, private transform helpers, FieldTrip conversion boundaries.
• STUDY/advanced statistics: LIMO-compatible design/results paths, PAC compute/cache/plot workflows, neighbour/interpolation behavior, optional external dependencies.
• Storage/session: EEGLAB storedisk and memory-mapped expectations need a Python-native large-dataset design rather than MATLAB class ports.
• ICLabel/viewprops: label statistics, alternate network/tooling decisions, property-browser/viewprops diagnostic parity.
• Documentation: current Sphinx docs exist, but need EEGLAB-like tutorial organization, Concepts Guide depth, command equivalence notes, GUI screenshots, and complete user journeys.

Explicit Non-Goals

• Do not port stale MATLAB demo/test/internal helpers just because names differ.
• Do not make package runtime code depend on src/eegprep/eeglab.
• Do not fake external-toolbox workflows with plausible shapes and no real computation.
• Do not vendor broad external plugin ecosystems into core EEGPrep unless a phase explicitly promotes one to a maintained bundled plugin surface.
• Do not replicate MATLAB GUI shim files one-for-one when a native Qt/Python implementation is the better standalone design.

Phase List

Phase issues:

1. Phase 1: Remaining-work audit expansion, runtime contract, and docs architecture #158 Remaining-work audit expansion, runtime contract, and docs architecture
2. Phase 2: clean_rawdata and FIRFilt bundled-plugin completion #159 clean_rawdata and FIRFilt bundled-plugin completion
3. Phase 3: DIPFIT and source-localization standalone parity #160 DIPFIT and source-localization standalone parity
4. Phase 4: STUDY statistics, PAC, and LIMO-compatible workflows #161 STUDY statistics, PAC, and LIMO-compatible workflows
5. Phase 5: Large-dataset storage and storedisk semantics #162 Large-dataset storage and storedisk semantics
6. Phase 6: ICLabel, viewprops, and visual diagnostics completion #163 ICLabel, viewprops, and visual diagnostics completion
7. Phase 7: EEGLAB-style Sphinx documentation and tutorials #164 EEGLAB-style Sphinx documentation and tutorials
8. Phase 8: Final integration, QA, release hardening, and evidence #165 Final integration, QA, release hardening, and evidence

Parallelization

1. Phase 1 must merge first. It defines the expanded matrix, documentation architecture, optional-dependency rules, and what counts as non-stale for this final epic.
2. After Phase 1, Phases 2, 3, 5, and 6 can run in parallel because they touch different plugin/runtime domains.
3. Phase 4 can start after Phase 1 and may run in parallel with 2/3/5/6, but must coordinate with Phase 3 for DIPFIT/STUDY source-localization assumptions and with Phase 5 for large STUDY data storage.
4. Phase 7 should start after Phase 1 for docs architecture but merge after Phases 2-6 so the user docs describe completed behavior, not intentions.
5. Phase 8 runs last after all feature/docs phases merge.

Recommended merge order:

1 -> 2 + 3 + 4 + 5 + 6 -> 7 -> 8 -> final epic PR

Epic-Level Acceptance Criteria

• EEGPrep remains standalone; no installed package runtime path depends on the vendored EEGLAB checkout.
• Every remaining non-stale EEGLAB workflow identified for this epic is implemented, intentionally classified, or documented as an explicit optional-dependency limitation.
• GUI, Python API, and eegprep-console remain synchronized for every new user-facing workflow.
• GUI features include side-by-side EEGLAB/EEGPrep visual parity images attached to phase PRs.
• Numerical workflows have MATLAB parity tests where deterministic and feasible.
• Sphinx docs are organized like a real user manual: installation, concepts, GUI workflows, command/console workflows, tutorials, API reference, plugin docs, developer docs, and migration notes for EEGLAB users.
• Final branch passes lint, type check, non-slow tests, MATLAB-enabled parity where available, docs build, visual parity suite, and GUI Agent mixed workflow QA.

[claude]

🤖 Plan:

• Read issue, confirm scope
• Duplicate-work preflight (phases Phase 1: Remaining-work audit expansion, runtime contract, and docs architecture #158–Phase 8: Final integration, QA, release hardening, and evidence #165, stacking PR [Parity] Complete remaining EEGLAB core gaps #152)
• Decide: no PR — epic is far beyond the <100-line bug-fix threshold
• Post analysis

Analysis

This is a meta epic, not an actionable single fix. The 8 phases are already filed as separate issues (#158–#165) and the epic explicitly stacks on PR #152 (feature/eeglab-core-parity-completion, OPEN, mergeable, all checks green). Both epic branches (feature/eeglab-full-standalone-completion, feature/eeglab-core-parity-completion) already exist on origin and currently point at the same commit, so no epic-level code work is staged here. The fix-issue skill targets <100-line, self-contained changes; this epic spans plugin depth, runtime/storage design, statistics, docs architecture, and final QA across the whole package.

Relevant items

• [Parity] Complete remaining EEGLAB core gaps #152 — base PR this epic stacks on; must merge first.
• Phase 1: Remaining-work audit expansion, runtime contract, and docs architecture #158 Phase 1 — audit expansion, runtime contract, docs architecture (gating phase, must merge before 2–7).
• Phase 2: clean_rawdata and FIRFilt bundled-plugin completion #159 Phase 3: DIPFIT and source-localization standalone parity #160 Phase 4: STUDY statistics, PAC, and LIMO-compatible workflows #161 Phase 5: Large-dataset storage and storedisk semantics #162 Phase 6: ICLabel, viewprops, and visual diagnostics completion #163 — Phases 2–6, parallelizable after Phase 1: Remaining-work audit expansion, runtime contract, and docs architecture #158.
• Phase 7: EEGLAB-style Sphinx documentation and tutorials #164 Phase 7 — docs; start after Phase 1: Remaining-work audit expansion, runtime contract, and docs architecture #158, merge after 2–6.
• Phase 8: Final integration, QA, release hardening, and evidence #165 Phase 8 — final integration/QA/release.
• .notes/eeglab-migration-gap-audit.md — source-of-truth gap list for this epic.
• docs/parity/eeglab_core_parity_matrix.json — 608/608 in-scope core rows already green per the epic body.

Proposed Path Forward

Do not open an epic-level PR. The correct unit of work is each phase issue, opened against feature/eeglab-full-standalone-completion per the epic's branching plan. Concretely:

1. Wait for [Parity] Complete remaining EEGLAB core gaps #152 to merge into develop, then rebase feature/eeglab-full-standalone-completion onto the updated feature/eeglab-core-parity-completion (or directly onto develop once [Parity] Complete remaining EEGLAB core gaps #152 lands).
2. Start with Phase 1 (Phase 1: Remaining-work audit expansion, runtime contract, and docs architecture #158): it must define the expanded gap matrix, the standalone runtime contract (no src/eegprep/eeglab/ runtime dependence), optional-dependency rules, and the Sphinx docs architecture that Phases 2–7 will fill in. Until Phase 1: Remaining-work audit expansion, runtime contract, and docs architecture #158 lands, Phases 2–6 have no agreed staleness/optional-dependency classification to work against.
3. After Phase 1: Remaining-work audit expansion, runtime contract, and docs architecture #158, fan out Phases 2, 3, 5, 6 in parallel (independent plugin/runtime domains), with Phase 4 coordinating with Phase 3 (DIPFIT/STUDY source-localization) and Phase 5 (large STUDY data).
4. Phase 7 (docs) starts after Phase 1: Remaining-work audit expansion, runtime contract, and docs architecture #158, merges after Phase 2: clean_rawdata and FIRFilt bundled-plugin completion #159–Phase 6: ICLabel, viewprops, and visual diagnostics completion #163.
5. Phase 8 runs last and produces evidence: lint, type-check, non-slow tests, MATLAB-enabled parity where available, docs build, visual parity suite, GUI Agent mixed-flow QA.

If a human reviewer wants any concrete sub-task picked up now, the only non-blocking, non-#152-dependent work is bookkeeping inside Phase 1's scope (e.g., expanding .notes/eeglab-migration-gap-audit.md with the bundled-plugin/runtime/storage/docs surfaces already enumerated in this epic body). That belongs on #158, not on a new PR against #157.

No code change opened.