eegproc.deep_learning.prepare_datasets module

prepare_datasets.py

Convert supported public EEG datasets into complete-trial NumPy arrays. Callers can then window and label these arrays for their own models. Outputs:

{dataset}_eeg.npy — float32, shape (n_subjects, n_trials, n_channels, n_samples) {dataset}_labels.npy — float32, shape (n_subjects, n_trials, n_label_dims)

Usage

# DEAP (point to the folder containing s01.dat … s32.dat) python prepare_datasets.py –dataset deap –input_dir /path/to/deap/data_preprocessed_python

# DREAMER (point to the folder containing dreamer_joined.csv) python prepare_datasets.py –dataset dreamer –input_dir /path/to/dreamer

# AMIGOS (point to the folder containing amigos_joined.csv, or to the # legacy unzipped ‘data_preprocessed’ folder containing # Data_Preprocessed_P01.mat … Data_Preprocessed_P40.mat) python prepare_datasets.py –dataset amigos –input_dir /path/to/amigos

# All three python prepare_datasets.py –dataset all –deap_dir /path/to/deap/data_preprocessed_python –dreamer_dir /path/to/dreamer –amigos_dir /path/to/amigos/data_preprocessed

# EEGEmotions (point to the folder containing eegemotions_labeled.csv and cowen_27_valence_arousal.csv) python prepare_datasets.py –dataset eegemotions –input_dir /path/to/eegemotions –eegemotions_label_mode emotion_27

# EEGEmotions with valence/arousal labels from the Cowen 27 mapping python prepare_datasets.py –dataset eegemotions –input_dir /path/to/eegemotions –eegemotions_label_mode valence_arousal

Output files are written to the current working directory (or –output_dir).

Dataset structures

DEAP (preprocessed Python version):
    s01.dat ... s32.dat — each is a pickle dict with keys:
        'data'   : (40, 40, 8064)  trials x (32 EEG + 8 peripheral) x samples
                   We keep only the first 32 channels (EEG).
                   Signals are already downsampled to 128 Hz and filtered 4-45 Hz.
                   The first 3 seconds of each trial (baseline) are pre-removed
                   in some versions; we trim to the last 60 s (7680 samples).
        'labels' : (40, 4)  valence, arousal, dominance, liking  (1-9 scale)

DREAMER (dreamer_joined.csv):
    Long/tidy format — one row per EEG sample with columns:
        subject_id, trial_id, segment, sample_idx,
        AF3, F7, F3, FC5, T7, P7, O1, O2, P8, T8, FC6, F4, F8, AF4,
        ECG1, ECG2, valence, arousal, dominance
    This script groups by subject_id/trial_id, keeps the 14 EEG channels, and
    selects only the contiguous stimulus segment for each subject/trial and
    applies EEGProc's preprocessing.bandpass_filter to that stimulus recording.
    The retained waveforms are theta (4-8 Hz), alpha (8-13 Hz), and
    beta (13-30 Hz); delta and gamma are omitted. A 50 Hz notch is applied
    before the band-pass filters. The 14 x 3 channel-band outputs are
    flattened channel-major, for example AF3_theta, AF3_alpha, AF3_beta,
    F7_theta, ... .
    Baseline rows are excluded. Stimulus lengths vary; filtering is performed
    on the full contiguous stimulus before taking its middle 60 s (7680 samples),
    which reduces boundary artifacts in the retained data.
    This three-band representation matches DREAMER's published 4-30 Hz
    preprocessing range and avoids constructing a gamma feature from data that
    may already have been low-pass filtered at 30 Hz.
    NOTE: even though the CSV includes dominance, this converter writes labels
    with shape (n_subjects, 18, 2) using [valence, arousal] only.

AMIGOS (joined CSV or legacy preprocessed Matlab version):
    ``amigos_joined.csv`` is a long-form table with one row per EEG sample.
    It contains ``subject_id``, ``trial_id``, ``sample_idx``, the 14 EEG
    channels in the same Emotiv EPOC order as DREAMER, two peripheral ECG
    columns that are ignored here, and ``valence``, ``arousal``,
    ``dominance`` labels. This script groups by subject/trial, keeps the 14
    EEG channels, extracts the center 60 s from each trial, and writes raw
    labels with shape ``(n_subjects, n_trials, 2)`` using [valence,
    arousal] only.

    For backwards compatibility, the legacy ``Data_Preprocessed_P01.mat`` ...
    ``Data_Preprocessed_P40.mat`` layout is still supported if the joined CSV
    is not present.

EEGEmotions (joined CSV + Cowen 27 mapping):
        ``eegemotions_labeled.csv`` stores one EEG sample per row with columns:
                subject_id, trial_id, segment, sample_idx,
                AF3, F7, F3, FC5, T7, P7, O1, O2, P8, T8, FC6, F4, F8, AF4,
                age, gender, nation, source_file, source_file_label,
                emo_label_cowen_27, emo_label_ekman_6
        This converter uses the 14 EEG channels above, keeps the first 27 emotion
        trials for each complete subject, and extracts the center 60 s from each
        trial. The labels can be written in one of two modes:

        - ``emotion_27``: one-hot vectors with shape ``(n_subjects, 27)``
        - ``valence_arousal``: mapped Cowen valence/arousal vectors with shape
            ``(n_subjects, 2)``

        The accompanying ``cowen_27_valence_arousal.csv`` file provides the
        emotion-to-valence/arousal mapping.

eegproc.deep_learning.prepare_datasets.load_amigos_joined_csv(filepath)[source]

Load the joined AMIGOS CSV and convert it to raw trial arrays.

The joined CSV stores one EEG sample per row, so this loader streams the file in subject/trial order, groups rows into trials, keeps only the 14 EEG channels, and extracts the center 60 s from each trial.

Parameters:: filepath (str)
Return type:: tuple[ndarray, ndarray]

eegproc.deep_learning.prepare_datasets.load_amigos_subject(filepath)[source]

Load one AMIGOS subject .mat file.

Parameters:

filepath (str)

Return type:

tuple[ndarray, ndarray]

Returns:

eeg (float32 ndarray, shape (AMIGOS_N_TRIALS, AMIGOS_N_CHANNELS, AMIGOS_TRIAL_SAMPLES))
labels (float32 ndarray, shape (AMIGOS_N_TRIALS, 2) [valence, arousal])

Raises:

ValueError – If one of the first AMIGOS_N_TRIALS trials is missing its EEG signal or its self-assessment label (this shouldn’t happen for any subject not already in AMIGOS_SKIPPED_SUBJECTS, since the missing-data issue in the public release only affects the 4 long-video trials this converter doesn’t use).

eegproc.deep_learning.prepare_datasets.load_cowen_27_mapping(filepath)[source]

Load the 27-row Cowen mapping, ordered by EEGEmotions-27 emotion ID.

Rows are matched by their emotion name, so the file’s own row order does not matter (eegproc-to-csv --dataset cowen27 sorts by quadrant). Row k - 1 of the returned array holds the valence and arousal of emotion ID k.

Parameters:: filepath (str)
Return type:: tuple[list[str], ndarray]

eegproc.deep_learning.prepare_datasets.load_deap_subject(filepath)[source]

Load one DEAP subject file.

Parameters:

filepath (str)

Return type:

tuple[ndarray, ndarray]

Returns:

eeg (float32 ndarray, shape (40, 32, 7680))
labels (float32 ndarray, shape (40, 4) [valence, arousal, dominance, liking])

eegproc.deep_learning.prepare_datasets.load_eegemotions_joined_csv(filepath, label_mode='emotion_27')[source]

Load eegemotions_labeled.csv and convert it to raw trial arrays.

Parameters:

filepath (str)
label_mode (str, default: 'emotion_27')

Return type:

tuple[ndarray, ndarray]

eegproc.deep_learning.prepare_datasets.prepare_amigos(input_dir, output_dir)[source]

Convert AMIGOS inputs to a single pair of .npy arrays.

input_dir can point to one of three things: - a directory containing amigos_joined.csv; - the amigos_joined.csv file itself; - a legacy data_preprocessed folder containing Data_Preprocessed_P*.mat.

The joined CSV path is preferred because it matches the current AMIGOS source file used by the joint-v2 pipeline.

Parameters:

input_dir (str)
output_dir (str)

Return type:

None

eegproc.deep_learning.prepare_datasets.prepare_deap(input_dir, output_dir)[source]

Convert all DEAP subject files to a single pair of .npy arrays.

Parameters:

input_dir (str)
output_dir (str)

Return type:

None

eegproc.deep_learning.prepare_datasets.prepare_dreamer(input_dir, output_dir)[source]

Convert dreamer_joined.csv to channel-band waveform arrays.

Only the contiguous stimulus segment is used. Baseline rows are excluded because the trial-level valence and arousal ratings describe the emotional film stimulus, not the pre-stimulus baseline. Filtering is applied to the complete stimulus recording before the middle 60 seconds are retained.

Parameters:

input_dir (str) – Folder containing dreamer_joined.csv.
output_dir (str) – Destination for dreamer_eeg.npy and dreamer_labels.npy.
shapes (Output)
-------------
dreamer_eeg.npy – Float32 (23, 18, 42, 7680). The feature dimension is 14 electrodes x 3 bands in channel-major order.
dreamer_labels.npy – Float32 (23, 18, 2) containing [valence, arousal].
windows (The converter does not pre-window these arrays. With four-second)
overlap (and 50%)
from (the training loader derives 29 flat window samples)
windows. (each retained 60-second trial and repeats the trial rating for those)

Return type:

None

eegproc.deep_learning.prepare_datasets.prepare_eegemotions(input_dir, output_dir, label_mode='emotion_27')[source]

Convert eegemotions_labeled.csv to a single pair of .npy arrays.

Parameters:

input_dir (str)
output_dir (str)
label_mode (str, default: 'emotion_27')

Return type:

None

eegproc.deep_learning.prepare_datasets.verify_npy(output_dir, dataset, label_mode=None)[source]

Reload and verify the saved .npy files.

Parameters:

output_dir (str)
dataset (str)
label_mode (str | None, default: None)

Return type:

None