GUI and Console Together#

EEGPrep is designed for a mixed interactive workflow. You can load and review data from the GUI, inspect the live workspace in eegprep-console, run a Python command, then return to the GUI without manually copying datasets between tools.

The important idea is simple: the GUI and console are two views of one EEGPrepSession.

When to Use This Workflow#

Use eegprep-console --full when you want to:

  • learn what each menu action does by reading LASTCOM;

  • inspect EEG fields immediately after a dialog closes;

  • try a Python command before committing it to a script;

  • compare multiple loaded datasets in ALLEEG;

  • review STUDY state while using Study menu actions;

  • keep a complete ALLCOM history for a notebook, script, or lab record.

Use eegprep-gui --full only when you want a GUI-only session and do not need live Python inspection.

Daily Workflow#

Start the shared session:

uv run eegprep-console --full

Then move between the GUI and console:

Load sample_data/eeglab_data.set with File > Load existing dataset.

In the console, inspect EEG["data"].shape, CURRENTSET, and LASTCOM.

Run pop_resample(EEG, 64) in the console.

Return to the GUI and open Plot > Channel data (scroll); the browser sees the resampled current dataset.

Open Tools > Filter the data from the GUI, press OK, then inspect LASTCOM and ALLCOM[-3:].

Copy the useful commands into a script with explicit assignment.

What Stays Synchronized#

Name

What it means

How it updates

EEG

Current dataset dictionary.

GUI actions and console pop_* wrappers store the new current dataset through the session.

ALLEEG

Loaded dataset list.

Load, save-as-new, delete, clone, and dataset-selection actions go through session storage helpers.

CURRENTSET

Current dataset selection, exposed as 0, a scalar, or a list in the console.

Dataset menu changes and console storage calls update the same value.

LASTCOM

Most recent replayable command string.

Successful GUI actions and history-aware pop_* calls replace it.

ALLCOM

Chronological session command history.

The session appends commands once, so GUI and console history stay in the same order.

STUDY and CURRENTSTUDY

Current group-analysis state.

Study menu actions and study pop_* calls update the shared session.

session.PLUGINLIST

Bundled and installed extension inventory.

Extension Manager and plugin registry calls store the inventory on the shared session object.

How EEGPrep Implements It#

EEGPrepSession is the single source of truth for interactive state. The main window, menus, dialogs, help actions, dataset menus, Study workflows, Extension Manager, and eegprep-console all read from and write to this session.

GUI actions should update state through session helpers such as store_current(), add_history(), set_study(), and notify_changed(). They should not mutate a GUI-only copy of EEG that the console cannot see.

Long-running GUI actions use the same session boundary. For example, GUI-launched ICA opens the EEGLAB-like pop_runica options dialog on the main thread, runs the ICA computation behind a progress dialog, then stores the updated dataset and history only after the worker finishes successfully. While the worker is running, progress messages are buffered safely for eegprep-console so the replayable command remains visible before related output.

eegprep-console wraps registered pop_* functions. When a bare call such as pop_resample(EEG, 64) returns a dataset and command string, the wrapper stores the returned dataset, updates LASTCOM and ALLCOM, and tells the GUI to refresh. This auto-store behavior belongs to eegprep-console because it has a session to update.

Normal Python scripts keep normal Python semantics:

EEG, com = pop_resample(EEG, 64, return_com=True)

Use explicit assignment in scripts, notebooks, tests, and batch jobs.

Run Registered Menus Without Dialogs#

Automation and parity checks can run a real registered menu workflow against the same session without opening Qt dialogs. Pass the exact menu label, its registered pop_* function, and explicit parameters:

from eegprep import EEGPrepSession, eeglab_execmenu

session = EEGPrepSession()
eeglab_execmenu(
    "From ASCII/float file or MATLAB array",
    "pop_importdata",
    {"data": data, "dataformat": "array", "srate": 100},
    session=session,
)
eeglab_execmenu(
    "Change sampling rate",
    "pop_resample",
    [64],
    session=session,
)

eeglab_execmenu verifies that the label and function identify the same declarative menu item, calls only an explicit set of noninteractive workflows, and updates EEG, ALLEEG, CURRENTSET, LASTCOM, and ALLCOM as one session operation. It never evaluates callback or history strings. For a deterministic replay, retain the label/function/parameter triples and dispatch them in the same order into a fresh EEGPrepSession.

History You Can Reuse#

After a GUI action:

print(LASTCOM)
for command in ALLCOM[-5:]:
    print(command)

The recorded commands are meant to be readable and scriptable. When you move them out of the console, keep explicit return values:

EEG, com = pop_eegfiltnew(EEG, locutoff=1, hicutoff=40, return_com=True)
EEG, com = pop_resample(EEG, 64, return_com=True)

Practical Rules#

  • Prefer eegprep-console --full while learning or reviewing data.

  • Use the GUI for inspection-heavy actions and the console for quick checks, summaries, and repeatable commands.

  • Do not edit ALLEEG by hand in the console unless you are deliberately managing session state yourself.

  • Use return_com=True when a command should appear in a reproducible script.

  • Remember that GUI selectors are user-facing, while direct NumPy slicing is zero-based Python.

  • Save reviewed datasets explicitly; synchronized state is live session state, not a substitute for saving files.

Troubleshooting State#

If the GUI and console do not show what you expect, inspect:

CURRENTSET
EEG.get("setname")
EEG["data"].shape
LASTCOM
ALLCOM[-3:]
CURRENTSTUDY

If a menu item is disabled, the current dataset or STUDY probably lacks the fields that workflow needs. For example, component-review menus need ICA fields, and Study plotting menus need an active STUDY with precomputed measures.