neurol.models package

Submodules

neurol.models.classification_tools module

Module containing functions for performing classification, via machine learning models or otherwise, related to Brain-Computer Interface applications.

neurol.models.classification_tools.get_channels(signal, channels, device=None)

Returns a signal with only the desired channels.

Parameters:
  • signal (np.ndarray) – a signal of shape [n_samples, n_channels]
  • channels (array) – str names or int indices of the desired channels. returned in given order.
  • device (str) – name of the device. Optional.
Returns:

numpy array of signal with shape [n_channels, n_desired_channels]. Includes only the selected channels in the order given.
neurol.models.classification_tools.softmax_predict(input_, predictor, thresh=0.5)

Consolidates a softmax prediction to a one-hot encoded prediction.

Parameters:
  • input – the input taken by the predictor
  • predictor – function which returns a softmax prediction given an input_
  • thresh – the threshold for a positive prediction for a particular class.
neurol.models.classification_tools.encode_ohe_prediction(prediction)

Returns the index number of the positive class in a one-hot encoded prediction.

neurol.models.classification_tools.decode_prediction(prediction, decode_dict)

Returns a more intelligible reading of the prediction based on the given decode_dict

neurol.models.classification_tools.threshold_clf(features, threshold, clf_consolidator='any')

Classifies given features based on a given threshold.

Parameters:
  • features – an array of numerical features to classify
  • threshold – threshold for classification. A single number, or an array corresponding to features for element-wise comparison.
  • clf_consolidator –

    method of consolidating element-wise comparisons with threshold into a single classification.

    ’any’: positive class if any features passes the threshold ‘all’: positive class only if all features pass threshold ‘sum’: a count of the number of features which pass the threshold function: a custom function which takes in an array of booleans
    and returns a consolidated classification
Returns:

classification for the given features. Return type clf_consolidator.

neurol.models.data_exploration module

Module containing functions to study and analyze neural signals, especially to provide insights for building machine learning models to perform classification relevant to Brain-Computer Interface applications.

neurol.models.data_exploration.plot_signal(signal, sampling_rate, signal_type=None, ch_names=None, event_timestamps=None, **plt_kwargs)

Plots signal.

Parameters:
  • signal – signal as array of shape [n_samples, n_channels].
  • sr (float) – sampling rate in samples per second.
  • signal_type – (optional) gives a title for the y-axis.
  • ch_names – (optional) array of names for each channel (used for legend).
  • event_timestamps – (optional) 1-D array of times at which an event/stimulus occured.
  • **plt_kwargs – matplotlib keyword args
neurol.models.data_exploration.plot_grid(signals, num_signals=None, sampling_rate=1, cols=4, fig_size=(10, 6), sharey=True, sharex=True, random=True, fig_axes=None, show=True)

Plot an (optionally random) set of signals [epochs] in a grid from a larger array of given signals.

Parameters:
  • signals – array of signals to plot from (num_signals, num_samples).
  • num_signals (int) – the number of siganls to plot.
  • sampling_rate (float) – sampling rate of signals.
  • cols (int) – the number of columns in the grid.
  • fig_size – tuple (x,y) of figure size in inches.
  • sharey (bool) – whether to share scale on y-axis (see matplotlib).
  • sharex (bool) – whether to share scale on x-axis (see matplotlib).
  • random (bool) – whether to choose signals randomly or just use the first num_signals.
  • fig_axes – optionally, an existing tuple of (fig,axes) to plot on (see matplotlib) rather creating new one.
  • show (bool) – whether to show plot inline.
Returns:

matplotlib figure and axes with sample of signals

plotted in a grid
Return type:

fig, axes
neurol.models.data_exploration.stim_triggered_average(signal, sampling_rate, timestamps, duration_before, duration_after, plot=False)

Inspired by the computational neuroscience concept of the spike-triggered average, this function computes the average signal characteristic around known events.

Parameters:
  • signal – signal as an array of shape [samples, channels].
  • sr (float) – sampling rate of the signal.
  • timestamps – array of floats containing the timestamps for each event.
  • duration_before – the duration to be considered before each event.
  • duration_after – the duration to be considered after each event.
  • plot (optional) – whether or not to plot the stim_triggered_average.
Returns:

average signal characteristic around event. relative_time: relative time of each sample in stim_triggered_average

with respect to event.
Return type:

stim_triggered_average
neurol.models.data_exploration.plot_PCA(epochs, sampling_rate=1, n_components=None, return_PCA=False, PCA_kwargs=None, plot_grid_kwargs=None)

performs principal component analysis and plots principal components of epochs of a signal.

Parameters:
  • epochs – array of epochs (n_epochs, n_samples).
  • sr (float) – sampling rate.
  • num_components (int) – number of components to use. If none is passed, all are used.
  • return_PCA (bool) – whether to return the independent components.
  • PCA_kwargs (dict) – dictionary containing kwargs for PCA function (see scikit-learn).
  • plot_grid_kwargs (dict) – dictionary containing kwargs for plot_grid function.
neurol.models.data_exploration.plot_ICA(epochs, sampling_rate=1, n_components=None, return_ICA=False, FastICA_kwargs=None, plot_grid_kwargs=None)

performs independent component analysis and plots independent components of epochs of a signal.

Parameters:
  • epochs – array of epochs (n_epochs, n_samples).
  • sr (float) – sampling rate.
  • num_components (int) – number of components to use. If none is passed, all are used.
  • return_ICA (bool) – whether to return the independent components.
  • FastICA_kwargs (dict) – dictionary containing kwargs for FastICA function (see scikit-learn).
  • plot_grid_kwargs (dict) – dictionary containing kwargs for plot_grid function.

neurol.models.model_tools module

Module for managing the models which come pre-packaged with neurol. Includes functionality for importing and using the models.

neurol.models.model_tools.get_model(model_name)

gets the specified trained model.

Parameters:model_name (str) – name of model. See documentation for list of available models.
Returns:trained model.of
Return type:model
neurol.models.model_tools.get_predictor(model_name)

gets the predictor for the specified model.

Parameters:model_name (str) – name of model. See documentation for list of available models.
Returns:predictor of trained model.
Return type:predictor

neurol.models.preprocessing module

Module containing functions for the preparation of neural data for use with with BCI-related models.

neurol.models.preprocessing.epoch(signal, window_size, inter_window_interval)

Creates overlapping windows/epochs of EEG data from a single recording.

Parameters:
  • signal – array of timeseries EEG data of shape [n_samples, n_channels]
  • window_size (int) – desired size of each window in number of samples
  • inter_window_interval (int) – interval between each window in number of samples (measured start to start)
Returns:

numpy array object with the epochs along its first dimension
neurol.models.preprocessing.labels_from_timestamps(timestamps, sampling_rate, length)

takes an array containing timestamps (as floats) and returns a labels array of size ‘length’ where each index corresponding to a timestamp via the ‘samplingRate’.

Parameters:
  • timestamps – an array of floats containing the timestamps for each
  • event (units matching sampling_rate) –
  • sampling_rate (float) – the sampling rate of the EEG data.
  • length (int) – the number of samples of the corresponing EEG recording.
Returns:

an integer array of size ‘length’ with a ‘1’ at each time index where a corresponding timestamp exists, and a ‘0’ otherwise.
neurol.models.preprocessing.label_epochs(labels, window_size, inter_window_interval, label_method)

create labels for individual eoicgs of EEG data based on the label_method.

Parameters:
  • labels – an integer array indicating a class for each sample measurement
  • window_size (int) – size of each window in number of samples (matching window_size in epoched data)
  • inter_window_interval (int) – interval between each window in number of samples (matching inter_window_interval in epoched data)
  • label_method (str/func) –

    method of consolidating labels contained in epoch into a single label.

    ’containment’: whether a positive label occurs in the epoch, ‘count’: the count of positive labels in the epoch, ‘mode’: the most common label in the epoch func: func_name(epoched_labels) outputs label of epoched_labels
Returns:

a numpy array with a label correponding to each epoch
neurol.models.preprocessing.label_epochs_from_timestamps(timestamps, sampling_rate, length, window_size, inter_window_interval, label_method='containment')

Directly creates labels for individual windows of EEG data from timestamps of events.

Parameters:
  • timestamps – an array of floats containing the timestamps for each event (units matching sampling_rate).
  • sampling_rate (float) – sampling rate of the recording.
  • length (int) – the number of samples of the corresponing EEG recording.
  • window_size (int) – size of each window in number of samples (matches window_size in epoched data)
  • inter_window_interval (int) – interval between each window in number of samples (matches inter_window_interval in epoched data)
  • label_method (str/func) –

    method of consolidating labels contained in epoch into a single label.

    ’containment’: whether a positive label occurs in the epoch, ‘count’: the count of positive labels in the epoch, ‘mode’: the most common label in the epoch func: func_name(epoched_labels) outputs label of epoched_labels
Returns:

an array with a label correponding to each window
neurol.models.preprocessing.epoch_and_label(data, sampling_rate, timestamps, window_size, inter_window_interval, label_method='containment')

Epochs a signal (single EEG recording) and labels each epoch using timestamps of events and a chosen labelling method.

Parameters:
  • data – array of timeseries EEG data of shape [n_samples, n_channels]
  • timestamps – an array of floats containing the timestamps for each event in units of time.
  • sampling_rate (float) – the sampling rate of the EEG data.
  • window_size (float) – desired size of each window in units of time.
  • inter_window_interval (float) – interval between each window in units of time (measured start to start)
  • label_method (str/func) –

    method of consolidating labels contained in epoch into a single label.

    ’containment’: whether a positive label occurs in the epoch, ‘count’: the count of positive labels in the epoch, ‘mode’: the most common label in the epoch func: func_name(epoched_labels) outputs label of epoched_labels
Returns:

array of epochs with shape [n_epochs, n_channels] labels: array of labels corresponding to each epoch of shape [n_epochs,]
Return type:

epochs
neurol.models.preprocessing.compute_signal_std(signal, corrupt_intervals=None, sampling_rate=1)

Computes and returns the standard deviation of a signal channel-wise while avoiding corrupt intervals

Parameters:
  • signal – signal of shape [n_samples, n_channels]
  • corrupt_intervals – an array of 2-tuples indicating the start and end time of the corrupt interval (units of time)
  • sampling_rate – the sampling rate in units of samples/unit of time
Returns:

standard deviation of signal channel-wise of shape [1, n_channels]
neurol.models.preprocessing.split_corrupt_signal(signal, corrupt_intervals, sampling_rate=1)

Splits a signal with corrupt intervals and returns array of signals with the corrupt intervals filtered out. This is useful for treating each non_corrupt segment as a seperate signal to ensure continuity within a single signal.

Parameters:
  • signal – signal of shape [n_samples, n_channels]
  • corrupt_intervals – an array of 2-tuples indicating the start and end time of the corrupt interval (units of time)
  • sampling_rate – the sampling rate in units of samples/unit of time
Returns:

array of non_corrupt signals of shape [n_signal, n_samples, n_channels]
neurol.models.preprocessing.epoch_band_features(epoch_, sampling_rate, bands='all', return_dict=True)

Computes power features of EEG frequency bands over the epoch channel-wise.

Parameters:
  • epoch – a single epoch of shape [n_samples, n_channels]
  • sampling_rate – the sampling rate of the signal in units of samples/sec
  • bands – the requested frequency bands to get power features for. ‘all’: all of [‘theta’, ‘alpha_low’, ‘alpha_high’, ‘beta’, ‘gamma’] otherwise an array of strings of the desired bands.
  • return_dict (bool) – returns band_features in the form of a dictionary if True, else returns as numpy array in order of bands
Returns:

a dictionary of arrays of shape [1, n_channels] containing the power features over each frequency band per channel.

Module contents