Concepts Guide#

EEGPrep uses plain Python objects while keeping the EEG workflow vocabulary many researchers already know. The main objects, command names, history behavior, and menu flow are designed to be predictable for EEG researchers, including people coming from EEGLAB.

Workspace Names#

eegprep-console --full opens a Qt GUI and an IPython console against one shared EEGPrepSession. The console starts with familiar workspace names:

Name	Meaning in EEGPrep
`EEG`	The current EEG dataset dictionary.
`ALLEEG`	List of loaded EEG dataset dictionaries.
`CURRENTSET`	Current dataset selection, exposed as `0` when empty, a scalar for one selected dataset, or a list for multi-dataset selection.
`LASTCOM`	Last replayable command string returned by a GUI or `pop_*` action.
`ALLCOM`	Ordered command history for the interactive session.
`STUDY`	Current group-level STUDY dictionary.
`CURRENTSTUDY`	`1` when a STUDY is active, otherwise `0`.

These are normal Python names in the console namespace, not hidden globals. GUI actions update them through the shared session. Console calls update the GUI when they go through eegprep-console wrappers.

The EEG Dataset Dictionary#

EEGPrep datasets are plain dictionaries with EEGLAB field names. Continuous data is channel-major, usually (nbchan, pnts). Epoched data is usually (nbchan, pnts, trials).

Core fields include:

Field	Purpose
`data`	NumPy array, memory-mapped array, or retrieved in-memory data.
`nbchan`, `pnts`, `trials`	Channel count, points per trial, and trial count.
`srate`, `xmin`, `xmax`, `times`	Sampling rate, time limits in seconds, and time vector in milliseconds.
`chanlocs`	Channel metadata such as labels, types, and locations.
`event` and `urevent`	Event records and original event references.
`epoch`	Per-epoch metadata for epoched datasets.
`icaweights`, `icasphere`, `icawinv`, `icaact`	ICA decomposition fields and activations.
`icachansind`	Channels used for ICA. Stored internally as Python zero-based indices.
`reject`	Manual, automatic, and component rejection marks.
`history`	Dataset-level command history.
`etc`	Structured extension metadata, including ICLabel classifications.

Events, Epochs, and Indexing#

EEGLAB event latencies are user-facing sample positions. EEGPrep preserves that public convention in command strings and event records. Python array slicing is still zero-based internally.

Practical rules:

Use event latency values as EEGLAB-facing sample positions when reading or writing event metadata.
Use Python zero-based indexing when slicing EEG["data"].
Most pop_* command strings print user-facing values so history can be read and reused later.
icachansind is normalized to zero-based integer indices after loading a MATLAB .set file, then converted back to one-based values when saving.
chanlocs[i]["urchan"], event[i]["urevent"], epoch[k]["event"], and epoch[k]["eventurevent"] follow the same rule: zero-based in memory, one-based on disk.
Single-trial datasets have no epoch structure: eeg_checkset empties it and removes event[i]["epoch"], as EEGLAB does.
Deleting a dataset empties its ALLEEG slot (an empty {} entry) instead of shifting later datasets down, so the numbers in the Datasets menu, CURRENTSET, and the history stay valid, as in EEGLAB. New datasets fill the lowest empty slot and trailing empty slots are dropped. Selecting an empty slot is not possible: the selection falls back to a remaining dataset, as EEGLAB’s redraw does.
Building a STUDY needs contiguous dataset numbers, so creating or editing one compacts the empty slots away and renumbers the remaining datasets. EEGLAB’s std_editset does the same. Each dataset keeps its own STUDY metadata, and your selection follows the dataset it was on rather than the number. Editing a STUDY design, precomputing measures, and preclustering leave ALLEEG untouched, as in EEGLAB.

Two deliberate differences from EEGLAB:

After a delete, EEGPrep selects the nearest remaining dataset at or above the deleted number, while EEGLAB always falls back to the lowest-numbered dataset. Staying near the deleted dataset is friendlier when you delete from a long list.
EEGLAB refuses to delete when only one dataset is loaded and tells you to clear all datasets instead. EEGPrep deletes it and leaves an empty ALLEEG.
pop_saveset writes the MATLAB classes EEGLAB expects: integer fields become double, boolean masks stay logical, and epoch event fields are cell arrays when any epoch holds more than one event.

For epoched data, EEG["data"][:, :, trial_index] is zero-based Python indexing. User-facing epoch and component selectors in GUI dialogs use one-based values.

Channel Locations#

chanlocs is a list-like channel table. Common keys are labels, type, theta, radius, X, Y, Z, sph_theta, sph_phi, and sph_radius. Channel location readers and editors keep the EEGLAB field names so topographic plotting, interpolation, DIPFIT, ICLabel features, and STUDY channel measures can share the same metadata.

Use pop_chanedit or pop_readlocs when working through interactive channel-location dialogs. Use readlocs or direct dictionary updates only when scripting and you already know the channel table shape you need.

ICA and ICLabel Fields#

ICA workflows write the core fields used throughout EEGPrep:

icaweights and icasphere store the unmixing transform.
icawinv stores scalp maps.
icaact can be cached or recomputed from the decomposition.
reject.gcompreject stores component rejection flags.
etc.ic_classification.ICLabel.classifications stores ICLabel class probabilities in the order Brain, Muscle, Eye, Heart, Line Noise, Channel Noise, Other.

Run pop_runica before pop_iclabel. Use pop_viewprops or pop_prop_extended to review component properties, labels, and DIPFIT projections when available.

STUDY Structure#

EEGPrep STUDY dictionaries cover the implemented standalone group-analysis surface:

datasetinfo records dataset membership and metadata.
design records independent variables and selected designs.
changrp stores channel measure caches such as ERP, spectrum, ERSP, ITC, and PAC.
cluster stores component measure caches and clustering metadata.

The current implementation keeps measure caches in EEGPrep-owned JSON-safe structures unless a workflow explicitly writes sidecar data. MATLAB-only LIMO result files and external FieldTrip STUDY source statistics are explicit backend boundaries; they are not silently emulated.

History and Replay#

The most important EEGLAB workflow is still available: run something from the GUI, inspect the command, then reuse it in a script.

EEG, LASTCOM = pop_resample(EEG, 64, return_com=True)
print(LASTCOM)
ALLCOM.append(LASTCOM)

Inside eegprep-console, bare calls such as pop_resample(EEG, 64) can auto-store the returned dataset in the shared session. Normal Python scripts do not do that; assign returned values explicitly.

Standalone Runtime Boundary#

The installed EEGPrep package must work without src/eegprep/eeglab. The vendored EEGLAB tree is a development reference for parity work, not a runtime dependency. Packaged help, bundled plugin data, montages, ICLabel assets, and Sphinx documentation are EEGPrep-owned resources.

EEGLAB References Used#

The manual structure follows the EEGLAB tutorial site’s emphasis on quickstart, concepts, importing, preprocessing, plotting, STUDY, scripting, and data structures, while rewriting the content for EEGPrep’s Python, Qt GUI, and eegprep-console behavior.