GUI Tutorials#

EEGPrep’s GUI is built for practical EEG review: use menus and dialogs for visual decisions, keep eegprep-console beside it for inspection and repeatable commands, and save the resulting datasets when review is complete.

Launch#

Use the full menu set while learning:

uv run eegprep-console --full

Use the GUI-only launcher when you do not need a console:

uv run eegprep-gui --full

The console workflow is recommended because it shows LASTCOM and ALLCOM after each menu action. See GUI and Console Together for the shared-session model and implementation details.

Note

Plotting commands such as Plot > Channel spectra and maps and Plot > Channel ERPs > With scalp maps open a figure window on any interactive backend, whether you trigger them from a Plot menu or call the matching pop_* function in eegprep-console. On non-interactive backends (for example Agg in headless runs) the figure is built and returned without opening a window.

When scripting, pass plot='off' to any plotting pop_* function to build and return the figure without popping a window, for example fig = pop_spectopo(EEG, 1, [], freqs=[10], plot='off')['figure'] to save or embed it. The default plot='on' displays it.

Load, Inspect, and Save a Dataset#

Open File > Load existing dataset.

Select sample_data/eeglab_data.set.

In the console, run EEG["data"].shape, len(ALLEEG), CURRENTSET, and LASTCOM.

Choose Plot > Channel data (scroll) to inspect the current dataset in EEGBrowser.

Choose File > Save current dataset as when you want a new .set file.

Equivalent console calls:

from pathlib import Path
from eegprep import pop_loadset, pop_saveset

EEG = pop_loadset(Path("sample_data") / "eeglab_data.set")
pop_saveset(EEG, Path("sample_data") / "eeglab_data_reviewed.set")

Filter and Resample#

Use these steps for a small, inspectable preprocessing pass on the tutorial dataset:

GUI action	Console equivalent
`Tools > Filter the data`	`pop_eegfiltnew(EEG, locutoff=1, hicutoff=40)`
`Tools > Change sampling rate`	`pop_resample(EEG, 64)`
`Plot > Channel spectra and maps`	`pop_spectopo(EEG, 1, [])`

Filtering with pop_eegfiltnew uses the bundled FIRFilt-style Hamming-window FIR defaults. Boundary events are respected when continuous data contains breaks. Resampling updates event latencies and clears stale ICA activations.

Clean Continuous Data#

The bundled clean_rawdata workflow is available through the extension menu surface and from Python:

from eegprep import pop_clean_rawdata

EEG, com = pop_clean_rawdata(
    EEG,
    FlatlineCriterion=5,
    ChannelCriterion=0.8,
    LineNoiseCriterion=4,
    Highpass=(0.25, 0.75),
    BurstCriterion=20,
    WindowCriterion=0.25,
    return_com=True,
)

Run this on continuous data before epoching. If the dialog offers a rejected data browser, accepting the browser keeps marks and history synchronized with the shared session.

Run ICA and Review ICLabel#

For a fast review tutorial, load the ICA sample first:

EEG = pop_loadset("sample_data/eeglab_data_epochs_ica.set")

Then use the GUI:

Choose Tools > Decompose data by ICA for datasets that do not already contain ICA fields. The sample above already has ICA.

Choose Tools > Classify components using ICLabel.

Choose Plot > Component properties to open the ICLabel-aware property dashboard.

Toggle component rejection marks, press OK, and inspect EEG["reject"]["gcompreject"] in the console.

Choose Tools > Remove components from data only after reviewing labels, scalp maps, spectra, activity, and any DIPFIT fields.

Equivalent console calls:

from eegprep import eeg_icalabelstat, pop_icflag, pop_iclabel, pop_subcomp, pop_viewprops

EEG, com = pop_iclabel(EEG, "default", return_com=True)
stats = eeg_icalabelstat(EEG, threshold=0.9, verbose=False)
figures = pop_viewprops(EEG, typecomp=0, chanorcomp=[1, 2, 3])
EEG, com = pop_icflag(EEG, return_com=True)
EEG, com = pop_subcomp(EEG, [], return_com=True)

Use the empty component list in pop_subcomp(EEG, []) to remove components currently marked in EEG.reject.gcompreject.

Sort Trials in an ERP Image#

An event-related potential (ERP) image stacks the single trials of one channel or component as colored rows, sorted by an event value, so latency or phase effects that the average hides become visible. Load the ICA sample, or reload sample_data/eeglab_data_epochs_ica.set if you removed components above:

Choose Plot > Channel ERP image.

Enter Cz (or 14) as the channel and keep smoothing at 10.

Press Epoch-sorting field and pick latency; a reminder asks for an event type while that box is empty. Then press Event type(s), pick rt, and press OK.

In the console, LASTCOM holds the Python call, for example pop_erpimage(EEG, 1, 'Cz', smooth=10, decimate=1, sortingtype=['rt'], sortingeventfield='latency').

Edit and run it there, for example with erpstd='on' added, to try erpimage options that have no dialog field (they also fit in More options). EEGLAB-style 'key', value pairs work only after all ten positional arguments, so add keywords to this call.

Choose the menu again: the dialog reopens with these values.

Equivalent console call:

from eegprep import pop_erpimage

result, com = pop_erpimage(EEG, 1, "Cz", None, "", 10, 1, ["rt"], None, "latency", return_com=True)
result.outdata.shape  # (frames, smoothed trials)
result.sortidx[:5]  # 0-based input trials, in plotted order

Both the menu and the console record the same command in ALLCOM; an ERP image does not change EEG or ALLEEG. Epochs without a matching event are left out of the image, and a console warning lists them. When no epoch has a matching event, pop_erpimage raises an error instead. Plot > Component ERP image works the same way for components, with an optional channel to project them onto.

Use EEGBrowser for Rejection#

Plot > Channel data (scroll) opens EEGBrowser for inspection. Rejection workflows open the same browser in a marking mode. Continuous marks can become sample-removal intervals through eeg_eegrej; epoch marks can update EEG.reject.rejmanual and then be removed with pop_rejepoch.

See EEGBrowser Workflows for browser modes, mark fields, and performance behavior.

Create a STUDY#

With multiple datasets loaded in ALLEEG:

Choose File > Create study > Using all loaded datasets.

Inspect STUDY and CURRENTSTUDY in the console.

Choose Study > Precompute channel measures for ERP, spectrum, ERSP, or ITC caches.

Choose Study > Plot channel measures to review cached measures.

Choose File > Save current study as for a durable .study file.

Equivalent console call:

STUDY, ALLEEG, com = pop_study(None, ALLEEG, name="Tutorial study", return_com=True)

See STUDY Workflows for design variables, cached measures, clustering, PAC, and explicit optional-backend boundaries.

DIPFIT Source Workflow#

Dataset-level DIPFIT helpers are bundled for standalone spherical workflows. Use them after ICA:

from eegprep import pop_dipfit_gridsearch, pop_dipfit_nonlinear, pop_dipfit_settings, pop_dipplot

EEG, com = pop_dipfit_settings(EEG, model="standardBESA", return_com=True)
EEG, com = pop_dipfit_gridsearch(
    EEG,
    [1],
    [-40, -20, 0, 20, 40],
    [-40, -20, 0, 20, 40],
    [20, 40, 60],
    40,
    return_com=True,
)
EEG, com = pop_dipfit_nonlinear(EEG, component=1, return_com=True)
figures, com = pop_dipplot(EEG, [1], summary="on", return_com=True)

MRI-derived BEM creation, AFNI atlas clipping, LORETA analysis, and STUDY-level source statistics remain explicit backend boundaries. EEGPrep raises clear errors for unavailable external workflows instead of producing placeholder results.

Troubleshooting GUI State#

If a menu item is disabled, check the current state:

CURRENTSET
CURRENTSTUDY
EEG.get("icaweights")
EEG.get("trials")

Use --full to show legacy and advanced menu entries. Use --no-plugins to diagnose extension startup problems with only core EEGPrep menus.