EEG Recording & Epochs

EEGRecording

Wraps an MNE Raw object with LOC-specific preprocessing and epoch extraction.

EEGRecording

Wraps an MNE Raw object with LOC-specific metadata and methods.

Provides a high-level interface for loading, preprocessing, and extracting PSD epochs from EEG recordings. Researchers can access the underlying MNE Raw object via :meth:to_mne for custom processing.

Example::

recording = eeg.load("subject01.set")
recording.preprocess()
epochs = recording.extract_epochs(duration=2.0)
profile = eeg.score(epochs)

sfreq property

Sampling frequency in Hz.

n_channels property

Number of channels.

channel_names property

Channel names.

duration property

Recording duration in seconds.

preprocessed = False instance-attribute

preprocessing_log = [] instance-attribute

format = format instance-attribute

source_path = source_path instance-attribute

__init__(raw, format='unknown', source_path=None)

preprocess(*, bandpass=(0.5, 45.0), notch=50.0, reference='average', pick_eeg=True)

Apply standard EEG preprocessing.

Parameters:

Name	Type	Description	Default
bandpass	tuple[float, float]	(low, high) cutoff frequencies in Hz.	(0.5, 45.0)
notch	float | None	Powerline frequency (50 Hz EU, 60 Hz US). None to skip.	50.0
reference	str	Re-reference method — "average" or channel name(s).	'average'
pick_eeg	bool	Whether to pick only EEG-typed channels.	True

Returns:

Type	Description
EEGRecording	self (for chaining).

extract_epochs(duration=2.0, *, nperseg=256, noverlap=128, fmin=0.5, fmax=45.0, subject=None, task=None)

Extract PSD epochs from the recording.

Segments the continuous EEG into non-overlapping epochs and computes the power spectral density using Welch's method.

Parameters:

Name	Type	Description	Default
duration	float	Epoch duration in seconds.	2.0
nperseg	int	Welch window length in samples.	256
noverlap	int	Welch overlap in samples.	128
fmin	float	Minimum frequency for PSD output.	0.5
fmax	float	Maximum frequency for PSD output.	45.0
subject	str | None	Optional subject ID for metadata.	None
task	str | None	Optional task label for metadata.	None

Returns:

Type	Description
EpochSet	EpochSet with PSD data ready for server-side scoring.

to_mne()

Get the underlying MNE Raw object for custom processing.

Returns:

Type	Description
Raw	MNE Raw object (same reference, not a copy).

plot_psd(show=True)

Plot PSD using MNE's built-in method.

EpochSet

Collection of PSD epochs ready for server-side TC scoring.

EpochSet

Collection of PSD epochs ready for server-side TC scoring.

Contains power spectral density data for fixed-duration epochs, averaged across all EEG channels. Band power extraction and TC scoring happen server-side (IP protected).

Attributes:

Name	Type	Description
psd		PSD array of shape (n_epochs, n_freqs).
freqs		Frequency axis in Hz, shape (n_freqs,).
timestamps		Epoch onset times in seconds, shape (n_epochs,).
metadata		Recording metadata (subject, task, etc.).

shape property

(n_epochs, n_freqs).

n_epochs property

freq_range property

(min_freq, max_freq) in Hz.

duration property

Total duration in seconds (approximate).

psd = psd instance-attribute

freqs = freqs instance-attribute

timestamps = timestamps instance-attribute

metadata = metadata or {} instance-attribute

__init__(psd, freqs, timestamps, metadata=None)

to_numpy()

Return PSD array as numpy.

to_dict()

Serialize for API request.

plot_psd(show=True, save=None)

Plot average PSD across all epochs.

Parameters:

Name	Type	Description	Default
show	bool	Whether to display interactively.	True
save	str | None	Path to save the figure.	None

Returns:

Type	Description
Figure	matplotlib Figure.

Internal Modules

These modules are used internally by EEGRecording and EEG. They are documented here for reference but you typically do not call them directly.

Loader

load_file(path, **kwargs)

Load an EEG file, auto-detecting format from extension.

Parameters:

Name	Type	Description	Default
path	str | Path	Path to EEG file.	required
**kwargs	object	Passed to the MNE reader.	{}

Returns:

Type	Description
tuple[Raw, str]	Tuple of (MNE Raw object, format string).

load_array(data, sfreq, ch_names=None)

Create MNE Raw from a NumPy array.

Parameters:

Name	Type	Description	Default
data	ndarray	EEG data array, shape (n_channels, n_samples).	required
sfreq	float	Sampling frequency in Hz.	required
ch_names	list[str] | None	Channel names. Defaults to Ch1, Ch2, ...	None

Returns:

Type	Description
tuple[Raw, str]	Tuple of (MNE Raw object, "array").

Preprocessing

preprocess(raw, *, bandpass=(0.5, 45.0), notch=50.0, reference='average', pick_eeg=True)

Apply standard EEG preprocessing pipeline.

Parameters:

Name	Type	Description	Default
raw	Raw	MNE Raw object (modified in-place).	required
bandpass	tuple[float, float]	(low, high) cutoff frequencies in Hz.	(0.5, 45.0)
notch	float | None	Powerline frequency to notch filter (50 Hz EU, 60 Hz US). Set to None to skip notch filtering.	50.0
reference	str	Re-reference method — "average", channel name, or list of channels.	'average'
pick_eeg	bool	Whether to pick only EEG channels (drop ECG, EOG, etc.).	True

Returns:

Type	Description
tuple[Raw, list[str]]	Tuple of (preprocessed Raw, log of steps applied).

PSD Computation

compute_psd_epochs(raw, epoch_duration=2.0, *, nperseg=256, noverlap=128, fmin=0.5, fmax=45.0)

Compute Welch PSD for fixed-duration epochs.

Segments the continuous EEG into non-overlapping epochs of epoch_duration seconds and computes the power spectral density for each epoch, averaged across all channels.

Parameters:

Name	Type	Description	Default
raw	Raw	Preprocessed MNE Raw object.	required
epoch_duration	float	Duration of each epoch in seconds.	2.0
nperseg	int	Welch window length in samples (capped at epoch length).	256
noverlap	int	Welch overlap in samples.	128
fmin	float	Minimum frequency to include in output PSD.	0.5
fmax	float	Maximum frequency to include in output PSD.	45.0

Returns:

Type	Description
tuple[ndarray, ndarray, ndarray]	Tuple of: - psd: (n_epochs, n_freqs) array of power spectral density values. - freqs: (n_freqs,) array of frequency bin centers in Hz. - timestamps: (n_epochs,) array of epoch onset times in seconds.