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 booleansand 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.