neurol package

neurol.BCI module

Module implementing a general Brain-Computer Interface which manages and incoming stream of neural data and responds to it in real-time.

class neurol.BCI.generic_BCI(classifier, transformer=None, action=<built-in function print>, calibrator=None)

Bases: object

Implements a generic Brain-Computer Interface.

Internally manages a buffer of the signal given in stream and continuously performs classification on appropriately transformed real-time neural data. At each classification, a corresponding action is performed.

Variables:
  • classifier (function) – a function which performs classification on the most recent data (transformed as needed). returns classification.
  • transformer (function) – function which takes in the most recent data (buffer) and returns the transformed input the classifer expects.
  • action (function) – a function which takes in the classification, and performs some action.
  • calibrator (function) – a function which is run on startup to perform calibration using stream; returns calibration_info which is used by classifier and transformer.
  • calibration_info – the result of the calibrator, if applicable.
  • buffer_length (int) – the length of the buffer; specifies the number of samples of the signal to keep for classification.
  • brain_state – the most recent brain state classification.
__init__(classifier, transformer=None, action=<built-in function print>, calibrator=None)

Initialize a generic BCI object.

See class documentation for infromation about the class itself.

Parameters:
  • classifier (function) – a function which performs classification on the most recent data (transformed as needed). returns class.
  • transformer (function) – function which takes in the most recent data (buffer) and returns the transformed input the classifer expects.
  • action (function) – a function which takes in the classification, and performs some action.
  • calibrator (function) – a function which is run on startup to perform calibration using stream; returns calibration_info which is used by classifier and transformer.
calibrate(stream)

runs the calibrator.

return value of calibrator is stored in the object’s calibration_info which the transformer and classifier can use at run-time of BCI.

Parameters:stream (neurol.streams object) – neurol stream for brain data.
run(stream)

Runs the defined Brain-Computer Interface.

Internally manages a buffer of the signal given in stream and continuously performs classification on appropriately transformed real-time neural data. At each classification, a corresponding action is performed.

Parameters:stream (neurol.streams object) – neurol stream for brain data.
test_update_rate(stream, test_length=10, perform_action=True)

Returns the rate at which the BCI is able to make a classification and perform its action.

Parameters:
  • stream (neurol.streams object) – neurol stream for brain data.
  • test_length (float) – how long to run the test for in seconds.
  • perform_action (bool) – whether to perform the action or skip it.
class neurol.BCI.fsm_BCI(classifier, transformer=None, action=<built-in function print>, calibrator=None)

Bases: neurol.BCI.generic_BCI

Implements a Finite-State-Machine-inspired Brain-Computer Interface.

Classification of brain-state is not only dependent on the transformed real-time brain signal, but also the previous brain state.

Internally manages a buffer of the signal given in stream and continuously performs classification on appropriately transformed real-time neural data. At each classification, a corresponding action is performed.

Variables:
  • classifier (function) – a function which performs classification on the most recent data (transformed as needed). returns classification.
  • transformer (function) – function which takes in the most recent data (buffer) and returns the transformed input the classifer expects.
  • action (function) – a function which takes in the classification, and performs some action.
  • calibrator (function) – a function which is run on startup to perform calibration using stream; returns calibration_info which is used by classifier and transformer.
  • calibration_info – the result of the calibrator, if applicable.
  • buffer_length (int) – the length of the buffer; specifies the number of samples of the signal to keep for classification.
  • brain_state – the most recent brain state classification.
class neurol.BCI.retentive_BCI(classifier, transformer=None, action=<built-in function print>, calibrator=None, memory_length=10)

Bases: neurol.BCI.generic_BCI

Implements a Brain-Computer Interface with memory of past brain states.

Classification of brain-state is not only dependent on the transformed real-time brain signal, but also the finite list of previous brain states.

Internally manages a buffer of the signal given in stream and continuously performs classification on appropriately transformed real-time neural data. At each classification, a corresponding action is performed.

Variables:
  • classifier (function) – a function which performs classification on the most recent data (transformed as needed). returns classification.
  • transformer (function) – function which takes in the most recent data (buffer) and returns the transformed input the classifer expects.
  • action (function) – a function which takes in the classification, and performs some action.
  • calibrator (function) – a function which is run on startup to perform calibration using stream; returns calibration_info which is used by classifier and transformer.
  • calibration_info – the result of the calibrator, if applicable.
  • brain_state – the most recent brain state classification.
  • memory_length (int) – number of brain states into the past to remember.
  • past_states – a list of the past classifications of brain states. used in next classification. length is memory_length.
__init__(classifier, transformer=None, action=<built-in function print>, calibrator=None, memory_length=10)

Initialize a retentive BCI object.

See class documentation for infromation about the class itself.

Parameters:
  • classifier (function) – a function which performs classification on the most recent data (transformed as needed). returns class.
  • transformer (function) – function which takes in the most recent data (buffer) and returns the transformed input the classifer expects.
  • action (function) – a function which takes in the classification, and performs some action.
  • calibrator (function) – a function which is run on startup to perform calibration using stream; returns calibration_info which is used by classifier and transformer.
  • memory_length (int) – number of brain states to remember into past.
class neurol.BCI.automl_BCI(model, epoch_len, n_states, transformer=None, action=<built-in function print>)

Bases: neurol.BCI.generic_BCI

Implements a Brain-Computer Interface which builds its own classifier by training a machine learning model in the calibration stage.

At calibration, data is recorded for some number of brain-states then a machine-learning classifier is trained on the transformed data.

Internally manages a buffer of the signal given in stream and continuously performs classification on appropriately transformed real-time neural data. At each classification, a corresponding action is performed.

Variables:
  • model – a model object which has fit(X, y) and predict(X) methods.
  • classifier (function) – the model’s predictor after training. accepts transformed data and returns classification.
  • transformer (function) – function which takes in the most recent data (buffer) and returns the transformed input the classifer expects.
  • action (function) – a function which takes in the classification, and performs some action.
  • brain_state – the most recent brain state classification.
__init__(model, epoch_len, n_states, transformer=None, action=<built-in function print>)

Initialize an autoML BCI object.

See class documentation for infromation about the class itself.

Parameters:
  • model – a model object which has fit(X, y) and predict(X) methods.
  • epoch_len (int) – the length of the epochs (in # of samples) used in training and prediction by the model.
  • n_states (int) – the number of brain states being classified.
  • transformer (function, optional) – function which takes in the most recent data (buffer) and returns the transformed input the classifer expects. Defaults to None.
  • action (function, optional) – a function which takes in the classification, and performs some action. Defaults to print.
build_model(stream, recording_length)

records brain signal

Parameters:
  • stream (neurol.streams object) – neurol stream for brain data.
  • recording_length (float) – length in seconds for the recording of each brain state to be used for training the model.
run(stream)

Runs the defined Brain-Computer Interface.

Internally manages a buffer of the signal given in stream and continuously performs classification on appropriately transformed real-time neural data. At each classification, a corresponding action is performed.

Parameters:stream (neurol.streams object) – neurol stream for brain data.

neurol.BCI_tools module

Module including utility functions for creating classifier’s, transfromer’s, and calibrator’s for use in the BCI module.

neurol.BCI_tools.ensemble_transform(signal, epoch_len=None, channels=None, device=None, transformers=None, filter_=False, sampling_rate=None, filter_kwargs=None)

Ensemble transform function. Takes in buffer as input. Extracts the appropriate channels and samples, performs filtering, and transforms.

Parameters:
  • signal (np.ndarray) – signal of shape: [n_samples, n_channels]
  • epoch_len (int) – length of epoch expected by classifier (# of samples). optional.
  • channels (list of str or int) – list of channels expected by classifier. See get_channels. optional.
  • device (str) – device name. used to get channels and sampling_rate.
  • filter (boolean) – whether to perform filtering
  • filter_kwargs (dict) – dictionary of kwargs passed to filtering function. See biosppy.signals.tools.filter_signal. by default, an order 8 bandpass butter filter is performed between 2Hz and 40Hz.
neurol.BCI_tools.filter_signal(signal, sampling_rate, ftype='butter', band='bandpass', frequency=(2, 40), order=8, **filter_kwargs)

applies frequency-based filters to a given signal.

Parameters:
  • signal (np.ndarray) – signal of shape [n_samples, n_channels]
  • sampling_rate (float) – sampling rate of signal.
  • ftype (str, optional) – type of filter. one of ‘FIR’, ‘butter’, ‘chebby1’, ‘chebby2’, ‘ellip’, or ‘bessel’. Defaults to ‘butter’.
  • band (str, optional) – band type. one of ‘lowpass’, ‘highpass’, ‘bandpass’, or ‘bandstop’. Defaults to ‘bandpass’.
  • frequency (float or tuple of floats, optional) – cutoff frequencies. single if ‘lowpass’/’highpass’, tuple if ‘bandpass’/’bandstop’. Defaults to (2,40).
  • order (int, optional) – order of filter. Defaults to 8.
  • **filter_kwargs – keyword args for biosppy.signals.tools.filter_signal
Returns:

filtered signal
Return type:

[np.ndarray]
neurol.BCI_tools.band_power_calibrator(stream, channels, device, bands, percentile=50, recording_length=10, epoch_len=1, inter_window_interval=0.2)

Calibrator for generic_BCI.BCI which computes a given percentile for the power of each frequency band across epochs channel-wise. Useful for calibrating a concentration-based BCI.

Parameters:
  • stream (neurol.streams object) – neurol stream for brain data.
  • channels – array of strings with the names of channels to use.
  • device (str) – device name for use by classification_tools
  • bands – the 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.
  • percentile – the percentile of power distribution across epochs to return for each band.
  • recording_length (float) – length of recording to use for calibration in seconds.
  • epoch_len (float) – the length of each epoch in seconds.
  • inter_window_interval (float) – interval between each window/epoch in seconds (measured start to start)
Returns:

array of shape [n_bands, n_channels] of the percentile of the power of each band
Return type:

clb_info
neurol.BCI_tools.band_power_transformer(signal, sampling_rate, bands)

Transformer for generic_BCI.BCI which chooses channels, epochs, and gets power features on some choice of bands.

Parameters:
  • signal (np.ndarray) – most recent stream data. shape: [n_samples, n_channels]
  • sampling_rate (float) – sampling_rate of signal.
  • bands – the frequency bands to get power features for. ‘all’: all of [‘theta’, ‘alpha_low’, ‘alpha_high’, ‘beta’, ‘gamma’] otherwise a list of strings of the desired bands.
Returns:

array of shape [n_bands, n_channels] of the channel-wise power of each band over the epoch.
Return type:

transformed_signal

neurol.plot module

Module for plotting stream of neural data. Includes time domain, fourrier transform, and spectrogram live plots.

neurol.plot.plot(stream, channels=None, w_size=(1920, 1080))

plots data stream. one row per channel.

Parameters:
  • stream (neurol.streams object) – neurol stream for a data source.
  • channels – channels to plot. list/tuple of channel indices, or dict with indices as keys and names as values. Defaults to None (plots all channels w/o names).
  • w_size (tuple, optional) – initial size of window in pixels. Defaults to (1920, 1080).
neurol.plot.plot_fft(stream, channels=None, w_size=(1920, 1080))

plots fourrier transform of data stream from inlet. one row per channel.

Parameters:
  • stream (neurol.streams object) – neurol stream for a data source.
  • channels – channels to plot. list/tuple of channel indices, or dict with indices as keys and names as values. Defaults to None (plots all channels w/o names).
  • w_size (tuple, optional) – initial size of window in pixels. Defaults to (1920, 1080).
neurol.plot.plot_spectrogram(stream, channels=None, w_size=(1920, 1080))

plots spectrogram of data stream from inlet. one row per channel.

Parameters:
  • stream (neurol.streams object) – neurol stream for a data source.
  • channels – channels to plot. list/tuple of channel indices, or dict with indices as keys and names as values. Defaults to None (plots all channels w/o names).
  • w_size (tuple, optional) – initial size of window in pixels. Defaults to (1920, 1080).

neurol.connect_device module

Module containing functions for quickly connecting to BCI-related streaming devices.

neurol.connect_device.connect_muse()

connects to any available muse headset. returns ble2lsl.ble2lsl.Streamer object.

neurol.connect_device.get_lsl_EEG_inlets()

resolves all EEG lsl streams and returns their inlets in an array.

neurol.streams

module for handling streams of data from different sources

class neurol.streams.lsl_stream(pylsl_inlet, buffer_length=2048)

Bases: object

A generalized stream object for an lsl data source.

Manages a buffer of data and makes it available. Used by neurol.BCI and neurol.plot.

__init__(pylsl_inlet, buffer_length=2048)

initialize an lsl_stream object.

Parameters:
  • pylsl_inlet (pylsl.pylsl.StreamInlet) – inlet of connected lsl device
  • buffer_length (int, optional) – length of data buffer. Defaults to 2048.
get_data(max_samples=2048)

gets latest data.

record_data(duration)

records from stream for some duration of time.

Parameters:duration (float) – length of recording in seconds.
update_buffer()

updates buffer with most recent available data.

Returns:True if new data available, False if not.
Return type:[bool]
close()

closes the pylsl inlet stream