medusa package
Subpackages
- medusa.bci package
- medusa.connectivity package
- medusa.graph_theory package
- Submodules
- medusa.graph_theory.assortativity module
- medusa.graph_theory.betweeenness_centrality module
- medusa.graph_theory.clustering_coefficient module
- medusa.graph_theory.complexity module
- medusa.graph_theory.degree module
- medusa.graph_theory.density module
- medusa.graph_theory.efficiency module
- medusa.graph_theory.eigen_centrality module
- medusa.graph_theory.modularity module
- medusa.graph_theory.participation_coefficient module
- medusa.graph_theory.path_length module
- medusa.graph_theory.surrogate_graph module
- medusa.graph_theory.transitivity module
- medusa.local_activation package
- medusa.meeg package
- medusa.plots package
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.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.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.
- 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
- 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
- class medusa.components.ConsistencyChecker[source]
Bases:
SerializableComponent
Class that provides functionality to check consistency across recordings to build a dataset
- 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
- 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
- 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
- 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
- class medusa.components.ExperimentData[source]
Bases:
SerializableComponent
Skeleton class for experiment data
- 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
- 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.
- 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.
- 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.
- 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
- 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_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_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”)
- 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
- 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.
- 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_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.
- 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
- classmethod from_serializable_obj(data)[source]
This function must return an instance of the class from a serializable (list or dict of primitive types)
- 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.
- 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
- 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]
- 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
- 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]
- 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
- 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
- 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
- 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
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.
- 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.
- 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.
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
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
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.signal_generators module
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.
- 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}
- 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.
- 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]
- 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
- 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.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]