medusa package

Subpackages

Submodules

medusa.artifact_removal module

medusa.artifact_removal.reject_noisy_epochs(epochs, signal_mean, signal_std, k=4, n_samp=2, n_cha=1)[source]

Simple thresholding method to reject noisy epochs. It discards epochs with n_samp samples greater than k*std in n_cha channels

Parameters

epochs (list or numpy.ndarray) – Epochs of signal with dimensions [n_epochs x samples x channels]

signal_meanfloat

Mean of the signal

signal_stdfloat

Standard deviation of the signal

kfloat

Standard deviation multiplier to calculate threshold

n_sampint

Minimum number of samples that have to be over the threshold in each epoch to be discarded

n_chaint

Minimum number of channels that have to have n_samples over the threshold in each epoch to be discarded

Returns

Percentage of reject epochs in

Return type

float

numpy.ndarray

Clean epochs

numpy.ndarray

Indexes for rejected epochs. True for discarded epoch

medusa.classification_utils module

medusa.classification_utils.categorical_labels(one_hot_labels)[source]
medusa.classification_utils.k_fold_split(x, y, k, keys=None, shuffle=False)[source]

Special implementation of k fold splitting that allows to split the dataset into k folds for cross validation in function of keys array.

It returns a list with the dataset for each iteration (k iterations).

Parameters

  • x (numpy array or list) – Training set data. Axis 0 represents each observation. Features could have one or more dimensions. For instance, [observations x eeg samples], [observations x eeg samples x channels]

  • y (numpy array or list) – Training set labels.

  • k (int) – Number of folds to split the dataset

  • keys (numpy array or list) – Keys to split the dataset. If None, the dataset is splitted considering each observation independently. If not None, each position of keys array identifies the set that owns the observation. For instance, This is useful to split the dataset by subjects or trials.

  • shuffle (boolean) – True if you want to shuffle the dataset randomly.

Returns

sets – List that contains a dict with the train and test set for each iteration of the k-fold algorithm.

Return type

list

Examples

>>> k_fold_iter = k_fold_split(x, y, k)
>>> k_fold_acc = 0
>>> for iter in k_fold_iter:
>>>     model.fit(iter[x_train, y_train])
>>>     y_test_pred = model.predict(iter[x_test, y_test])
>>>     k_fold_acc += np.sum(y_test_pred == y_test)/len(y_test)
>>>     k_fold_acc = k_fold_acc/len(k_fold_iter)
medusa.classification_utils.one_hot_labels(categorical_labels)[source]

medusa.components module

Created on Monday March 15 19:27:14 2021

In this module, you will find the main components of medusa, which provide skeletons for particular implementations. Enjoy!

@author: Eduardo Santamaría-Vázquez

class medusa.components.Algorithm[source]

Bases: ProcessingMethod

Algorithm class is the main tool within medusa to implement standalone processing algorithms that can be shared as a simple file, supporting third-party libraries, such as sklearn. It allows persistence to save the algorithm and its state or use it later using dill package. Take into account that the algorithm needs access to the original classes and methods in order to be reconstructed.

Check this tutorial to better understand the usage of this class.

__init__(**kwargs)[source]

ProcessingMethod constructor

Parameters

kwargs – Key-value arguments that define the exposed methods and output signature. This is used by class Algorithm for a correct implementation of signal processing pipelines.

add_method(method_key, method_instance)[source]
add_pipeline(pipeline_key, pipeline_instance)[source]
exec_pipeline(pipeline_key, **kwargs)[source]

Execute pipeline

classmethod from_pickleable_obj(alg)[source]

Returns the instance of the unpickled version of the pickleable representation given by function to_pickleable_representation. Therefore, this parameter is, by default, an instance of the class and no additional treatment is required. In some cases (i.e., keras models), the pickleable_representation may not be the instance, but some other pickleable format with the required information of the method to reinstantiate the instance itself (i.e., weights for keras models). In such cases, this function must be overriden

Parameters

pickleable_obj (object) – Pickleable representation of the processing method instance.

Returns

instance – Instance of the processing method

Return type

ProcessingMethod

get_inst(method_key)[source]

Returns the instance of a method given the key

to_pickleable_obj()[source]

Returns a pickleable representation of the class. In most cases, the instance of the class is directly pickleable (e.g., all medusa methods, sklearn classifiers), but this may not be the case for some methods (i.e., keras models). Therefore, this function must be overridden in such cases.

Returns

representation – Pickleable representation of the instance.name

Return type

object

class medusa.components.BiosignalData[source]

Bases: SerializableComponent

Skeleton class for biosignals

abstract classmethod from_serializable_obj(dict_data)[source]

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

abstract to_serializable_obj()[source]

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

class medusa.components.ConsistencyChecker[source]

Bases: SerializableComponent

Class that provides functionality to check consistency across recordings to build a dataset

__init__()[source]
add_consistency_rule(rule, rule_params, parent=None)[source]

Adds a consistency check for the specified attribute It provides 2 levels of consistency using parameter key, enough to check attributes inside biosignal or experiments classes

Parameters

  • rule (str {'check-attribute-type'|'check-attribute-value'|) –

    ‘check-values-in-attribute’|’check-if-attribute-exists’| ‘check-if-type-exists’}

    Check mode of this attribute. Modes:
    • check-attribute-type: checks if the attribute has the type

      specified in parameter check_value.

    • check-attribute-value: checks if the attribute has the

      value specified in parameter check_value

    • check-values-in-attribute: checks if the attribute

      contains the values (the attribute must support in operation). It can check keys in dicts or values in lists or sets.

    • check-attribute: checks if the attribute exists

    • check-type: checks if the class contains attributes with

      the specified type. Use operator to define establish rules about the number of attributes allowed with the specified type

  • rule_params (dict) –

    Specifies the rule params. Depending on the rule, it must contain the following key-value pairs:

    • check-attribute-type: {attribute: str, type: class or list}.

      If type is list, it will be checked that the attribute is of one of the types defined in the list

    • check-attribute-value: {attribute: str, value: obj}

    • check-values-in-attribute: {attribute: str, values: list}

    • check-attribute: {attribute: str}

    • check-type: {type: class, limit: int, operator: str {‘<’|’>’|’

      <=’|’>=’|’==’|’!=’}

  • parent (str or None) – Checks the rule inside specified parent. If None, the parent is the recording itself. Therefore, the parent must be a class. This parameter designed to allow check rules inside biosignals or experiments class. If the parent is in deeper levels, use points to define the parent. For example, you can check the labels of the channels in an EEG recording setting this parameter as eeg.channel_set

check_consistency(recording)[source]

Checks the consistency of a recording according to the current rules

Parameters

recording (Recording) – Recording to be checked

classmethod from_serializable_obj(dict_data)[source]

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

to_serializable_obj()[source]

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

class medusa.components.CustomBiosignalData[source]

Bases: BiosignalData

Custom biosignal data class. This class does not check the arguments and provides less functionality that more specific classes. It should only be used for custom signals that do not fit in other data classes

__init__(**kwargs)[source]

CustomBiosginal constructor

Parameters

kwargs (kwargs) – Key-value arguments to be saved in the class. This general class does not check anything

classmethod from_serializable_obj(dict_data)[source]

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

to_serializable_obj()[source]

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

class medusa.components.CustomExperimentData[source]

Bases: ExperimentData

Custom experiment data class. This class does not check the arguments and provides less functionality that a proper experiment class. It should only be used for custom experiments that do not fit in other experiment data classes

__init__(**kwargs)[source]

CustomExperimentData constructor

Parameters

kwargs (kwargs) – Key-value arguments to be saved in the class. This general class does not check anything

classmethod from_serializable_obj(dict_data)[source]

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

to_serializable_obj()[source]

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

class medusa.components.Dataset[source]

Bases: ABC

Class to handle multiple recordings maintaining consistency

__init__(consistency_checker=None)[source]

Class constructor

Parameters

consistency_checker (ConsistencyChecker) – Consistency checker for this dataset.

add_recordings(recordings)[source]

Adds one or more recordings to the dataset, checking the consistency

Parameters

recordings (list or medusa.data_structures.Recording) – List containing the paths to recording files or instances of Recording class

custom_operations_on_recordings(recording)[source]

Function add_recordings calls this function before adding each recording to the dataset. Implement this method in custom classes to have personalized behaviour (e.g., change the channel set)

Parameters

recording (subclass of Recording) – Recording that will be changed. It can also be a subclass of Recording

Returns

recording – Modified recording

Return type

Recording

class medusa.components.ExperimentData[source]

Bases: SerializableComponent

Skeleton class for experiment data

abstract classmethod from_serializable_obj(dict_data)[source]

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

abstract to_serializable_obj()[source]

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

class medusa.components.PickleableComponent[source]

Bases: ABC

Skeleton class for pickleable components. These components must implement functions to transform the class to a pickleable object using dill package. It must be used in classes that need persistence but only make sense in Python and thus, they do not require multiplatform compatibility (i.e., signal processing methods)

abstract classmethod from_pickleable_obj(pickleable_obj)[source]

Returns the instance of the unpickled version of the pickleable representation given by function to_pickleable_representation. Therefore, this parameter is, by default, an instance of the class and no additional treatment is required. In some cases (i.e., keras models), the pickleable_representation may not be the instance, but some other pickleable format with the required information of the method to reinstantiate the instance itself (i.e., weights for keras models). In such cases, this function must be overriden

Parameters

pickleable_obj (object) – Pickleable representation of the processing method instance.

Returns

instance – Instance of the component

Return type

PickleableComponent

classmethod load(path)[source]
save(path, protocol=0)[source]

Saves the class using dill into pickle format

abstract to_pickleable_obj()[source]

Returns a pickleable representation of the class. In most cases, the instance of the class is directly pickleable (e.g., all medusa methods, sklearn classifiers), but this may not be the case for some methods (i.e., keras models). Therefore, this function must be overridden in such cases.

Returns

representation – Pickleable representation of the instance.name

Return type

object

class medusa.components.Pipeline[source]

Bases: object

Pipeline that defines the tasks and connections between methods of a signal processing task. This class does not check if the connections are valid. This is done by Algorithm class, which compiles the connections with the available methods

Check this tutorial to better understand the usage of this class.

__init__()[source]

Pipeline constructor

add(method_func_key, **kwargs)[source]

Adds a method to the pipeline

Parameters

  • method_func_key (str) – Method identifier and function to be executed, separated by semicolon. Example: fir_filter:fit

  • kwargs – Key-value arguments defining the input arguments of the methods. The key specifies the input argument. The value can be a static value (i.e., int, float, object instance) or a connection to the output of another stage of the pipeline. In this case, use method conn_to

conn_to(uid, out_key, conn_exp=None)[source]

Returns a PipelineConnector object that defines a connection between the input of a method and the ouput of a previous stage of the pipeline.

Parameters

  • uid (int) – Stage unique id returned by input or add methods.

  • out_key (str) – Key of the output of the method given by uid that will be connected to the input argument.

  • conn_exp (callable) – Expresion that transforms the connected variable in some way. Fore instance, select a certain key from a dictionary, reshape an array, etc.

input(args)[source]

Defines the input arguments of the pipeline

Parameters

args (list of str) – List of input arguments to the pipeline

class medusa.components.PipelineConnector[source]

Bases: object

Auxiliary class to define connections between stages of a pipeline

Check this tutorial to better understand the usage of this class.

__init__(method_uid, output_key, conn_exp=None)[source]

PipelineConnector constructor

Parameters

  • method_uid (int) – Unique method identifier of method whose output will be connected.

  • output_key (str) – Key of the output of method_id that will be passed. Useful when a method returns several variables, but only 1 is useful as input to other stage. If None, the output will be passed straightaway.

  • conn_exp (callable) – Expresion that transforms the connected variable in some way. Fore instance, select a certain key from a dictionary, reshape an array, etc.

static from_dict(dict_data)[source]
to_dict()[source]
class medusa.components.ProcessingClassWrapper[source]

Bases: ProcessingMethod

ProcessingMethod wrapper for external classes (e.g., sklearn classifier). Use it to add an instance of the desired class to an algorithm. When designing your pipeline, take into account that the input signature (arguments) of the methods will be inherited from the original class.

DISCLAIMER: This wrapper may not work with all classes, since it uses some hacking to bind the methods and attributes of the original instance to this wrapper, changing the original type. Additionally, it is assumed that the instance is pickleable. If this is not the case, or something doesn’t work, you’ll have to design your own wrapper subclassing ProcessingMethod, which is also very easy and quick.

Check this tutorial to better understand the usage of this class.

__init__(instance, **kwargs)[source]

ProcessingClassWrapper constructor

Parameters

  • instance (object) – Instance of the class that will be implemented

  • kwargs – Key-value arguments that define the exposed methods and output signature. This is used by class Algorithm for a correct implementation of signal processing pipelines.

to_pickleable_obj()[source]

Returns a pickleable representation of the class. In most cases, the instance of the class is directly pickleable (e.g., all medusa methods, sklearn classifiers), but this may not be the case for some methods (i.e., keras models). Therefore, this function must be overridden in such cases.

Returns

representation – Pickleable representation of the instance.name

Return type

object

class medusa.components.ProcessingFuncWrapper[source]

Bases: ProcessingMethod

ProcessingMethod wrapper for processing functions. Use to add a processing function to an algorithm

Check this tutorial to better understand the usage of this class.

__init__(func, outputs, **kwargs)[source]

ProcessingFuncWrapper constructor

Parameters

  • func (callable) – Function that will be implemented

  • outputs (list) – Output signature of the method (output variables). This is used by class Algorithm for a correct implementation of signal processing pipelines.

class medusa.components.ProcessingMethod[source]

Bases: PickleableComponent

Skeleton class for processing methods. This class implements some useful features that allow the implementations of Algorithms, a key component of medusa.

Check this tutorial to better understand the usage of this class.

__init__(**kwargs)[source]

ProcessingMethod constructor

Parameters

kwargs – Key-value arguments that define the exposed methods and output signature. This is used by class Algorithm for a correct implementation of signal processing pipelines.

classmethod from_pickleable_obj(pickleable_obj)[source]

Returns the instance of the unpickled version of the pickleable representation given by function to_pickleable_representation. Therefore, this parameter is, by default, an instance of the class and no additional treatment is required. In some cases (i.e., keras models), the pickleable_representation may not be the instance, but some other pickleable format with the required information of the method to reinstantiate the instance itself (i.e., weights for keras models). In such cases, this function must be overriden

Parameters

pickleable_obj (object) – Pickleable representation of the processing method instance.

Returns

instance – Instance of the processing method

Return type

ProcessingMethod

get_exposed_methods()[source]
to_pickleable_obj()[source]

Returns a pickleable representation of the class. In most cases, the instance of the class is directly pickleable (e.g., all medusa methods, sklearn classifiers), but this may not be the case for some methods (i.e., keras models). Therefore, this function must be overridden in such cases.

Returns

representation – Pickleable representation of the instance.name

Return type

object

class medusa.components.Recording[source]

Bases: SerializableComponent

Class intended to save the data from one recording. It implements all necessary methods to save and load from several formats. It accepts different kinds of data: experiment data, which saves all the information about the experiment (e.g., events); biosignal data (e.g., EEG, MEG, NIRS), bioimaging data (e.g., fMRI, MRI); and custom data (e.g., photos, videos, audio). Temporal data must be must be synchronized with the reference. To assure multiplatform interoperability, this class must be serializable using python primitive types.

__init__(subject_id, recording_id=None, description=None, source=None, date=None, **kwargs)[source]

Recording dataset constructor. Custom useful parameters can be provided to save in the class.

Parameters

  • subject_id (int or str) – Subject identifier

  • recording_id (str or None) – Identifier of the recording for automated processing or easy identification

  • description (str or None) – Description of this recording. Useful to write comments (e.g., the subject moved a lot, the experiment was interrupted, etc)

  • source (str or None) – Source of the data, such as software, equipment, experiment, etc

  • kwargs (custom key-value parameters) – Other useful parameters (e.g., software version, research team, laboratory, etc)

add_bioimaging(bioimaging, key=None)[source]
add_biosignal(biosignal, key=None)[source]

Adds a biosignal recording. Each biosignal has predefined classes that must be instantiated before (e.g., EEG, MEG)

Parameters

  • biosignal (biosignal class) – Instance of the biosignal class. This class must be serializable. Current available: EEG, MEG.

  • key (str) – Custom name for this biosignal. If not provided, the biosignal will be saved in an attribute according to its type in lowercase (e.g., eeg, meg, etc). This parameter is useful if several biosignals of the same type are added to this recording

add_custom_data(data, key=None)[source]
add_experiment_data(experiment_data, key=None)[source]

Adds the experiment data of this recording. Each experiment should have a predefined class that must be instantiated before. Several classes are defined within medusa core, but it also can be a custom experiment.

Parameters

  • experiment_data (experiment class) – Instance of an experiment class. This class can be custom if it is serializable, but it is recommended to use the classes provided by medusa core in different modules (e.g., bci.erp_paradigms.rcp)

  • key (str) – Custom name for this experiment. If not provided, the experiment will be saved in an attribute according to its type (e.g., rcp, cake paradigm, etc). This parameter is useful if several experiments of the same type are added to this recording

cast_biosignal(key, biosignal_class)[source]

This function casts a biosignal to the class passed in biosignal_class

cast_experiment(key, experiment_class)[source]

This function casts an experiment of recording run to the class passed in experiment_class

classmethod from_serializable_obj(rec_dict)[source]

Function that loads the class from a python dictionary

get_biosignals_with_class_name(biosignal_class_name)[source]

This function returns the biosignals with a specific class name

Parameters

biosignal_class_name (str) – Class name of the biosignal (e.g., “EEG”)

get_experiments_with_class_name(exp_class_name)[source]

This function returns the experiments with a specific class name

Parameters

exp_class_name (str) – Class name of the experiment (e.g., “ERPSpellerData”)

rename_attribute(old_key, new_key)[source]

Rename an attribute. Useful to unify attribute names on fly while creating a dataset.

Parameters

  • old_key (str) – Old attribute key

  • new_key (str) – New attribute key

to_serializable_obj()[source]

This function returns a serializable dict (primitive types) containing the attributes of the class

class medusa.components.SerializableComponent[source]

Bases: ABC

Skeleton class for serializable components. These components must implement functions to transform the class to multiplatform formats, such as json, bson and mat. It must be used in classes that need persistence across multple platforms (i.e., recordings)

abstract classmethod from_serializable_obj(data)[source]

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

classmethod load(path, data_format=None)[source]

Loads the file with the correct data structures

Parameters

  • path (str) – File path

  • data_format (None or str) – File format. If None, the format will be given by the file extension

Returns

Recording class with the correct data structures

Return type

Recording

classmethod load_from_bson(path)[source]
classmethod load_from_json(path, encoding='utf-8')[source]
classmethod load_from_mat(path, squeeze_me=True, simplify_cells=True, restore_none_objects=True)[source]

Load a mat file using scipy and restore its original class

Parameters

  • path (str) – Path to file

  • restore_none_objects (bool) – If True, it ensures that all ‘null’ strings are restored as None objects in case that these objects were removed upon saving. Nonetheless, it is computationally expensive, so it is better to leave to False and ensure manually.

classmethod load_from_pickle(path)[source]
save(path, data_format=None)[source]

Saves the component to the specified format.

Compatible formats:

  • bson: This format is safe, efficient, easy to use and multiplatform.

    Thus, it comes with advantages in comparison to other formats. BSON format requires serializable classes to python primary types.

  • json: This format is safe, human readable and multiplatform, widely

    used for web applications. Nevertheless, files are encoded in utf-8 and thus occupy more space. JSON format requires serializable classes to python primary types.

  • mat: This is a binary format widely used in research for its

    compatibility with Matlab. Very powerful and safe, but lacks of wide multiplatform compatibility. MAT format requires serializable classes, but allows numpy types.

  • pickle: This format is easy to use but lacks of multiplatform

    interoperability and it’s not very efficient.

Parameters

  • path (str) – File path. If data_format is None, The data format will be automatically decoded from the path extension.

  • data_format (str) – Format to save the recording. Current supported formats:

save_to_bson(path)[source]

Saves the class attributes in BSON format

save_to_json(path, encoding='utf-8', indent=4)[source]

Saves the class attributes in JSON format

save_to_mat(path, avoid_none_objects=True)[source]

Save the class in a MATLAB .mat file using scipy

Parameters

  • path (str) – Path to file

  • avoid_none_objects (bool) – If True, it ensures that all None objects are removed from the object to save to avoid scipy.io.savemat error with this type. Nonetheless, it is computationally expensive, so it is better to leave to False and ensure manually.

save_to_pickle(path, protocol=0)[source]

Saves the class using dill into pickle format

abstract to_serializable_obj()[source]

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

class medusa.components.SettingsTreeItem[source]

Bases: SerializableComponent

General class to represent settings.

__init__(key, info, value_type=None, value=None)[source]

Class constructor.

Parameters

  • key (str) – Tree item key

  • info (str) – Information about this item

  • value_type (str ['string'|'number'|'boolean'|'dict'|'list'], optional) – Type of the data stored in attribute value. Leave to None if the item is going to be a tree.

  • value (str, int, float, bool, dict or list, optional) – Tree item value. It must be one of the JSON types to be compatible with serialization. Leave to None if the item is going to be a tree.

add_item(item)[source]

Adds tree item to the tree. Use this function to build a custom tree. Take into account that if this function is used, attributes value and type will be set to None and ‘tree’, respectively.

Parameters

item (SettingsTreeItem) – Tree item to add

count_items()[source]
classmethod from_serializable_obj(data)[source]

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

is_tree()[source]
set_data(value_type, value)[source]

Adds tree item to the tree. Use this function to build a custom tree.

Parameters

  • value_type (str or list ['string'|'number'|'boolean'|'dict'|'list']) – Type of the data stored in attribute value. If a list is provided, several data types are accepted for attribute value.

  • value (str, int, float, bool, dict or list) – Tree item value. It must be one of the JSON types to be compatible with serialization. If list or dict, the items must be of type SettingsTreeItem.

to_serializable_obj()[source]

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

class medusa.components.ThreadWithReturnValue[source]

Bases: Thread

This class inherits from thread class and allows getting the target function return

__init__(group=None, target=None, name=None, args=(), kwargs={})[source]

This constructor should always be called with keyword arguments. Arguments are:

group should be None; reserved for future extension when a ThreadGroup class is implemented.

target is the callable object to be invoked by the run() method. Defaults to None, meaning nothing is called.

name is the thread name. By default, a unique name is constructed of the form “Thread-N” where N is a small decimal number.

args is the argument tuple for the target invocation. Defaults to ().

kwargs is a dictionary of keyword arguments for the target invocation. Defaults to {}.

If a subclass overrides the constructor, it must make sure to invoke the base class constructor (Thread.__init__()) before doing anything else to the thread.

join(*args)[source]

Wait until the thread terminates.

This blocks the calling thread until the thread whose join() method is called terminates – either normally or through an unhandled exception or until the optional timeout occurs.

When the timeout argument is present and not None, it should be a floating point number specifying a timeout for the operation in seconds (or fractions thereof). As join() always returns None, you must call is_alive() after join() to decide whether a timeout happened – if the thread is still alive, the join() call timed out.

When the timeout argument is not present or None, the operation will block until the thread terminates.

A thread can be join()ed many times.

join() raises a RuntimeError if an attempt is made to join the current thread as that would cause a deadlock. It is also an error to join() a thread before it has been started and attempts to do so raises the same exception.

run()[source]

Method representing the thread’s activity.

You may override this method in a subclass. The standard run() method invokes the callable object passed to the object’s constructor as the target argument, if any, with sequential and keyword arguments taken from the args and kwargs arguments, respectively.

medusa.deep_learning_models module

class medusa.deep_learning_models.EEGInceptionv1[source]

Bases: ProcessingMethod

EEG-Inception as described in Santamaría-Vázquez et al. 2020 [1]. This model is specifically designed for EEG classification tasks.

References

[1] Santamaría-Vázquez, E., Martínez-Cagigal, V., Vaquerizo-Villar, F., & Hornero, R. (2020). EEG-Inception: A Novel Deep Convolutional Neural Network for Assistive ERP-based Brain-Computer Interfaces. IEEE Transactions on Neural Systems and Rehabilitation Engineering.

__init__(input_time=1000, fs=128, n_cha=8, filters_per_branch=8, scales_time=(500, 250, 125), dropout_rate=0.25, activation='elu', n_classes=2, learning_rate=0.001, gpu_acceleration=None)[source]

ProcessingMethod constructor

Parameters

kwargs – Key-value arguments that define the exposed methods and output signature. This is used by class Algorithm for a correct implementation of signal processing pipelines.

fit(X, y, fine_tuning=False, shuffle_before_fit=False, **kwargs)[source]

Fit the model. All additional keras parameters of class tensorflow.keras.Model will pass through. See keras documentation to know what can you do: https://keras.io/api/models/model_training_apis/.

If no parameters are specified, some default options are set [1]:

  • Epochs: 100 if fine_tuning else 500

  • Batch size: 32 if fine_tuning else 1024

  • Callbacks: self.fine_tuning_callbacks if fine_tuning else

    self.training_callbacks

Parameters

  • X (np.ndarray) – Feature matrix. If shape is [n_observ x n_samples x n_channels], this matrix will be adapted to the input dimensions of EEG-Inception [n_observ x n_samples x n_channels x 1]

  • y (np.ndarray) – Feature matrix. If shape is [n_observ x n_samples x n_channels], this matrix will be adapted to the input dimensions of EEG-Inception [n_observ x n_samples x n_channels x 1]

  • fine_tuning (bool) – Set to True to use the default training parameters for fine tuning. False by default.

  • shuffle_before_fit (bool) – If True, the data will be shuffled before training just once. Note that if you use the keras native argument ‘shuffle’, the data is shuffled each epoch.

  • kwargs – Key-value arguments will be passed to the fit function of the model. This way, you can set your own training parameters using keras API. See https://www.tensorflow.org/api_docs/python/tf/keras/Model#fit

classmethod from_pickleable_obj(pickleable_obj)[source]

Returns the instance of the unpickled version of the pickleable representation given by function to_pickleable_representation. Therefore, this parameter is, by default, an instance of the class and no additional treatment is required. In some cases (i.e., keras models), the pickleable_representation may not be the instance, but some other pickleable format with the required information of the method to reinstantiate the instance itself (i.e., weights for keras models). In such cases, this function must be overriden

Parameters

pickleable_obj (object) – Pickleable representation of the processing method instance.

Returns

instance – Instance of the processing method

Return type

ProcessingMethod

get_weights()[source]
load_weights(weights_path)[source]
predict_proba(X)[source]

Model prediction scores for the given features.

Parameters

X (np.ndarray) – Feature matrix. If shape is [n_observ x n_samples x n_channels], this matrix will be adapted to the input dimensions of EEG-Inception [n_observ x n_samples x n_channels x 1]

save_weights(path)[source]
set_weights(weights)[source]
to_pickleable_obj()[source]

Returns a pickleable representation of the class. In most cases, the instance of the class is directly pickleable (e.g., all medusa methods, sklearn classifiers), but this may not be the case for some methods (i.e., keras models). Therefore, this function must be overridden in such cases.

Returns

representation – Pickleable representation of the instance.name

Return type

object

static transform_data(X, y=None)[source]

Transforms input data to the correct dimensions for EEG-Inception

Parameters

  • X (np.ndarray) – Feature matrix. If shape is [n_observ x n_samples x n_channels], this matrix will be adapted to the input dimensions of EEG-Inception [n_observ x n_samples x n_channels x 1]

  • y (np.ndarray) – Labels array. If labels are in categorical format, they will be converted to one-hot encoding.

class medusa.deep_learning_models.EEGNet[source]

Bases: ProcessingMethod

EEG-Inception as described in Lawhern et al. 2018 [1]. This model is specifically designed for EEG classification tasks.

Original source https://github.com/vlawhern/arl-eegmodels

References

[1] Lawhern, V. J., Solon, A. J., Waytowich, N. R., Gordon, S. M., Hung, C. P., & Lance, B. J. (2018). EEGNet: a compact convolutional neural network for EEG-based brain–computer interfaces. Journal of neural engineering, 15(5), 056013.

__init__(nb_classes, n_cha=64, samples=128, dropout_rate=0.5, kern_length=64, F1=8, D=2, F2=16, norm_rate=0.25, dropout_type='Dropout', learning_rate=0.001, gpu_acceleration=None)[source]

ProcessingMethod constructor

Parameters

kwargs – Key-value arguments that define the exposed methods and output signature. This is used by class Algorithm for a correct implementation of signal processing pipelines.

fit(X, y, fine_tuning=False, shuffle_before_fit=False, **kwargs)[source]

Fit the model. All additional keras parameters of class tensorflow.keras.Model will pass through. See keras documentation to know what can you do: https://keras.io/api/models/model_training_apis/.

If no parameters are specified, some default options are set [1]:

  • Epochs: 100 if fine_tuning else 500

  • Batch size: 32 if fine_tuning else 1024

  • Callbacks: self.fine_tuning_callbacks if fine_tuning else

    self.training_callbacks

Parameters

  • X (np.ndarray) – Feature matrix. If shape is [n_observ x n_samples x n_channels], this matrix will be adapted to the input dimensions of EEG-Inception [n_observ x n_samples x n_channels x 1]

  • y (np.ndarray) – Feature matrix. If shape is [n_observ x n_samples x n_channels], this matrix will be adapted to the input dimensions of EEG-Inception [n_observ x n_samples x n_channels x 1]

  • fine_tuning (bool) – Set to True to use the default training parameters for fine tuning. False by default.

  • shuffle_before_fit (bool) – If True, the data will be shuffled before training.

  • kwargs – Key-value arguments will be passed to the fit function of the model. This way, you can set your own training parameters for keras. See https://www.tensorflow.org/api_docs/python/tf/keras/Model#fit

classmethod from_pickleable_obj(pickleable_obj)[source]

Returns the instance of the unpickled version of the pickleable representation given by function to_pickleable_representation. Therefore, this parameter is, by default, an instance of the class and no additional treatment is required. In some cases (i.e., keras models), the pickleable_representation may not be the instance, but some other pickleable format with the required information of the method to reinstantiate the instance itself (i.e., weights for keras models). In such cases, this function must be overriden

Parameters

pickleable_obj (object) – Pickleable representation of the processing method instance.

Returns

instance – Instance of the processing method

Return type

ProcessingMethod

get_weights()[source]
load_weights(weights_path)[source]
predict_proba(X)[source]

Model prediction scores for the given features.

Parameters

X (np.ndarray) – Feature matrix. If shape is [n_observ x n_samples x n_channels], this matrix will be adapted to the input dimensions of EEG-Inception [n_observ x n_samples x n_channels x 1]

save_weights(path)[source]
set_weights(weights)[source]
to_pickleable_obj()[source]

Returns a pickleable representation of the class. In most cases, the instance of the class is directly pickleable (e.g., all medusa methods, sklearn classifiers), but this may not be the case for some methods (i.e., keras models). Therefore, this function must be overridden in such cases.

Returns

representation – Pickleable representation of the instance.name

Return type

object

static transform_data(X, y=None)[source]

Transforms input data to the correct dimensions for EEG-Inception

Parameters

  • X (np.ndarray) – Feature matrix. If shape is [n_observ x n_samples x n_channels], this matrix will be adapted to the input dimensions of EEG-Inception [n_observ x n_samples x n_channels x 1]

  • y (np.ndarray) – Labels array. If labels are in categorical format, they will be converted to one-hot encoding.

class medusa.deep_learning_models.EEGSym[source]

Bases: ProcessingMethod

EEGSym as described in Pérez-Velasco et al. 2022 [1]. This model is specifically designed for EEG classification tasks.

References

[1] Pérez-Velasco, S., Santamaría-Vázquez, E., Martínez-Cagigal, V., Marcos-Martínez, D., & Hornero, R. (2022). EEGSym: Overcoming Intersubject Variability in Motor Imagery Based BCIs with Deep Learning. IEEE Transactions on Neural Systems and Rehabilitation Engineering.

__init__(input_time=3000, fs=128, n_cha=8, filters_per_branch=24, scales_time=(500, 250, 125), dropout_rate=0.4, activation='elu', n_classes=2, learning_rate=0.001, ch_lateral=3, spatial_resnet_repetitions=1, residual=True, symmetric=True, gpu_acceleration=None)[source]

ProcessingMethod constructor

Parameters

kwargs – Key-value arguments that define the exposed methods and output signature. This is used by class Algorithm for a correct implementation of signal processing pipelines.

fit(X, y, fine_tuning=False, shuffle_before_fit=False, augmentation=True, **kwargs)[source]

Fit the model. All additional keras parameters of class tensorflow.keras.Model will pass through. See keras documentation to know what can you do: https://keras.io/api/models/model_training_apis/.

If no parameters are specified, some default options are set [1]:

  • Epochs: 100 if fine_tuning else 500

  • Batch size: 32 if fine_tuning else 2048

  • Callbacks: self.fine_tuning_callbacks if fine_tuning else

    self.training_callbacks

Parameters

  • X (np.ndarray) – Feature matrix. If shape is [n_observ x n_samples x n_channels], this matrix will be adapted to the input dimensions of EEG-Inception [n_observ x n_samples x n_channels x 1]

  • y (np.ndarray) – Feature matrix. If shape is [n_observ x n_samples x n_channels], this matrix will be adapted to the input dimensions of EEG-Inception [n_observ x n_samples x n_channels x 1]

  • fine_tuning (bool) – Set to True to use the default training parameters for fine tuning. False by default.

  • shuffle_before_fit (bool) – If True, the data will be shuffled before training just once. Note that if you use the keras native argument ‘shuffle’, the data is shuffled each epoch.

  • kwargs – Key-value arguments will be passed to the fit function of the model. This way, you can set your own training parameters using keras API. See https://www.tensorflow.org/api_docs/python/tf/keras/Model#fit

classmethod from_pickleable_obj(pickleable_obj)[source]

Returns the instance of the unpickled version of the pickleable representation given by function to_pickleable_representation. Therefore, this parameter is, by default, an instance of the class and no additional treatment is required. In some cases (i.e., keras models), the pickleable_representation may not be the instance, but some other pickleable format with the required information of the method to reinstantiate the instance itself (i.e., weights for keras models). In such cases, this function must be overriden

Parameters

pickleable_obj (object) – Pickleable representation of the processing method instance.

Returns

instance – Instance of the processing method

Return type

ProcessingMethod

static general_module(input, scales_samples, filters_per_branch, ncha, activation, dropout_rate, average, spatial_resnet_repetitions=1, residual=True, init=False)[source]

General inception/residual module.

This function returns the input with the operations of a inception or residual module from the publication applied.

Parameters

  • input (list) – List of input blocks to the module.

  • scales_samples (list) – List of samples size of the temporal operations kernels.

  • filters_per_branch (int) – Number of filters in each Inception branch. The number should be multiplies of 8.

  • ncha – Number of input channels.

  • activation (str) – Activation

  • dropout_rate (float) – Dropout rate

  • spatial_resnet_repetitions (int) – Number of repetitions of the operations of spatial analysis at each step of the spatiotemporal analysis. In the original publication this value was set to 1 and not tested its variations.

  • residual (Bool) – If the residual operations are present in EEGSym architecture.

  • init (Bool) – If the module is the first one applied to the input, to apply a channel merging operation if the architecture does not include residual operations.

Returns

block_out – List of outputs modules

Return type

list

get_weights()[source]
load_weights(weights_path)[source]
predict_proba(X)[source]

Model prediction scores for the given features.

Parameters

X (np.ndarray) – Feature matrix. If shape is [n_observ x n_samples x n_channels], this matrix will be adapted to the input dimensions of EEG-Sym [n_observ x n_samples x n_channels x 1]

preprocessing_function(augmentation=True)[source]

Custom Data Augmentation for EEGSym.

Parameters

augmentation (Bool) – If the augmentation is performed to the input.

Returns

data_augmentation – Data augmentation performed to each trial

Return type

function

save_weights(path)[source]
set_weights(weights)[source]
symmetric_channels(X, channels)[source]

This function takes a set of channels and puts them in a symmetric input needed to apply EEGSym.

to_pickleable_obj()[source]

Returns a pickleable representation of the class. In most cases, the instance of the class is directly pickleable (e.g., all medusa methods, sklearn classifiers), but this may not be the case for some methods (i.e., keras models). Therefore, this function must be overridden in such cases.

Returns

representation – Pickleable representation of the instance.name

Return type

object

static transform_data(X, y=None)[source]

Transforms input data to the correct dimensions for EEGSym

Parameters

  • X (np.ndarray) – Feature matrix. If shape is [n_observ x n_samples x n_channels], this matrix will be adapted to the input dimensions of EEG-Inception [n_observ x n_samples x n_channels x 1]

  • y (np.ndarray) – Labels array. If labels are in categorical format, they will be converted to one-hot encoding.

trial_iterator(X, y, batch_size=32, shuffle=True, augmentation=True)[source]

Custom trial iterator to pretrain EEGSym.

Parameters

  • X (tf.tensor) – Input tensor of EEG features.

  • y (tf.tensor) – Input tensor of labels.

  • batch_size (int) – Number of features in each batch.

  • shuffle (Bool) – If the features are shuffled at each training epoch.

  • augmentation (Bool) – If the augmentation is performed to the input.

Returns

trial_iterator – Iterator used to train the model.

Return type

tf.keras.preprocessing.image.NumpyArrayIterator

medusa.emg module

class medusa.emg.EMG[source]

Bases: BiosignalData

Electromiography (EMG) biosignal data class.

__init__(times, signal, fs, channel_set, location=None, **kwargs)[source]

EMG 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]. EMG samples (the units should be defined using kwargs)

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

  • channel_set (list or Object) – Channel information

  • location (string) – Location of the recording (e.g., quadriceps)

  • kwargs (kwargs) – Key-value arguments to be saved in the class. This general class does not check anything

classmethod from_serializable_obj(dict_data)[source]

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

to_serializable_obj()[source]

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

medusa.epoching module

medusa.epoching.check_epochs_feasibility(timestamps, onsets, fs, t_window)[source]

Checks if the extraction of the desired window is feasible with the available samples. Sometimes, the first/last stimulus sample is so close to the beginning/end of the signal data chunk that there are not enough samples to compute this window. In this case, the function will return “first” or “last” to identify which onset can not be extracted with the current t_window. It will return ‘ok’ if there is no conflict.

Parameters

timestamps (list or numpy.ndarray) – Timestamps of each biosginal sample

onsetslist or numpy.ndarray

Events timestamps

fsfloat

Sample rate

t_windowlist or numpy.ndarray

Temporal window in ms of the epoch. For example, t_window = [0, 1000] takes the epoch form 0 ms to 1000 ms after each onset (0 ms represents the onset).

Returns

feasibility – “ok” If window extraction is feasible. “first” If window extraction is not feasible for the first onset. “last” If window extraction is not feasible for the last onset.

Return type

string

medusa.epoching.get_epochs(signal, epochs_length, stride=None, norm=None)[source]
This function returns the signal divided in epochs following a sliding

window approach

Parameters

  • signal (list or numpy.ndarray) – Array to extract epochs with shape [samples, channels]

  • epochs_length (int) – Epochs length in samples

  • stride (int, optional) – Separation between consecutive epochs in samples. If None, stride is set to epochs_length.

  • norm (str, optional) – Set to ‘z’ for Z-score normalization or ‘dc’ for DC normalization. Statistical parameters are computed using the whole epoch.

Returns

Structured data with dimensions [n_epochs x length x n_channels]

Return type

numpy.ndarray

medusa.epoching.get_epochs_of_events(timestamps, signal, onsets, fs, w_epoch_t, w_baseline_t=None, norm=None)[source]

This function calculates the epochs of signal given the onsets of events.

Parameters

  • timestamps (list or numpy.ndarray) – Timestamps of each biosignal sample

  • signal (list or numpy.ndarray) – Biosignal samples

  • onsets (list or numpy.ndarray) – Events timestamps

  • fs (float) – Sample rate

  • w_epoch_t (list or numpy.ndarray) – Temporal window in ms of the epoch. For example, t_baseline = [0, 1000] takes the epoch form 0 ms to 1000 ms after each onset (0 ms represents the onset).

  • w_baseline_t (list or numpy.ndarray, optional) – Temporal window in ms of the baseline. For example, t_baseline = [-500, 100] takes the baseline form -500 ms before each onset to 100 ms after each onset (0 ms represents the onset). This chunk of signal is used to normalize the epoch, if aplicable

  • norm (str, optional) – Set to ‘z’ for Z-score normalization or ‘dc’ for DC normalization. Statistical parameters are computed using the whole epoch.

Returns

Structured data with dimensions [events x samples x channels]

Return type

numpy.ndarray

medusa.epoching.normalize_epochs(epochs, norm_epochs=None, norm='z')[source]

Normalizes epochs

Parameters

  • epochs (list or numpy.ndarray) – Epochs of signal with dimensions [n_epochs x n_samples x n_channels]

  • norm_epochs (list or numpy.ndarray, optional) – Epochs of signal with dimensions [n_epochs x n_samples x n_channels] that are used to compute the statistical parameters for normalization. If None, norm_epochs=epochs.

  • norm (str) – Set to ‘z’ for Z-score normalization or ‘dc’ for DC normalization. Statistical parameters are computed using the whole epoch.

medusa.epoching.reject_noisy_epochs(epochs, signal_mean, signal_std, k=4, n_samp=2, n_cha=1)[source]

Simple thresholding method to reject noisy epochs. It discards epochs with n_samp samples greater than k*std in n_cha channels

Parameters

epochs (list or numpy.ndarray) – Epochs of signal with dimensions [n_epochs x samples x channels]

signal_meanfloat

Mean of the signal

signal_stdfloat

Standard deviation of the signal

kfloat

Standard deviation multiplier to calculate threshold

n_sampint

Minimum number of samples that have to be over the threshold in each epoch to be discarded

n_chaint

Minimum number of channels that have to have n_samples over the threshold in each epoch to be discarded

Returns

Percentage of reject epochs in

Return type

float

numpy.ndarray

Clean epochs

numpy.ndarray

Indexes for rejected epochs. True for discarded epoch

medusa.epoching.resample_epochs(epochs, t_window, target_fs)[source]

Resample epochs to the target_fs.

IMPORTANT: No antialising filter is applied

Parameters

  • epochs (list or numpy.ndarray) – Epochs of signal with dimensions [n_epochs x samples x channels]

  • t_window (list or numpy.ndarray) – Temporal window in ms of the epoch. For example, t_window = [0, 1000] takes the epoch form 0 ms to 1000 ms after each onset (0 ms represents the onset).

  • target_fs (float) – Target sample rate

Returns

Final epochs with dimensions [events x target_samples x channels]

Return type

numpy.ndarray

medusa.epoching.time_to_sample_index_events(times, onsets)[source]

Converts an array of time onsets to an array that indicates the sample index of the event

timeslist or numpy.ndarray

Array of shape [n_samples]. Timestamps of the biosignal

onsetslist or numpy.ndarray

Array of shape [n_events]. Onsets in time of the events

numpy.ndarray

Array of shape [n_samples]. The array is 1 only in the nearest timestamp to each onset, otherwise 0

medusa.frequency_filtering module

class medusa.frequency_filtering.FIRFilter[source]

Bases: ProcessingMethod

__init__(order, cutoff, btype, width=None, window='hamming', scale=True, filt_method='filtfilt', axis=0)[source]

FIR filter designed using the implementation of scipy.signal.firwin. See the documentation of this function to find useful information about this class

Parameters

  • order (int) – Length of the filter (number of coefficients, i.e. the filter order + 1). numtaps must be odd if a passband includes the Nyquist frequency.

  • cutoff (float or 1-D array_like) – Cutoff frequency of filter (expressed in the same units as fs) OR an array of cutoff frequencies (that is, band edges). In the latter case, the frequencies in cutoff should be positive and monotonically increasing between 0 and fs/2. The values 0 and fs/2 must not be included in cutoff.

  • btype (str {‘bandpass’|‘lowpass’|‘highpass’|‘bandstop’}) – Band type of the filter. It also controls the parameter pass_zero of them scipy.signal.firwin function

  • width (float or None, optional) – If width is not None, then assume it is the approximate width of the transition region (expressed in the same units as fs) for use in Kaiser FIR filter design. In this case, the window argument is ignored.

  • window (string or tuple of string and parameter values, optional) – Desired window to use. See scipy.signal.get_window for a list of windows and required parameters.

  • scale (bool, optional) –

    Set to True to scale the coefficients so that the frequency response is exactly unity at a certain frequency. That frequency is either:

    • 0 (DC) if the first passband starts at 0 (i.e. pass_zero is

      True)

    • fs/2 (the Nyquist frequency) if the first passband ends at

      fs/2 (i.e the filter is a single band highpass filter); center of first passband otherwise

  • filt_method (str {'lfilter', 'filtfilt'}) – Filtering method. See scipy.signal.lfilter or scipy.signal.filtfilt for more information.

  • axis (int) – The axis to which the filter is applied. By convention, signals in medusa are defined by [samples x channels], so axis is set to 0 by default.

display()[source]
fit(fs)[source]
fit_transform(signal, fs)[source]

Fits and applies the filter

Parameters

  • signal (np.ndarray) – Signal to filter. By default, the expected shape is [samples x channels], but this order can be changed using axis parameter in constructor.

  • fs (float) – The sampling frequency of the signal in Hz. Each frequency in cutoff must be between 0 and fs/2. Default is 2.

transform(signal)[source]
class medusa.frequency_filtering.IIRFilter[source]

Bases: ProcessingMethod

__init__(order, cutoff, btype, filt_method='sosfiltfilt', axis=0)[source]

IIR Butterworth filter wrapper designed using implementation of scipy.signal.butter. See the documentation of this function to find useful information about this class.

Parameters

  • order (int) – Length of the filter (number of coefficients, i.e. the filter order + 1). This parameter must be odd if a passband includes the Nyquist frequency.

  • cutoff (float or 1-D array_like) – Cutoff frequency of filter (expressed in the same units as fs) OR an array of cutoff frequencies (that is, band edges). In the latter case, the frequencies in cutoff should be positive and monotonically increasing between 0 and fs/2. The values 0 and fs/2 must not be included in cutoff.

  • btype (str {‘bandpass’|‘lowpass’|‘highpass’|‘bandstop’}) – Band type of the filter. It also controls the parameter pass_zero of them scipy.signal.firwin function

  • filt_method (str {'sosfilt', 'sosfiltfilt'}) – Filtering method. See scipy.signal.sosfilt or scipy.signal.sosfiltfilt for more information. For real time fitlering, use sosfilt. For offline filtering, sosfiltfilt is the recommended filtering method.

  • axis (int) – The axis to which the filter is applied. By convention, signals in medusa are defined by [samples x channels], so axis is set to 0 by default.

display()[source]

Displays the filter. Function fit must be called first. This uses the function medusa.frequency_filtering.display_filter()

fit(fs, n_cha=None)[source]

Fits the filter

Parameters

  • fs (float) – The sampling frequency of the signal in Hz. Each frequency in cutoff must be between 0 and fs/2. Default is 2.

  • n_cha (int) – Number of channels. Used to compute the initial conditions of the filter. Only required with sosfilt filtering method (online filtering)

fit_transform(signal, fs)[source]

Fits and applies the filter

Parameters

  • signal (np.ndarray) – Signal to filter. By default, the expected shape is [samples x channels], but this order can be changed using axis parameter in constructor.

  • fs (float) – The sampling frequency of the signal in Hz. Each frequency in cutoff must be between 0 and fs/2. Default is 2.

transform(signal)[source]

Applies the filter to the signal

Parameters

signal (np.ndarray) – Signal to filter. By default, the expected shape is [samples x channels], but this order can be changed using axis parameter in constructor.

medusa.frequency_filtering.display_filter(b, a, fs)[source]

Displays the frequency response of a given filter.

Parameters

  • b (np.ndarray) – Numerator of the filter

  • a (np.ndarray) – Denominator of the filter

  • fs (float) – Sampling frequency of the signal (in Hz)

medusa.nirs module

class medusa.nirs.NIRS[source]

Bases: BiosignalData

Near Infrarred Spectroscopy (NIRS) biosignal data class.

__init__(times, signal, fs, channel_set, **kwargs)[source]

EMG 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]. EMG samples (the units should be defined using kwargs)

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

  • channel_set (list or Object) – Channel information

  • kwargs (kwargs) – Key-value arguments to be saved in the class. This general class does not check anything

classmethod from_serializable_obj(dict_data)[source]

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

to_serializable_obj()[source]

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

medusa.notify_me module

medusa.notify_me.notify_me(mailto, subject, body, mailfrom, password, host='smtp.live.com')[source]

This method implements sending an email (ONLY TESTED FROM A HOTMAIL ADDRESS) to any email address. To allow the email sending from you Hotmail account, you have to validate it, if you get an error please check your inbox (probably, a confirmation mail has been sent).

Parameters

  • mailto (string) – Mail recipient address.

  • subject (string) – Mail subject.

  • body (string) – Mail body.

  • mailfrom (string) – Mail sender address.

  • password (string) – Password from mailfrom address.

  • host (string) – SMTP host of the “mailfrom” address. In case of Hotmail use “smtp.live.com”

medusa.optimization module

class medusa.optimization.Grinder[source]

Bases: object

__init__(**hyparams)[source]
get_hyparams(idx)[source]
class medusa.optimization.Optimizer[source]

Bases: object

__init__(obj, func, grinder, args=None, previous_hist=None)[source]
get_best_hyparams()[source]
optimize(max_iter, approach, save_history=True)[source]
set_bayes_opt_params(n_samp, rbf_length_scale=1)[source]

medusa.pearson_corr_matrix module

medusa.pearson_corr_matrix.pearson_corr_matrix(a, b)[source]

This method implements the Pearson correlation row wise (correlates each row in a with each row in b). The input is [n_samples x n_channels], but the matrices are transposed in a first step.

Parameters

  • a (numpy 2D matrix) – First variable to be correlated. [n_samples x n_channels].

  • b (numpy 2D matrix) – Second variable to be correlated. [n_samples x n_channels].

Returns

corr_values – matrix containing the correlation values. [n_channels x n_channels].

Return type

numpy 2D square matrix

medusa.performance_analysis module

medusa.performance_analysis.perf_analysis(func)[source]

Returns the run time of the decorated function

medusa.signal_generators module

class medusa.signal_generators.SignalGenerator[source]

Bases: ABC

__init__(fs)[source]
abstract get_chunk(duration, n_channels)[source]
class medusa.signal_generators.SinusoidalSignalGenerator[source]

Bases: SignalGenerator

Experimental class for sinusoidal signals generation

__init__(fs, freqs, noise_type='white', noise_params={'mean': 0, 'sigma': 1})[source]
get_chunk(duration, n_channels)[source]

medusa.signal_orthogonalization module

medusa.signal_orthogonalization.signal_orthogonalization_cpu(signal_1, signal_2)[source]

This method implements the ortogonalization of each channel of signal_1 regarding all the channels in signal_2 using CPU

REFERENCES: O’Neill, G. C., Barratt, E. L., Hunt, B. A., Tewarie, P. K., & Brookes, M.J. (2015). Measuring electrophysiological connectivity by power envelope correlation: a technical review on MEG methods. Physics in Medicine & Biology, 60(21), R271.

Parameters

  • signal_1 (numpy 2D matrix) – First MEEG Signal. Allowed dimensions: [n_epochs, n_samples, n_channels], [n_samples, n_channels] and [n_samples].

  • signal_2 (numpy 2D matrix) – Second MEEG Signal. If empty signal_2 will be set to be equal to signal_1. Allowed dimensions: [n_epochs, n_samples, n_channels], [n_samples, n_channels] and [n_samples].

Returns

signal_ort – MEEG ortogonalised signals. The first dimension is epochs. The second dimension is samples. The fourth dimension is the channel of first signal, and the second dimension is regarding which channel of second signal it has been orthogonalized the channel in third dimension. [n_epochs, n_samples, n_channels, n_channels].

Return type

numpy 3D matrix

medusa.signal_orthogonalization.signal_orthogonalization_gpu(signal_1, signal_2)[source]

This function ortogonalizes each channel of signal_1 regarding all the channels in signal_2. Based in O’Neill et al. 2015

Parameters

  • signal_1 (numpy 3D matrix) – First MEEG Signal. Allowed dimensions: [n_epochs, n_samples, n_channels], [n_samples, n_channels] and [n_samples].

  • signal_2 (numpy 3D matrix) – Second MEEG Signal. If empty signal_2 will be set to be equal to signal_1. Allowed dimensions: [n_epochs, n_samples, n_channels], [n_samples, n_channels] and [n_samples].

Returns

signal_ort – MEEG ortogonalized signals. The first dimension is epochs. The second dimension is samples. The fourth dimension is the channel of first signal, and the second dimension is regarding which channel of second signal it has been orthogonalized the channel in third dimension. [n_epochs, n_samples, n_channels, n_channels].

Return type

numpy 3D matrix

medusa.signal_orthogonalization.signal_orthogonalization_gpu_old(signal_1, signal_2)[source]

DEPRECATED: This functions performs the orthogonalization of the signal but it is not vectorized nor allow epochs as inputs. Its use is not recommended.

This function ortogonalizes each channel of signal_1 regarding all the channels in signal_2. Based in O’Neill et al. 2015

Parameters

  • signal_1 (numpy 2D matrix) – MEEG Signal. SamplesXChannel.

  • signal_2 (numpy 2D matrix) – MEEG Signal. SamplesXChannel.

Returns

signal_ort – MEEG ortogonalised signals. Samples x Channel x Channel.

The first dimension are the samples, the third is the base channel used to ortogonalize the other channels and the second dimension are the ortogonalized channels regarding the third dimension

Return type

numpy 3D matrix

medusa.spatial_filtering module

class medusa.spatial_filtering.CCA[source]

Bases: ProcessingMethod

The class CCA performs a Canonical Correlation Analysis filtering. First, function fit() sould be called to train the spatial filters. Then, spatial filters could be used to project testing data. After fit(), the following attributes are computed:

wx

Mixing matrix for projecting the data, where spatial filters are stored in columns.

Type

{(channels, no_filters) ndarray}

wy

Mixing matrix for projecting the reference, where spatial filters are stored in columns.

Type

{(channels, no_filters) ndarray}

r

Sample canonical correlations.

Type

{(channels, ) ndarray}

__init__()[source]

ProcessingMethod constructor

Parameters

kwargs – Key-value arguments that define the exposed methods and output signature. This is used by class Algorithm for a correct implementation of signal processing pipelines.

static canoncorr(X, Y)[source]

Computes the canonical correlation analysis (CCA) for the data matrices X (dimensions N-by-P1) and Y (dimensions N-by-P2). X and Y must have the same number of observations (rows) but can have different numbers of variables (cols). The j-th columns of A and B contain the canonial coefficients, i.e. the linear combination of variables making up the j-th canoncial variable for X and Y, respectively. If X or Y are less than full rank, canoncorr gives a warning and returns zeros in the rows of A or B corresponding to dependent columns of X or Y. Final dimension D is computed as D = min(rank_X, rank_Y). .. rubric:: Notes

This method is adapted from the MATLAB function ‘canoncorr’. Check that file in case of conflicts, doubts or additional information.

Parameters

  • X ({(N, P1) ndarray}) – Input matrix with dimensions N-by-P1. Rows are observations and cols are variables.

  • Y ({(N, P2) ndarray}) – Input matrix with dimensions N-by-P1. Rows are observations and cols are variables.

Returns

  • A ({(P1, D) ndarray}) – Sample canonical coefficients for the variables in X. The j-th column of A contains the linear combination of variables that makes up the j-th canonical variable for X. If X is less than full rank, A will have zeros in the rows corresponding to dependent cols of X.

  • B ({(P2, D) ndarray}) – Sample canonical coefficients for the variables in Y. The j-th column of B contains the linear combination of variables that makes up the j-th canonical variable for Y. If Y is less than full rank, B will have zeros in the rows corresponding to dependent cols of Y.

  • r ({(D,) ndarray}) – Sample canonical correlations. The j-th element of r is the correlation between the h-th columns of the canonical scores for the variables in X and Y.

References

[1] Krzanowski, W.J., Principles of Multivariate Analysis, Oxford University Press, Oxford, 1988. [2] Seber, G.A.F., Multivariate Observations, Wiley, New York, 1984.

Example

>>> import numpy as np
>>> X = np.random.rand(10, 4)
>>> Y = np.random.rand(10, 4)
>>> A, B, r = canoncorr(X, Y)
fit(x, y)[source]

Fits the CCA spatial filters given the two input matrices data and reference, storing relevant parameters. :param x: First input matrix, usually data with concatenated epochs. :type x: {(samples, channels) ndarray} :param y: Second input matrix, usually the data reference. The number of

samples must match the samples of the data matrix. Repeat the reference if necessary before calling this function.

static from_dict(dict_data)[source]
project(data, filter_idx=0, projection='wy')[source]

Projects the input data matrix using the given spatial filter. Note that the spatial filter will have dimensions [no. channels x no. channels].

Parameters

  • data ({(samples, channels) ndarray}) – Testing data matrix. The number of channels must be the same as the no. channels used to train.

  • filter_idx ({int}, optional) – Indexes of the spatial filters to be used. Since filters are sorted by their importance in terms of correlation, the default filter (0) is the one that yields highest correlation.

  • projection ({str}, optional) – Canonical coefficients to be used in projection. By default, the function uses Wy. Typically, if data is averaged, Wy must be used; otherwise, if data is not averaged and just concatenated, Wx must be used.

Returns

projected_data – Projected data along the selected spatial filter.

Return type

{(samples, ) ndarray}

to_dict()[source]
class medusa.spatial_filtering.CSP[source]

Bases: ProcessingMethod

The class CSP performs a Common Spatial Pattern filtering.

filters

Mixing matrix (spatial filters are stored in columns).

Type

{(…, M, M) numpy.ndarray, (…, M, M) matrix}

eigenvalues

Eigenvalues of w.

Type

(…, M) numpy.ndarray

patterns

De-mixing matrix (activation patterns are stored in columns).

Type

numpy.ndarray

__init__(n_filters=4)[source]
n_filterint or None

Number of most discriminant CSP filters to decompose the signal into (must be less or equal to the number of channels in your signal). If int it will return that number of filters. If None it will return all calculated filters.

adj_pham(x, eps=1e-06, n_iter_max=15)[source]

Approximate joint diagonalization based on pham’s algorithm. This is a direct implementation of the PHAM’s AJD algorithm [1]. Extracted from pyriemann module: http://github.com/alexandrebarachant/pyRiemann

Parameters

  • x (ndarray, shape (n_trials, n_channels, n_channels)) – A set of covariance matrices to diagonalize

  • eps (float (default 1e-6)) – tolerance for stopping criterion.

  • n_iter_max (int (default 15)) – The maximum number of iteration to reach convergence.

Returns

  • v (numpy.ndarray, [n_channels, n_channels]) – Diagonalizer

  • d (numpy.ndarray, [n_trials, n_channels, n_channels]) – Set of quasi diagonal matrices

References

[1] Pham, Dinh Tuan. “Joint approximate diagonalization of positive definite Hermitian matrices.” SIAM Journal on Matrix Analysis and Applications 22, no. 4 (2001): 1136-1152.

fit(X, y)[source]

Train Common Spatial Patterns (CSP) filters

Train Common Spatial Patterns (CSP) filters with support to >2 classes based on support multiclass CSP by means of approximate joint diagonalization. In this case, the spatial filter selection is achieved according to [1].

Parameters

  • X (numpy.ndarray, [n_trials, samples, channels]) – Epoched data of shape (n_trials, samples, channels)

  • y (numpy.ndarray, [n_trials,]) – Labels for epoched data of shape (n_trials,)

References

[1] Grosse-Wentrup, Moritz, and Martin Buss. “Multiclass common spatial patterns and information theoretic feature extraction.” Biomedical Engineering, IEEE Transactions on 55, no. 8 (2008): 1991-2000.

static from_dict(dict_data)[source]
project(X)[source]

This method projects the input data X with the spatial filters W

Parameters

X (numpy.ndarray [n_trials, samples, channels]) – Input data (dimensions [n_trials, samples, channels])

Returns

Array with the epochs of signal projected in the CSP space

Return type

numpy.ndarray [n_trials, n_filters, samples]

to_dict()[source]
class medusa.spatial_filtering.LaplacianFilter[source]

Bases: ProcessingMethod

Class for fitting and applying Laplacian Filter to EEG Signals. A channel set from EEGChannelSet class must have been defined before calling LaplacianFilter class.

This class implements the second order Hjorth’s approximation of the Laplacian surface for a spatial-discrete system [1].

It counts with two different modes: - Auto: First, the location of the channel to be filtered is identified.

This allows us to determine the number of surrounding electrodes to be taken into account when calculating the laplacian surface (i.e., an electrode located in the center of the assembly is not the same as an electrode located in a corner). Then, apply the Laplacian surface correction taking into account the distance at which each electrode is located. It should take into account that this mode only applies the laplacian surface to the closest electrodes, so for next-nearest neighbours [2] the custom mode should be used.

  • Custom: In this mode, a list containing the labels of the channels to be

    used to calculate the Laplacian surface of each channel to be filtered must be defined. This allows the design of long distance filters [2].

References [1] Claudio Carvalhaes, J. Acacio de Barros, The surface Laplacian technique

in EEG: Theory and methods, International Journal of Psychophysiology, Volume 97, Issue 3, 2015, Pages 174-188.

[2] Dennis J McFarland, Lynn M. McCabe, Stephen V. David, Jonathan R. Wolpaw,

Spatial filter selection for EEG-based communication, Electroencephalography and clinical Neurophysiology, Volume 193, 1997, Pages 386-394.

__init__(channel_set, mode='auto')[source]

ProcessingMethod constructor

Parameters

kwargs – Key-value arguments that define the exposed methods and output signature. This is used by class Algorithm for a correct implementation of signal processing pipelines.

apply_lp(signal)[source]

Applies Laplacian filter to an EEG signal

Parameters

signal (np.ndarray) – Array of EEG signal with shape [N_samples x N_channels]

Returns

  • s_filtered (np.ndarray)

  • Filtered EEG signal with shape [N_samples x len(l_cha_to_filter)].

fit_lp(l_cha_to_filter, l_cha_laplace=None)[source]

Fits the Laplacian Filter depending on the mode chosen

Parameters

  • l_cha_to_filter (list of strings) – List [N x 1] containing the labels of the channels to filter. Used in both filtering modes.

  • l_cha_laplace (list) – List of lists [N x M] containing the labels of the channels to compute the laplace filter for channel in position Ni of l_cha_to_filter. Only used in mode custom.

medusa.spatial_filtering.car(signal)[source]

Implementation of the common average reference (CAR) spatial filter.

This class applies a CAR filter over a signal with shape [samples x channels]. The CAR filtering substracts the averaged signal of all electrodes to every single one, following the expression below:

X_car = X - (1/N)*sum(X,2),

where X is the EEG signal with dimensions [samples x channels], N is the total number of channels, and sum(~,2) denotes the sum over the second dimension (i.e., over the channels, returning a [samples x 1] signal). In practice, this operation can be implemented as a matrix multiplication:

X_car = (M * X’)’,

where X is the original signal [samples x ch], and M is the spatial filter matrix, composed by:

1-(1/N) -1/N -1/N |
M = | -1/N 1-(1/N) -1/N |
-1/N -1/N 1-(1/N) |
Parameters

signal (np.ndarray) –

EEG raw signal with dimensions [samples x ch]. Note that the TRIGGER channel must be DELETED before calling this function. In other words, eeg_signal must not contain the TRIGGER channel, only the EEG

channels.

Returns

signal – Filtered signal

Return type

np.array

medusa.tensorflow_integration module

Created on Monday March 15 19:27:14 2021

This module provides

@author: Eduardo Santamaría-Vázquez

exception medusa.tensorflow_integration.DeviceNotAvailable[source]

Bases: Exception

__init__(device)[source]
exception medusa.tensorflow_integration.NoCPU[source]

Bases: Exception

__init__()[source]
exception medusa.tensorflow_integration.NoGPU[source]

Bases: Exception

__init__()[source]
medusa.tensorflow_integration.check_gpu_acceleration()[source]

Checks if there is GPU acceleration available

medusa.tensorflow_integration.check_tf_config(autoconfig=False)[source]

Checks if tensorflow has been configured

Parameters

autoconfig: bool

If tensorflow has not been configured and autoconfig is True, tensorflow is configured automatically, trying GPU first.

medusa.tensorflow_integration.config_tensorflow(gpu_acceleration=True, device=None)[source]

This function makes a very simple configuration of tensorflow, checking if Tensorflow >= 2.0.0 and GPU acceleration is available. For more advanced options, use the tensorflow native API.

Parameters

  • gpu_acceleration (bool) – Enables GPU acceleration. The function will check if this feature is available and select the proper device.

  • device (str, optional) – Device that will be selected. Use tf.config.list_logical_devices() to list the current available devices.

medusa.tensorflow_integration.get_tf_device_name()[source]

Returns the tensorflow device used by medusa

medusa.transforms module

medusa.transforms.hilbert(signal)[source]

This method implements the Hilbert transform.

Parameters

signal (numpy.ndarray) – Input signal with shape [n_epochs x n_samples x n_channels].

Returns

hilb – Analytic signal of x [n_epochs, n_samples, n_channels].

Return type

numpy 3D matrix

medusa.transforms.normalize_psd(psd, norm='rel')[source]

Normalizes the PSD using different methods.

Parameters

  • psd (numpy array or list) – Power Spectral Density (PSD) of the signal with shape [samples], [samples x channels] or [epochs x samples x channels]. It assumes PSD is the one-sided spectrum.

  • norm (string) – Normalization to be performed. Choose z for z-score or rel for relative power.

medusa.transforms.power_spectral_density(signal, fs, segment_pct=80, overlap_pct=50, window='boxcar')[source]

This method allows to compute the one-sided power spectral density (PSD) by means of Welch’s periodogram method. This method wraps around scipy.signal.welch method to compute the PSD, allowing to pass epoched signals and defining the segment length and overlap in percentage, simplifying the use for specific purposes. For more advanced configurations, use the original scipy (or equivalent) function.

Parameters

  • signal (numpy nd array) – Signal with shape [n_epochs x n_samples x n_channels].

  • fs (int) – Sampling frequency of the signal

  • segment_pct (float) – Percentage of the signal (n_samples) used to calculate the FFT. Default: 80% of the signal.

  • overlap_pct (float) – Percentage of overlap (n_samples) for the Welch method. Default: 50% of the signal.

  • window – Desired window to use. See scipy.signal.welch docs for more details

Returns

  • f (numpy 1D array) – Array of sampled frequencies.

  • psd (numpy 2D array) – PSD of the signal with shape [n_epochs, n_samples, n_channels]

medusa.utils module

medusa.utils.check_dimensions(data)[source]

This function checks if data dimensions are [n_epochs x n_samples x n_channels] and transforms to it if not