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.BWRFeatureExtraction[source]

Bases: ProcessingMethod

Feature extraction method designed to extract event-wise epochs from c-VEP stimulation paradigms to perform bitwise reconstruction (BWR)

__init__(w_epoch_t=(0, 500), target_fs=20, w_baseline_t=(- 250, 0), norm='z', concatenate_channels=True, safe_copy=True)[source]

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

check_predict_feasibility_signal(times, cycle_onsets, fps, code_len, fs)[source]

static generate_bit_wise_onsets(cycle_onsets, frames_per_second, code_len)[source]

transform_dataset(dataset, show_progress_bar=True)[source]

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, cycle_onsets, fps, code_len)[source]

Function to extract VEP 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.

Parameters

times (list or numpy.ndarray) – 1D numpy array [n_samples]. Timestamps of each sample. If they are not available, generate them artificially. Nevertheless, all signals and events must have the same temporal origin
signal (list or numpy.ndarray) – 2D numpy array [n_samples x n_channels]. EEG samples (the units should be defined using kwargs)
fs (int or float) – Sample rate of the recording.
cycle_onsets (list or numpy.ndarray [n_cycles x 1]) – Timestamps indicating the start of each stimulation cycle
fps (int) – Frames per second of the screen that presents the stimulation
code_len (int) – Length of the c-VEP codes

Returns

features – Feature array with the epochs of signal

Return type

np.ndarray [n_events x n_samples x n_channels]

class medusa.bci.cvep_spellers.CMDModelBWREEGInception[source]

Bases: CVEPSpellerModel

Class that uses the bitwise reconstruction (BWR) paradigm with an EEG-Inception model

build()[source]: This function builds the model, adding all the processing methods to the pipeline. It must be called after configure.

check_predict_feasibility_signal(times, cycle_onsets, fps, code_len, fs)[source]

configure(bpf=(7, (1.0, 60.0)), notch=(7, (49.0, 51.0)), w_epoch_t=(0, 500), target_fs=200, n_cha=16, filters_per_branch=12, scales_time=(250, 125, 62.5), dropout_rate=0.15, activation='elu', n_classes=2, learning_rate=0.001, batch_size=256, max_training_epochs=500, validation_split=0.1, shuffle_before_fit=True)[source]: 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, show_progress_bar=False)[source]

predict(times, signal, fs, channel_set, x_info, **kwargs)[source]

predict_dataset(dataset, show_progress_bar=False)[source]

class medusa.bci.cvep_spellers.CMDModelBWRLDA[source]

Bases: CVEPSpellerModel

Class that uses the bitwise reconstruction (BWR) paradigm with an LDA classifier

build()[source]: This function builds the model, adding all the processing methods to the pipeline. It must be called after configure.

check_predict_feasibility_signal(times, cycle_onsets, fps, code_len, fs)[source]

configure(bpf=(7, (1.0, 60.0)), notch=(7, (49.0, 51.0)), w_epoch_t=(0, 500), target_fs=None)[source]: 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, show_progress_bar=False)[source]

predict(times, signal, fs, channel_set, x_info, **kwargs)[source]

predict_dataset(dataset, show_progress_bar=False)[source]

class medusa.bci.cvep_spellers.CVEPModelCircularShifting[source]

Bases: Algorithm

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

ProcessingMethod constructor

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

check_predict_feasibility(dataset)[source]

check_predict_feasibility_signal(times, onsets, fs)[source]

fit_dataset(dataset, roll_targets=False, **kwargs)[source]

must_stop(corr_vector, std=3.0)[source]

predict(times, signal, trial_idx, exp_data, sig_data)[source]

predict_dataset(dataset)[source]

class medusa.bci.cvep_spellers.CVEPSpellerData[source]

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, spell_result, fps_resolution, spell_target=None, raster_events=None, **kwargs)[source]

classmethod from_serializable_obj(dict_data)[source]: This function must return an instance of the class from a serializable dict (primitive types)

to_serializable_obj()[source]: This function must return a serializable dict (primitive types) containing the relevant attributes of the class

class medusa.bci.cvep_spellers.CVEPSpellerDataset[source]

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)[source]

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)[source]

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

Parameters: recording (subclass of Recording) – Recording that will be changed. It can also be a subclass of Recording
Returns: recording – Modified recording
Return type: Recording

class medusa.bci.cvep_spellers.CVEPSpellerModel[source]

Bases: Algorithm

__init__()[source]: Class constructor

abstract build(*args, **kwargs)[source]: This function builds the model, adding all the processing methods to the pipeline. It must be called after configure.

abstract configure(**kwargs)[source]: This function must be used to configure the model before calling build method. Class attribute settings attribute must be set with a dict

abstract fit_dataset(dataset, **kwargs)[source]

abstract predict(times, signal, fs, channel_set, x_info, **kwargs)[source]

abstract predict_dataset(dataset, **kwargs)[source]

class medusa.bci.cvep_spellers.CircularShiftingClassifier[source]

Bases: ProcessingMethod

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

__init__(correct_raster_latencies=False, art_rej=None, extra_epoch_samples=21, **kwargs)[source]: Class constructor

fit_dataset(dataset, roll_targets=False, show_progress_bar=True)[source]

Parameters: dataset (CVEPSpellerDataset) –

predict(times, signal, trial_idx, exp_data, sig_data)[source]

predict_dataset(dataset, show_progress_bar=True)[source]

Parameters: dataset (CVEPSpellerDataset) –

class medusa.bci.cvep_spellers.CircularShiftingEarlyStopping[source]

Bases: ProcessingMethod

__init__(**kwargs)[source]: Class constructor

check_early_stop(corr_vector, std=3.0)[source]

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[source]

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))[source]

ProcessingMethod constructor

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

fit(fs)[source]

Fits the IIR filters.

Parameters: fs (float) – Sample rate of the signal.

fit_transform_dataset(dataset, show_progress_bar=True)[source]

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 (CVEPSpellerDataset) – CVEPSpellerDataset with the recordings to be preprocessed.
show_progress_bar (bool) – Show progress bar

fit_transform_signal(signal, fs)[source]

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)[source]

Parameters: dataset (CVEPSpellerDataset) –

transform_signal(signal)[source]

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[source]

Bases: object

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

__init__(polynomial, base=2, seed=None, center=False)[source]: Constructor of LFSR

static lfsr(polynomial, base=2, seed=None, center=False)[source]

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[source]

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))[source]

ProcessingMethod constructor

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

fit(fs)[source]

Fits the IIR filters.

Parameters: fs (float) – Sample rate of the signal.

fit_transform_dataset(dataset, show_progress_bar=True)[source]

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 (CVEPSpellerDataset) – CVEPSpellerDataset with the recordings to be preprocessed.
show_progress_bar (bool) – Show progress bar

fit_transform_signal(signal, fs)[source]

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)[source]

Parameters: dataset (CVEPSpellerDataset) –

transform_signal(signal)[source]

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)[source]: With circular shifts (periodic correlation)

medusa.bci.cvep_spellers.autocorr_zeropad(x)[source]: With zero padding, equivalent to np.correlate()

medusa.bci.cvep_spellers.check_if_shifted(seq1, seq2)[source]

medusa.bci.cvep_spellers.command_decoding_accuracy_per_cycle(selected_commands_per_cycle, target_commands)[source]

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

Parameters

selected_commands_per_cycle (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_cycles 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_cycle – Accuracy of the command decoding stage for each number of cycles considered in the analysis. Shape [n_sequences]

Return type

float

medusa.bci.cvep_spellers.decode_commands_from_events(event_scores, commands_info, event_run_idx, event_trial_idx, event_cycle_idx)[source]

Command decoder for c-VEP-based spellers based on the bitwise reconstruction paradigm (BWR), i.e., models that predict the command sequence stimulus by stimulus.

ToDo: allow multi-matrix paradigms with different number of levels. See: module erp_based_spellers for reference.

Parameters

event_scores (list or np.ndarray) – Array with the score for each stimulation
commands_info (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.
event_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.
event_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.
event_cycle_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_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_cycle (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_cycles x 2]
cmd_scores_per_cycle – Scores for each command per cycle. Shape [n_runs x n_trials x n_levels x n_cycles x n_commands x 1]. The score of each cycle is calculated using all the previous cycles as well.

medusa.bci.cvep_spellers.get_items_by_sorted_sequences(experiment, trial_idx, sorted_seqs, sorted_corrs=None)[source]

Parameters: experiment (CVEPSpellerData) –

medusa.bci.cvep_spellers.get_unique_sequences_from_targets(experiment)[source]

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[source]

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__()[source]: Class constructor

build()[source]: 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)[source]: 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)[source]

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)[source]

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[source]

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__()[source]: Class constructor

build()[source]: 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)[source]: 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)[source]

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)[source]

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[source]

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__()[source]: Class constructor

build()[source]: 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)[source]: 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)[source]

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)[source]

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[source]

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__()[source]: Class constructor

build()[source]: 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)[source]: 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)[source]

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)[source]

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[source]

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)[source]

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()[source]: This function computes the control state label vector (0 -> non-control state, 1 -> control state).

compute_erp_labels()[source]: 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)[source]: This function must return an instance of the class from a serializable dict (primitive types)

get_batches_associated_to_cmd(matrix_idx, command_idx)[source]

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)[source]

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)[source]

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()[source]: This function must return a serializable dict (primitive types) containing the relevant attributes of the class

class medusa.bci.erp_spellers.ERPSpellerDataset[source]

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)[source]

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)[source]

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

Parameters: recording (subclass of Recording) – Recording that will be changed. It can also be a subclass of Recording
Returns: recording – Modified recording
Return type: Recording

class medusa.bci.erp_spellers.ERPSpellerModel[source]

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.

medusa.bci.metrics module

medusa.bci.metrics.itr(accuracy, n_commands, selections_per_min)[source]

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[source]

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)[source]

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)[source]

fit_signal(labels, times, signal, fs, onsets, **kwargs)[source]

fit_transform_dataset(dataset, show_progress_bar=True, **kwargs)[source]

fit_transform_signal(labels, times, signal, fs, onsets, **kwargs)[source]

transform_dataset(dataset, show_progress_bar=True, **kwargs)[source]

transform_signal(times, signal, fs, onsets, **kwargs)[source]

class medusa.bci.mi_paradigms.MIData[source]

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)[source]

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)[source]: This function must return an instance of the class from a serializable dict (primitive types)

to_serializable_obj()[source]: This function must return a serializable dict (primitive types) containing the relevant attributes of the class

class medusa.bci.mi_paradigms.MIDataset[source]

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)[source]

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)[source]

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

Parameters: recording (subclass of Recording) – Recording that will be changed. It can also be a subclass of Recording
Returns: recording – Modified recording
Return type: Recording

class medusa.bci.mi_paradigms.MIModel[source]

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.

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[source]

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)[source]

ProcessingMethod constructor

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

calibration(eeg)[source]

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()[source]: Function to check the correct definition of training band dictionary.

training(eeg)[source]

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[source]

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)[source]

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)[source]

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)[source]

Calculates Graph metric from adjacency matrix.

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

ext_feature(signal, signal_artifacts)[source]

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)[source]

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(filtered_signal, signal_artifacts)[source]

This functions establish the baseline value. :param filtered_signal: Signal filtered in the narrow band for training.

[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].
Returns: baseline_value
Return type: float

class medusa.bci.nft_paradigms.NeurofeedbackData[source]

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)[source]

classmethod from_serializable_obj(dict_data)[source]: This function must return an instance of the class from a serializable dict (primitive types)

to_serializable_obj()[source]: This function must return a serializable dict (primitive types) containing the relevant attributes of the class

class medusa.bci.nft_paradigms.PowerBasedNFTModel[source]

Bases: Algorithm

__init__(fs, filter_dict, l_baseline_t, update_feature_window, update_rate, montage, target_channels, mode, apply_car, apply_laplacian, right_ch_idx=None, pct_tol_ocular=None, pct_tol_muscular=None)[source]: 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)[source]

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()[source]: Function to check the correct definition of training band dictionary.

training(eeg)[source]

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[source]

Bases: ProcessingMethod

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

__init__(l_baseline_t=5, fs=250, update_feature_window=2, right_ch_idx=None, update_rate=0.25, pct_tol=0.9, f_dict=None, mode=None)[source]

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.
right_ch_idx: list (optional): List containng the indexes of the channels that will be used to predict right motor imagery. The indexes are relative to the target channels list. This argument is only necessary when using the neurofeedback-based motor imagery.
update_rate: float: Value of the real-time feedback calculation rate.
pct_tol: numpy.ndarray: Array containing variance increase (in percentage) tolerated.
mode: str: “single” or “ratio”

band_power(signal, signal_artifacts)[source]

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)[source]

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)[source]

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[source]

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)[source]

ProcessingMethod constructor

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

fit(fs)[source]

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)[source]

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)[source]

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)[source]

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)[source]

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)[source]

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.