medusa.bci package

Submodules

medusa.bci.cvep_spellers module

In this module you will find useful functions and classes to operate with data recorded using spellers based on code-modulated visual evoked potentials (c-VEP), which are widely used by the BCI community. Enjoy!

@author: Víctor Martínez-Cagigal

class medusa.bci.cvep_spellers.CVEPModelCircularShifting

Bases: Algorithm

__init__(bpf=[[7, (1.0, 30.0)]], notch=[7, (49.0, 51.0)], art_rej=None, correct_raster_latencies=False, *args, **kwargs)

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.

check_predict_feasibility(dataset)

check_predict_feasibility_signal(times, onsets, fs)

fit_dataset(dataset, **kwargs)

must_stop(corr_vector, std=3.0)

predict(times, signal, trial_idx, exp_data, sig_data)

predict_dataset(dataset)

class medusa.bci.cvep_spellers.CVEPSpellerData

Bases: ExperimentData

Experiment info class for c-VEP-based spellers. It supports nested multi-level paradigms. This unified class can be used to represent a run of every c-VEP stimulation paradigm designed to date, and is the expected class for feature extraction and command decoding functions of the module medusa.bci.cvep_paradigms. It is complicated, but powerful so.. use it well!

__init__(mode, paradigm_conf, commands_info, onsets, command_idx, unit_idx, level_idx, matrix_idx, cycle_idx, trial_idx, cvep_model, spell_result, fps_resolution, spell_target=None, raster_events=None, **kwargs)

classmethod from_serializable_obj(dict_data)

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

to_serializable_obj()

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

class medusa.bci.cvep_spellers.CVEPSpellerDataset

Bases: Dataset

This class inherits from medusa.data_structures.Dataset, increasing its functionality for datasets with data from c-VEP-based spellers. It provides common ground for the rest of functions in the module.

__init__(channel_set, fs=None, biosignal_att_key='eeg', experiment_att_key='cvepspellerdata', experiment_mode=None, track_attributes=None)

Constructor

Parameters

• channel_set (meeg.EEGChannelSet) – EEG channel set. Only these channels will be kept in the dataset, the others will be discarded. Also, the signals will be rearranged, keeping the same channel order, avoiding errors in future stages of the signal processing pipeline

• fs (int, float or None) – Sample rate of the recordings. If there are recordings with different sample rates, the consistency of the dataset can be still assured using resampling

• biosignal_att_key (str) – Name of the attribute containing the target biosignal that will be used to extract the features. It has to be the same in all recordings (e.g., ‘eeg’, ‘meg’).

• experiment_att_key (str or None) – Name of the attribute containing the target experiment that will be used to extract the features. It has to be the same in all recordings (e.g., ‘rcp_data’, ‘cake_paradigm_data’). It is mandatory when a recording of the dataset contains more than 1 experiment data

• experiment_mode (str {‘train’|’test’|None}) – Mode of the experiment. If this dataset will be used to fit a model, set to train to avoid errors

• track_attributes (dict of dicts or None) –

  This parameter indicates custom attributes that must be tracked in feature extraction functions and how. The keys are the name of the attributes, whereas the values are dicts indicating the tracking mode {‘concatenate’|’append’} and parent. Option concatenate is only available for attributes of type list or numpy arrays, forming a 1 dimensional array with the data from all recordings. Option append is used to save all kind of objects for each recording, forming a list whose length will be the number of recordings in the dataset. A set of default attributes is defined, so this parameter will be None in most cases. Example to track 2 custom attributes (i.e., date and experiment_equipment):

  track_attributes = {

  ‘date’: {

  ‘track_mode’: ‘append’, ‘parent’: None

  }, ‘experiment_equipment’: {

  ’track_mode’: ‘append’, ‘parent’: experiment_att_key

  }

  }

custom_operations_on_recordings(recording)

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.bci.cvep_spellers.CircularShiftingClassifier

Bases: ProcessingMethod

Standard feature extraction method for c-VEP-based spellers. Basically, it computes a template for each sequence.

__init__(correct_raster_latencies=False, art_rej=None, **kwargs)

Class constructor

fit_dataset(dataset, std_epoch_rejection=3.0, show_progress_bar=True)

Parameters

dataset (CVEPSpellerDataset) –

predict(times, signal, trial_idx, exp_data, sig_data)

predict_dataset(dataset, show_progress_bar=True)

Parameters

dataset (CVEPSpellerDataset) –

class medusa.bci.cvep_spellers.CircularShiftingEarlyStopping

Bases: ProcessingMethod

__init__(**kwargs)

Class constructor

check_early_stop(corr_vector, std=3.0)

Early stopping method based on normal distributions.

Parameters

• corr_vector (list() or 1D ndarray) – Vector that represents the sorted correlations for each of the possible commands, where corr_vector[0] must point to the most probable selected command.

• std (int) – Multiplier that determines if the selected command is an outlier of the normal distribution made up from the rest of correlations. Typical values are: 1 (outside 68% of data), 2 (outside 95% of data), and 3 (default, outside 99.7% of data).

Returns

• must_stop (bool) – True if it is possible to stop now, false otherwise.

• probs (1D ndarray) – Current estimated probabilities of being selected (sorted).

class medusa.bci.cvep_spellers.FilterBankPreprocessing

Bases: ProcessingMethod

Just the common preprocessing applied in c-VEP-based spellers. Simple, quick and effective: frequency IIR band-pass and notch filters

__init__(filter_bank=None, notch_order=7, notch_cutoff=(49.0, 51.0))

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(fs)

Fits the IIR filters.

Parameters

fs (float) – Sample rate of the signal.

fit_transform_dataset(dataset, show_progress_bar=True)

Fits the IIR filters and transforms an EEG dataset applying the filters sequentially. Each recording is preprocessed independently, taking into account possible differences in sample rate.

Parameters

• dataset (ERPSpellerDataset) – ERPSpellerDataset with the recordings to be preprocessed.

• show_progress_bar (bool) – Show progress bar

fit_transform_signal(signal, fs)

Fits the IIR filters and transforms an EEG signal applying them sequentially

Parameters

• signal (np.array or list) – Signal to transform. Shape [n_samples x n_channels]

• fs (float) – Sample rate of the signal.

transform_dataset(dataset, show_progress_bar=True)

Parameters

dataset (CVEPSpellerDataset) –

transform_signal(signal)

Transforms an EEG signal applying the filter bank

Parameters

signal (np.array or list) – Signal to transform. Shape [n_samples x n_channels]

class medusa.bci.cvep_spellers.LFSR

Bases: object

Computes a Linear-Feedback Shift Register (LFSR) sequence.

__init__(polynomial, base=2, seed=None, center=False)

Constructor of LFSR

static lfsr(polynomial, base=2, seed=None, center=False)

This method implements a Linear-Feedback Shift Register (LFSR).

IMPORTANT: maximal length sequences (m-sequences) can be only generated if the polynomial (taps) is primitive. I.e.:

• the number of taps is even.

• the set of taps is setwise co-prime (there must be no divisor

other than 1 common to all taps).

A list of primitive polynomials in function of the order m can be found here: https://en.wikipedia.org/wiki/Linear-feedback_shift_register

NOTE: if the seed is composed by all zeros, the output sequence will be zeros.

Parameters

• polynomial (list) – Generator polynomial. E.g. (bias is specified for math convention but not used): “1 + x^5 + x^6” would be [0, 0, 0, 0, 1, 1]. “1 + 2x + x^4” would be [2, 0, 0, 1]

• base (int) – (Optional, default: base = 2) Base of the sequence events that belongs to the Galois Field of the same base. By default, base=2, so only events of type {0,1} (or {-1,1} are part of the returned sequence.

• seed (list) – (Optional) Initial state. If not provided, the default state is a one-array with length equal to the order of the polynomial.

• center (bool) – (Optional, default = False) Determines if a centering over zero must be performed in the returned sequence (e.g., {0,1} -> {-1,1})

Returns

sequence – LFSR m-sequence (maximum length is base^order-1), where order is the order of the polynomial.

Return type

list

class medusa.bci.cvep_spellers.StandardPreprocessing

Bases: ProcessingMethod

Just the common preprocessing applied in c-VEP-based spellers. Simple, quick and effective: frequency IIR band-pass and notch filters

__init__(bpf_order=7, bpf_cutoff=(0.5, 60.0), notch_order=7, notch_cutoff=(49.0, 51.0))

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(fs)

Fits the IIR filters.

Parameters

fs (float) – Sample rate of the signal.

fit_transform_dataset(dataset, show_progress_bar=True)

Fits the IIR filters and transforms an EEG dataset applying the filters sequentially. Each recording is preprocessed independently, taking into account possible differences in sample rate.

Parameters

• dataset (ERPSpellerDataset) – ERPSpellerDataset with the recordings to be preprocessed.

• show_progress_bar (bool) – Show progress bar

fit_transform_signal(signal, fs)

Fits the IIR filters and transforms an EEG signal applying them sequentially

Parameters

• signal (np.array or list) – Signal to transform. Shape [n_samples x n_channels]

• fs (float) – Sample rate of the signal.

transform_dataset(dataset, show_progress_bar=True)

Parameters

dataset (CVEPSpellerDataset) –

transform_signal(signal)

Transforms an EEG signal applying IIR filterings

Parameters

signal (np.array or list) – Signal to transform. Shape [n_samples x n_channels]

medusa.bci.cvep_spellers.autocorr_circular(x)

With circular shifts (periodic correlation)

medusa.bci.cvep_spellers.autocorr_zeropad(x)

With zero padding, equivalent to np.correlate()

medusa.bci.cvep_spellers.check_if_shifted(seq1, seq2)

medusa.bci.cvep_spellers.get_items_by_sorted_sequences(experiment, trial_idx, sorted_seqs, sorted_corrs=None)

Parameters

experiment (CVEPSpellerData) –

medusa.bci.cvep_spellers.get_unique_sequences_from_targets(experiment)

Function that returns the unique sequences of all targets. return

Parameters

experiment (CVEPSpellerData) –

medusa.bci.erp_spellers module

Created on Monday March 15 19:27:14 2021

In this module you will find useful functions and classes to operate with data recorded using spellers based on event-related pontentials (ERP), which are widely used by the BCI community. Enjoy!

@author: Eduardo Santamaría-Vázquez

class medusa.bci.erp_spellers.CMDModelEEGInception

Bases: ERPSpellerModel

Command decoding model for ERP-based spellers model based on EEG-Inception, a powerful deep convolutional neural network specifically developed for BCI applications [1].

Dataset features:

• Sample rate of the signals > 128 Hz. The model can handle recordings

  with different sample rates.

• Recommended channels: [‘Fz’, ‘Cz’, ‘Pz’, ‘P3’, ‘P4’, ‘PO7’, ‘PO8’, ‘Oz’].

Processing pipeline:

• Preprocessing:

  • IIR Filter (order=5, cutoff=(0.5, 45) Hz: unlike FIR filters, IIR

    filters are quick and can be applied in small signal chunks. Thus, they are the preferred method for frequency filter in online systems

  • Common average reference (CAR): widely used spatial filter that

    increases the signal-to-noise ratio of the ERPs.

• Feature extraction:

  • Epochs (window=(0, 1000) ms, resampling to 128 HZ): the epochs of

    signal are extract for each stimulation. Baseline normalization is also applied, taking the window (-250, 0) ms relative to the stimulus onset.

• Feature classification

  • EEG-Inception: convolutional neural network [1].

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__()

Class constructor

build()

This function builds the model, adding all the processing methods to the pipeline. It must be called after configure.

configure(cnn_n_cha=8, fine_tuning=False, shuffle_before_fit=True, validation_split=0.2, init_weights_path=None, gpu_acceleration=True)

This function must be used to configure the model before calling build method. Class attribute settings attribute must be set with a dict

fit_dataset(dataset, **kwargs)

Function that receives an ERPSpellerDataset and uses its data to fit the model. By default, executes pipeline ‘fit_dataset’. Override method for other behaviour.

Parameters

• dataset (ERPSpellerDataset) – Dataset with recordings from an ERP-based speller experiment

• kwargs (key-value arguments) – Optional parameters depending on the specific implementation of the model

Returns

fit_results – Dict with the information of the fot process. For command decoding models, at least it has to contain keys spell_result, spell_result_per_seq and spell_acc_per_seq, which contain the decoded commands, the decoded commands and the command decoding accuracy per sequences of stimulation considered in the analysis.

Return type

dict

predict(times, signal, fs, channel_set, exp_info, **kwargs)

Function that receives EEG signal and experiment info from an ERP-based speller to decode the user’s intentions. Used in online experiments. By default, executes pipeline ‘predict’. Override method for other behaviour.

Parameters

• times (list or numpy.ndarray) – Timestamps of the EEG samples

• signal (list or numpy.ndarray) – EEG samples with shape [n_samples x n_channels]

• fs (float) – Sample rate of the EEG signal

• l_cha (list) – List of channel labels

• x_info (dict) – Dict with the needed experiment info to decode the commands. It has to contain keys: paradigm_conf, onsets, batch_idx, group_idx, unit_idx, level_idx, matrix_idx, sequence_idx, trial_idx, run_idx. See ERPSpellerData to know how are defined these variables.

• kwargs (key-value arguments) – Optional parameters depending on the specific implementation of the model

class medusa.bci.erp_spellers.CMDModelEEGNet

Bases: ERPSpellerModel

Command decoding model for ERP-based spellers model based on EEGNet, a compact deep convolutional neural network specifically developed for EEG applications [1].

Dataset features:

• Sample rate of the signals > 128 Hz. The model can handle recordings

  with different sample rates.

• Recommended channels: [‘Fz’, ‘Cz’, ‘Pz’, ‘P3’, ‘P4’, ‘PO7’, ‘PO8’, ‘Oz’].

Processing pipeline: - Preprocessing:

• IIR Filter (order=5, cutoff=(0.5, 45) Hz: unlike FIR filters, IIR

  filters are quick and can be applied in small signal chunks. Thus, they are the preferred method for frequency filter in online systems

• Common average reference (CAR): widely used spatial filter that

  increases the signal-to-noise ratio of the ERPs.

• Feature extraction:

  • Epochs (window=(0, 1000) ms, resampling to 128 HZ): the epochs of

    signal are extract for each stimulation. Baseline normalization is also applied, taking the window (-250, 0) ms relative to the stimulus onset.

• Feature classification

  • EEGNet: compact convolutional network.

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__()

Class constructor

build()

This function builds the model, adding all the processing methods to the pipeline. It must be called after configure.

configure(cnn_n_cha=8, fine_tuning=False, shuffle_before_fit=True, validation_split=0.2, init_weights_path=None, gpu_acceleration=True)

This function must be used to configure the model before calling build method. Class attribute settings attribute must be set with a dict

fit_dataset(dataset, **kwargs)

Function that receives an ERPSpellerDataset and uses its data to fit the model. By default, executes pipeline ‘fit_dataset’. Override method for other behaviour.

Parameters

• dataset (ERPSpellerDataset) – Dataset with recordings from an ERP-based speller experiment

• kwargs (key-value arguments) – Optional parameters depending on the specific implementation of the model

Returns

fit_results – Dict with the information of the fot process. For command decoding models, at least it has to contain keys spell_result, spell_result_per_seq and spell_acc_per_seq, which contain the decoded commands, the decoded commands and the command decoding accuracy per sequences of stimulation considered in the analysis.

Return type

dict

predict(times, signal, fs, channel_set, x_info, **kwargs)

Function that receives EEG signal and experiment info from an ERP-based speller to decode the user’s intentions. Used in online experiments. By default, executes pipeline ‘predict’. Override method for other behaviour.

Parameters

• times (list or numpy.ndarray) – Timestamps of the EEG samples

• signal (list or numpy.ndarray) – EEG samples with shape [n_samples x n_channels]

• fs (float) – Sample rate of the EEG signal

• l_cha (list) – List of channel labels

• x_info (dict) – Dict with the needed experiment info to decode the commands. It has to contain keys: paradigm_conf, onsets, batch_idx, group_idx, unit_idx, level_idx, matrix_idx, sequence_idx, trial_idx, run_idx. See ERPSpellerData to know how are defined these variables.

• kwargs (key-value arguments) – Optional parameters depending on the specific implementation of the model

class medusa.bci.erp_spellers.CMDModelRLDA

Bases: ERPSpellerModel

Command decoding model for ERP-based spellers model based on regularized linear discriminant analysis (rLDA) based on the implementation of Krusienski et al 2008 [1].

Dataset features:

• Sample rate of the signals > 20 Hz. The model can handle recordings

  with different sample rates.

• Recommended channels: [‘Fz’, ‘Cz’, ‘Pz’, ‘P3’, ‘P4’, ‘PO7’, ‘PO8’, ‘Oz’].

Processing pipeline: - Preprocessing (medusa.bci.erp_spellers.StandardPreprocessing):

• IIR Filter (order=5, cutoff=(0.5, 10) Hz: unlike FIR filters, IIR

  filters are quick and can be applied in small signal chunks. Thus, they are the preferred method for frequency filter in online systems.

• Common average reference (CAR): widely used spatial filter that

  increases the signal-to-noise ratio of the ERPs.

• Feature extraction (medusa.bci.erp_spellers.StandardFeatureExtraction):

  • Epochs (window=(0, 1000) ms, resampling to 20 HZ): the epochs of

    signal are extracted for each stimulation. Baseline normalization is also applied, taking the window (-250, 0) ms relative to the stimulus onset.

• Feature classification (

sklearn.discriminant_analysis.LinearDiscriminantAnalysis)

• Regularized linear discriminant analysis (rLDA): we use the sklearn

  implementation, with eigen solver and auto shrinkage paramers. See reference in sklearn doc.

References

[1] Krusienski, D. J., Sellers, E. W., McFarland, D. J., Vaughan, T. M., & Wolpaw, J. R. (2008). Toward enhanced P300 speller performance. Journal of neuroscience methods, 167(1), 15-21.

__init__()

Class constructor

build()

This function builds the model, adding all the processing methods to the pipeline. It must be called after configure.

configure(p_filt_cutoff=(0.5, 10), f_w_epoch_t=(0, 800), f_target_fs=20)

This function must be used to configure the model before calling build method. Class attribute settings attribute must be set with a dict

fit_dataset(dataset, **kwargs)

Function that receives an ERPSpellerDataset and uses its data to fit the model. By default, executes pipeline ‘fit_dataset’. Override method for other behaviour.

Parameters

• dataset (ERPSpellerDataset) – Dataset with recordings from an ERP-based speller experiment

• kwargs (key-value arguments) – Optional parameters depending on the specific implementation of the model

Returns

fit_results – Dict with the information of the fot process. For command decoding models, at least it has to contain keys spell_result, spell_result_per_seq and spell_acc_per_seq, which contain the decoded commands, the decoded commands and the command decoding accuracy per sequences of stimulation considered in the analysis.

Return type

dict

predict(times, signal, fs, channel_set, x_info, **kwargs)

Function that receives EEG signal and experiment info from an ERP-based speller to decode the user’s intentions. Used in online experiments. By default, executes pipeline ‘predict’. Override method for other behaviour.

Parameters

• times (list or numpy.ndarray) – Timestamps of the EEG samples

• signal (list or numpy.ndarray) – EEG samples with shape [n_samples x n_channels]

• fs (float) – Sample rate of the EEG signal

• l_cha (list) – List of channel labels

• x_info (dict) – Dict with the needed experiment info to decode the commands. It has to contain keys: paradigm_conf, onsets, batch_idx, group_idx, unit_idx, level_idx, matrix_idx, sequence_idx, trial_idx, run_idx. See ERPSpellerData to know how are defined these variables.

• kwargs (key-value arguments) – Optional parameters depending on the specific implementation of the model

class medusa.bci.erp_spellers.CSDModelEEGInception

Bases: ERPSpellerModel

Control state detection model for ERP-based spellers model based on EEG-Inception, a powerful deep convolutional neural network specifically developed for BCI applications [1]. More information about this control state detection method can be found in [2].

Dataset features:

• Sample rate of the signals > 128 Hz. The model can handle recordings

  with different sample rates.

• Recommended channels: [‘Fz’, ‘Cz’, ‘Pz’, ‘P3’, ‘P4’, ‘PO7’, ‘PO8’, ‘Oz’].

Processing pipeline:

• Preprocessing:

  • IIR Filter (order=5, cutoff=(0.5, 45) Hz: unlike FIR filters, IIR

    filters are quick and can be applied in small signal chunks. Thus, they are the preferred method for frequency filter in online systems

  • Common average reference (CAR): widely used spatial filter that

    increases the signal-to-noise ratio of the ERPs.

• Feature extraction:

  • Epochs (window=(0, 1000) ms, resampling to 128 HZ): the epochs of

    signal are extract for each stimulation. Baseline normalization is also applied, taking the window (-250, 0) ms relative to the stimulus onset.

• Feature classification

  • EEG-Inception: convolutional neural network

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.

[2] Eduardo Santamaría-Vázquez, Víctor Martínez-Cagigal, Sergio Pérez-Velasco, Diego Marcos-Martínez, Roberto Hornero, Robust Asynchronous Control of ERP-Based Brain-Computer Interfaces using Deep Learning, Computer Methods and Programs in Biomedicine, vol. 215, Marzo, 2022

__init__()

Class constructor

build()

This function builds the model, adding all the processing methods to the pipeline. It must be called after configure.

configure(cnn_n_cha=8, fine_tuning=False, shuffle_before_fit=True, validation_split=0.2, init_weights_path=None, gpu_acceleration=True)

This function must be used to configure the model before calling build method. Class attribute settings attribute must be set with a dict

fit_dataset(dataset, **kwargs)

Function that receives an ERPSpellerDataset and uses its data to fit the model. By default, executes pipeline ‘fit_dataset’. Override method for other behaviour.

Parameters

• dataset (ERPSpellerDataset) – Dataset with recordings from an ERP-based speller experiment

• kwargs (key-value arguments) – Optional parameters depending on the specific implementation of the model

Returns

fit_results – Dict with the information of the fot process. For command decoding models, at least it has to contain keys spell_result, spell_result_per_seq and spell_acc_per_seq, which contain the decoded commands, the decoded commands and the command decoding accuracy per sequences of stimulation considered in the analysis.

Return type

dict

predict(times, signal, fs, channel_set, x_info, **kwargs)

Function that receives EEG signal and experiment info from an ERP-based speller to decode the user’s intentions. Used in online experiments. By default, executes pipeline ‘predict’. Override method for other behaviour.

Parameters

• times (list or numpy.ndarray) – Timestamps of the EEG samples

• signal (list or numpy.ndarray) – EEG samples with shape [n_samples x n_channels]

• fs (float) – Sample rate of the EEG signal

• l_cha (list) – List of channel labels

• x_info (dict) – Dict with the needed experiment info to decode the commands. It has to contain keys: paradigm_conf, onsets, batch_idx, group_idx, unit_idx, level_idx, matrix_idx, sequence_idx, trial_idx, run_idx. See ERPSpellerData to know how are defined these variables.

• kwargs (key-value arguments) – Optional parameters depending on the specific implementation of the model

class medusa.bci.erp_spellers.ERPSpellerData

Bases: ExperimentData

Experiment info class for ERP-based spellers. It supports nested multi-level paradigms. This unified class can be used to represent a run of every ERP stimulation paradigm designed to date, and is the expected class for feature extraction and command decoding functions of the module medusa.bci.erp_paradigms. It is complicated, but powerful so.. use it well!

__init__(mode, paradigm_conf, commands_info, onsets, batch_idx, group_idx, unit_idx, level_idx, matrix_idx, sequence_idx, trial_idx, spell_result, control_state_result, spell_target=None, control_state_target=None, **kwargs)

ERPSpellerData constructor

Parameters

• mode (str) – Mode of this run. Values: {“train”|”test”}

• paradigm_conf (list) –

  This parameter describes the paradigm configuration for the experiment. The array must have shape [n_matrices x n_units x n_groups x n_batches x n_commands/batch]. The matrix is the maximum entity of the paradigm and only one can be used in each trial. The units are smaller entities that are used in multi-level paradigms, such as the Hex-O-spell (HOS) paradigm [1]. In this case, each level can use a different unit, affecting the selected command for the trial. For instance, in the HOS paradigm, you should define 1 matrix with 7 units, one for the initial menu and 6 for the second level of each command (letters). Importantly, commands must be unequivocally defined in each matrix. Therefore, units cannot share command identifiers. Then, the groups describe aggregations of commands that are highlighted at the same time. For instance, the row-column paradigm (RCP) [2] has 2 groups of commands (i.e., rows and columns), whereas the HOS has only 1 (i.e., each command is highlighted individually). Finally, batches contain the commands IDs defined in each group. In an RCP matrix of 6x6, each of the 2 groups has 6 batches, corresponding to the rows and columns. This structure supports nested multi-level matrices, providing compatibility with all paradigms to date and setting a general framework for feature extraction and command decoding functions. The relationship between the command IDs and the letters or actions should be defined in other variable, but it is not necessary for signal processing.

  Example of 2x2 RCP paradigm:

  rcp_conf = [

  # Matrices [

  # Units [

  # Groups [

  # Batches [0, 1], [2, 3]

  ], [

  [0, 2], [1, 3]

  ]

  ]

  ]

  ]

  Example of HOS paradigm:

  hos_conf = [

  # Matrices [

  # Units [

  # Groups [

  # Batches [0], [1], [2], [3], [4], [5]

  ],

  ], [

  [

  [6], [7], [8], [9], [10], [11]

  ],

  ], [

  [

  [12], [13], [14], [15], [16], [17]

  ],

  ], [

  [

  [18], [19], [20], [21], [22], [23]

  ],

  ], [

  [

  [24], [25], [26], [27], [28], [29]

  ],

  ]

  ]

  ]

• commands_info (list) – List containing the command information per matrix. Each position must be a dict, whose keys are the command ids used in paradigm_conf. The value must be another dict containing important information about each command (e.g., label, text, action, icon path, etc). This information may be different for different use cases, but must be serializable (i.e., contain primitive types). Shape [n_matrices x n_commands].

• onsets (list or numpy.ndarray) – Timestamp of each stimulation. This timestamps have to be synchronized with the EEG (or other biosignal) timestamps in order to assure a correct functioning of all medusa functions. Shape: [n_stim x 1]

• batch_idx (list or numpy.ndarray) – Index of the highlighted batch for each stimulation. A batch represents the highlighted commands in each stimulation. For example in the row-col paradigm (RCP) represents each row and column. Shape: [n_stim x 1]

• group_idx (list or numpy.ndarray) – Index of the group that has been highlighted. Groups represent the different aggregations of batches. Between batches of different groups, 1 command must be common. For example in the RCP there are 2 groups: rows and columns. In this paradigm, between each pair of batches (e.g., row=2, col=4), there is only one command in common. Shape: [n_stim x 1]

• unit_idx (list or numpy.ndarray) – Index of the unit used in each stimulation. Units are low level entities used in multi-level paradigms, such as HOS paradigm [1]. For each level, only 1 unit can be used. As the trial may have several layers, several units can be used in 1 trial. For instance, in the HOS, the first unit is the main menu. The other 6 units are each of the lower level entities that are displayed in the second level of stimulation. Shape: [n_stim x 1]

• level_idx (list or numpy.ndarray) – Index of the level of each stimulation. Levels represent each one of the selections that must be made before a trial is finished. For example, in the Hex-O-spell paradigm there are 2 levels (see [1]). Shape: [n_stim x 1]

• matrix_idx (list or numpy.ndarray) – Index of the matrix used in each stimulation. Each matrix can contain several levels. The matrix has to be the same accross the entire trial. Shape: [n_stim x 1]

• sequence_idx (list or numpy.ndarray) – Index of the sequence for each stimulation. A sequence represents a round of stimulation: all commands have been highlighted 1 time. This class support dynamic stopping in different levels. Shape: [n_stim x 1]

• trial_idx (list or numpy.ndarray) – Index of the trial for each stimulation. A trial represents the selection of a final command. Depending on the number of levels, the final selection takes N intermediate selections.

• spell_result (list or numpy.ndarray) – Spell result of the run. Each position contains the matrix and command id that identifies the selected command per trial and level. Shape [n_trials x n_levels x 2]. Eg., in the RCP: [[[matrix_idx, cmd_id], [matrix_idx, cmd_id]]].

• control_state_result (list or numpy.ndarray) – Control state result of the run. Each position contains the detected control state of the user per trial (0 -> non-control, 1-> control). Shape: [n_trials x 1]. Values {0|1}

• spell_target (list or numpy.ndarray or None) – Spell target of the run. Each position contains the matrix and command id per level that identifies the target command of the trial. Shape [n_trials x n_levels x 2]. Eg., in the RCP: [[[matrix_idx, cmd_id], [matrix_idx, cmd_id], etc]].

• control_state_target (list or numpy.ndarray or None) – Control state target of the run. Each position contains the target control state of the user per trial (0 -> non-control, 1-> control). Shape: [n_trials x 1]. Values {0|1}

• kwargs (kwargs) – Custom arguments that will also be saved in the class

References

[1] Blankertz, B., Dornhege, G., Krauledat, M., Schröder, M., Williamson, J., Murray-Smith, R., & Müller, K. R. (2006). The Berlin Brain-Computer Interface presents the novel mental typewriter Hex-o-Spell.

[2] Farwell, L. A., & Donchin, E. (1988). Talking off the top of your head: toward a mental prosthesis utilizing event-related brain potentials. Electroencephalography and clinical Neurophysiology, 70(6), 510-523.

compute_control_state_labels()

This function computes the control state label vector (0 -> non-control state, 1 -> control state).

compute_erp_labels()

This function computes the erp label vector (0 if the epoch doesn’t have ERP, 1 if the epoch have ERP).

classmethod from_serializable_obj(dict_data)

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

get_batches_associated_to_cmd(matrix_idx, command_idx)

This function returns the batches associated to the given command as defined in the paradigm configuration

Parameters

• matrix_idx (int) – Matrix of the command

• command_idx (int) – Index of the command as defined in attribute commands_info

static get_paradigm_conf_for_hox(matrix_dims, commands_info_hox=None)

Returns the paradigm configuration matrix for the Hex-O-Speller (HOX) or cake paradigms from the Berlin BCI Group [1]. This paradigm has 2 levels of selection with 6 commands in each unit.

Parameters

• matrix_dims (list or np.array) – Array containing the dimensions of the matrices used in the experiment. For each matrix, the first position is the number of commands of the first level and the second the number of commands of the second level (typically both are 6). Shape [n_matrices x 2]

• commands_info_hox (list or None) – Array containing the dict info of each command. The first dimension are the matrices, the second dimension represent the units, and the third dimension contains the dictionary with the info of each command. Typically, this paradigm has 7 units of 6 commands each. As defined by the Berlin BCI group: 1 menu matrix and 6 matrix for each group of 6 letters. Therefore, with this setup, this array has shape [n_matrices x 7 x 6]

Returns

• paradigm_conf (list) – Array with the paradigm configuration for an RCP paradigm

• commands_info (list) – Flattened version of commands_info input. It contains the command information corresponding to paradigm_conf. If input parameter commands_info is None, this output will be a skeleton with an empty dict for each command. If input commands_info is provided, it will be incorporated in the output

References

[1] Blankertz, B., Dornhege, G., Krauledat, M., Schröder, M., Williamson, J., Murray-Smith, R., & Müller, K. R. (2006). The Berlin Brain-Computer Interface presents the novel mental typewriter Hex-o-Spell.

static get_paradigm_conf_for_rcp(matrix_dims, commands_info_rcp=None)

Returns the paradigm configuration matrix for the row-column paradigm (RCP) experiment [1]

Parameters

• matrix_dims (list or np.array) – Array containing the dimensions of the matrices used in the experiment. For each matrix, the first position is the number of rows and the second the number of columns. Shape [n_matrices x 2]

• commands_info_rcp (list or None) – Array containing the dict info of each command, arranged in 2D matrices. Shape [n_matrices x n_rows x n_cols]

Returns

• paradigm_conf (list) – Array with the paradigm configuration for an RCP paradigm

• commands_info (list) – Flattened version of commands_info input. It contains the command information corresponding to paradigm_conf. If input parameter commands_info is None, this output will be a skeleton with an empty dict for each command. If input commands_info is provided, it will be incorporated in the output

References

[1] Farwell, L. A., & Donchin, E. (1988). Talking off the top of your head: toward a mental prosthesis utilizing event-related brain potentials. Electroencephalography and clinical Neurophysiology, 70(6), 510-523.

to_serializable_obj()

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

class medusa.bci.erp_spellers.ERPSpellerDataset

Bases: Dataset

This class inherits from medusa.data_structures.Dataset, increasing its functionality for datasets with data from ERP-based spellers. It provides common ground for the rest of functions in the module.

__init__(channel_set, fs=None, biosignal_att_key='eeg', experiment_att_key='erpspellerdata', experiment_mode=None, track_attributes=None)

Constructor

Parameters

• channel_set (meeg.EEGChannelSet) – EEG channel set. Only these channels will be kept in the dataset, the others will be discarded. Also, the signals will be rearranged, keeping the same channel order, avoiding errors in future stages of the signal processing pipeline

• fs (int, float or None) – Sample rate of the recordings. If there are recordings with different sample rates, the consistency of the dataset can be still assured using resampling

• biosignal_att_key (str) – Name of the attribute containing the target biosginal that will be used to extract the features. It has to be the same in all recordings (e.g., ‘eeg’, ‘meg’).

• experiment_att_key (str or None) – Name of the attribute containing the target experiment that will be used to extract the features. It has to be the same in all recordings (e.g., ‘rcp_data’, ‘cake_paradigm_data’). It is mandatory when a recording of the dataset contains more than 1 experiment data

• experiment_mode (str {‘train’|’test’|None}) – Mode of the experiment. If this dataset will be used to fit a model, set to train to avoid errors

• track_attributes (dict of dicts or None) –

  This parameter indicates custom attributes that must be tracked in feature extraction functions and how. The keys are the name of the attributes, whereas the values are dicts indicating the tracking mode {‘concatenate’|’append’} and parent. Option concatenate is only available for attributes of type list or numpy arrays, forming a 1 dimensional array with the data from all recordings. Option append is used to save all kind of objects for each recording, forming a list whose length will be the number of recordings in the dataset. A set of default attributes is defined, so this parameter will be None in most cases. Example to track 2 custom attributes (i.e., date and experiment_equipment):

  track_attributes = {

  ‘date’: {

  ‘track_mode’: ‘append’, ‘parent’: None

  }, ‘experiment_equipment’: {

  ’track_mode’: ‘append’, ‘parent’: experiment_att_key

  }

  }

custom_operations_on_recordings(recording)

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.bci.erp_spellers.ERPSpellerModel

Bases: Algorithm

Skeleton class for ERP-based spellers models. This class inherits from components.Algorithm. Therefore, it can be used to create standalone algorithms that can be used in compatible apps from medusa-platform for online experiments. See components.Algorithm to know more about this functionality.

Related tutorials:

• Overview of erp_spellers module [LINK]

• Create standalone models for ERP-based spellers compatible with

  Medusa platform [LINK]

__init__()

Class constructor

abstract build(*args, **kwargs)

This function builds the model, adding all the processing methods to the pipeline. It must be called after configure.

static check_for_non_control_data(cs_labels, cs_target, throw_warning=True)

Checks the data for non-control trials.

Returns

check – True if there is non-control trials in the data, False otherwise.

Return type

bool

abstract configure(**kwargs)

This function must be used to configure the model before calling build method. Class attribute settings attribute must be set with a dict

fit_dataset(dataset, **kwargs)

Function that receives an ERPSpellerDataset and uses its data to fit the model. By default, executes pipeline ‘fit_dataset’. Override method for other behaviour.

Parameters

• dataset (ERPSpellerDataset) – Dataset with recordings from an ERP-based speller experiment

• kwargs (key-value arguments) – Optional parameters depending on the specific implementation of the model

Returns

fit_results – Dict with the information of the fot process. For command decoding models, at least it has to contain keys spell_result, spell_result_per_seq and spell_acc_per_seq, which contain the decoded commands, the decoded commands and the command decoding accuracy per sequences of stimulation considered in the analysis.

Return type

dict

static get_control_data(x, x_info)

Selects only the control trials in the dataset. Useful to fit command decoding models.

predict(times, signal, fs, l_cha, x_info, **kwargs)

Function that receives EEG signal and experiment info from an ERP-based speller to decode the user’s intentions. Used in online experiments. By default, executes pipeline ‘predict’. Override method for other behaviour.

Parameters

• times (list or numpy.ndarray) – Timestamps of the EEG samples

• signal (list or numpy.ndarray) – EEG samples with shape [n_samples x n_channels]

• fs (float) – Sample rate of the EEG signal

• l_cha (list) – List of channel labels

• x_info (dict) – Dict with the needed experiment info to decode the commands. It has to contain keys: paradigm_conf, onsets, batch_idx, group_idx, unit_idx, level_idx, matrix_idx, sequence_idx, trial_idx, run_idx. See ERPSpellerData to know how are defined these variables.

• kwargs (key-value arguments) – Optional parameters depending on the specific implementation of the model

class medusa.bci.erp_spellers.StandardFeatureExtraction

Bases: ProcessingMethod

Standard feature extraction method for ERP-based spellers. Basically, it gets the raw epoch for each stimulation event.

__init__(w_epoch_t=(0, 1000), target_fs=20, w_baseline_t=(- 250, 0), norm='z', concatenate_channels=True, safe_copy=True)

Class constructor

w_epoch_tlist

Temporal window in ms for each epoch relative to the event onset (e.g., [0, 1000])

target_fsfloat of None

Target sample rate of each epoch. If None, all the recordings must have the same sample rate, so it is strongly recommended to set this parameter to a suitable value to avoid problems and save time

w_baseline_tlist

Temporal window in ms to be used for baseline normalization for each epoch relative to the event onset (e.g., [-250, 0])

normstr {‘z’|’dc’}

Type of baseline normalization. Set to ‘z’ for Z-score normalization or ‘dc’ for DC normalization

concatenate_channelsbool

This parameter controls the shape of the feature array. If True, all channels will be concatenated, returning an array of shape [n_events x (samples x channels)]. If false, the array will have shape [n_events x samples x channels]

safe_copybool

Makes a safe copy of the signal to avoid changing the original samples due to references

transform_dataset(dataset, show_progress_bar=True)

High level function to easily extract features from EEG recordings and save useful info for later processing. Nevertheless, the provided functionality has several limitations and it will not be suitable for all cases and processing pipelines. If it does not fit your needs, create a custom function iterating the recordings and using extract_erp_features, a much more low-level and general function. This function does not apply any preprocessing to the signals, this must be done before

Parameters

• dataset (ERPSpellerDataset) – List of data_structures.Recordings or data_structures.Dataset. If this parameter is a list of recordings, the consistency of the dataset will be checked. Otherwise, if the parameter is a dataset, this function assumes that the consistency is already checked

• show_progress_bar (bool) – Show progress bar

Returns

• features (numpy.ndarray) – Array with the biosignal samples arranged in epochs

• track_info (dict) – Dictionary with tracked information across all recordings

transform_signal(times, signal, fs, onsets)

Function to extract ERP features from raw signal. It returns a 3D

feature array with shape [n_events x n_samples x n_channels]. This function does not track any other attributes. Use for online processing and custom higher level functions.

timeslist 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

signallist or numpy.ndarray

2D numpy array [n_samples x n_channels]. EEG samples (the units should be defined using kwargs)

fsint or float

Sample rate of the recording.

onsetslist or numpy.ndarray [n_events x 1]

Timestamp of each event

featuresnp.ndarray [n_events x n_samples x n_channels]

Feature array with the epochs of signal

class medusa.bci.erp_spellers.StandardPreprocessing

Bases: ProcessingMethod

Just the common preprocessing applied in ERP-based spellers. Simple, quick and effective: frequency IIR filter followed by common average reference (CAR) spatial filter.

__init__(order=5, cutoff=(0.5, 10), btype='bandpass', filt_method='sosfiltfilt')

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(fs, n_cha=None)

Fits the IIR filter.

Parameters

• fs (float) – Sample rate of the signal.

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

fit_transform_dataset(dataset, show_progress_bar=True)

Fits the IIR filter and transforms an EEG signal applying the filter and CAR sequentially. Each recording is preprocessed independently, taking into account possible differences in sample rate.

Parameters

• dataset (ERPSpellerDataset) – ERPSpellerDataset with the recordings to be preprocessed.

• show_progress_bar (bool) – Show progress bar

fit_transform_signal(signal, fs)

Fits the IIR filter and transforms an EEG signal applying IIR filtering and CAR sequentially

Parameters

• signal (np.array or list) – Signal to transform. Shape [n_samples x n_channels]

• fs (float) – Sample rate of the signal.

transform_signal(signal)

Transforms an EEG signal applying IIR filtering and CAR sequentially

Parameters

signal (np.array or list) – Signal to transform. Shape [n_samples x n_channels]

medusa.bci.erp_spellers.command_decoding_accuracy(selected_commands, target_commands)

Computes the accuracy of the selected sequence of targets given the objective

Parameters

• selected_commands (list) – Target commands. Each position contains the matrix index and command id per level that identifies the selected command of the trial. Shape [n_runs x n_trials x n_levels x 2]

• target_commands (list) – Target commands. Each position contains the matrix index and command id per level that identifies the target command of the trial. Shape [n_runs x n_trials x n_levels x 2]

Returns

accuracy – Accuracy of the command decoding stage

Return type

float

medusa.bci.erp_spellers.command_decoding_accuracy_per_seq(selected_commands_per_seq, target_commands)

Computes the accuracy of the selected sequence of targets given the target

Parameters

• selected_commands_per_seq (list) – List with the spell result per sequence as given by function decode_commands. Shape [n_runs x n_trials x n_levels x n_sequences x 2]

• target_commands (list) – Target commands. Each position contains the matrix index and command id per level that identifies the target command of the trial. Shape [n_runs x n_trials x n_levels x 2]

Returns

acc_per_seq – Accuracy of the command decoding stage for each number of sequences considered in the analysis. Shape [n_sequences]

Return type

float

medusa.bci.erp_spellers.control_state_detection_accuracy(selected_control_state, target_control_state)

Computes the accuracy of the selected control states given the target

Parameters

• selected_control_state (list) – Target commands. Each position contains the matrix index and command id per level that identifies the selected command of the trial. Shape [n_runs x n_trials]

• target_control_state (list) – Target control state. Each position contains the control state of the trial. Shape [n_runs x n_trials]

Returns

accuracy – Accuracy of the command decoding stage

Return type

float

medusa.bci.erp_spellers.control_state_detection_accuracy_per_seq(selected_control_state_per_seq, target_control_state)

Returns the accuracy of the selected sequence of predicted control states given the target.

Parameters

• selected_control_state_per_seq (list) – List with the control state detection result per sequence as given by function detect_control_state. Shape [n_runs x n_trials x n_sequences]

• target_control_state (list) – Numpy array with dimensions [n_runs x n_trials] with the real control state of each trial

Returns

acc_per_seq – Accuracy of the control state detection stage

Return type

float

medusa.bci.erp_spellers.decode_commands(scores, paradigm_conf, run_idx, trial_idx, matrix_idx, level_idx, unit_idx, sequence_idx, group_idx, batch_idx)

Command decoder for ERP-based spellers.

Parameters

• scores (list or np.ndarray) – Array with the score for each stimulation

• paradigm_conf (list or np.ndarray) – Array containing the unified speller matrix structure with shape [n_runs x n_matrices x n_units x n_groups x n_batches x n_commands/batch]. All ERP-based speller paradigms can be adapted to this format and use this function for command decoding. See ERPSpellerData class for more info.

• run_idx (list or numpy.ndarray [n_stim x 1]) – Index of the run for each stimulation. This variable is automatically retrieved by function extract_erp_features_from_dataset as part of the track info dict. The run indexes must be related to paradigm_conf, keeping the same order. Therefore paradigm_conf[np.unique(run_idx)[0]] must retrieve the paradigm configuration of run 0.

• trial_idx (list or numpy.ndarray [n_stim x 1]) – Index of the trial for each stimulation. A trial represents the selection of a final command. Depending on the number of levels, the final selection takes N intermediate selections.

• matrix_idx (list or numpy.ndarray [n_stim x 1]) – Index of the matrix used in each stimulation. Each matrix can contain several levels. The matrix has to be the same accross the entire trial.

• level_idx (list or numpy.ndarray [n_stim x 1]) – Index of the level of each stimulation. Levels represent each one of the selections that must be made before a trial is finished. For example, in the Hex-O-spell paradigm there are 2 levels (see [1]).

• unit_idx (list or numpy.ndarray [n_stim x 1]) – Index of the unit used in each stimulation. Units are low level entities used in multi-level paradigms, such as HOS paradigm [1]. For each level, only 1 unit can be used. As the trial may have several layers, several units can be used in 1 trial. For instance, in the HOS, there are 7 units. The first unit is the main menu. The other 6 units are each of the lower level entities that are displayed in the second level of stimulation.

• sequence_idx (list or numpy.ndarray [n_stim x 1]) – Index of the sequence for each stimulation. A sequence represents a round of stimulation: all commands have been highlighted 1 time. This class support dynamic stopping in different levels.

• group_idx (list or numpy.ndarray [n_stim x 1]) – Index of the group that has been highlighted. Groups represent the different aggregations of batches. Between batches of different groups, 1 command must be common. For example in the RCP there are 2 groups: rows and columns. In this paradigm, between each pair of batches (e.g., row=2, col=4), there is only one command in common.

• batch_idx (list or numpy.ndarray [n_stim x 1]) – Index of the code of the highlighted batch for each stimulation. A batch represents the highlighted commands in each stimulation. For example in the row-col paradigm (RCP) represents each row and column.

Returns

• selected_commands (list) – Selected command for each trial considering all sequences of stimulation. Each command is organized in an array [matrix_idx, command_id]. Take into account that the command ids are unique for each matrix, and therefore only the command of the last level should be useful to take action. Shape [n_runs x n_trials x n_levels x 2]

• selected_commands_per_seq (list) – Selected command for each trial and sequence of stimulation. The fourth dimension of the array contains [matrix_idx, command_id]. To calculate the command for each sequence, it takes into account the scores of all the previous sequences as well. Shape [n_runs x n_trials x n_levels x n_sequences x 2]

• scores (list) – Scores for each command per sequence. Shape [n_runs x n_trials x n_levels x n_sequences x n_commands x 1]. The score of each sequence is calculated independently of the previous sequences.

medusa.bci.erp_spellers.detect_control_state(scores, run_idx, trial_idx, sequence_idx)

Detects the user’s control state for each trial, assigning 0 to non-control and 1 to control states.

Parameters

• scores (list or np.ndarray) – Array with the score per stimulation.

• run_idx (list or numpy.ndarray [n_stim x 1]) – Index of the run for each stimulation.

• trial_idx (list or numpy.ndarray [n_stim x 1]) – Index of the trial for each stimulation. A trial represents the selection of a final command. Depending on the number of levels, the final selection takes N intermediate selections.

• sequence_idx (list or numpy.ndarray [n_stim x 1]) – Index of the sequence for each stimulation. A sequence represents a round of stimulation: all commands have been highlighted 1 time. This class support dynamic stopping in different levels.

Returns

• selected_control_state (list) – Selected control state for each trial considering all sequences of stimulation. Shape [n_runs x n_trials]

• selected_control_state_per_seq (list) – Selected command for each trial and sequence of stimulation. The fourth dimension of the array contains [matrix_idx, command_id]. To calculate the command for each sequence, it takes into account the scores of all the previous sequences as well. Shape [n_runs x n_trials x n_sequences]

• scores (list) – Scores for each command per sequence. Shape [n_runs x n_trials x n_levels x n_sequences]. The score of each sequence is calculated independently of the previous sequences.

medusa.bci.erp_spellers.get_selected_commands_info(selected_commands, commands_info)

Returns the info dict of the selected commands

Parameters

• selected_commands (list) – Selected command for each trial. Each command is organized in an array [matrix_idx, command_id]. Take into account that the command ids are unique for each matrix, and therefore only the command of the last level should be useful to take action. Shape [n_runs x n_trials x n_levels x 2]

• commands_info (list) – List containing the command information per run and matrix. Each position must be a dict, whose keys are the commands ids used in paradigm_conf. The value must be another dict containing important information about each command (e.g., label, text, action, icon path, etc). This information may be different for different use cases, but must be serializable (i.e., contain primitive types). Shape [n_runs x n_matrices x n_commands]

Returns

selected_commands_info – List containing the information dict of the selected commands

Return type

list

medusa.bci.erp_spellers.split_erp_features(sets_pct, trial_idx_key='trial_idx', **kwargs)

This function splits randomly an ERP dataset keeping the relation between epochs and trials, which enables a later analysis of command prediction.

Parameters

• sets_pct (list) – List containing the percentage of for each set. For example, sets_pct=[60, 20, 20] will split the dataset in three sets, one that contains 60% of the trials, and two that contains 20% each.

• trial_idx_key (string) – Sets the trial_track_key, which is a vector that keeps the relation between trials and stimulus.

• kwargs (key-value arguments) – Variables to split.

Returns

variables – List of the sets containing a dict with the split variables

Return type

list

medusa.bci.metrics module

medusa.bci.metrics.itr(accuracy, n_commands, selections_per_min)

Calculates the information transfer rate (ITR) in bits/min. This metric is widely used to assess the performance of a BCI. However, it has serious limitations for online systems: (i) it assumes that the probability of selecting all symbols is the same; (ii) the system is memoryless; (iii) a synchronous paradigm is used; (iv) users cannot correct mistakes.

Parameters

• accuracy (float or list of floats) – Accuracy of the system (between 0 and 1).

• n_commands (int) – Number of possible commands to be selected.

• selections_per_min (float) – Number of selections that have been performed in a minute.

Returns

itr – ITR corresponding to each accuracy in bits per min (bpm).

Return type

float or list of floats

medusa.bci.mi_paradigms module

In this module you will find useful functions and classes to operate with data recorded using motor imagery paradigms, which are widely used by the BCI community. Enjoy!

@author: Sergio Pérez-Velasco & Víctor Martínez-Cagigal

class medusa.bci.mi_paradigms.CSPFeatureExtraction

Bases: ProcessingMethod

Common Spatial Patterns (CSP) feature extraction method for MI-based spellers.

Processing pipeline: - Use of StandardFeatureExtraction to get the raw epoch of each MI event. - Extract CSP features of those MI events. - Log-var features

__init__(n_filters=4, safe_copy=True, normalize_log_vars=True, **kwargs)

Class constructor.

n_filtersint 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 None, all filters will be used.

safe_copybool

Makes a safe copy of the signal to avoid changing the original samples due to references

normalize_log_varsbool

If true, log-var features are normalized.

**kwargsdict()

Parameters from StandardFeatureExtraction are not detailed here. Please refer to the StandardFeatureExtraction documentation to know more, as they are passed through kwargs.

After using the function self.fit(), the attributes are computed:

CSP

methods fit and project.

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

Mixing matrix (spatial filters are stored in columns).

eigenvalues(…, M) numpy.ndarray

Eigenvalues of w.

patternsnumpy.ndarray

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

Type

CSP class with attributes filters, eigenvalues, patterns and

fit_dataset(dataset, show_progress_bar=True, **kwargs)

fit_signal(labels, times, signal, fs, onsets, **kwargs)

fit_transform_dataset(dataset, show_progress_bar=True, **kwargs)

fit_transform_signal(labels, times, signal, fs, onsets, **kwargs)

transform_dataset(dataset, show_progress_bar=True, **kwargs)

transform_signal(times, signal, fs, onsets, **kwargs)

class medusa.bci.mi_paradigms.MIData

Bases: ExperimentData

Class with the necessary attributes to define motor imagery (MI) experiments. It provides compatibility with high-level functions for this MI paradigms in BCI module.

__init__(mode, onsets, w_trial_t, calibration_onset_w=None, w_preparation_t=None, w_rest_t=None, mi_labels=None, mi_labels_info=None, mi_result=None, paradigm_info=None, **kwargs)

MIData constructor

Parameters

• mode (str {"train"|"test"|"guided test"}) – Mode of this run.

• onsets (list or numpy.ndarray [n_stim x 1]) – Timestamp of the cue with respect to the EEG signal (just when the motor imagery starts).

• w_trial_t (list [start, end]) – Temporal window of the motor imagery with respect to each onset in ms. For example, if w_trial_t = [500, 4000] the subject was performing the motor imagery task from 500ms to 4000ms after the onset.

• calibration_onset_w (list [start, end]) – Timestamps of the onsets regarding the calibration window, if exists, respect to the EEG signal.

• w_preparation_t (list [start, end]) – Temporal window of the preparation time (no motor imagery), if exists, with respect to each onset in ms.

• w_rest_t (list [start, end]) – Temporal window of the rest time (no motor imagery), if exists, with respect to each onset in ms.

• mi_labels (list or numpy.ndarray [n_mi_labels x 1]) – Only in train mode. Contains the mi labels of each stimulation, as many as classes in the experiment.

• mi_labels_info (dict) –

  Contains the description of the mi labels. Example:

  mi_labels_info =

  {0: “Rest”, 1: “Left_hand”, 2: “Right_hand”}

• mi_result (list or numpy.ndarray [n_mi_labels x 1]) – Result of this run. Each position contains the data of the selected target at each trial.

• paradigm_info (dict()) – Recommended but not mandatory. Use this variable to keep the information regarding the different timings of the paradigm.

• kwargs (kwargs) – Custom arguments that will also be saved in the class (e.g., timings, calibration gaps, etc.)

classmethod from_serializable_obj(dict_data)

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

to_serializable_obj()

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

class medusa.bci.mi_paradigms.MIDataset

Bases: Dataset

This class inherits from medusa.data_structures.Dataset, increasing its functionality for datasets with data from MI experiments. It provides common ground for the rest of functions in the module.

__init__(channel_set, fs=None, biosignal_att_key='eeg', experiment_att_key='midata', experiment_mode=None, track_attributes=None)

Constructor

Parameters

• channel_set (meeg.EEGChannelSet) – EEG channel set. Only these channels will be kept in the dataset, the others will be discarded. Also, the signals will be rearranged, keeping the same channel order, avoiding errors in future stages of the signal processing pipeline

• fs (int, float or None) – Sample rate of the recordings. If there are recordings with different sample rates, the consistency of the dataset can be still assured using resampling

• biosignal_att_key (str) – Name of the attribute containing the target biosginal that will be used to extract the features. It has to be the same in all recordings (e.g., ‘eeg’, ‘meg’).

• experiment_att_key (str or None) – Name of the attribute containing the target experiment that will be used to extract the features. It has to be the same in all recordings (e.g., ‘mi_left_right’, ‘rest_mi’). It is mandatory when a recording of the dataset contains more than 1 experiment data

• experiment_mode (str {‘train’|’test’|’guided test’|None}) – Mode of the experiment. If this dataset will be used to fit a model, set to train to avoid errors

• track_attributes (dict of dicts or None) –

  This parameter indicates custom attributes that must be tracked in feature extraction functions and how. The keys are the name of the attributes, whereas the values are dicts indicating the tracking mode {‘concatenate’|’append’} and parent. Option concatenate is only available for attributes of type list or numpy arrays, forming a 1 dimensional array with the data from all recordings. Option append is used to save all kind of objects for each recording, forming a list whose length will be the number of recordings in the dataset. A set of default attributes is defined, so this parameter will be None in most cases. Example to track 2 custom attributes (i.e., date and experiment_equipment):

  track_attributes = {

  ‘date’: {

  ‘track_mode’: ‘append’, ‘parent’: None

  }, ‘experiment_equipment’: {

  ’track_mode’: ‘append’, ‘parent’: experiment_att_key

  }

  }

custom_operations_on_recordings(recording)

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.bci.mi_paradigms.MIModel

Bases: Algorithm

Skeleton class for MI-based BCIs models. This class inherits from components.Algorithm. Therefore, it can be used to create standalone algorithms that can be used in compatible apps from medusa-platform for online experiments. See components.Algorithm to know more about this functionality.

Related tutorials:

• Overview of mi_paradigms module [LINK]

• Create standalone models for MI-based BCIs compatible with

  Medusa platform [LINK]

__init__()

Class constructor

abstract build(*args, **kwargs)

This function builds the model, adding all the processing methods to the pipeline. It must be called after configure.

abstract configure(**kwargs)

This function must be used to configure the model before calling build method. Class attribute settings attribute must be set with a dict

fit_dataset(dataset, **kwargs)

Function that receives an MIDataset and uses its data to fit the model. By default, executes pipeline ‘fit_dataset’. Override method for other behaviour.

Parameters

• dataset (MIDataset) – Dataset with recordings from an MI-based BCI experiment

• kwargs (key-value arguments) – Optional parameters depending on the specific implementation of the model

Returns

fit_results – Dict with the information of the fit process. For command decoding models, at least it has to contain keys mi_target, mi_result and accuracy, which contain the target MI, the decoded MI and the decoding accuracy in the analysis.

Return type

dict

predict(times, signal, fs, l_cha, x_info, **kwargs)

Function that receives EEG signal and experiment info from an MI-based trial to decode the user’s intentions. Used in online experiments. By default, executes pipeline ‘predict’. Override method for other behaviour.

Parameters

• times (list or numpy.ndarray) – Timestamps of the EEG samples

• signal (list or numpy.ndarray) – EEG samples with shape [n_samples x n_channels]

• fs (float) – Sample rate of the EEG signal

• l_cha (list) – List of channel labels

• x_info (dict) – Dict with the needed experiment info to decode the commands. It has to contain keys: mode, onsets, w_trial_t. See MIData to know how are defined these variables.

• kwargs (key-value arguments) – Optional parameters depending on the specific implementation of the model

class medusa.bci.mi_paradigms.MIModelCSP

Bases: MIModel

Decoding model for MI-based BCI applications based on Common Spatial Patterns (CSP).

It is strongly recommended to update the default settings by passing arguments through **kwargs. See the different algorithms to know more about the possible parameters: StandardPreprocessing, CSPFeatureExtraction and StandardFeatureExtraction.

Dataset features: - Sample rate of the signals > 60 Hz. The model can handle recordings

with different sample rates.

• Recommended channels to be present: [‘C3’, ‘C4’].

Processing pipeline: - Preprocessing (medusa.bci.erp_spellers.StandardPreprocessing):

• IIR Filter (order=5, cutoff=(8, 30) Hz: unlike FIR filters, IIR

  filters are quick and can be applied in small signal chunks. Thus, they are the preferred method for frequency filter in online systems.

• Common average reference (CAR): widely used spatial filter that

  increases the signal-to-noise ratio of the MI control signals.

• Feature extraction (medusa.bci.mi_paradigms.CSPFeatureExtraction):

  • Epochs (window=(0, 2000) ms, resampling to 60 HZ): the epochs of

    signal are extracted for each stimulation. Baseline normalization is also applied, taking the window (-1000, 0) ms relative to the stimulus onset.

  • CSP projection: Epochs are then projected according to a CSP filter

    previously trained.

  • Log variance: Log variance features are extracted from the CSP

    projection.

• Feature classification (

sklearn.discriminant_analysis.LinearDiscriminantAnalysis)

• Regularized linear discriminant analysis (rLDA): we use the sklearn

  implementation, with eigen solver and auto shrinkage paramers. See reference in sklearn doc.

__init__()

Class constructor

build()

Initializes the different methods that comprise the MIModelCSP pipeline.

configure(p_filt_cutoff=(8, 30), w_epoch_t=(0, 2000), w_baseline_t=(- 1000, 0), target_fs=60, **kwargs)

Configures the default settings.

fit_dataset(dataset, get_training_accuracy=True, k_fold=5, **kwargs)

Function to fit a dataset using MIModelCSP.

Parameters

• dataset (MIDataset) – MI dataset used for training.

• get_training_accuracy (bool) – Whether to perform an estimation on training accuracy after fitting.

• k_fold (int) – Number of k-folds used in the k-fold cross-validation procedure to estimate the training accuracy.

• **kwargs (dict) – These parameters will be overwritten over self.settings.

Returns

assessment – Dictionary containing the details of the training accuracy estimation.

Return type

dict

predict(times, signal, fs, channel_set, x_info, **kwargs)

Function to predict an individual signal in MIModelCSP.

Parameters

• times (ndarray (n_samples,)) – Timestamp array

• signal (ndarray (n_samples x n_channels)) – Signal data.

• fs (int) – Sampling frequency.

• channel_set (EEGChannelSet or similar) – Channel montage.

• x_info (dict) – Dictionary containing the trial “onsets” and “mi_labels”. If the latter is not specified, accuracy is not calculated.

• **kwargs (dict) – These parameters will be overwritten over self.settings.

Returns

decoding – Dictionary containing the decoding.

Return type

dict

predict_dataset(dataset, **kwargs)

Function to predict a dataset using MIModelCSP.

Parameters

• dataset (MIDataset) – Test dataset.

• **kwargs (dict) – These parameters will be overwritten over self.settings.

Returns

decoding – Dictionary containing the decoding.

Return type

dict

class medusa.bci.mi_paradigms.MIModelEEGSym

Bases: MIModel

Decoding model for MI-based BCI applications based on EEGSym [1], a deep convolutional neural network developed for inter-subjects MI classification.

Dataset features:

• Sample rate of the signals > 128 Hz. The model can handle recordings

  with different sample rates.

• Recommended channels: [‘F7’, ‘C3’, ‘Po3’, ‘Cz’, ‘Pz’, ‘F8’, ‘C4’, ‘Po4’].

Processing pipeline:

• Preprocessing:

  • IIR Filter (order=4, lowpass=49 Hz: unlike FIR filters, IIR filters

    are quick and can be applied in small signal chunks. Thus, they are the preferred method for frequency filter in online systems

  • Common average reference (CAR): widely used spatial filter that

    increases the signal-to-noise ratio.

• Feature extraction:

  • Epochs (window=(0, 2000) ms, resampling to 128 HZ): the epochs of

    signal are extracted after each onset. Baseline normalization is also applied, taking the same epoch window.

• Feature classification

  • EEGSym: convolutional neural network [1].

References

[1] Pérez-Velasco, S., Santamaría-Vázquez, E., Martínez-Cagigal, V., Marcos-Mateo, D., & Hornero, R. (2020). EEGSym: Overcoming Intersubject Variability in Motor Imagery Based BCIs with Deep Learning. ?.

__init__()

Class constructor

build()

This function builds the model, adding all the processing methods to the pipeline. It must be called after configure.

configure(cnn_n_cha=8, ch_lateral=3, fine_tuning=False, shuffle_before_fit=True, validation_split=0.4, init_weights_path=None, gpu_acceleration=False, augmentation=False)

This function must be used to configure the model before calling build method. Class attribute settings attribute must be set with a dict

fit_dataset(dataset, continuous=False, **kwargs)

Function that receives an MIDataset and uses its data to fit the model. By default, executes pipeline ‘fit_dataset’. Override method for other behaviour.

Parameters

• dataset (MIDataset) – Dataset with recordings from an MI-based BCI experiment

• kwargs (key-value arguments) – Optional parameters depending on the specific implementation of the model

Returns

fit_results – Dict with the information of the fit process. For command decoding models, at least it has to contain keys mi_target, mi_result and accuracy, which contain the target MI, the decoded MI and the decoding accuracy in the analysis.

Return type

dict

predict(times, signal, fs, channel_set, x_info, **kwargs)

Function that receives EEG signal and experiment info from an MI-based trial to decode the user’s intentions. Used in online experiments. By default, executes pipeline ‘predict’. Override method for other behaviour.

Parameters

• times (list or numpy.ndarray) – Timestamps of the EEG samples

• signal (list or numpy.ndarray) – EEG samples with shape [n_samples x n_channels]

• fs (float) – Sample rate of the EEG signal

• l_cha (list) – List of channel labels

• x_info (dict) – Dict with the needed experiment info to decode the commands. It has to contain keys: mode, onsets, w_trial_t. See MIData to know how are defined these variables.

• kwargs (key-value arguments) – Optional parameters depending on the specific implementation of the model

class medusa.bci.mi_paradigms.StandardFeatureExtraction

Bases: ProcessingMethod

Standard feature extraction method for MI-based spellers. Basically, it gets the raw epoch for each MI event.

__init__(safe_copy=True)

Class constructor. All parameters except “safe_copy” must be specified in each method.

Parameters

safe_copy (bool) – Makes a safe copy of the signal to avoid changing the original samples due to references.

transform_dataset(dataset, show_progress_bar=True, w_epoch_t=(0, 3000), baseline_mode='trial', w_baseline_t=(- 1500, - 500), norm='z', target_fs=128, concatenate_channels=False, sliding_w_lims_t=None, sliding_t_step=None, sliding_win_len=None, **kwargs)

Method to extract epochs from an entire MIDataset

High level function to easily extract features from EEG recordings and save useful info for later processing. Nevertheless, the provided functionality has several limitations and it will not be suitable for all cases and processing pipelines. If it does not fit your needs, create a custom function iterating the recordings and using extract_erp_features, a much more low-level and general function. This function does not apply any preprocessing to the signals, this must be done before.

Most parameters are shared with StandardFeatureExtraction.transform_signal() method, check it for more information. Only the new parameters or those that behave differently than the aforementioned method are detailed below. These new parameters are related to a continuous extraction of epochs using a sliding window between a desired epoch range, instead of extracting only one epoch for each onset.

Parameters

• dataset (MIDataset) – MIDataset instance containing the MIData recordings.

• show_progress_bar (bool) – Boolean to show (or not) the progress bar info.

• sliding_w_lims_t (list, tuple, ndarray, or None) – 2D window that indicates the range (start, end) for the sliding window approach. If None, no sliding window would be applied. This parameter delimits the number of windows to be extracted for each onset, so none of them can fall outside the range (excluding baseline).

• sliding_t_step (int, None) – Step in samples that is used to separate the sliding windows. If None, no sliding window would be applied.

• sliding_win_len (int, None) – Length in samples of the sliding windows. Please note that the w_epoch_t parameter would not be used if the sliding window approach is used. If None, no sliding window would be applied.

• baseline_mode ({'run', 'trial', None, 'sliding'}) –

  The baseline_mode has an additional feature when sliding window is used:

  • ”run”: common baseline extracted from the start of the run.

  • ”trial”: common baseline for the trial, i.e., all the windows

  that belongs to an onset; extracted relative to the onset. - None: no baseline. - “sliding”: baseline is applied to each sliding window, and it is relative to the start of each sliding window.

Returns

• features (numpy.ndarray) – Array with the biosignal samples arranged in epochs.

• track_info (dict) – Dictionary with tracked information across all recordings.

transform_signal(times, signal, fs, onsets, w_epoch_t=(0, 3000), baseline_mode='trial', w_baseline_t=(- 1500, - 500), norm='z', target_fs=128, concatenate_channels=False, **kwargs)

Method to extract epochs from an individual signal.

Parameters

• times (ndarray (n_samples,)) – Timestamp array

• signal (ndarray (n_samples x n_channels)) – Signal data.

• fs (int) – Sampling frequency.

• onsets (ndarray (n_trials,)) – Timestamps for the MI event onsets.

• w_epoch_t (list, tuple, or ndarray) – Temporal window in ms for each epoch relative to the event onset (e.g., [0, 3000])

• baseline_mode (basestring {'run', 'trial', None}) – If “run”, the baseline will be extracted from the very beginning of the run (i.e., the first samples of the signal). If “trial” (default), the baseline will be extracted for each trial relative to the onset. If None, no baseline extraction will be performed.

• w_baseline_t (list, tuple, or ndarray) – Temporal window in ms to be used for baseline normalization. If baseline_mode = “run”, the window is relative to the start of the signal. If baseline_mode = “trial”, the window is relative to each trial onset (e.g., [-1500, -500]).

• norm (str {'z'|'dc'}) – Type of baseline normalization. Set to ‘z’ for Z-score normalization (subtract the mean and divide by the std), or ‘dc’ for DC normalization (subtract the mean).

• target_fs (float of None) – Target sample rate of each epoch. If None, no resampling will be applied. Please note that, in this case, all the recordings must have the same sample rate.

• concatenate_channels (bool) – This parameter controls the shape of the feature array. If True, all channels will be concatenated, returning an array of shape [n_events x (samples x channels)]. If false, the array will have shape [n_events x samples x channels].

Returns

features – MI epochs extracted with shape [n_events x samples x channels], or [n_events x (samples x channels)] if concatenate_channels == True.

Return type

ndarray

class medusa.bci.mi_paradigms.StandardPreprocessing

Bases: ProcessingMethod

Just the common preprocessing applied in MI-based BCI. Simple, quick and effective: frequency IIR filter followed by common average reference (CAR) spatial filter.

__init__(order=5, cutoff=[8, 30], btype='bandpass', temp_filt_method='sosfiltfilt')

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(fs, n_cha=None)

Fits the IIR filter.

Parameters

• fs (float) – Sample rate of the signal.

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

fit_transform_dataset(dataset, show_progress_bar=True)

Fits the IIR filter and transforms an EEG signal applying the filter and CAR sequentially. Each recording is preprocessed independently, taking into account possible differences in sample rate.

Parameters

• dataset (MIDataset) – MIDataset with the recordings to be preprocessed.

• show_progress_bar (bool) – Show progress bar

fit_transform_signal(signal, fs)

Fits the IIR filter and transforms an EEG signal applying IIR filtering and CAR sequentially

Parameters

• signal (np.array or list) – Signal to transform. Shape [n_samples x n_channels]

• fs (float) – Sample rate of the signal.

transform_dataset(dataset, show_progress_bar=True, **kwargs)

Transforms an MIDataset applying IIR filtering and CAR sequentially

Parameters

• signal (np.array or list) – Signal to transform. Shape [n_samples x n_channels]

• dataset (MIDataset) –

transform_signal(signal)

Transforms an EEG signal applying IIR filtering and CAR sequentially

Parameters

signal (np.array or list) – Signal to transform. Shape [n_samples x n_channels]

medusa.bci.nft_paradigms module

In this module you will find useful functions and classes to apply on-line Neurofeedback models. Each model is based on different features to be used as target to train. Enjoy!

@author: Diego Marcos-Martínez

class medusa.bci.nft_paradigms.ConnectivityBasedNFTModel

Bases: Algorithm

__init__(fs, filter_dict, l_baseline_t, update_feature_window, update_rate, montage, target_channels, fc_measure, mode, apply_car, pct_tol_ocular=None, pct_tol_muscular=None)

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.

calibration(eeg)

It pre-process eeg, gets signal filtered in artifact-related bands and filters the pre-processed eeg in training band. Then, it calculates the baseline value. :param eeg: [n_samples, n_channels] :type eeg: numpy.ndarray

Returns

baseline_value

Return type

float

check_cutoff_settings()

Function to check the correct definition of training band dictionary.

training(eeg)

It pre-process eeg, gets signal filtered in artifact-related bands and filters the pre-processed eeg in training band. Then, it calculates the feedback value. :param eeg: [n_samples, n_channels] :type eeg: numpy.ndarray

Returns

feedback_value

Return type

float

class medusa.bci.nft_paradigms.ConnectivityExtraction

Bases: ProcessingMethod

Functional Connectivity-based features to extract from user’s EEG.

__init__(l_baseline_t=5, fs=250, update_feature_window=2, update_rate=0.25, fc_measure=None, mode=None, montage=None, target_channels=None, pct_tol=0.9)

Class constructor

l_baseline_t: int

Time employed to calculate the number of samples to obtain baseline connectivity parameter. In seconds.

fs: int or float

Sample rate of the recording.

update_feature_window: int or float

Length in seconds of the temporal window applied to calculate the feature.

update_rate: int or float

Feedback update time in online mode.

fc_measure: str

“WPLI” or “AECORT”. Measure of Functional Connectivity to calculate.

mode: str

“Global coupling”, “Strength” or “Coupling”. Information extracted from adjacency matrix.

montage: EEGChannelSet target_channels: list or None

List containing the labels of the target channels.

pct_tol: numpy.ndarray Array containing variance increase (in percentage) tolerated.

calculate_adj_mat(signal)

This function calculates the adjacency matrix depending on the FC mode. :param signal: Signal filtered in the narrow band for training.

[n_epochs, n_samples, n_channels] or [n_samples, n_channels].

Returns

adj_mat – [n_epochs, n_channels, n_channels].

Return type

numpy.ndarray

calculate_feature(adj_mat)

Calculates Graph metric from adjacency matrix.

Parameters

adj_mat (numpy.ndarray) – [n_channels, n_channels].

ext_feature(signal, signal_artifacts)

Function for extracting FC values in online mode. :param signal: Signal filtered in the narrow band for training. [n_samples, n_channels]. :type signal: numpy.ndarray :param signal_artifacts: Array containing the signal filtered in each frequency band associated

to the artifacts to avoid. [n_artifact_bands, n_samples, n_channels].

Returns

c_value

Return type

float

mean_coupling(adj_mat)

This function calculates the connectivity values between all the

target channels and average it value.

Parameters

adj_mat (numpy.ndarray) – [n_channels, n_channels].

set_baseline(signal, signal_artifacts, filtered_signal)

This functions establish the baseline value. :param signal: Original signal pre-processed (offset and power-line removed, and CAR)

[n_samples, n_channels].

Parameters

• signal_artifacts (numpy.ndarray) – Array containing the signal filtered in each frequency band associated to the artifacts to avoid. [n_artifact_bands, n_samples, n_channels].

• filtered_signal (numpy.ndarray) – Signal filtered in the narrow band for training. [n_samples, n_channels].

Returns

baseline_value

Return type

float

class medusa.bci.nft_paradigms.NeurofeedbackData

Bases: ExperimentData

Experiment info class for Neurofeedback training experiments. It records the important events that take place during a Neurofeedback run, allowing offline analysis.

__init__(run_onsets, run_durations, run_success, run_pauses, run_restarts, medusa_nft_app_settings, nft_values, nft_times, nft_baseline)

classmethod from_serializable_obj(dict_data)

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

to_serializable_obj()

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

class medusa.bci.nft_paradigms.PowerBasedNFTModel

Bases: Algorithm

__init__(fs, filter_dict, l_baseline_t, update_feature_window, update_rate, montage, target_channels, mode, apply_car, apply_laplacian, pct_tol_ocular=None, pct_tol_muscular=None)

Pipeline for Power-based Neurofeedback training. This class inherits from components.Algorithm. Therefore, it can be used to create standalone algorithms that can be used in compatible apps from medusa-platform for online experiments. See components.Algorithm to know more about this functionality.

calibration(eeg, **kwargs)

It pre-process eeg and gets signal filtered in artifact-related bands. Then, it calculates the baseline value. :param eeg: [n_samples, n_channels] :type eeg: numpy.ndarray

Returns

baseline_value

Return type

float

check_cutoff_settings()

Function to check the correct definition of training band dictionary.

training(eeg)

It pre-process eeg, gets signal filtered in artifact-related bands. Then, it calculates the feedback value. :param eeg: [n_samples, n_channels] :type eeg: numpy.ndarray

Returns

feedback_value

Return type

float

class medusa.bci.nft_paradigms.PowerExtraction

Bases: ProcessingMethod

Power-based features to extract from user’s EEG.

__init__(l_baseline_t=5, fs=250, update_feature_window=2, update_rate=0.25, pct_tol=0.9, f_dict=None, mode=None)

Class constructor

l_baseline_t: int

Time employed to calculate the number of samples to obtain baseline power parameter. In seconds.

fs: int or float

Sample rate of the recording.

update_feature_window = int

Length in seconds of the temporal window applied to calculate the feature.

update_rate: int or float

Feedback update time in online mode.

f_dict: dict

Dict containing the frequency bands associated to training band and artifacts to avoid.

pct_tol: numpy.ndarray

Array containing variance increase (in percentage) tolerated.

mode: str

“single” or “ratio”

band_power(signal, signal_artifacts)

This function returns the band power from Power Spectral Density. If signal noise is above the pre-established thresholds, this function will return None.

Parameters

• signal (numpy.ndarray) – Signal pre-processed. [n_samples, n_channels].

• signal_artifacts (numpy.ndarray) – Signal filtered in the frequency bands associated to the artifacts to be avoided. [n_artifact_bands, n_samples, n_channels].

Returns

b_power

Return type

float or None

power(psd)

This function calculates power from Power Spectral Density :param psd: [n_epochs, n_samples, n_channels]. :type psd: numpy.ndarray

Returns

powers – [n_training_bands].

Return type

numpy.ndarray

set_baseline(signal, signal_artifacts)

This function sets the power baseline, given the already filtered EEG containing the calibration phase. Also, takes into account the Neurofeedback training mode, so performs different baseline calculations depending on the mode set.

Parameters

• signal (numpy.ndarray) – EEG already pre-processed. [n_samples, n_channels].

• signal_artifacts (numpy.ndarray) – Signal filtered in the frequency bands associated to the artifacts to be avoided. [n_artifact_bands, n_samples, n_channels].

Returns

baseline_power

Return type

float

class medusa.bci.nft_paradigms.SignalPreprocessing

Bases: ProcessingMethod

Common preprocessing applied in Neurofeedback applications. It is composed by a frequency IIR filter followed by a spatial filters. Functions are adapted to filter the signal in more than one frequency range, if necessary.

__init__(filter_dict=None, montage=None, target_channels=None, laplacian=False, car=False, n_cha_lp=None)

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(fs)

Fits the IIR filter and Laplacian spatial filter (if selected) for signal preprocessing stage.

Parameters

fs (float) – Sampling rate in Hz.

narrow_transform(signal, parallel_computing=True)

Applies the IIR filter for narrow band filtering.

Parameters

• signal (list or numpy.ndarray) – Signal to transform. Shape [n_samples x n_channels].

• parallel_computing (bool) – If true, it filters the signal concurrently.

Returns

signal – Signal filtered in the training band [n_samples, n_channels].

Return type

numpy.ndarray

prep_fit_transform(fs, signal)

Fits the IIR filter and transforms an EEG signal applying IIR filter and spatial filters sequentially.

Parameters

• fs (float) – Sampling rate in Hz.

• n_cha_lp (int) – Number of nearest channels to compute Laplacian spatial filter (Auto mode).

• signal (list or numpy.ndarray) – Signal to transform. Shape [n_samples x n_channels]

Returns

• signal (numpy.ndarray) – Original signal with power line and offset removed, and spatially filtered if chosen. [n_samples, n_channels].

• signal_artifacts (numpy.ndarray) – If it has been chosen to reject artifact sections, this matrix contains the filtered signal in the frequency bands associated with these artifacts. [n_artifact_bands, n_samples, n_channels].

prep_transform(signal, parallel_computing=True)

Transforms an EEG signal applying IIR filter. It also applies CAR and Laplacian spatial filter sequentially if desired.

Parameters

• signal (list or numpy.ndarray) – Signal to transform. Shape [n_samples x n_channels]

• parallel_computing (bool) – If true, it filters the signal concurrently

Returns

• signal_ (numpy.ndarray) – Original signal with power line and offset removed, and spatially filtered if chosen. [n_samples, n_channels].

• signal_artifacts (numpy.ndarray) – If it has been chosen to reject artifact sections, this matrix contains the filtered signal in the frequency bands associated with these artifacts. [n_artifact_bands, n_samples, n_channels].

medusa.bci.nft_paradigms.ignore_noisy_windows(signals, thresholds, pct_tol)

This function check if a specific signal segment contains noise above the pre-established thresholds. :param signals: Array containing the signal filtered in the frequency bands associated to

artifacts to avoid. [n_artifact_bands, n_samples, n_channels].

Parameters

• thresholds (numpy.ndarray) – Array containing the variance thresholds related to artifacts to avoid.

• pct_tol (numpy.ndarray) – Array containing variance increase (in percentage) tolerated.

medusa.bci.nft_paradigms.make_windows(signal, fs, update_feature_window, update_rate, n_cha=1, n_samp=2, k=4, reject=True)

Parameters

• signal (numpy.ndarray) – Signal to be converted into epochs. [n_samples, n_channels].

• fs (int or float) – Sampling rate.

• update_feature_window (int or float) – Time window taken for the calculation of the characteristic (in seconds).

• update_rate (int or float) – Feedback update time in online mode.

• n_cha (int) – Threshold number of channels meeting the rejection condition to reject the epoch.

• n_samp (int) – Threshold number of samples meeting the rejection condition to reject the epoch.

• k (int) – Standard deviation of the signal. Used in the definition of the rejection criterion.

• reject (bool) – If true, it returns the epochs that have not been reject. Else, it returns the whole windowed signal.

Returns

• good_epochs (numpy.ndarray) – Array containing the signal divided into epochs that are not noisy. [n_epochs, n_samples, n_channels].

• ind (numpy.ndarray) –

  Array containing bools. True for epochs that were rejected and False for

  epochs that were not.