medusa.meeg package

Submodules

medusa.meeg.meeg module

Created on Monday March 15 19:27:14 2021

In this module, you will find all functions and data structures related to EEG and MEG signals. Enjoy!

References

https://stefanappelhoff.com/eeg_positions https://github.com/sappelhoff/eeg_positions https://mne.tools/dev/auto_tutorials/intro/40_sensor_locations.html

@author: Eduardo Santamaría-Vázquez

class medusa.meeg.meeg.Connecitivity

Bases: object

Customizable class with connectivity info from EEG/MEG recordings

__init__(data, trial_len, parameter, filt_mode, **kwargs)

Class constructor

Parameters

• data (bla bla) – Bla bla

• trial_len (bla bla) – Bla bla

• parameter (bla bla) – Bla bla

• filt_mode (bla bla) – Bla bla

• kwargs – Optional information of the EEG recording (e.g. subject, amplifier, etc)

class medusa.meeg.meeg.EEG

Bases: BiosignalData

Electroencephalography (EEG) biosignal

__init__(times, signal, fs, channel_set, **kwargs)

EEG constructor

Parameters

• times (list or numpy.ndarray) – 1D numpy array [n_samples]. Timestamps of each sample. If they are not available, generate them artificially. Nevertheless, all signals and events must have the same temporal origin

• signal (list or numpy.ndarray) – 2D numpy array [n_samples x n_channels]. EEG samples (the units should be defined using kwargs)

• fs (int or float) – Sample rate of the recording.

• channel_set (meeg_standards.EEGChannelSet) – EEG channel set

• kwargs (kwargs) – Any other parameter provided will be saved in the class (e.g., equipment description)

change_channel_set(channel_set)

Smart change of channel set, updating the signal and all related attributes

Parameters

channel_set (meeg_standards.EEGChannelSet) – EEG channel set

classmethod from_serializable_obj(dict_data)

This function must return an instance of the class from a serializable dict (primitive types)

to_serializable_obj()

This function must return a serializable dict (primitive types) containing the relevant attributes of the class

class medusa.meeg.meeg.EEGChannelSet

Bases: SerializableComponent

Class to represent an EEG montage with ordered channels in specific coordinates. It also provides functionality to load channels from EEG standards 10-20, 10-10 and 10-5 directly from the labels.

__init__(reference_method='common', dim='2D', coord_system='spherical')

Constructor of class EEGChannelSet

Parameters

• reference_method (str {'common'|'average'|'bipolar'}) – Reference method. Recordings with common reference are referenced to the same channel (e.g., ear lobe, mastoid). Recordings with average reference are referenced to the average of all or several channels. Finally, bipolar reference is the subtraction of 2 channels.

• dim (str {'2D'|'3D'}) – Dimensions of the coordinates plane.

• coord_system (str {'cartesian'|'spherical'}) – Coordinates system. Take into account that, if dim = ‘2D’ spherical refers to polar coordinates

add_channel(channel, reference)

Function to add a channel to the end of the current montage. Take into account that the order of the channels is important!

Parameters

• channel (dict) –

  Dict with the channel data. The easiest way to calculate it is using function get_standard_channel_data_from_label. Keys:

  • label: channel label

  • coordinates: depends on the coordinate system and dimensions:

    • Dim = 2D:

      • Cartesian coordinates. Ex: {‘x’: 0.5, ‘y’: 0}

      • Spherical coordinates Ex: {‘r’: 0.5,

        ’theta’: np.pi/2}

    • Dim = 3D:

      • Cartesian coordinates. Ex: {‘x’: 0.5,

        ’y’: 0, ‘z’: 0.8}

      • Spherical coordinates. Ex: {‘r’: 0.5,

        ’theta’: np.pi/2, ‘phi’: np.pi/4}

• reference (dict, list of dicts or str, optional) – For common and bipolar reference modes, reference must be a dict with the label and coordinates of the reference. For average reference, it can be ‘all’ to indicate a common average reference, or a list of dicts (with label and coordinates) of the averaged reference for each channel

See also

get_standard_channel_data_from_label

returns channel data given the channel label and the standard. It can be used to get the reference

check_channels_labels(labels, strict=False)

Checks the order and labels of the channels

Parameters

• labels (list) – Labels to check. The order matters

• strict (bool) – If True, comparison is strict. The function will check that the channel set contains the channels given by parameter labels and in the same order. If false, the function checks that the channels are contained in the channel set, but they could be in different order and the set could contain more channels

Returns

check – True if the labels and order are the same. False otherwise

Return type

bool

compute_dist_matrix()

This function computes the distances between all channels in the channel set and stores them into a matrix.

Returns

dist_matrix – Distances between all the channels.

Return type

ndarray of dimensions [ncha x ncha]

classmethod from_serializable_obj(dict_data)

This function must return an instance of the class from a serializable (list or dict of primitive types)

get_cha_idx_from_labels(labels)

Returns the position of the channels given the labels

Parameters

labels (list) – Labels to check. The order matters

Returns

indexes – Indexes of the channels in the set

Return type

np.ndarray

set_ground(ground)

Sets the ground of the montage

Parameters

ground (dict) –

Dict with the ground data. The easiest way to calculate it is using function get_standard_channel_data_from_label. Keys:

• label: channel label

• coordinates: depends on the coordinate system and dimensions:

  • Dim = 2D:

    • Cartesian coordinates. Ex: {‘x’: 0.5, ‘y’: 0}

    • Spherical coordinates Ex: {‘r’: 0.5,

      ’theta’: np.pi/2}

  • Dim = 3D:

    • Cartesian coordinates. Ex: {‘x’: 0.5,

      ’y’: 0, ‘z’: 0.8}

    • Spherical coordinates. Ex: {‘r’: 0.5,

      ’theta’: np.pi/2, ‘phi’: np.pi/4}

set_montage(channels, ground=None, allow_unlocated_channels=False)

Sets a custom montage, overwriting the previous one. Add single channels more easily using function add_custom_channel and add_standard_channel.

Parameters

• channels (list) – List of dicts, each of them representing a channel. The dict must contain the label, coordinates according to parameters dim an coord_system, and reference. For common reference mode, the reference must be a single channel with label and coordinates. For average reference mode, reference can be a list of dicts with the channels (label and coordinates) or “all”, to specify common average reference. For bipolar reference mode, the reference must be a single channel with label and coordinates. In all cases you can set the reference to None, but this is not recommended. The definition of the coordinates may be skipped depending on the value of allow_unlocated_channels.

• ground (dict) – Dict containing the label and coordinates of the ground electrode

• allow_unlocated_channels (bool) – If False, the coordinates of all channels must be defined within channels dict. If True, the channels may not have known coordinates, This may be convenient if the localization of a channel is not known or it has a non-standard label, but the behaviour in functions that need coordinates (e.g., topographic_plots) is unpredictable.

See also

set_standard_montage

preferred choice in most cases

set_standard_montage(l_cha=None, l_reference=None, l_ground=None, montage='10-05', drop_landmarks=True, allow_unlocated_channels=False, standard=None)

Set standard EEG channels with common reference. In 3 dimensions, the equator is taken a Nz-T10-Iz-T9.

Parameters

• l_cha (list, optional) – List of channels labels. The data will be returned keeping the same order. If None, the channels will be returned in the same order as they appear in the corresponding standard in medusa.meeg

• l_reference (str, optional) – Label of the reference. Usual choices are left preauricular point (LPA) and right preauricular point (RPA). Leave to None if you do not want to specify the reference (not recommended). Use only if reference_method is ‘common’.

• l_ground (str, optional) – Label of the ground. Usual choices are AFz or FPz.

• montage (str {'10-20'|'10-10'|'10-05'} or dict) – EEG standard. If its a string, the corresponding labels and locations of the standard channels will be loaded using the files in medusa.meeg. To load a different montage, use function as meeg.read_montage_file and pass the returned dict here.

• drop_landmarks (bool) – Drop landmarks: nasion (NAS), left preauricular point (LPA) and right preauricular point (RPA) or mastoids (M1, M2). These are usually used as reference or ground points, so they are usually removed from the channel set for data analysis. Only used if l_cha is None.

• allow_unlocated_channels (bool) – If False, all the labels in parameter l_cha must be contained in the montage, which contains the corresponding coordinates. If True, the channels may not be in the standard, and they will be saved with no coordinates. This allows to save labels that are not defined in the montage, but the behaviour in functions that need locations (e.g., topographic_plots) is unpredictable.

• standard (str) – DEPRECATED. Only left for compatibility reasons.

sort_nearest_channels()

Sorts the nearest channels for each possible channel :returns: sorted_dist_ch – Dictionary that includes, for each channel (as a key), the rest

of channels sorted by its closeness to that channel.

Return type

dict()

subset(cha_idx)

Selects the channels given the indexes, creating a subset. The order of the channels will be updated

Parameters

cha_idx (np.ndarray) – Indexes of the channels to select. The order matters

to_serializable_obj()

This function must return a serializable object (list or dict of primitive types) containing the relevant attributes of the class

class medusa.meeg.meeg.MEEGChannel

Bases: SerializableComponent

This class implements a M/EEG channel.

__init__(label, coordinates=None, reference=None)

Constructor for class MEEGChannel.

Parameters

• label (str) – Label of the channel.

• coordinates (dict, optional) – Dict with the coordinates of the electrode. It is strongly recommended to set this optional parameter in order to use advanced features of MEDUSA (e.g., topographic plots).

• reference (MEEGChannel, optional) – Use only for bipolar montages to define the reference electrode.

classmethod from_serializable_obj(data)

This function must return an instance of the class from a serializable (list or dict of primitive types)

classmethod from_standard_set(label, standard='10-5')

to_serializable_obj()

This function must return a serializable object (list or dict of primitive types) containing the relevant attributes of the class

class medusa.meeg.meeg.MEG

Bases: BiosignalData

Magnetoencephalography (MEG) biosignal

__init__(times, signal, fs, channel_set, **kwargs)

MEG constructor

Parameters

• times (list or numpy.ndarray) – 1D numpy array [n_samples]. Timestamps of each sample. If they are not available, generate them artificially. Nevertheless, all signals and events must have the same temporal origin

• signal (list or numpy.ndarray) – 2D numpy array [n_samples x n_channels]. MEG samples (the units should be defined using kwargs)

• fs (int or float) – Sample rate of the recording.

• channel_set (list or meeg_standards.MEGChannelSet) – MEG channel set.

• kwargs (kwargs) – Any other parameter provided will be saved in the class (e.g., equipment description)

change_channel_set(channel_set)

Smart change of channel set, updating the signal and all related attributes

Parameters

channel_set (meeg_standards.MEGChannelSet) – MEG channel set

classmethod from_serializable_obj(dict_data)

This function must return an instance of the class from a serializable dict (primitive types)

static load_meg_signal_from_spm_file(path, fs)

Function to load a MEG recording from a spm file

Parameters

• path (str) – Path of the file

• fs (int or float) – Sample rate of the recording

to_serializable_obj()

This function must return a serializable dict (primitive types) containing the relevant attributes of the class

class medusa.meeg.meeg.MEGChannelSet

Bases: SerializableComponent

__init__()

classmethod from_serializable_obj(dict_data)

This function must return an instance of the class from a serializable (list or dict of primitive types)

to_serializable_obj()

This function must return a serializable object (list or dict of primitive types) containing the relevant attributes of the class

exception medusa.meeg.meeg.UnknownStandardChannel

Bases: Exception

__init__(msg=None)

Class constructor

Parameters

msg (string or None) – Custom message

medusa.meeg.meeg_montages module

exception medusa.meeg.meeg_montages.ChannelNotFound

Bases: Exception

__init__(l_cha)

exception medusa.meeg.meeg_montages.UnlocatedChannel

Bases: Exception

__init__(l_cha)

medusa.meeg.meeg_montages.get_standard_montage(standard, dim, coord_system)

Loads a standard from the ones included in MEDUSA

medusa.meeg.meeg_montages.read_montage_file(path, file_format, dim, coord_system)

This function reads a montage file.

Parameters

• path (str) – Path of the file

• file_format (str) –

  File format. Current accepted file formats:

  • csv (.csv): Comma separated values. Example:

    Format csv (cartesian, 2D):

    label, x, y C3, -0.3249, 0.0000 C4, 0.3249, 0.0000 Cz, 0.0000, 0.0000 …, …, …

  • tsv (.tsv): Tab separated values. Example:

    Format tsv (cartesian, 2D):

    label x y C3 -0.3249 0.0000 C4 0.3249 0.0000 Cz 0.0000 0.0000 … … …

  • eeglab (.xyz): EEGLAB toolbox format. Example:

    Format eeglab (cartesian, 3D):

    1 -3.277285 14.159082 -0.441064 AG001 2 -5.717206 13.304894 0.167594 AG002 3 -7.723112 12.035844 0.923781 AG003 … … …

  • brainstorm (.txt): Brainstorm toolbox format. Example:

    Format brainstorm (cartesian, 3D):

    C3 -4.025389 68.267399 112.962637 C4 -3.409963 -70.131718 111.811990 O1 -86.474171 34.971167 48.738844 … … …

• dim (str) – Dimensions. Must be ‘2D’ or ‘3D’

• coord_system (str) – For 2D, “cartesian” or “polar”. For 3D “cartesian” or “spherical”

medusa.meeg.meeg_montages.switch_coordinates_system(montage, dim, coord_system)

Switch the coordinates system of the montage. If the the coordinates are

cartesian, it switches to spherical and viceversa

Parameters

• montage (dict) – Montage data

• dim (str {'2D', '3D'}) – Current dimensions of the montage

• coord_system (str {'cartesian', 'spherical'}) – Current coordinates system