Phase 4: STUDY statistics, PAC, and LIMO-compatible workflows

[suraj-ranganath]

🤖 Phase 4 completes advanced STUDY statistics, PAC, and LIMO-compatible workflows where EEGPrep can provide real standalone behavior.

Summary

Bring advanced group/statistical workflows to product quality: PAC compute/cache/plot behavior, LIMO-compatible design/result surfaces or explicit optional integration, neighbour/interpolation assumptions, and STUDY statistics/reporting paths that researchers expect after STUDY preprocessing.

Scope

• PAC: practical standalone pac, pac_cont, std_pac, std_pacplot, and std_readpac behavior or a clear optional-dependency-backed implementation if needed.
• LIMO-compatible workflows: pop_limo, pop_limoresults, std_limo, std_limodesign, std_limoresults, std_limoerase, and result readers, implemented as standalone EEGPrep statistical workflows where feasible or clear integration points where not.
• STUDY neighbour/interpolation/stat parameter workflows that were classified as external or runtime skips but are needed by real user flows.
• Cross-check with Phase 3 for source localization and Phase 5 for large STUDY data/cache storage.

Acceptance Criteria

• No user-facing advanced STUDY/PAC/LIMO path silently no-ops or returns fake results.
• Implemented workflows have docs, help, replayable commands, GUI/console synchronization, and sample multi-dataset tests.
• Optional external dependencies are explicit in pyproject.toml, docs, error messages, and tests if adopted.
• MATLAB parity tests cover deterministic structures/results where feasible; numerical tolerances are documented.
• GUI dialogs/plots have visual parity evidence.

Required References

• AGENTS.md
• src/eegprep/eeglab/functions/studyfunc/
• src/eegprep/eeglab/functions/timefreqfunc/pac.m
• src/eegprep/eeglab/functions/timefreqfunc/pac_cont.m
• src/eegprep/functions/studyfunc/
• src/eegprep/functions/timefreqfunc/
• .agents/skills/eegprep-feature-development/SKILL.md
• .agents/skills/eeglab-gui-visual-parity/SKILL.md
• .agents/skills/gui-agent-flow-qa/SKILL.md

/goal

/goal Complete advanced EEGPrep STUDY statistics, PAC, and LIMO-compatible workflows from the final parity audit. Use EEGLAB as behavior reference but implement real standalone Python behavior or explicit optional-dependency integrations; no fake result placeholders. Verify with multi-dataset sample fixtures, MATLAB parity where deterministic, GUI visual parity, console/history sync tests, docs/help resources, ruff/format/ty, non-slow pytest, and pre-commit. Coordinate contracts with DIPFIT/source and storage phases, and report any remaining external-only limitations clearly.

[claude]

🤖 Plan:

• Fetch issue and confirm scope
• Duplicate-work preflight (open PRs/issues)
• Survey current PAC / LIMO / STUDY-stats surface area
• Post research + proposed approach for human review
• Await scope/sequencing decision before opening implementation PRs

Research

Phase 4 covers three independent sub-areas with no current implementations in eegprep: PAC (pac, pac_cont, std_pac, std_pacplot, std_readpac), LIMO-compatible workflows (pop_limo, pop_limoresults, std_limo, std_limodesign, std_limoresults, std_limoerase), and the STUDY neighbour/interpolation/statistics-parameter paths that earlier phases deferred. Nothing under src/eegprep/functions/timefreqfunc/ or src/eegprep/functions/studyfunc/ currently exposes these surfaces; only help text references them as deferred. Implementing all three to the issue's acceptance bar (real standalone behaviour, MATLAB parity tests, GUI visual parity, docs/help, multi-dataset fixtures) is well over 100 lines and crosses many modules, so a single PR is not appropriate.

Relevant code

• src/eegprep/functions/timefreqfunc/__init__.py — only newtimef/newcrossf present; no pac*.
• src/eegprep/functions/studyfunc/__init__.py — no std_limo*, std_pac*, pop_limo*, std_stat* modules.
• src/eegprep/resources/help/pop_studydesign.md#L21 — current help defers LIMO/precompute/plotting to later phases.
• src/eegprep/resources/help/eeg_helpstatistics.md#L11-L15 — STUDY/LIMO statistics explicitly listed as not yet covered.
• src/eegprep/functions/guifunc/menu_placeholders.py — placeholder inventory is empty; menu coverage for these actions needs to be added or wired through pop wrappers.

Duplicate-work preflight: open PR #152 (feature/eeglab-core-parity-completion) targets remaining core gaps but does not overlap PAC/LIMO/STUDY-stats. No open PR is implementing this issue.

Proposed Approach

Recommend splitting Phase 4 into three sequential sub-issues + PRs so each lands reviewable and testable:

1. STUDY statistics core (foundation for both other tracks). Port statcond, bootstat, fdr, std_stat, neighbour computation, and spherical-spline interpolation glue used by STUDY plots. Add pop_statparams GUI parity and console-replayable history. Tests: MATLAB parity for statcond/fdr on small fixtures (Engine/Octave-gated), multi-dataset sample fixture for std_stat. This is the prerequisite for meaningful PAC group plots and any LIMO result reader.

2. PAC compute + STUDY integration. Port pac and pac_cont (modulation index + phase-locking) into functions/timefreqfunc/, then std_pac, std_readpac, std_pacplot into functions/studyfunc/. Reuse newtimef-style spectral helpers already present. Tests: numerical parity vs MATLAB on a 2-channel synthetic dataset, plus a small sample_data multi-dataset PAC fixture and a visual parity case under tools/visual_parity for std_pacplot. Standalone implementation — no optional dep required.

3. LIMO-compatible workflows. Two viable paths; need a decision before coding (see Open Questions): (a) implement a standalone EEGPrep LIMO-style mass-univariate GLM that consumes STUDY designs and emits the same on-disk result layout EEGLAB writes, or (b) make LIMO an explicit optional dependency surfaced through a limo_eeg Python wrapper with clear pyproject.toml extra, error messages, and skipped tests. Either way ports pop_limo, pop_limoresults, std_limo, std_limodesign, std_limoresults, std_limoerase. Tests: design-matrix parity for std_limodesign, end-to-end small-design run, result reader round-trip.

For each sub-PR: add Markdown help under src/eegprep/resources/help/, ensure return_com=True paths and EEGPrepSession history sync, register any new GUI dialog in menu_placeholders.py removals + pop_* wrappers, attach visual-parity screenshots to the PR (not the repo), and run ./pre-commit.py --fix + uv run pytest -m "not slow".

Open Questions (need human decision before implementation)

1. LIMO path (a) standalone GLM vs (b) optional limo_eeg/limo-python dep — which does the maintainer prefer for the catalog story?
2. MATLAB-parity tolerance for PAC modulation-index values and STUDY statcond permutation distributions — acceptable rtol/atol?
3. Are PAC-on-source and LIMO source-space results required in Phase 4 or do they sit behind Phase 3 (DIPFIT, Phase 3: DIPFIT and source-localization standalone parity #160) and Phase 5 (Phase 5: Large-dataset storage and storedisk semantics #162) completion?
4. Should STUDY neighbour computation reuse MNE's find_ch_adjacency (already a dep) or be a fresh port of EEGLAB std_prepare_neighbors?

Will hold off implementation until these are resolved; happy to open the STUDY-stats foundation PR first as soon as it's green-lit since it is the unblocker for the rest.

[suraj-ranganath]

🤖 Phase PR for this issue has merged into feature/eeglab-full-standalone-completion and integration checks are passing on the epic branch. Closing this phase issue as completed.