conninfpy.eeg_utils

EEG-specific data structures and reshape helpers.

class conninfpy.eeg_utils.Electrodes(*values)[source]

Bases: Enum

Class to return EEG electrode names and respective IDs based on 10-20 EEG system.

>>> Electrodes.Fp2.value
2
>>> Electrodes.P3.name
'P3'

Fp1 = 1

Fp2 = 2

F7 = 3

F3 = 4

Fz = 5

F4 = 6

F8 = 7

T3 = 8

T4 = 9

T5 = 10

T6 = 11

O1 = 12

O2 = 13

C3 = 14

Cz = 15

C4 = 16

P3 = 17

Pz = 18

P4 = 19

class conninfpy.eeg_utils.Bands(*values)[source]

Bases: Enum

Class to return EEG frequency bands with respective IDs.

>>> Bands.alpha1.value
3
>>> Bands.get_name_by_id(6)
'beta2'

delta = 1

theta = 2

alpha1 = 3

alpha2 = 4

beta1 = 5

beta2 = 6

gamma = 7

static get_name_by_id(id)[source]: Electrode name for a 1-based electrode id.

static get_values()[source]: List of member names for this enum.

class conninfpy.eeg_utils.PairsElectrodes1020(electrodes: Type[Electrodes])[source]

Bases: object

Class to resolve & return electrode pairs based on 10-20 EEG system.

Methods:: electrode_pairs: Function to resolve indexed electrode names. create_pairs_dict: Function to create mapped dictionary of electodes with pairs.
Attributes:: electrodes (List[Electrodes]): List of electrodes to consider nearest (List[Tuple[str, str]]): List of electrode pairs

>>> electrodes = [Electrodes.Fp1, Electrodes.Fp2, Electrodes.Fz]
>>> pairs_obj = PairsElectrodes1020(electrodes)
>>> pairs_obj.electrode_pairs
[('Fp1', 'Fp2'), ('Fp1', 'Fz'), ('Fp2', 'Fz')]
>>> pairs_dict = pairs_obj.create_pairs_dict(pairs_obj.nearest, filter_by=['Fp1'])
>>> ('Fp1', 'Fp2') in pairs_dict
True

property electrode_pairs

Returns electrode names as an indexed list as per combinations

>>> electrodes = [Electrodes.Fp1, Electrodes.Fp2, Electrodes.Fz]
>>> pairs_obj = PairsElectrodes1020(electrodes)
>>> pairs_obj.electrode_pairs
[('Fp1', 'Fp2'), ('Fp1', 'Fz'), ('Fp2', 'Fz')]

create_pairs_dict(pairs_list, filter_by=None)[source]

Map electrode pairs to the matching entries of pairs_list.

Parameters:

pairs_list (list of tuple) – Electrode-pair column names to be mapped.
filter_by (list of str, optional) – Keep only pair names containing at least one of these substrings.

Returns:

Keys are electrode-pair tuples (from self.electrodes), values are the matching entries of pairs_list.

Return type:

dict

Examples

>>> electrodes = [Electrodes.Fp1, Electrodes.Fp2, Electrodes.Fz]
>>> pairs_obj = PairsElectrodes1020(electrodes)
>>> pairs_obj.electrode_pairs
[('Fp1', 'Fp2'), ('Fp1', 'Fz'), ('Fp2', 'Fz')]

class conninfpy.eeg_utils.EEGData(data, subj_list, electrodes, el_pairs_list, bands)[source]

Bases: object

Container for band-resolved EEG connectivity data.

data

Connectivity values per subject, electrode pair, and band.

Type:: np.ndarray of shape (n_subjects, n_chan_pairs, n_freqs)

subj_list

Subject identifiers for the first axis of data.

Type:: list of str

electrodes

Electrode enum used to build the pairs.

Type:: type[Electrodes]

el_pairs_list

Electrode pairs indexing the second axis of data.

Type:: iterable of tuple

bands

Frequency-band labels for the third axis of data.

Type:: list

conninfpy.eeg_utils.read_from_eeg_dataframe(path_to_df, cond_prefix='fo', band_list=None)[source]

Read EEG connectivity data from a wide CSV into an EEGData.

The CSV has one row per subject and one column per <cond_prefix>_<band>_<pair> entry; the 10-20 electrode pairs are reconstructed from the column names.

Parameters:

path_to_df (str) – Path to the CSV file.
cond_prefix (str, optional) – Condition prefix identifying the relevant columns (default 'fo').
band_list (list of int, optional) – Frequency bands to keep; defaults to all seven Bands.

Returns:

With data of shape (n_subjects, n_chan_pairs, n_bands).

Return type:

EEGData

Examples

>>> eeg_data = read_from_eeg_dataframe('datasets/eeg_dataframe_nansfilled.csv', cond_prefix='fo')
>>> eeg_data.data.shape
(177, 171, 7)

conninfpy.eeg_utils.reshape_eeg_data(data: ndarray, reshape_bands: bool = True) → ndarray[source]

Unfold pair-indexed EEG data into per-band (n_chans, n_chans) matrices.

Parameters:

data (np.ndarray of shape (n_subjects, n_chan_pairs, n_bands)) – Pair-indexed data (a single subject may be passed as 2D).
reshape_bands (bool, optional) – If True, return block-diagonal matrices of shape (n_subjects, n_chans * n_bands, n_chans * n_bands) where each diagonal block is one band. If False, return (n_subjects, n_chans, n_chans, n_bands). Default True.

Returns:

Shape (n_chans, n_chans, n_bands) or (n_chans * n_bands, n_chans * n_bands) for single-subject input; batched shapes otherwise.

Return type:

np.ndarray

Notes

Assumes the 19-electrode 10-20 system (Electrodes).

Examples

>>> n_pairs = np.random.rand(2, len(PairsElectrodes1020(Electrodes).electrode_pairs), 3)
>>> reshape_eeg_data(n_pairs, reshape_bands=False).shape
(2, 19, 19, 3)
>>> reshape_eeg_data(n_pairs, reshape_bands=True).shape
(2, 57, 57)

conninfpy.eeg_utils.inverse_reshape_eeg_data(reshaped_data: ndarray, reshape_bands: bool = True) → ndarray[source]

Inverse of reshape_eeg_data().

Parameters:

reshaped_data (np.ndarray) – Shape (n_subjects, n_chans, n_chans, n_bands), or (n_subjects, n_chans * n_bands, n_chans * n_bands) when reshape_bands=True (a single subject may be passed as 2D).
reshape_bands (bool, optional) – Whether the input is in band-flattened (block-diagonal) form.

Returns:

Pair-indexed data of shape (n_subjects, n_chan_pairs, n_bands), or (n_chan_pairs, n_bands) for single-subject input.

Return type:

np.ndarray

Examples

>>> n_pairs = np.random.rand(2, len(PairsElectrodes1020(Electrodes).electrode_pairs), 3)
>>> reshaped = reshape_eeg_data(n_pairs, reshape_bands=True)
>>> reshaped.shape
(2, 57, 57)
>>> inverse_reshape_eeg_data(reshaped, reshape_bands=True).shape
(2, 171, 3)