neurol package

Submodules

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.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.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.streams module

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

Module contents