mindaffectBCI.decoder package

Submodules

mindaffectBCI.decoder.FileProxyHub module

class mindaffectBCI.decoder.FileProxyHub.FileProxyHub(filename: str = None, speedup: float = None, use_server_ts: bool = True)[source]

Bases: object

Proxy UtopiaClient which gets messages from a saved log file

autoconnect(*args, **kwargs)[source]

[summary]

getNewMessages(timeout_ms)[source]

[summary]

Parameters:timeout_ms ([type]) – [description]
Returns:[description]
Return type:[type]
getTimeStamp()[source]

[summary]

Returns:[description]
Return type:[type]
sendMessage(msg)[source]

[summary]

Parameters:msg ([type]) – [description]
mindaffectBCI.decoder.FileProxyHub.testcase(filename, fs=200, fs_out=200, stopband=((45, 65), (0, 3), (25, -1)), order=4)[source]

[summary]

Parameters:
  • filename ([type]) – [description]
  • fs (int, optional) – [description]. Defaults to 200.
  • fs_out (int, optional) – [description]. Defaults to 200.
  • stopband (tuple, optional) – [description]. Defaults to ((45,65),(0,3),(25,-1)).
  • order (int, optional) – [description]. Defaults to 4.

mindaffectBCI.decoder.UtopiaDataInterface module

class mindaffectBCI.decoder.UtopiaDataInterface.TransformerMixin[source]

Bases: object

fit(X)[source]
transform(X)[source]
class mindaffectBCI.decoder.UtopiaDataInterface.UtopiaDataInterface(datawindow_ms=60000, msgwindow_ms=60000, data_preprocessor=None, stimulus_preprocessor=None, send_signalquality=True, timeout_ms=100, mintime_ms=50, fs=None, U=None, sample2timestamp='lower_bound_tracker', clientid=None)[source]

Bases: object

Adaptor class for interfacing between the decoder logic and the data source

This class provides functionality to wrap a real time data and stimulus stream to make it easier to implement standard machine learning pipelines. In particular it provides streamed pre-processing for both EEG and stimulus streams, and ring-buffers for the same with time-stamp based indexing.

VERBOSITY = 1[source]
add_sample_timestamps(d: numpy.ndarray, timestamp: float, fs: float)[source]

add per-sample timestamp information to the data matrix

Parameters:
  • d (np.ndarray) – (t,d) the data matrix to attach time stamps to
  • timestamp (float) – the timestamp of the last sample of d
  • fs (float) – the nomional sample rate of d
Returns:

(t,d+1) data matrix with attached time-stamp channel

Return type:

np.ndarray

connect(host=None, port=-1, queryifhostnotfound=True)[source]

[make a connection to the utopia host]

Parameters:
  • host ([type], optional) – [description]. Defaults to None.
  • port (int, optional) – [description]. Defaults to -1.
  • queryifhostnotfound (bool, optional) – [description]. Defaults to True.
Returns:

[description]

Return type:

[type]

extract_data_segment(bgn_ts, end_ts=None)[source]

extract a segment of data based on a start and end time-stamp

Parameters:
  • bgn_ts (float) – segment start time-stamp
  • end_ts (float, optional) – segment end time-stamp. Defaults to None.
Returns:

the data between these time-stamps, or None if timestamps invalid

Return type:

(np.ndarray)

extract_msgs_segment(bgn_ts, end_ts=None)[source]

[extract the messages between start/end time stamps]

Parameters:
  • bgn_ts ([type]) – [description]
  • end_ts ([type], optional) – [description]. Defaults to None.
Returns:

[description]

Return type:

[type]

extract_stimulus_segment(bgn_ts, end_ts=None)[source]

extract a segment of the stimulus stream based on a start and end time-stamp

Parameters:
  • bgn_ts (float) – segment start time-stamp
  • end_ts (float, optional) – segment end time-stamp. Defaults to None.
Returns:

the stimulus events between these time-stamps, or None if timestamps invalid

Return type:

(np.ndarray)

getNewMessages(timeout_ms=0)[source]

[get new messages from the UtopiaHub]

Parameters:timeout_ms (int, optional) – [description]. Defaults to 0.
Returns:[description]
Return type:[type]
getTimeStamp()[source]

[summary]

Returns:[description]
Return type:[type]
initDataRingBuffer()[source]

[initialize the data ring buffer, by getting some seed messages and datapackets to get the data sizes etc.]

Returns:[description]
Return type:[type]
initStimulusRingBuffer()[source]

initialize the data ring buffer, by getting some seed messages and datapackets to get the data sizes etc.

isConnected()[source]

[summary]

Returns:[description]
Return type:[type]
local_slope(nsamp, data_ts)[source]

compute a robust local slope estimate

Parameters:
  • nsamp ([type]) – [description]
  • data_ts ([type]) – [description]
Returns:

[description]

Return type:

[type]

plot_raw_preproc_data(d_raw, d_preproc, ts)[source]

[debugging function to check the diff between the raw and pre-processed data]

Parameters:
  • d_raw ([type]) – [description]
  • d_preproc ([type]) – [description]
  • ts ([type]) – [description]
preprocess_message(m: mindaffectBCI.utopiaclient.UtopiaMessage)[source]

[apply pre-processing to topia message before any more work]

Parameters:m (UtopiaMessage) – [description]
Returns:[description]
Return type:[type]
processDataPacket(m: mindaffectBCI.utopiaclient.DataPacket)[source]

[pre-process a datapacket message ready to be inserted into the ringbuffer]

Parameters:m (DataPacket) – [description]
Returns:[description]
Return type:[type]
processStimulusEvent(m: mindaffectBCI.utopiaclient.StimulusEvent)[source]

[pre-process a StimulusEvent message ready to be inserted into the stimulus ringbuffer]

Parameters:m (StimulusEvent) – [description]
Returns:[description]
Return type:[type]
push_back_newmsgs(oldmsgs)[source]

[put unprocessed messages back onto the newmessages queue]

Parameters:oldmsgs ([type]) – [description]
run(timeout_ms=30000)[source]

[test run the interface forever, just getting and storing data]

Parameters:timeout_ms (int, optional) – [description]. Defaults to 30000.
sendMessage(msg: mindaffectBCI.utopiaclient.UtopiaMessage)[source]

[send a UtopiaMessage to the utopia hub]

Parameters:msg (UtopiaMessage) – [description]
update(timeout_ms=None, mintime_ms=None)[source]

Update the tracking state w.r.t. the data source

By adding data to the data_ringbuffer, stimulus info to the stimulus_ringbuffer, and other messages to the messages ring buffer.

Args
timeout_ms : int
max block waiting for messages before returning
mintime_ms : int
min time to accumulate messages before returning
Returns
newmsgs : [newMsgs :UtopiaMessage]
list of the new utopia messages from the server
nsamp: int
number of new data samples in this call Note: use data_ringbuffer[-nsamp:,…] to get the new data
nstimulus : int
number of new stimulus events in this call Note: use stimulus_ringbuffer[-nstimulus:,…] to get the new data
update_and_send_ElectrodeQualities(d_raw: numpy.ndarray, d_preproc: numpy.ndarray, ts: int)[source]

[compute running estimate of electrode qality and stream it]

Parameters:
  • d_raw (np.ndarray) – [description]
  • d_preproc (np.ndarray) – [description]
  • ts (int) – [description]
update_electrode_powers(d_raw: numpy.ndarray, d_preproc: numpy.ndarray)[source]

track exp-weighted-moving average centered power for 2 input streams – the raw and the preprocessed

Parameters:
  • d_raw (np.ndarray) – [description]
  • d_preproc (np.ndarray) – [description]
Returns:

[description]

Return type:

[type]

class mindaffectBCI.decoder.UtopiaDataInterface.butterfilt_and_downsample(stopband=((0, 5), (5, -1)), order: int = 6, fs: float = 250, fs_out: float = 60, ftype='butter')[source]

Bases: mindaffectBCI.decoder.UtopiaDataInterface.TransformerMixin

Incremental streaming transformer to provide filtering and downsampling data transformations

Parameters:TransformerMixin ([type]) – sklearn compatible transformer
fit(X, fs: float = None, zi=None)[source]

[summary]

Parameters:
  • X ([type]) – [description]
  • fs (float, optional) – [description]. Defaults to None.
  • zi ([type], optional) – [description]. Defaults to None.
Returns:

[description]

Return type:

[type]

static testcase()[source]

test the filt+downsample transformation filter by incremental calling

transform(X, Y=None)[source]

[summary]

Parameters:
  • X ([type]) – [description]
  • Y ([type], optional) – [description]. Defaults to None.
Returns:

[description]

Return type:

[type]

class mindaffectBCI.decoder.UtopiaDataInterface.channel_power_standardizer(reg=0.0001, axis=-2)[source]

Bases: mindaffectBCI.decoder.UtopiaDataInterface.TransformerMixin

Incremental streaming tranformer to channel power normalization in an input stream

fit(X)[source]

[summary]

Parameters:X ([type]) – [description]
testcase(dur=3, fs=100, blksize=10)[source]

[summary]

Parameters:
  • dur (int, optional) – [description]. Defaults to 3.
  • fs (int, optional) – [description]. Defaults to 100.
  • blksize (int, optional) – [description]. Defaults to 10.
transform(X)[source]

add per-sample timestamp information to the data matrix

Parameters:X (float) – the data to decorrelate
Returns:the decorrelated data
Return type:np.ndarray
class mindaffectBCI.decoder.UtopiaDataInterface.power_tracker(halflife_mu_ms, halflife_power_ms, fs, car=True)[source]

Bases: mindaffectBCI.decoder.UtopiaDataInterface.TransformerMixin

Incremental streaming transformer from raw n-channel data, to exponientially smoothed channel powers

Parameters:TransformerMixin ([type]) – sklearn compatiable transformer
fit(X)[source]

[summary]

Parameters:X ([type]) – [description]
Returns:[description]
Return type:[type]
hl2alpha(hl)[source]

[summary]

Parameters:hl ([type]) – [description]
Returns:[description]
Return type:[type]
mean()[source]

[summary]

Returns:[description]
Return type:[type]
power()[source]

[summary]

Returns:[description]
Return type:[type]
static testcase()[source]

[summary]

transform(X: numpy.ndarray)[source]

compute the exponientially weighted centered power of X

Parameters:X (np.ndarray) – samples x channels data
Returns:the updated per-channel power
Return type:np.ndarray
class mindaffectBCI.decoder.UtopiaDataInterface.stim2eventfilt(evtlabs=None, histlen=20)[source]

Bases: mindaffectBCI.decoder.UtopiaDataInterface.TransformerMixin

Incremental streaming transformer to transform a sequence of stimulus states to a brain event sequence

For example by transforming a sequence of stimulus intensities, to rising and falling edge events.

fit(X)[source]

[summary]

Parameters:X ([type]) – [description]
Returns:[description]
Return type:[type]
testcase()[source]

test the stimulus transformation filter by incremental calling

transform(X)[source]

[transform Stimulus-encoded to brain-encoded]

Parameters:X ([type]) – [description]
Returns:[description]
Return type:[type]
class mindaffectBCI.decoder.UtopiaDataInterface.temporal_decorrelator(order=10, reg=0.0001, eta=1e-05, axis=-2)[source]

Bases: mindaffectBCI.decoder.UtopiaDataInterface.TransformerMixin

Incremental streaming tranformer to decorrelate temporally channels in an input stream

fit(X)[source]

[summary]

Parameters:X ([type]) – [description]
testcase(dur=3, fs=100, blksize=10)[source]

[summary]

Parameters:
  • dur (int, optional) – [description]. Defaults to 3.
  • fs (int, optional) – [description]. Defaults to 100.
  • blksize (int, optional) – [description]. Defaults to 10.
transform(X)[source]

add per-sample timestamp information to the data matrix

Parameters:
  • X (float) – the data to decorrelate
  • nsamp (int) – number of samples to interpolate
Returns:

the decorrelated data

Return type:

np.ndarray

mindaffectBCI.decoder.UtopiaDataInterface.testERP()[source]

[summary]

mindaffectBCI.decoder.UtopiaDataInterface.testElectrodeQualities(X, fs=200, pktsize=20)[source]

[summary]

Parameters:
  • X ([type]) – [description]
  • fs (int, optional) – [description]. Defaults to 200.
  • pktsize (int, optional) – [description]. Defaults to 20.
Returns:

[description]

Return type:

[type]

mindaffectBCI.decoder.UtopiaDataInterface.testFileProxy(filename, fs_out=999)[source]

[summary]

Parameters:
  • filename ([type]) – [description]
  • fs_out (int, optional) – [description]. Defaults to 999.
mindaffectBCI.decoder.UtopiaDataInterface.testFileProxy2(filename)[source]

[summary]

Parameters:filename ([type]) – [description]
mindaffectBCI.decoder.UtopiaDataInterface.testPP()[source]

[summary]

mindaffectBCI.decoder.UtopiaDataInterface.testRaw()[source]

[summary]

class mindaffectBCI.decoder.UtopiaDataInterface.timestamp_interpolation(fs=None, sample2timestamp=None, max_delta=200)[source]

Bases: mindaffectBCI.decoder.UtopiaDataInterface.TransformerMixin

Incremental streaming tranformer to transform from per-packet time-stamps to per-sample timestamps with time-stamp smoothing, de-jittering, and dropped-sample detection.

fit(ts, nsamp=1)[source]

[summary]

Parameters:
  • ts ([type]) – [description]
  • nsamp (int, optional) – [description]. Defaults to 1.
testcase(npkt=1000, fs=100)[source]

[summary]

Parameters:
  • npkt (int, optional) – [description]. Defaults to 1000.
  • fs (int, optional) – [description]. Defaults to 100.
transform(timestamp: float, nsamp: int = 1)[source]

add per-sample timestamp information to the data matrix

Parameters:
  • timestamp (float) – the timestamp of the last sample of d
  • nsamp (int) – number of samples to interpolate
Returns:

(nsamp) the interpolated time-stamps

Return type:

np.ndarray

mindaffectBCI.decoder.analyse_datasets module

mindaffectBCI.decoder.analyse_datasets.analyse_dataset(X: numpy.ndarray, Y: numpy.ndarray, coords, model: str = 'cca', test_idx=None, cv=True, tau_ms: float = 300, fs: float = None, rank: int = 1, evtlabs=None, offset_ms=0, center=True, tuned_parameters=None, ranks=None, retrain_on_all=True, **kwargs)[source]

cross-validated training on a single datasets and decoing curve estimation

Parameters:
  • X (np.ndarray) – the X (EEG) sequence
  • Y (np.ndarray) – the Y (stimulus) sequence
  • coords ([type]) – array of dicts of meta-info describing the structure of X and Y
  • fs (float) – the data sample rate (if coords is not given)
  • model (str, optional) – The type of model to fit, as in model_fitting.py. Defaults to ‘cca’.
  • cv (bool, optional) – flag if we should train with cross-validation using the cv_fit method. Defaults to True.
  • test_idx (list-of-int, optional) – indexs of test-set trials which are not passed to fit/cv_fit. Defaults to True.
  • tau_ms (float, optional) – length of the stimulus-response in milliseconds. Defaults to 300.
  • rank (int, optional) – rank of the decomposition in factored models such as cca. Defaults to 1.
  • evtlabs ([type], optional) – The types of events to used to model the brain response, as used in stim2event.py. Defaults to None.
  • offset_ms ((2,) – float, optional): Offset for analysis window from start/end of the event response. Defaults to 0.
Raises:

NotImplementedError – if you use for a model which isn’t implemented

Returns:

the cv score for this dataset dc (tuple): the information about the decoding curve as returned by decodingCurveSupervised.py Fy (np.ndarray): the raw cv’d output-scores for this dataset as returned by decodingCurveSupervised.py clsfr (BaseSequence2Sequence): the trained classifier

Return type:

score (float)

mindaffectBCI.decoder.analyse_datasets.analyse_datasets(dataset: str, model: str = 'cca', dataset_args: dict = None, loader_args: dict = None, preprocess_args: dict = None, clsfr_args: dict = None, tuned_parameters: dict = None, **kwargs)[source]

analyse a set of datasets (multiple subject) and generate a summary decoding plot.

Parameters:
  • dataset ([str]) – the name of the dataset to load
  • model (str, optional) – The type of model to fit. Defaults to ‘cca’.
  • dataset_args ([dict], optional) – additional arguments for get_dataset. Defaults to None.
  • loader_args ([dict], optional) – additional arguments for the dataset loader. Defaults to None.
  • clsfr_args ([dict], optional) – additional aguments for the model_fitter. Defaults to None.
  • tuned_parameters ([dict], optional) – sets of hyper-parameters to tune by GridCVSearch
mindaffectBCI.decoder.analyse_datasets.analyse_train_test(X: numpy.ndarray, Y: numpy.ndarray, coords, splits=1, label: str = '', model: str = 'cca', tau_ms: float = 300, fs: float = None, rank: int = 1, evtlabs=None, preprocess_args=None, clsfr_args: dict = None, **kwargs)[source]

analyse effect of different train/test splits on performance and generate a summary decoding plot.

Parameters:
  • () (splits) – list of list of train-test split pairs.
  • dataset ([str]) – the name of the dataset to load
  • model (str, optional) – The type of model to fit. Defaults to ‘cca’.
  • dataset_args ([dict], optional) – additional arguments for get_dataset. Defaults to None.
  • loader_args ([dict], optional) – additional arguments for the dataset loader. Defaults to None.
  • clsfr_args ([dict], optional) – additional aguments for the model_fitter. Defaults to None.
  • tuned_parameters ([dict], optional) – sets of hyper-parameters to tune by GridCVSearch
mindaffectBCI.decoder.analyse_datasets.debug_test_dataset(X, Y, coords=None, label=None, tau_ms=300, fs=None, offset_ms=0, evtlabs=None, rank=1, model='cca', preprocess_args: dict = None, clsfr_args: dict = None, plotnormFy=False, triggerPlot=False, **kwargs)[source]

Debug a data set, by pre-processing, model-fitting and generating various visualizations

Parameters:
  • X (nTrl,nSamp,d) – The preprocessed EEG data
  • Y (nTrl,nSamp,nY) – The stimulus information
  • coords ([type], optional) – meta-info about the dimensions of X and Y. Defaults to None.
  • label ([type], optional) – textual name for this dataset, used for titles and save-file names. Defaults to None.
  • tau_ms (int, optional) – stimulus-response length in milliseconds. Defaults to 300.
  • fs ([type], optional) – sample rate of X and Y. Defaults to None.
  • offset_ms (int, optional) – offset for start of stimulus response w.r.t. stimulus time. Defaults to 0.
  • evtlabs ([type], optional) – list of types of stimulus even to fit the model to. Defaults to None.
  • rank (int, optional) – the rank of the model to fit. Defaults to 1.
  • model (str, optional) – the type of model to fit. Defaults to ‘cca’.
  • preprocess_args (dict, optional) – additional arguments to send to the data pre-processor. Defaults to None.
  • clsfr_args (dict, optional) – additional arguments to pass to the model fitting. Defaults to None.
Returns:

the cv score for this dataset dc (tuple): the information about the decoding curve as returned by decodingCurveSupervised.py Fy (np.ndarray): the raw cv’d output-scores for this dataset as returned by decodingCurveSupervised.py clsfr (BaseSequence2Sequence): the trained classifier

Return type:

score (float)

mindaffectBCI.decoder.analyse_datasets.debug_test_single_dataset(dataset: str, filename: str = None, dataset_args=None, loader_args=None, *args, **kwargs)[source]

run the debug_test_dataset for a single subject from dataset

Parameters:
  • dataset ([str]) – the dataset to load with get_dataset from datasets.py
  • filename ([str], optional) – a specific filename regular expression to match to process. Defaults to None.
Returns:

the model fitted during the dataset testing

Return type:

clsfr [BaseSeq2seq]

mindaffectBCI.decoder.analyse_datasets.flatten_decoding_curves(decoding_curves)[source]

take list of (potentially variable length) decoding curves and make into a single array

mindaffectBCI.decoder.analyse_datasets.plot_trial_summary(X, Y, Fy, Fe=None, Py=None, fs=None, label=None, evtlabs=None, centerx=True, xspacing=10, sumFy=True, Yerr=None)[source]

generate a plot summarizing the inputs (X,Y) and outputs (Fe,Fe) for every trial in a dataset for debugging purposes

Parameters:
  • X (nTrl,nSamp,d) – The preprocessed EEG data
  • Y (nTrl,nSamp,nY) – The stimulus information
  • Fy (nTrl,nSamp,nY) – The output scores obtained by comping the stimulus-scores (Fe) with the stimulus information (Y)
  • Fe ((nTrl,nSamp,nY,nE), optional) – The stimulus scores, for the different event types, obtained by combining X with the decoding model. Defaults to None.
  • Py ((nTrl,nSamp,nY), optional) – The target probabilities for each output, derived from Fy. Defaults to None.
  • fs (float, optional) – sample rate of X, Y, used to set the time-axis. Defaults to None.
  • label (str, optional) – A textual label for this dataset, used for titles & save-files. Defaults to None.
  • centerx (bool, optional) – Center (zero-mean over samples) X for plotting. Defaults to True.
  • xspacing (int, optional) – Gap in X units between different channel lines. Defaults to 10.
  • sumFy (bool, optional) – accumulate the output scores before plotting. Defaults to True.
  • Yerr (bool (nTrl,), optional) – indicator for which trials the model made a correct prediction. Defaults to None.
mindaffectBCI.decoder.analyse_datasets.run_analysis()[source]

mindaffectBCI.decoder.ccaViewer module

mindaffectBCI.decoder.ccaViewer.ccaViewer(*args, **kwargs)[source]
mindaffectBCI.decoder.ccaViewer.parse_args()[source]
mindaffectBCI.decoder.ccaViewer.run(ui: mindaffectBCI.decoder.UtopiaDataInterface.UtopiaDataInterface, timeout_ms: float = inf, tau_ms: float = 500, offset_ms=(-15, 0), evtlabs=None, ch_names=None, nstimulus_events: int = 600, rank: int = 3, reg=0.02, center: bool = True, host: str = '-', stopband=None, out_fs=100)[source]

view the live CCA decomposition.

mindaffectBCI.decoder.dataset debugging module

mindaffectBCI.decoder.datasets module

mindaffectBCI.decoder.datasets.brains_on_fire_online()[source]
mindaffectBCI.decoder.datasets.cocktail()[source]
mindaffectBCI.decoder.datasets.dataset_generator(dataset, **kwargs)[source]

generator for individual datasets from the given set of datasets

mindaffectBCI.decoder.datasets.get_dataset(dsname, *args, **kwargs)[source]
mindaffectBCI.decoder.datasets.lowlands()[source]

generate the directory+filename info for the lowlands noisetagging dataset

mindaffectBCI.decoder.datasets.mTRF_audio()[source]
mindaffectBCI.decoder.datasets.mark_EMG()[source]
mindaffectBCI.decoder.datasets.mindaffectBCI(exptdir, **args)[source]
mindaffectBCI.decoder.datasets.ninapro_db2()[source]
mindaffectBCI.decoder.datasets.openBMI(dstype='SSVEP')[source]
mindaffectBCI.decoder.datasets.p300_prn(label: str = None)[source]

generate dataset+filename for p300-prn2

mindaffectBCI.decoder.datasets.plos_one()[source]

generate the directory+filename info for the plos_one noisetagging dataset

mindaffectBCI.decoder.datasets.tactileP3()[source]

generate dataset+filename for tactile P3

mindaffectBCI.decoder.datasets.tactile_PatientStudy()[source]

generate dataset+filename for p300-prn2

mindaffectBCI.decoder.datasets.test_loader(loadfn, filenames, dataroot, **kwargs)[source]
mindaffectBCI.decoder.datasets.testcase()[source]
mindaffectBCI.decoder.datasets.testdataset(fn, **args)[source]

a conforming toy dataset loader

mindaffectBCI.decoder.datasets.toy()[source]

make a toy dataset for testing

mindaffectBCI.decoder.datasets.twofinger()[source]

mindaffectBCI.decoder.dec_test module

mindaffectBCI.decoder.decoder module

mindaffectBCI.decoder.decoder.combine_Ptgt(pvals_objIDs)[source]

combine target probabilities in a correct way

Parameters:pvals_objIDs (list (pval,objId)) – list of Ptgt,objID pairs for outputs at different time points.
Returns:target probabilities (np.ndarray (outputs,)) : object IDs for the targets
Return type:(np.ndarray (outputs,))
mindaffectBCI.decoder.decoder.dataset_to_XY_ndarrays(dataset)[source]

convert a dataset, consisting of a list of pairs of time-stamped data and stimulus events, to 3-d matrices of X=(trials,samples,channels) and Y=(trials,samples,outputs)

Parameters:dataset ([type]) – list of pairs of time-stamped data and stimulus events
Returns:the per-trial data Y (tr,samp,nY): the per-trial stimulus, with sample rate matched to X X_ts (tr,samp): the time-stamps for the smaples in X Y_ts (tr,samp): the time-stamps for the stimuli in Y
Return type:X (tr,samp,d)
mindaffectBCI.decoder.decoder.doCalibrationSupervised(ui: mindaffectBCI.decoder.UtopiaDataInterface.UtopiaDataInterface, clsfr: mindaffectBCI.decoder.model_fitting.BaseSequence2Sequence, **kwargs)[source]

do a calibration phase = basically just extract the training data and train a classifier from the utopiaInterface

Parameters:
  • ui (UtopiaDataInterface) – buffered interface to the data and stimulus streams
  • clsfr (BaseSequence2Sequence) – the classifier to use to fit a model to the calibration data
  • cv (int, optional) – the number of cross-validation folds to use for model generalization performance estimation. Defaults to 2.
  • prior_dataset ([type], optional) – data-set from a previous calibration run, used to accumulate data over subsequent calibrations. Defaults to None.
  • ranks (tuple, optional) – a list of model ranks to optimize as hyperparameters. Defaults to (1,2,3,5).
Returns:

the gathered calibration data X : the calibration data as a 3-d array (tr,samp,d) Y : the calibration stimulus as a 3-d array (tr,samp,num-outputs)

Return type:

dataset [type]

mindaffectBCI.decoder.decoder.doModelFitting(clsfr: mindaffectBCI.decoder.model_fitting.BaseSequence2Sequence, dataset, cv: int = 2, prior_dataset=None, ranks=(1, 2, 3, 5), fs: float = None, n_ch: int = None, **kwargs)[source]

fit a model given a dataset

Parameters:
  • clsfr (BaseSequence2Sequence) – the classifier to use to fit a model to the calibration data
  • cv (int, optional) – the number of cross-validation folds to use for model generalization performance estimation. Defaults to 2.
  • prior_dataset ([type], optional) – data-set from a previous calibration run, used to accumulate data over subsequent calibrations. Defaults to None.
  • ranks (tuple, optional) – a list of model ranks to optimize as hyperparameters. Defaults to (1,2,3,5).
Returns:

the estimated model generalization performance on the training data. dataset [type]: the gathered calibration data X : the calibration data as a 3-d array (tr,samp,d) Y : the calibration stimulus as a 3-d array (tr,samp,num-outputs)

Return type:

perr (float)

mindaffectBCI.decoder.decoder.doPrediction(clsfr: mindaffectBCI.decoder.model_fitting.BaseSequence2Sequence, data, stimulus, prev_stimulus=None)[source]

given the current trials data, apply the classifier and decoder to make target predictions

Parameters:
  • clsfr (BaseSequence2Sequence) – the trained classifier to apply to the data
  • data (np.ndarray (time,channels)) – the pre-processed EEG data
  • stimulus (np.ndarray (time,outputs)) – the raw stimulus information
  • prev_stimulus (np.ndarray, optional) – previous stimulus before stimulus – poss needed for correct event coding. Defaults to None.
Returns:

Fy scores for each output at each time-point

Return type:

(np.ndarray (time,outputs))

mindaffectBCI.decoder.decoder.doPredictionStatic(ui: mindaffectBCI.decoder.UtopiaDataInterface.UtopiaDataInterface, clsfr: mindaffectBCI.decoder.model_fitting.BaseSequence2Sequence, model_apply_type: str = 'trial', timeout_ms: float = None, block_step_ms: float = 100, maxDecisLen_ms: float = 8000)[source]

do the prediction stage = basically extract data/msgs from trial start and generate a prediction from them ‘’’

Parameters:
  • ui (UtopiaDataInterface) – buffered interface to the data and stimulus streams
  • clsfr (BaseSequence2Sequence) – the trained classification model
  • maxDecisLen_ms (float, optional) – the maximum amount of data to use to make a prediction, i.e. prediction sliding window size. Defaults to 8000
mindaffectBCI.decoder.decoder.getCalibration_dataset(ui: mindaffectBCI.decoder.UtopiaDataInterface.UtopiaDataInterface)[source]

extract a labelled dataset from the utopiaInterface, which are trials between modechange messages

Parameters:ui (UtopiaDataInterface) – the data interface object
Returns:list of pairs of time-stamped data and stimulus information as 2d (time,ch) (or (time,output)) numpy arrays
Return type:(list (data,stimulus))
mindaffectBCI.decoder.decoder.get_trial_start_end(msgs, start_ts=None)[source]

get the start+end times of the trials in a utopia message stream

Parameters:
  • msgs ([mindaffectBCI.UtopiaMessage]) – list of messages recenty recieved
  • start_ts (float, optional) – time-stamp for start of current trial. Defaults to None.
Returns:

list of completed trial (start_ts,end_ts) time-stamp tuples (float): start_ts for trial started but not finished (list UtopiaMessage): list of unprocessed messages

Return type:

(list (start_ts,end_ts))

mindaffectBCI.decoder.decoder.load_previous_dataset(f: str)[source]

search standard directory locations and load a previously saved (pickled) calibration dataset

Parameters:f (str, file-like) – buffered interface to the data and stimulus streams
Returns:list of stimulus,data pairs for each trial
Return type:(list of (data,stimulus))
mindaffectBCI.decoder.decoder.parse_args()[source]
mindaffectBCI.decoder.decoder.plot_trial_summary(Ptgt, Fy=None, Py=None, fs: float = None)[source]

Plot a summary of the trial decoding information

Parameters:
  • Ptgt (np.ndarray) – the current output probabilities
  • Fy (np.ndarray) – the raw output scores over time
  • Py (np.ndarray) – the raw probabilities for each target over time
  • fs (float, optional) – the data sample rate. Defaults to None.
mindaffectBCI.decoder.decoder.redraw_plots()[source]
mindaffectBCI.decoder.decoder.run(ui: mindaffectBCI.decoder.UtopiaDataInterface.UtopiaDataInterface = None, clsfr: mindaffectBCI.decoder.model_fitting.BaseSequence2Sequence = None, msg_timeout_ms: float = 100, host: str = None, prior_dataset: str = None, tau_ms: float = 450, offset_ms: float = 0, out_fs: float = 100, evtlabs=None, stopband=((45, 65), (5.5, 25, 'bandpass')), ftype='butter', order: int = 6, cv: int = 5, prediction_offsets=None, logdir=None, calplots: bool = False, predplots: bool = False, label: str = None, **kwargs)[source]

run the main decoder processing loop

Parameters:
  • ui (UtopiaDataInterface, optional) – The utopia data interface class. Defaults to None.
  • clsfr (BaseSequence2Sequence, optional) – the classifer to use when model fitting. Defaults to None.
  • msg_timeout_ms (float, optional) – timeout for getting new messages from the data-interface. Defaults to 100.
  • host (str, optional) – hostname for the utopia hub. Defaults to None.
  • tau_ms (float, optional) – length of the stimulus response. Defaults to 400.
  • offset_ms (float, optiona) – offset in ms to shift the analysis window. Use to compensate for response lag. Defaults to 0.
  • stopband (tuple, optional) – temporal filter specification for UtopiaDataInterface.butterfilt_and_downsample. Defaults to ((45,65),(5.5,25,’bandpass’))
  • ftype (str, optional) – type of temporal filter to use. Defaults to ‘butter’.
  • logdir (str, optional) – location to save output files. Defaults to None.
  • order (int, optional) – order of temporal filter to use. Defaults to 6.
  • out_fs (float, optional) – sample rate after the pre-processor. Defaults to 100.
  • evtlabs (tuple, optional) – the brain event coding to use. Defaults to None.
  • calplots (bool, optional) – flag if we make plots after calibration. Defaults to False.
  • predplots (bool, optional) – flag if we make plots after each prediction trial. Defaults to False.
  • prior_dataset ([str,(dataset)]) – calibration data from a previous run of the system. Used to pre-seed the model. Defaults to None.
  • prediction_offsets ([ListInt], optional) – a list of stimulus offsets to try at prediction time to cope with stimulus timing jitter. Defaults to None.
mindaffectBCI.decoder.decoder.send_prediction(ui: mindaffectBCI.decoder.UtopiaDataInterface.UtopiaDataInterface, Ptgt, used_idx=None, timestamp: int = -1)[source]

Send the current prediction information to the utopia-hub

Parameters:
  • ui (UtopiaDataInterface) – the interface to the data-hub
  • Ptgt (np.ndarray (outputs,)) – the current distribution of target probabilities over outputs
  • used_idx (np.ndarray, optional) – a set of output indices currently used. Defaults to None.
  • timestamp (int, optional) – time stamp for which this prediction applies. Defaults to -1.
mindaffectBCI.decoder.decoder.strip_unused(Y)[source]

strip unused outputs from the stimulus info in Y

Parameters:Y (np.ndarray (time,outputs)) – the full stimulus information, potentionally with many unused outputs
Returns:Y with unused outputs removed
Return type:(np.ndarray (time,used-outputs))

mindaffectBCI.decoder.decodingCurveSupervised module

mindaffectBCI.decoder.decodingCurveSupervised.compute_decoding_curve(Fy: numpy.ndarray, objIDs, integerationLengths, **kwargs)[source]

compute the decoding curves from the given epoch+output scores in Fy

Parameters:
  • (float (objIDs) – ((nM,)nTrl,nEp,nY)) : per-epoch output scores
  • (float – (nY,)) : the objectIDs for the outputs in Fy
  • integerationLengths (float (nInt,)) – a list of integeration lengths to compute peformance at
Returns:

bool) : flag if prediction was incorrect at this integeration length for this trial Perr (nTrl,nInt : float) : compute probability of error for this integeration length and trial aveProbErr (nInt: float) : average error probablility at this integeration length aveProbErrEst (nInt: float): average estimated error probability for this integeration length

Return type:

Yerr (nTrl,nInt

mindaffectBCI.decoder.decodingCurveSupervised.compute_stopping_curve(nInt, integerationLengths, Perr, Yerr)[source]

compute the stopping curve – which is the performance at times when stopping threshold (Perr) is passed

Parameters:
  • nInt (int) – number of time points to compute the stopping curve at
  • integerationLengths (list int) – the set of integeration lengths at which stopping curve is computed
  • Perr (nTrl,nInt) – Probability of error at each time point
  • Yerr (nTrl,nInt) – For each time point if the ‘best’ prediction is correct or not
Returns:

[description]

Return type:

[type]

mindaffectBCI.decoder.decodingCurveSupervised.decodingCurveSupervised(Fy, objIDs=None, nInt=(30, 25), dedup0=True, **kwargs)[source]

Compute a decoding curve, i.e. mistake-probability over time for probability based stopping from the per-epoch output scores

Parameters:
  • Fy (nModel,nTrl,nEp,nY) – similarity score for each input epoch for each output N.B. Supervised decoder only has 1 model!!!
  • objIDs (nY,) – mapping from rows of Fy to output object IDs. N.B. assumed objID==0 is true target N.B. if objIDs > size(Fy,2), then additional virtual outputs are added
  • nInt (2,) – the number of integeration lengths to use, numThresholds. Defaults to ([30,25])
Returns:

the actual integeration lengths in samples ProbErr (float (nInt,)) : empherical error probablility at this integeration length ProbErrEst (float (nInt,)) : decoder estimate of the error rate for each integeration length StopPerr (nInt,) : error rate at this average trial length when using ProbErrEst-thresholding based stopping StopThresh (nInt,) : ProbErrEst threshold used to get this average trial length. Yerr (bool (nTrl,nInt)) : flag if prediction was incorrect at this integeration length for this trial Perr (float (nTrl,nInt)) : compute probability of incorrect prediction for this integeration length and trial

Return type:

integerationLengths (int (nInt,))

mindaffectBCI.decoder.decodingCurveSupervised.plot_decoding_curve(integerationLengths, aveProbErr, *args)[source]

plot the decoding curve

Parameters:
  • integerationLengths ([type]) – [description]
  • aveProbErr ([type]) – [description]
mindaffectBCI.decoder.decodingCurveSupervised.print_decoding_curve(integerationLengths, aveProbErr, aveProbErrEst=None, stopYerr=None, stopPerrThresh=None)[source]

[summary]

Parameters:
  • integerationLengths ([type]) – [description]
  • aveProbErr ([type]) – [description]
  • aveProbErrEst ([type], optional) – [description]. Defaults to None.
  • stopYerr ([type], optional) – [description]. Defaults to None.
  • stopPerrThresh ([type], optional) – [description]. Defaults to None.
Returns:

[description]

Return type:

[type]

mindaffectBCI.decoder.decodingCurveSupervised.testcase()[source]

[summary]

mindaffectBCI.decoder.decodingSupervised module

mindaffectBCI.decoder.decodingSupervised.decodingSupervised(Fy, softmaxscale=3.5, marginalizemodels=True, marginalizedecis=False, prior=None, nocontrolamplitude=None, tiebreaking_noise=0.001, **kwargs)[source]

true-target estimator and error-probility estimator for each trial

Parameters:
  • Fy (nModel,nTrl,nEp,nY) – The output scores.
  • softmaxscale (float, optional) – the scale length to pass to zscore2Ptgt_softmax.py, this is the inverse noise sigma. Defaults to 3.5.
  • badFyThresh (int, optional) – threshold for detction of bad Fy entry, in std-dev. Defaults to 4.
  • centFy (bool, optional) – bool, do we center Fy before computing important (true). Defaults to True.
  • detrendFy (bool, optional) – [description]. Defaults to True.
  • nEpochCorrection (int, optional) – int, number of epochs to use a base for correction of number epochs in the sum. such that: zscore = Fy / ( sigma * ( 1+1/(nEpoch/nEpochErrorCorrection)) ), basically, nEpoch < nEpochCorrection have highly increased Perr, so unlikely to be selected. Defaults to 100.
  • minDecisLen (int, optional) –
    int, number of epochs to use as base for distribution of time-based decision points.
    i.e. decisions at, [1,2,4,…2^n]*exptDistDecis

    OR: minDecisLen<0 => decision point every abs(minDeicsLen) epochs. Defaults to 0.

  • maxDecisLen (int, optional) – maximum number of epochs for a decision. Defaults to 0.
  • bwdAccumulate (bool, optional) – accumulate data backwards from last epoch gathered. Defaults to False.
  • marginalizemodels (bool, optional) – [description]. Defaults to True.
  • marginalizedecis (bool, optional) – [description]. Defaults to False.
  • prior ([type], optional) – [description]. Defaults to None.
  • nocontrolamplitude ([type], optional) – [description]. Defaults to None.
  • priorsigma (tuple, optional) – (sigma,N) prior estimate of sigma2 and number pseudo-points. Defaults to (-1,120).
  • tiebreaking_noise ([type], optional) – [description]. Defaults to 1e-3.
Raises:

NotImplementedError – [description]

Returns:

the most likely / minimum error output for each decision point Perr (nTrl,nDecis): the probability that this selection is an ERROR for each decision point Ptgt (nTrl,nDecis,nY): the probability each target is the true target for each decision point decisMdl, decisEp

Return type:

Yest (nTrl,nDecis)

Copyright (c) MindAffect B.V. 2018

mindaffectBCI.decoder.decodingSupervised.decodingSupervised_streamed(Fy, softmaxscale=3, nocontrolamplitude=None, marginalizemodels=False)[source]

true-target estimator and error-probility estimator for each trial Inputs:

Fy - (nModel,nTrl,nEp,nY) [#Y x #Epoch x #Trials x nModels] softmaxscale - the scale length to pass to zscore2Ptgt_softmax.py badFyThresh - threshold for detction of bad Fy entry, in std-dev centFy - bool, do we center Fy before computing important (true) nEpochCorrection - int, number of epochs to use a base for correction of number epochs in the sum.

such that: zscore = Fy / ( sigma * ( 1+1/(nEpoch/nEpochErrorCorrection)) ), basically, nEpoch < nEpochCorrection have highly increased Perr, so unlikely to be selected
minDecisLen - int, number of epochs to use as base for distribution of time-based decision points.
i.e. decisions at, [1,2,4,…2^n]*exptDistDecis

OR: minDecisLen<0 => decision point every abs(minDeicsLen) epochs

bwdAccumulate - [bool], accumulate data backwards from last epoch gathered maxDecisLen - maximum number of epochs for a decision

Outputs:
Yest - (nTrl,nDecis) [ nDecis x nTrl ] the most likely / minimum error output for each decision point Perr - (nTrl,nDecis) [ nDecix x nTrl ] the probability that this selection is an ERROR for each decision point Ptgt - (nTrl,nDecis,nY) [ nY x nDecis x nTrl ] the probability each target is the true target for each decision point

Copyright (c) MindAffect B.V. 2018

mindaffectBCI.decoder.decodingSupervised.testcase()[source]

mindaffectBCI.decoder.devent2stimsequence module

mindaffectBCI.decoder.devent2stimsequence.devent2stimSequence(devents)[source]

convert a set of STIMULUSEVENT messages into a stimulus-sequence array with stimulus-times as expected by the utopia RECOGNISER

Inputs:
devents - [nEvt]:UtopiaMessage list of UtopiaMessage messages
i.e. a decoded utopia STIMULUSEVENT message, should be of type
{ msgID:’E’byte, timeStamp:int, objIDs:(nObj:byte), objState:(nObj:byte) }
Outputs:
Me - (nEvt,nY :int) The extract stimulus sequence objIDs - (nY :byte) The set of used object IDs stimTimes_ms - (nEvt :int) The timestamp of each event in milliseconds isistimEvent - (nEp :bool) Indicator which input events are stimulus events

Copyright (c) MindAffect B.V. 2018

mindaffectBCI.decoder.devent2stimsequence.upsample_stimseq(sample_ts, ss, stimulus_ts, objIDs=None, usedobjIDs=None, trlen=None)[source]

upsample a set of timestamped stimulus states to a sample rate WARNING: assumes sample_ts and stimulus_ts are in ascending sorted order!

mindaffectBCI.decoder.erpViewer module

mindaffectBCI.decoder.erpViewer.erpViewer(ui: mindaffectBCI.decoder.UtopiaDataInterface.UtopiaDataInterface, timeout_ms: float = inf, tau_ms: float = 500, offset_ms=(-15, 0), evtlabs=None, ch_names=None, nstimulus_events: int = 600, rank=3, center=True)[source]

simple sig-viewer using the ring-buffer for testing

mindaffectBCI.decoder.lower_bound_tracker module

class mindaffectBCI.decoder.lower_bound_tracker.lower_bound_tracker(window_size=200, C=(0.1, None), outlier_thresh=(1, None), step_size=10, step_threshold=2, a0=1, b0=0, warmup_size=10)[source]

Bases: object

sliding window lower bound trend tracker, which fits a line to the lower-bound of the inputs x,y

append(X, Y)[source]
fit(X, Y)[source]
getX(y)[source]
getY(x)[source]
reset(keep_model=False)[source]

reset the data for model fitting

Parameters:keep_model (bool, optional) – keep the model as well as data. Defaults to False.
static testcase(savefile='-')[source]
transform(X, Y)[source]
update()[source]

update the model based on the data in the sliding window

mindaffectBCI.decoder.model_fitting module

class mindaffectBCI.decoder.model_fitting.BaseEstimator[source]

Bases: object

class mindaffectBCI.decoder.model_fitting.BaseSequence2Sequence(evtlabs=('re', 'fe'), tau=18, offset=0, priorweight=200, startup_correction=100, prediction_offsets=None, minDecisLen=0, bwdAccumulate=False, verb=0)[source]

Bases: mindaffectBCI.decoder.model_fitting.BaseEstimator, mindaffectBCI.decoder.model_fitting.ClassifierMixin

Base class for sequence-to-sequence learning. Provides, prediction and scoring functions, but not the fitting method

static audc_score(Fy, marginalizemodels=True)[source]

compute area under decoding curve score from Fy, assuming Fy[:,:,0] is the true classes score

clear()[source]
cv_fit(X, Y, cv=5, fit_params: dict = {}, verbose: bool = 0, return_estimator: bool = True, calibrate_softmax: bool = True, retrain_on_all: bool = True)[source]

Cross-validated fit the model for generalization performance estimation

N.B. write our own as sklearn doesn’t work for getting the estimator values for structured output.

Parameters:
  • X ([type]) – [description]
  • Y ([type]) – [description]
  • cv (int, optional) – the number of folds to use, or a fold generator. Defaults to 5.
  • fit_params (dict, optional) – additional parameters to pass to the self.fit(X,Y,…) function. Defaults to dict().
  • verbose (bool, optional) – flag for model fitting verbosity. Defaults to 0.
  • return_estimator (bool, optional) – should we return the cross-validated predictions. Defaults to True.
  • calibrate_softmax (bool, optional) – after fitting the model, should we use the cross-validated predictions to calibrate the probability estimates. Defaults to True.
  • dedup0 (bool, optional) – should we de-duplicate copies of the ‘true-target’. Defaults to True.
  • retrain_on_all (bool, optional) – should we retrain the model on all the data after the cv folds. Defaults to True.
Returns:

dictionary with the results

Return type:

results (dict)

decode_proba(Fy, minDecisLen=0, bwdAccumulate=True, marginalizemodels=True, marginalizedecis=False)[source]

Convert stimulus scores to stimulus probabities of being the target

Parameters:
  • Fy (np.ndarray (tr,samp,nY)) – the multi-trial stimulus sequence scores
  • minDecisLen (int,optional) – minimum number of samples on which to make a prediction. Defaults to 0.
  • bwdAccumulate (bool, optional) – accumulate information backwards in the trials. Defaults to True.
  • marginalizemodels (bool,optional) – flag if we should marginalize over models when have multiple prediction models. Defaults to True.
  • marginalizedecis (bool, optional) – flag if we should marginalize over decision points when have multiple. Defaults to False.
Raises:

NotFittedError – [description]

Returns:

score for each decision point in each trial for each output. Higher score means more ‘likely’ to be the ‘true’ target

Return type:

Ptgt (np.ndarray (tr,nDecis,nY))

fit(X, Y)[source]

fit model mapping 2 multi-dim time series: X = (tr, samp, d), Y = (tr, samp, e)

is_fitted()[source]
plot_model(**kwargs)[source]
predict(X, Y, dedup0=True, prevY=None, offsets=None)[source]

Generate predictions with the fitted model for the paired data + stimulus-sequences

N.B. this implementation assumes linear coefficients in W_ (nM,nfilt,d) and R_ (nM,nfilt,nE,tau)
Parameters:
  • X (np.ndarray (tr,samp,d)) – the multi-trial data
  • Y (np.ndarray (tr,samp,nY)) – the multi-trial stimulus sequences
  • dedup0 ([type], optional) – remove duplicates of the Yidx==0, i.e. 1st, assumed true, output of Y. Defaults to True.
  • prevY ([type], optional) – previous stimulus sequence information. for partial incremental calls. Defaults to None.
  • offsets ([ListInt], optional) – list of offsets in Y to try when decoding, to override the class variable. Defaults to None.
Raises:

NotFittedError – raised if try to predict without first fitting

Returns:

score for each output in each trial. Higher score means more ‘likely’ to be the ‘true’ target

Return type:

Fy (np.ndarray (mdl,tr,samp,nY)

predict_proba(X, Y, marginalizemodels=True, marginalizedecis=True, startup_correction=100, minDecisLen=None, bwdAccumulate=True, dedup0=True, prevY=None)[source]

Predict the probability of each output for paired data/stimulus sequences

Parameters:
  • X (np.ndarray (tr,samp,d)) – the multi-trial data
  • Y (np.ndarray (tr,samp,nY)) – the multi-trial stimulus sequences
  • dedup0 (bool, optional) – remove duplicates of the Yidx==0, i.e. 1st, assumed true, output of Y. Defaults to True.
  • prevY (np.ndarray, optional) – previous stimulus sequence information. for partial incremental calls. Defaults to None.
  • minDecisLen (int,optional) – minimum number of samples on which to make a prediction
  • marginalizemodels (bool,optional) – flag if we should marginalize over models when have multiple prediction models. Defaults to True.
  • marginalizedecis (bool, optional) – flag if we should marginalize over decision points when have multiple. Defaults to False.
Raises:

NotFittedError – [description]

Returns:

Probability of each output being the target. Higher score means more ‘likely’ to be the ‘true’ target

Return type:

Ptgt (np.ndarray (tr,nDecis,nY)

score(X, Y)[source]

score this model on this data, N.B. for model_selection higher is better

stim2event(Y, prevY=None)[source]

transform Stimulus-encoded to brain-encoded, if needed

transform(X)[source]

transform raw data into raw stimulus scores by convolving X with the model, i.e. Fe = X (*) (W*R)

Parameters:X (np.ndarray (nTrl,nSamp,d) – The raw eeg data.
Returns:The raw stimulus scores.
Return type:Fe (np.ndarray (nTrl,nSamp,nE))
class mindaffectBCI.decoder.model_fitting.BwdLinearRegression(evtlabs=('re', 'fe'), tau=18, offset=0, reg=None, rcond=1e-05, badEpThresh=6, center=True, **kwargs)[source]

Bases: mindaffectBCI.decoder.model_fitting.BaseSequence2Sequence

Sequence 2 Sequence learning using backward linear regression W*X = Y

fit(X, Y)[source]

fit 2 multi-dim time series: X = (tr, samp, d), Y = (tr, samp, e)

class mindaffectBCI.decoder.model_fitting.ClassifierMixin[source]

Bases: object

class mindaffectBCI.decoder.model_fitting.FwdLinearRegression(evtlabs=('re', 'fe'), tau=18, offset=0, reg=None, rcond=1e-06, badEpThresh=6, center=True, **kwargs)[source]

Bases: mindaffectBCI.decoder.model_fitting.BaseSequence2Sequence

Sequence 2 Sequence learning using forward linear regression X = A*Y

fit(X, Y)[source]

fit 2 multi-dim time series: X = (tr, samp, d), Y = (tr, samp, e)

class mindaffectBCI.decoder.model_fitting.LinearSklearn(clsfr, labelizeY=False, ignore_unlabelled=True, badEpThresh=None, **kwargs)[source]

Bases: mindaffectBCI.decoder.model_fitting.BaseSequence2Sequence

Wrap a normal sk-learn classifier for sequence to sequence learning

fit(X, Y)[source]

fit model mapping 2 multi-dim time series: X = (tr, samp, d), Y = (tr, samp, e)

static sklearn_fit(X, Y, clsfr, tau, offset, labelizeY=False, ignore_unlabelled=True, badEpThresh=None, verb=0)[source]

fit 2 multi-dim time series: X = (tr, samp, d), Y = (tr, samp, e) using a given sklearn linear_model method

class mindaffectBCI.decoder.model_fitting.MultiCCA(evtlabs=('re', 'fe'), tau=18, offset=0, rank=1, reg=(1e-08, None), rcond=(0.0001, 1e-08), badEpThresh=6, symetric=False, center=True, CCA=True, priorweight=200, startup_correction=100, prediction_offsets=None, minDecisLen=100, bwdAccumulate=False, **kwargs)[source]

Bases: mindaffectBCI.decoder.model_fitting.BaseSequence2Sequence

Sequence 2 Sequence learning using CCA as a bi-directional forward/backward learning method

cv_fit(X, Y, cv=5, fit_params: dict = {}, verbose: bool = 0, return_estimator: bool = True, calibrate_softmax: bool = True, retrain_on_all: bool = True, ranks=None)[source]

cross validated fit to the data. N.B. write our own as sklearn doesn’t work for getting the estimator values for structured output.

fit(X, Y, stimTimes=None)[source]

fit 2 multi-dim time series: X = (tr, samp, d), Y = (tr, samp, Y)

fit_b(X)[source]

fit the bias parameter given the other parameters and a dataset

Parameters:X (np.ndarray) – the target data
exception mindaffectBCI.decoder.model_fitting.NotFittedError[source]

Bases: Exception

class mindaffectBCI.decoder.model_fitting.StratifiedKFold(n_splits)[source]

Bases: object

split(X, Y)[source]
mindaffectBCI.decoder.model_fitting.plot_model_weights(model: mindaffectBCI.decoder.model_fitting.BaseSequence2Sequence, ch_names=None)[source]
mindaffectBCI.decoder.model_fitting.testLeadLag()[source]
mindaffectBCI.decoder.model_fitting.testcase(dataset='toy', loader_args={})[source]
mindaffectBCI.decoder.model_fitting.visualize_Fy_Py(Fy, Py)[source]

mindaffectBCI.decoder.multipleCCA module

mindaffectBCI.decoder.multipleCCA.cvSupervised(Xe, Me, stimTimes, evtlabs=('re', 'fe'), n_splits=10, rank=1)[source]

do a cross-validated training of a multicca model using sklearn

mindaffectBCI.decoder.multipleCCA.filterbank_testcase()[source]
mindaffectBCI.decoder.multipleCCA.fit_predict(X, Y, tau=10, uss_args={}, mcca_args={})[source]
mindaffectBCI.decoder.multipleCCA.multipleCCA(Cxx=None, Cxy=None, Cyy=None, reg=1e-08, rank=1, CCA=True, rcond=0.0001, symetric=False)[source]
Compute multiple CCA decompositions using the given summary statistics
[J,W,R]=multiCCA(Cxx,Cxy,Cyy,regx,regy,rank,CCA)
Inputs:

Cxx = (d,d) current data covariance Cxy = (nM,nE,tau,d) current per output ERPs Cyy = (nM,nE,tau,nE,tau) current response covariance for each output reg = (1,) :float or (2,):float linear weighting reg strength or separate values for Cxx and Cyy

OR (d,) regularisation ridge coefficients for Cxx (0)

rank= [1x1] number of top cca components to return (1) CCA = [bool] or (2,):bool flag if we normalize the spatial dimension. (true) rcond = [float] tolerance for singular eigenvalues. (1e-4)

or [2x1] separate rcond for Cxx (rcond(1)) and Cyy (rcond(2)) or [2x1] (-1<-0) negative values = keep this fraction of eigen-values or (2,1) <-1 keep this many eigenvalues

symetric = [bool] us symetric whitener?

Outputs:
J = (nM,) optimisation objective scores W = (nM,rank,d) spatial filters for each output R = (nM,rank,nE,tau) responses for each stimulus event for each output

Examples

# Supervised CCA Y = (nEp/nSamp,nY,nE) indicator for each event-type and output of it’s type in each epoch X = (nEp/nSamp,tau,d) sliced pre-processed raw data into per-stimulus event responses stimTimes = (nEp) # sample number for each epoch or None if sample rate Cxx,Cxy,Cyy=updateSummaryStatistics(X, Y, stimTimes) J,w, r=multiCCA(Cxx, Cxy, Cyy, reg) # w=(nM,d)[dx1],r=(nM,nE,tau)[tau x nE] are the found spatial,spectral filters # incremental zeroTrain Cxx=[];Cxy=[];Cyy=[]; prediction=[]; while isCalibration:

# Slicing newX,newE,stimTimes= preprocessnSliceTrial(); #function which get 1 trials data+stim # Model Fitting Cxx, Cxy, Cyy= updateSummaryStatistics(newX, newE, stimTimes, Cxx, Cxy, Cyy); J, w, r = multipleCCA(Cxx, Cxy, Cyy, regx, regy) # w=[dx1],r=[tau x nE] are the found spatial,spectral filters

end # re-compute with current state, can try different regulisors, e.g. for adaptive bad-ch regx = updateRegFromBadCh(); J, w, r=multipleCCA(Cxx, Cxy, Cyy, reg)

Copyright (c) MindAffect B.V. 2018

mindaffectBCI.decoder.multipleCCA.robust_whitener(C: numpy.ndarray, reg: float = 0, rcond: float = 1e-06, symetric: bool = True, verb: int = 0)[source]

compute a robust whitener for the input covariance matrix C, s.t. isqrtC*C*isqrtC.T = I :param C: Sample covariance matrix of the data :type C: (d,d) np.ndarray :param reg: regularization strength when computing the whitener. Defaults to 0. :type reg: float, optional :param rcond: reverse-condition number for truncating degenerate eigen-values when computing the inverse. Defaults to 1e-6. :type rcond: float, optional :param symetric: flag to produce a symetric-whitener (which preserves location) or not. Defaults to True. :type symetric: bool, optional :param verb: verbosity level. Defaults to 0. :type verb: int, optional

Returns:The whitening matrix iW (np.ndarray): The inverse whitening matrix
Return type:W (np.ndarray)
mindaffectBCI.decoder.multipleCCA.testcase()[source]
mindaffectBCI.decoder.multipleCCA.testcase_matlab_summarystatistics()[source]

mindaffectBCI.decoder.multipleMCCA module

mindaffectBCI.decoder.multipleMCCA.cvSupervised(Xe, Me, stimTimes, evtlabs=('re', 'fe'), n_splits=10, rank=1)[source]

do a cross-validated training of a multicca model using sklearn

mindaffectBCI.decoder.multipleMCCA.multipleCCA(Cxx=None, Cxy=None, Cyy=None, reg=0, regy=0, rank=1, CCA=True, rcond=1e-06, symetric=False)[source]
Compute multiple multi-way CCA (MCCA) decompositions using the given summary statistics
[J,W,R]=multiCCA(Cxx,Cxy,Cyy,regx,regy,rank,CCA)
Inputs:

Cxx = (d,d) current data cross-covariance (or any n-way symetric covariance matrix) Cxy = (nM,nE,tau,d) current per output ERPs Cyy = (nM,nE,tau,nE,tau) current response covariance for each output reg = (1,) :float or (2,):float linear weighting reg strength or separate values for Cxx and Cyy

OR (d,) regularisation ridge coefficients for Cxx (0)

rank= [1x1] number of top cca components to return (1) CCA = [bool] or (2,):bool flag if we normalize the X component, or the Y component. (true) rcond = [float] tolerance for singular eigenvalues. (1e-4)

or (2,) separate rcond for Cxx (rcond(1)) and Cyy (rcond(2)) or (2,1) (-1<-0) negative values = keep this fraction of eigen-values or (2,1) <-1 keep this many eigenvalues

symetric = [bool] us symetric whitener?

Outputs:
J = [nY x 1] optimisation objective scores W = [d x rank x nY] spatial filters for each output R = [tau x nE x rank x nY] responses for each stimulus event for each output

Examples

# Supervised CCA Y = (nEp/nSamp,nY,nE) indicator for each event-type and output of it’s type in each epoch X = (nEp/nSamp,tau,d) sliced pre-processed raw data into per-stimulus event responses stimTimes = (nEp) # sample number for each epoch or None if sample rate Cxx,Cxy,Cyy=updateSummaryStatistics(X, Y, stimTimes) J,w, r=multiCCA(Cxx, Cxy, Cyy, reg) # w=(nM,d)[dx1],r=(nM,nE,tau)[tau x nE] are the found spatial,spectral filters # incremental zeroTrain Cxx=[];Cxy=[];Cyy=[]; prediction=[]; while isCalibration:

# Slicing newX,newE,stimTimes= preprocessnSliceTrial(); #function which get 1 trials data+stim # Model Fitting Cxx, Cxy, Cyy= updateSummaryStatistics(newX, newE, stimTimes, Cxx, Cxy, Cyy); J, w, r = multipleCCA(Cxx, Cxy, Cyy, regx, regy) # w=[dx1],r=[tau x nE] are the found spatial,spectral filters

end # re-compute with current state, can try different regulisors, e.g. for adaptive bad-ch regx = updateRegFromBadCh(); J, w, r=multipleCCA(Cxx, Cxy, Cyy, reg)

Copyright (c) MindAffect B.V. 2018

mindaffectBCI.decoder.multipleMCCA.plot_multicca_solution(w, r)[source]
mindaffectBCI.decoder.multipleMCCA.robust_whitener(C: numpy.ndarray, reg: float = 0, rcond: float = 1e-06, symetric: bool = True, verb: int = 0)[source]

compute a robust whitener for the input covariance matrix C, s.t. isqrtC*C*isqrtC.T = I :param C: Sample covariance matrix of the data :type C: (d,d) np.ndarray :param reg: regularization strength when computing the whitener. Defaults to 0. :type reg: float, optional :param rcond: reverse-condition number for truncating degenerate eigen-values when computing the inverse. Defaults to 1e-6. :type rcond: float, optional :param symetric: flag to produce a symetric-whitener (which preserves location) or not. Defaults to True. :type symetric: bool, optional :param verb: verbosity level. Defaults to 0. :type verb: int, optional

Returns:The whitening matrix iW (np.ndarray): The inverse whitening matrix
Return type:W (np.ndarray)
mindaffectBCI.decoder.multipleMCCA.testcase()[source]

mindaffectBCI.decoder.normalizeOutputScores module

mindaffectBCI.decoder.normalizeOutputScores.c4(n)[source]
mindaffectBCI.decoder.normalizeOutputScores.estimate_Fy_noise_variance(Fy, decisIdx=None, centFy=True, detrendFy=False, priorsigma=None, verb=0)[source]

Estimate the noise variance for Fy

Parameters:
  • Fy ([np.ndarray]) – (nTr,nEp,nY) the output scores
  • decisIdx ([type], optional) – [description]. Defaults to None.
  • centFy (bool, optional) – flag if we should center over outputs before computing variance. Defaults to True.
  • detrendFy (bool, optional) – flag if we should detrend Fy before computing it’s variance. Defaults to True.
  • priorsigma ([type], optional) – Prior estimate for the variance. Defaults to None.
Returns:

(nTr, nDecis) estimated variance per sample at each decision point

Return type:

sigma2 ([np.ndarray])

mindaffectBCI.decoder.normalizeOutputScores.estimate_Fy_noise_variance_2(Fy, decisIdx=None, centFy=True, detrendFy=False, priorsigma=None, verb=0)[source]

Estimate the noise variance for Fy

Parameters:
  • Fy ([np.ndarray]) – (nTr,nEp,nY) the output scores
  • decisIdx ([type], optional) – [description]. Defaults to None.
  • centFy (bool, optional) – flag if we should center over outputs before computing variance. Defaults to True.
  • detrendFy (bool, optional) – flag if we should detrend Fy before computing it’s variance. Defaults to True.
  • priorsigma ([type], optional) – Prior estimate for the variance. Defaults to None.
Returns:

(nTr, nDecis) estimated variance per sample at each decision point

Return type:

sigma2 ([np.ndarray])

mindaffectBCI.decoder.normalizeOutputScores.filter_Fy(Fy, filtLen=None, B=None)[source]
mindaffectBCI.decoder.normalizeOutputScores.get_valid_epochs_outputs(Fy, validTgt=None)[source]

get the number valid epoch and outputs from a zero-padded Fy set

Parameters:
  • Fy ([np.ndarray]) – (nTrl,nEp,nY) the output scores
  • validTgt ([np.ndarray]) – (nTrl,nY) flag if this output is used in this trial
Returns:

(nTrl,) number valid outputs per trial nEp ([np.ndarray]): (nTrl,) number valid epochs per trial validTgt ([np.ndarray]): (nTrl,nY) flag if this output is used in this trial

Return type:

nY ([np.ndarray])

mindaffectBCI.decoder.normalizeOutputScores.mktestFy(nY=10, nM=1, nEp=360, nTrl=100, sigstr=0.5, startupNoisefrac=0.5, offsetstr=10, trlenfrac=0.25)[source]
mindaffectBCI.decoder.normalizeOutputScores.normalizeOutputScores(Fy, validTgt=None, badFyThresh=4, centFy=True, detrendFy=False, nEpochCorrection=0, minDecisLen=0, maxDecisLen=0, bwdAccumulate=False, priorsigma=None)[source]

normalize the raw output scores to feed into the Perr computation

Parameters:
  • Fy (nM,nTr,nEp,nY) – float
  • validTgt (nM,nTr,nY) – bool indication of which outputs are used in each trial
  • badFyThresh – threshold for detction of bad Fy entry, in std-dev
  • centFy (bool) – do we center Fy before computing important (true)
  • nEpochCorrection (int) – number of epochs to use a base for correction of number epochs in the sum. basically, nEpoch < nEpochCorrection have highly increased Perr, so unlikely to be selected
  • minDecisLen (int) –
    int, number of epochs to use as base for distribution of time-based decision points.
    i.e. decisions at, [1,2,4,…2^n]*exptDistDecis

    OR: minDecisLen<0 => decision point every abs(minDeicsLen) epochs

  • maxDecisLen (int) – maximum number of epochs for a decision
  • bwdAccumulate (bool) – accumulate data backwards from last epoch gathered
  • prior_sigma (float,float) – prior estimate of the variance and it’s equivalent samples weight (sigma,N)
Returns:

scaled summed scores sFy_scale (nM,nTr,nDecis,1): the normalization scaling factor Nep (nDecis,): number of epochs included in each score nEp,nY (nTrl): the detected number epoch/output for each trial

Return type:

ssFy (nM,nTr,nDecis,nY)

Copyright (c) MindAffect B.V. 2018

mindaffectBCI.decoder.normalizeOutputScores.plot_normalizedScores(Fy, ssFy, scale_sFy, decisIdx)[source]

plot the normalized score and raw summed score for comparsion

mindaffectBCI.decoder.normalizeOutputScores.testcase()[source]

mindaffectBCI.decoder.normalizeOutputScores_streamed module

mindaffectBCI.decoder.normalizeOutputScores_streamed.compute_pval_curve(X, pval)[source]
mindaffectBCI.decoder.normalizeOutputScores_streamed.compute_softmax_curve(X, pval, scale=3)[source]
mindaffectBCI.decoder.normalizeOutputScores_streamed.incremental_estimate_noise_variance(Fy, old_sigma2, filtLen)[source]
mindaffectBCI.decoder.normalizeOutputScores_streamed.normalizeOutputScores_streamed(Fy, validTgt=None, badFyThresh=6, centFy=True, blockSize=30, filtLen=5)[source]

normalize the raw output scores to feed into the Perr computation Inputs:

Fy - (nM,nTr,nEp,nY):float validTgt - (nM,nTr,nY):bool indication of which outputs are used in each trial

badFyThresh - threshold for detction of bad Fy entry, in std-dev centFy - bool, do we center Fy before computing important (true) blockSize - maximum number of epochs single normalized sum
Outputs:
ssFy - (nM,nTr,nDecis,nY):float scaled summed scores scale_sFy - (nM,nTr,nDecis):float scaling factor for each decision point N - (nDecis):int the number of elements summed in each block

Copyright (c) MindAffect B.V. 2018

mindaffectBCI.decoder.normalizeOutputScores_streamed.softmax_nout_corr(n)[source]

approximate correction factor for probabilities out of soft-max to correct for number of outputs

mindaffectBCI.decoder.normalizeOutputScores_streamed.softmax_vs_nout(nruns, nout, sscale)[source]
mindaffectBCI.decoder.normalizeOutputScores_streamed.testcase(Fy=None)[source]

mindaffectBCI.decoder.offline_analysis module

mindaffectBCI.decoder.preprocess module

mindaffectBCI.decoder.preprocess.butter_filterbank(X: numpy.ndarray, filterbank, fs: float, axis=-2, order=4, ftype='butter', verb=1)[source]
mindaffectBCI.decoder.preprocess.extract_envelope(X, fs, stopband=None, whiten=True, filterbank=None, log=True, env_stopband=(10, -1), verb=False, plot=False)[source]

extract the envelope from the input data

Parameters:
  • X ([type]) – [description]
  • fs ([type]) – [description]
  • stopband ([type], optional) – pre-filter stop band. Defaults to None.
  • whiten (bool, optional) – flag if we spatially whiten before envelope extraction. Defaults to True.
  • filterbank ([type], optional) – set of filters to apply to extract the envelope for each filter output. Defaults to None.
  • log (bool, optional) – flag if we return raw power or log-power. Defaults to True.
  • env_stopband (tuple, optional) – post-filter on the extracted envelopes. Defaults to (10,-1).
  • verb (bool, optional) – verbosity level. Defaults to False.
  • plot (bool, optional) – flag if we plot the result of each preprocessing step. Defaults to False.
Returns:

the extracted envelopes

Return type:

X

mindaffectBCI.decoder.preprocess.fft_filterbank(X: numpy.ndarray, filterbank, fs: float, axis=-2, verb=1)[source]
mindaffectBCI.decoder.preprocess.fir(X: numpy.ndarray, ntap=3, dilation=1)[source]
mindaffectBCI.decoder.preprocess.plot_grand_average_spectrum(X, fs: float, axis: int = -2, ch_names=None, log=False)[source]
mindaffectBCI.decoder.preprocess.preprocess(X, Y, coords, fs=None, whiten=False, whiten_spectrum=False, decorrelate=False, badChannelThresh=None, badTrialThresh=None, center=False, car=False, standardize=False, stopband=None, filterbank=None, nY=None, fir=None)[source]

apply simple pre-processing to an input dataset

Parameters:
  • X ([type]) – the EEG data (tr,samp,d)
  • Y ([type]) – the stimulus (tr,samp,e)
  • coords ([type]) – [description]
  • whiten (float, optional) – if >0 then strength of the spatially regularized whitener. Defaults to False.
  • whiten_spectrum (float, optional) – if >0 then strength of the spectrally regularized whitener. Defaults to False.
  • badChannelThresh ([type], optional) – threshold in standard deviations for detection and removal of bad channels. Defaults to None.
  • badTrialThresh ([type], optional) – threshold in standard deviations for detection and removal of bad trials. Defaults to None.
  • center (bool, optional) – flag if we should temporally center the data. Defaults to False.
  • car (bool, optional) – flag if we should spatially common-average-reference the data. Defaults to False.
Returns:

the EEG data (tr,samp,d) Y ([type]): the stimulus (tr,samp,e) coords ([type]): meta-info for the data

Return type:

X ([type])

mindaffectBCI.decoder.preprocess.rmBadChannels(X: numpy.ndarray, Y: numpy.ndarray, coords, thresh=3.5)[source]

remove bad channels from the input dataset

Parameters:
  • X ([np.ndarray]) – the eeg data as (trl,sample,channel)
  • Y ([np.ndarray]) – the associated stimulus info as (trl,sample,stim)
  • coords ([type]) – the meta-info about the channel
  • thresh (float, optional) – threshold in standard-deviations for removal. Defaults to 3.5.
Returns:

X (np.ndarray) Y (np.ndarray) coords

mindaffectBCI.decoder.preprocess.rmBadTrial(X, Y, coords, thresh=3.5, verb=1)[source]

[summary]

Parameters:
  • X ([np.ndarray]) – the eeg data as (trl,sample,channel)
  • Y ([np.ndarray]) – the associated stimulus info as (trl,sample,stim)
  • coords ([type]) – the meta-info about the channel
  • thresh (float, optional) – threshold in standard-deviations for removal. Defaults to 3.5.
Returns:

X (np.ndarray) Y (np.ndarray) coords

mindaffectBCI.decoder.preprocess.spatially_whiten(X: numpy.ndarray, *args, **kwargs)[source]

spatially whiten the nd-array X

Parameters:X (np.ndarray) – the data to be whitened, with channels/space in the last axis
Returns:the whitened X W (np.ndarray): the whitening matrix used to whiten X
Return type:X (np.ndarray)
mindaffectBCI.decoder.preprocess.spectrally_whiten(X: numpy.ndarray, reg=0.01, axis=-2)[source]

spatially whiten the nd-array X

Parameters:X (np.ndarray) – the data to be whitened, with channels/space in the last axis
Returns:the whitened X W (np.ndarray): the whitening matrix used to whiten X
Return type:X (np.ndarray)
mindaffectBCI.decoder.preprocess.standardize_channel_power(X: numpy.ndarray, sigma2: numpy.ndarray = None, axis=-2, reg=0.1, alpha=0.001)[source]

Adaptively standardize the channel powers

Parameters:
  • X (np.ndarray) – The data to standardize
  • sigma2 (np.ndarray, optional) – previous channel powers estimates. Defaults to None.
  • axis (int, optional) – dimension of X which is time. Defaults to -2.
  • reg ([type], optional) – Regularisation strength for power estimation. Defaults to 1e-1.
  • alpha ([type], optional) – learning rate for power estimation. Defaults to 1e-3.
Returns:

the standardized version of X sigma2 : the estimated channel power at the last sample of X

Return type:

sX

mindaffectBCI.decoder.preprocess.temporally_decorrelate(X: numpy.ndarray, W: numpy.ndarray = 50, reg=0.5, eta=1e-07, axis=-2, verb=0)[source]

temporally decorrelate each channel of X by fitting and subtracting an AR model

Parameters:
  • X (np.ndarray trl,samp,d) – the data to be whitened, with channels/space in the last axis
  • W (tau,d) – per channel AR coefficients
  • reg (float) – regularization strength for fitting the AR model. Defaults to 1e-2
  • eta (float) – learning rate for the SGD. Defaults to 1e-5
Returns:

the whitened X W (np.ndarray (tau,d)): the AR model used to sample ahead predict X

Return type:

X (np.ndarray)

mindaffectBCI.decoder.preprocess.testCase_filterbank()[source]
mindaffectBCI.decoder.preprocess.testCase_spectralwhiten()[source]
mindaffectBCI.decoder.preprocess.testCase_temporallydecorrelate(X=None, fs=100)[source]
mindaffectBCI.decoder.preprocess.test_fir()[source]

mindaffectBCI.decoder.readCapInf module

mindaffectBCI.decoder.readCapInf.getPosInfo(chnames=None, capFile='1010', overridechnms=0, prefixMatch=False, verb=0, capDir=None)[source]

add electrode position info to a dimInfo structure

cnames,pos2d,pos3d,iseeg=getPosInfo(di,capFile,overridechnms,prefixMatch,verb,capDir)

Inputs:
cnames – channel names to get pos-info for capFile – file name of a file which contains the pos-info for this cap overridechnms – flag that we should ignore the channel names in di prefixMatch – [bool] match channel names if only the start matches? verb – [int] verbosity level (0) capDir – ‘str’ directory to search for capFile
Outputs:
cnames – [str] the names of the channels xy – (nCh,2):float the 2d position of the channels xyz – (nCh,2):float the 3d position of the channels iseeg - (nCh,):bool flag if this is an eeg channel, i.e. if it’s name matched
mindaffectBCI.decoder.readCapInf.latlong2xy(latlong)[source]

convert lat-long to 2-d unrolled x,y coordinates

mindaffectBCI.decoder.readCapInf.latlong2xyz(latlong)[source]

convert lat-long into 3-d x,y,z coords on the sphere

mindaffectBCI.decoder.readCapInf.readCapInf(cap='1010.txt', capRoots=None, verb=0)[source]

read a cap file

Cname,latlong,xy,xyz,capfile=readCapInf(cap,capDir)

Inputs:

cap – file name of the cap-file capRoot – directory(s) to look for caps in ([‘.’,mfiledir,mfiledir’/positions’,’../../resources/caps/’])

mindaffectBCI.decoder.readCapInf.testCase()[source]
mindaffectBCI.decoder.readCapInf.xy2latlong(xy)[source]

convert xy to lat-long, taking care to prevent division by 0

mindaffectBCI.decoder.readCapInf.xyz2xy(xyz)[source]

convert 3d xyz coords to unrolled 2d xy positions

mindaffectBCI.decoder.scoreOutput module

mindaffectBCI.decoder.scoreOutput.convWX(X, W)[source]

apply spatial filter W to X

mindaffectBCI.decoder.scoreOutput.convXYR(X, Y, W, R, offset)[source]
mindaffectBCI.decoder.scoreOutput.convYR(Y, R, offset=None)[source]

compute the convolution of Y with R

mindaffectBCI.decoder.scoreOutput.datasettest()[source]
mindaffectBCI.decoder.scoreOutput.dedupY0(Y, zerodup=True, yfeatdim=True, verb=0)[source]

remove outputs which are duplicates of the first (objID==0) output Inputs:

Y=(tr,ep,Y,e) zerodup : bool

if True, then if mi is the duplicate, then zero the duplicate, i.e. of Y[…,mi,:]=0 else, we zero out ojID==0, i.e. Y[…,0,:]=0
Outputs:
Y=(tr,ep,Y,e) version of Y with duplicates of 1st row of Y set to 0
mindaffectBCI.decoder.scoreOutput.plot_Fy(Fy, cumsum=True, label=None, legend=False, maxplots=25)[source]
mindaffectBCI.decoder.scoreOutput.plot_Fycomparsion(Fy, Fys, ti=0)[source]
mindaffectBCI.decoder.scoreOutput.plot_outputscore(X, Y, W=None, R=None, offset=0)[source]
mindaffectBCI.decoder.scoreOutput.scoreOutput(Fe_mTSe, Y_TSye, dedup0=None, R=None, offset=None, outputscore='ip')[source]

score each output given information on which stim-sequences corrospend to which inputs

Args

Fe_mTSe (nM,nTrl,nSamp,nE): similarity score for each event type for each stimulus Y_TSye (nTrl,nSamp,nY,nE): Indicator for which events occured for which outputs

nE=#event-types nY=#possible-outputs nEpoch=#stimulus events to process
R_mket (nM,nfilt,nE,tau): FWD-model (impulse response) for each of the event types, used to correct the
scores for correlated responses.

offset (int): A (set of) offsets to try when decoding. Defaults to None. dedup0 (int): remove duplicate copies of output O, >0 remove the copy, <0 remove objID==0 (used when cross validating calibration data) outputscore (str): type of score to compute. one-of: ‘ip’, ‘sse’. Defaults to ‘ip’

Returns
Fy_mTSy (nM,nTrl,nSamp,nY): similarity score for each input epoch for each output

Copyright (c) MindAffect B.V. 2018

mindaffectBCI.decoder.scoreOutput.testcases()[source]

mindaffectBCI.decoder.scoreStimulus module

mindaffectBCI.decoder.scoreStimulus.factored2full(W, R)[source]

convert a factored spatio-temporal model to a full model Inputs:

W (nM,rank,d) spatial filter set (BWD model) R (nM,rank,e,tau) temporal filter set (FWD model)
Output:
W (nM,e,tau,d) spatio-temporal filter (BWD model)
mindaffectBCI.decoder.scoreStimulus.plot_Fe(Fe)[source]
mindaffectBCI.decoder.scoreStimulus.scoreStimulus(X, W, R=None, b=None, offset=0, f=None, isepoched=None)[source]

Apply spatio-temporal (possibly factored) model to data Inputs:

X = (nTrl x nSamp x d) raw response for the current stimulus event
d=#electrodes tau=#response-samples nEpoch=#stimulus events to process
OR
(nTrl x nEpoch x tau x d) pre-sliced raw data

W = (nM x nfilt x d) spatial filters for each output R = (nM x nfilt x nE x tau) responses for each stimulus event for each output

OR
W = (nM x nE x tau x d) spatio-temporal filter per event type and model R = None b = (nE,1) bias for each stimulus type offset = 0 (1,1) offset in X for applying W
Outputs:
Fe= (nM x nTrl x nEpoch/nSamp x nE) similarity score for each input epoch for each output

Copyright (c) MindAffect B.V. 2018

mindaffectBCI.decoder.scoreStimulus.scoreStimulusCont(X, W, R=None, b=None, offset=0)[source]

Apply spatio-tempoal (possibly factored) model to raw (non epoched) data

Parameters:
  • X (np.ndarray (nTr,nSamp,d)) – raw per-trial data
  • W (np.ndarray (nM,nfilt,d)) – spatial filters for each factor
  • R (np.ndarray (nM,nfilt,nE,tau) – responses for each stimulus event for each output
  • b (np.ndarray (nE,1)) – offset for each stimulus type
Returns:

similarity score for each input epoch for each output

Return type:

np.ndarray (nM,nTrl,nSamp,nE)

mindaffectBCI.decoder.scoreStimulus.scoreStimulusEpoch(X, W, R=None, b=None)[source]
Apply spatio-temporal (possibly factored) model to epoched data
X = (nTrl x nEpoch x tau x d) pre-sliced raw data W = (nM x nfilt x d) spatial filters for each output R = (nM x nfilt x nE x tau) responses for each stimulus event for each output
OR
W = (nM x nE x tau x d) spatio-temporal filter per event type and model R = None b = (nE,1) offset for each stimulus type
Outputs:
Fe= (nM x nTrl x nEpoch/nSamp x nE) similarity score for each input epoch for each output
mindaffectBCI.decoder.scoreStimulus.scoreStimulusEpoch_factored(X, W, R, b=None)[source]
Apply factored spatio-temporal model to epoched data
X = (nTrl x nEpoch x tau x d) pre-sliced raw data W = (nM x nfilt x d) spatial filters for each output R = (nM x nfilt x nE x tau) responses for each stimulus event for each output b = (nE,1) offset for each stimulus type
Outputs:
Fe= (nM x nTrl x nEpoch x nE) similarity score for each input epoch for each output
mindaffectBCI.decoder.scoreStimulus.scoreStimulusEpoch_full(X, W, b=None)[source]
Apply full spatio-temporal model to epoched data
X = (nTrl x nEpoch x tau x d) pre-sliced raw data W = (nM x nE x tau x d) spatio-temporal filter per event type and model b = (nE,1) offset for each stimulus type
Outputs:
Fe= (nM x nTrl x nEpoch/nSamp x nE) similarity score for each input epoch for each output
mindaffectBCI.decoder.scoreStimulus.testcase()[source]

mindaffectBCI.decoder.sigViewer module

mindaffectBCI.decoder.sigViewer.parse_args()[source]
mindaffectBCI.decoder.sigViewer.run(ui: mindaffectBCI.decoder.UtopiaDataInterface.UtopiaDataInterface = None, host=None, timeout_ms: float = inf, center=True, timerange: int = 5, nstimulus_lines: int = 1, ndata_lines: int = -1, datastep: int = 20, stimstep: int = 1, stopband=((0, 3), (25, -1)), out_fs=60, ch_names=None)[source]

simple sig-viewer using the ring-buffer for testing

mindaffectBCI.decoder.sigViewer.sigViewer(*args, **kwargs)[source]

mindaffectBCI.decoder.startUtopiaHub module

mindaffectBCI.decoder.startUtopiaHub.run(label='', logdir=None)[source]

mindaffectBCI.decoder.stim2event module

mindaffectBCI.decoder.stim2event.stim2event(M, evtypes=('re', 'fe'), axis=-1, oM=None)[source]

convert per-sample stimulus sequence into per-sample event sequence (e.g. rising/falling edge, or long/short flash)

Parameters:
  • M (..samp) or (..,samp,nY) – for and/non-target features
  • - [nE] (evnames) – str list of strings: “0”, “1”, “00”, “11”, “01” (aka. ‘re’), “10” (aka, fe), “010” (aka. short), “0110” (aka long) “nt”+evtname : non-target event, i.e. evtname occured for any other target “any”+evtname: any event, i.e. evtname occured for any target “rest” - not any of the other event types, N.B. must be last in event list “raw” - unchanged input intensity coding “grad” - 1st temporal derivative of the raw intensity
  • - (oM) –
  • -
Outputs:
evt - (M.shape,nE) event sequence

Examples

#For a P300 bci, with target vs. non-target response use:
M = np.array([[1,0,0,0,0,0,1,0],[0,0,1,0,0,0,0,0],[0,0,0,0,1,0,0,0]]).T E = stim2event(M,evtypes=[‘re’,’ntre’], axis=-2)
#Or modeling as two responses, target-stim-response and any-stim-response
E = stim2event(M,evtypes=(‘re’,’anyre’), axis=-2)
mindaffectBCI.decoder.stim2event.testcase()[source]

mindaffectBCI.decoder.timestamp_check module

mindaffectBCI.decoder.timestamp_check.timestampPlot(filename=None)[source]

mindaffectBCI.decoder.trigger_check module

mindaffectBCI.decoder.trigger_check.run(hostname='-', stopband=(0.1, 45, 'bandpass'), fs_out=250, **kwargs)[source]

online continuously updating trigger check plot

mindaffectBCI.decoder.trigger_check.triggerPlot(X, Y, fs, clsfr=None, fig=None, evtlabs=('re', 'fe'), tau_ms=125, offset_ms=-25, max_samp=10000, trntrl=None, plot_model=True, plot_trial=True, ax=None, **kwargs)[source]
mindaffectBCI.decoder.trigger_check.trigger_check(filename=None, evtlabs=('re', 'fe'), tau_ms=125, offset_ms=-25, stopband=(0.1, 45, 'bandpass'), fs_out=250, trntrl=slice(None, 10, None), trnsamp=6000, max_samp=6000, plot_model=True, plot_trial=True, plot_epoch_lines=False, **kwargs)[source]

make a set of visualizations of the stimulus->measurement time-lock

Parameters:
  • filename ([type], optional) – The name of the file to load. Defaults to None.
  • evtlabs (tuple, optional) – The event coding to use for how stimulus changes map into trigger inputs. Defaults to (‘0’,’1’).
  • tau_ms (int, optional) – The duration of the stimulus response. Defaults to 400.
  • offset_ms (int, optional) – Offset of the start of the stimulus response w.r.t. the trigger time. Defaults to -50.
  • max_samp (int, optional) – Limit in the number of samples for each trial. Defaults to 6000.
  • stopband (tuple, optional) – Temporal filter used to pre-process the EEG. Defaults to (.1,45,’bandpass’).
  • fs_out (int, optional) – Sample rate of the EEG used for analysis. Defaults to 250.

mindaffectBCI.decoder.updateSummaryStatistics module

mindaffectBCI.decoder.updateSummaryStatistics.Cxx_diag2full(Cxx_tdd)[source]
mindaffectBCI.decoder.updateSummaryStatistics.Cyx_diag2full(Cyx_tyed, tau, offset=None)[source]
mindaffectBCI.decoder.updateSummaryStatistics.Cyy_diag2full(Cyy_tyee)[source]

convert diag compressed Cyy to full version

Parameters:Cyy ([type]) – (tau,nY,nE,nY,nE) or (tau,nY,nE,nE)
Returns:block up-scaled Cyy
Return type:Cyy_yetyet (nY,nE,tau,nE,tau)
mindaffectBCI.decoder.updateSummaryStatistics.Cyy_tyeye_diag2full(Cyy_tyeye)[source]

[summary]

Parameters:Cyy_tyeye ([type]) – the input compressed version of Cyy
Returns:the expanded version of Cyy
Return type:Cyy_yetyet
mindaffectBCI.decoder.updateSummaryStatistics.Cyy_yetet_diag2full(Cyy_yetet)[source]

[summary]

Parameters:Cyy_yetet ([type]) – the input compressed version of Cyy
Returns:the expanded version of Cyy
Return type:Cyy_yetyet
mindaffectBCI.decoder.updateSummaryStatistics.autocov(X, tau)[source]

Compute the cross-auto-correlation of X, i.e. spatial-temporal covariance Inputs:

X – (nTrl, nSamp, d) the data to have autocov computed
nSamp = temporal dim, d = spatial dim

tau – number of samples in the autocov

Outputs:
Ctdtd – (tau, d, tau, d)
mindaffectBCI.decoder.updateSummaryStatistics.compCxx_diag(X_TSd, tau: float, offset: float = 0, unitnorm: bool = True, center: bool = False)[source]

Compute the main tau diagonal entries of a Cyy tensor :param X_TSd: the new stim info to be added

Indicator for which events occured for which outputs nE=#event-types nY=#possible-outputs nEpoch=#stimulus events to process
Parameters:
  • tau (int) – number of time-shifts to compute over
  • offset (int) – offset in for tau=0 (Note: ignored here)
  • unitnorm (bool) – flag if we normalize the Cyy with number epochs. Defaults to True.
Returns:

Cxx_tdd – (tau, d, d)

mindaffectBCI.decoder.updateSummaryStatistics.compCxx_full(X_TSd, tau: float, offset=0, unitnorm: bool = False, center: bool = False)[source]

Compute the main tau diagonal entries of a Cyy tensor :param X_TSd: the input d dimensional data :type X_TSd: nTrl, nSamp, d :param tau: number of time-shifts to compute over :type tau: int :param offset: offset in for tau=0 (Note: ignored here) :type offset: int :param unitnorm: flag if we normalize the Cyy with number epochs. Defaults to True. :type unitnorm: bool

Returns:Cxx_fdfd – (tau, d, tau d) the full cross auto-covariance
mindaffectBCI.decoder.updateSummaryStatistics.compCyx_diag(X_TSd, Y_TSye, tau=None, offset=0, center=False, verb=0, unitnorm=True)[source]

Args: X_TSd (nTrl, nSamp, d): raw response for the current stimulus event

d=#electrodes
Y_TSye (nTrl, nSamp, nY, nE): Indicator for which events occured for which outputs
nE=#event-types nY=#possible-outputs nEpoch=#stimulus events to process
Returns:cross covariance at different offsets taus : relative offsets (t_y - t_x)
Return type:Cyx_tyed (nY, nE, tau, d)
mindaffectBCI.decoder.updateSummaryStatistics.compCyx_full(X_TSd, Y_TSye, tau=None, offset=0, center=False, verb=0, unitnorm=True)[source]

Args: X_TSd (nTrl, nSamp, d): raw response for the current stimulus event

d=#electrodes
Y_TSye (nTrl, nSamp, nY, nE): Indicator for which events occured for which outputs
nE=#event-types nY=#possible-outputs nEpoch=#stimulus events to process
Returns:cross covariance at different offsets
Return type:Cyx_tyetd (nY, nE, tau, d)
mindaffectBCI.decoder.updateSummaryStatistics.compCyy_diag(Y, tau: float, unitnorm: bool = True)[source]

Compute the main tau diagonal entries of a Cyy tensor :param Y: the new stim info to be added

Indicator for which events occured for which outputs nE=#event-types nY=#possible-outputs nEpoch=#stimulus events to process
Parameters:
  • tau (int) – number of samples in the stimulus response
  • unitnorm (bool) – flag if we normalize the Cyy with number epochs. Defaults to True.
Returns:

Return type:

Cyy_tyeye (tau,nY,nE,nY,nE)

mindaffectBCI.decoder.updateSummaryStatistics.compCyy_diag_perY(Y, tau: float, unitnorm: bool = True, perY: bool = True)[source]

Compute the main tau diagonal entries of a Cyy tensor for each output independently :param Y_TSye: the new stim info to be added

Indicator for which events occured for which outputs nE=#event-types nY=#possible-outputs nEpoch=#stimulus events to process
Parameters:
  • tau (int) – number of samples in the stimulus response
  • unitnorm (bool) – flag if we normalize the Cyy with number epochs. Defaults to True.
Returns:

Return type:

Cyy_tyee (tau, nY, nE, nE)

mindaffectBCI.decoder.updateSummaryStatistics.compCyy_full(Y_TSye, tau: int, offset: int = 0, unitnorm: bool = True)[source]

Compute the full YY cross auto-covariance

Parameters:
  • Y_TSye (nTrl, nSamp, nY, nE) – the new stim info to be added Indicator for which events occured for which outputs nE=#event-types nY=#possible-outputs nEpoch=#stimulus events to process
  • tau (int) – number of samples in the stimulus response
  • offset (int) – offset from time-zero for the cross computation (Note: ignored here)
  • unitnorm (bool) – flag if we normalize the Cyy with number epochs. Defaults to True.
Returns:

Cyy_yetyet – (nY, nE, tau, nY, nE, tau)

mindaffectBCI.decoder.updateSummaryStatistics.cov(X)[source]

Compute the spatial covariance Input:

X = (…,d) data, with features in the last dimension
Output:
Cxx = (d,d)
mindaffectBCI.decoder.updateSummaryStatistics.crossautocov(X, Y, tau, offset=0)[source]

Compute the cross-auto-correlation between 2 datasets, X,Y, i.e. the double spatial-temporal covariance Inputs:

X – (nTrl, nSamp, dx) the data to have autocov computed
nSamp = temporal dim, dx = spatial dim x
Y – (nTrl, nSamp, dy) the data to have autocov computed
nSamp = temporal dim, dy = spatial dim y
tau – :int number of samples in the cov
OR
[int,int] time lags for x and y
Outputs:
Ctdtd – (taux, dx, tauy, dy)
mindaffectBCI.decoder.updateSummaryStatistics.plotCxy(Cyx_yetd, evtlabs=None, fs=None)[source]
mindaffectBCI.decoder.updateSummaryStatistics.plot_erp(erp, evtlabs=None, outputs=None, times=None, fs=None, ch_names=None, axis=-1, plottype='plot', offset=0, ylim=None, suptitle: str = None, block: bool = False)[source]

Make a multi-plot of the event ERPs (as stored in erp) erp = (nY, nE, tau, d) current per output ERPs

mindaffectBCI.decoder.updateSummaryStatistics.plot_factoredmodel(A, R, S=None, evtlabs=None, times=None, ch_names=None, ch_pos=None, fs=None, offset_ms=None, offset=None, spatial_filter_type='Filter', label=None, ncol=2)[source]

Make a multi-plot of a factored model A_kd = k components and d sensors R_ket = k components, e events, tau samples response-duration

mindaffectBCI.decoder.updateSummaryStatistics.plot_subspace(X_TSfd, Y_TSye, W_kd, R_ket, S_y, f_f, offset: int = 0, fs: float = 100, block: bool = False, label: str = None)[source]

plot the subspace source activity of a fwd-bwd model

Parameters:
  • X_TSfd ([type]) – [description]
  • Y_TSye ([type]) – [description]
  • W_kd ([type]) – [description]
  • R_ket ([type]) – [description]
  • S_y ([type]) – [description]
  • f_f ([type]) – [description]
  • offset (int, optional) – [description]. Defaults to 0.
  • fs (float, optional) – [description]. Defaults to 100.
  • block (bool, optional) – [description]. Defaults to False.
  • label (str, optional) – [description]. Defaults to None.
mindaffectBCI.decoder.updateSummaryStatistics.plot_summary_statistics(Cxx_dd, Cyx_yetd, Cyy_yetet, evtlabs=None, outputs=None, times=None, ch_names=None, fs=None, label: str = None)[source]

Visualize the summary statistics (Cxx_dd, Cyx_yetd, Cyy) of a dataset

It is assumed the data has ‘d’ channels, with ‘nE’ different types of trigger event, and a response length of ‘tau’ for each trigger.

Parameters:
  • Cxx_dd (d,d) – spatial covariance
  • Cxy_yetd (nY, nE, tau, d) – per-output event related potentials (ERPs)
  • Cyy_yetet (nY, nE, tau, nE, tau) – updated response covariance for each output
  • evtlabs ([type], optional) – the labels for the event types. Defaults to None.
  • times ([type], optional) – values for the time-points along tau. Defaults to None.
  • ch_names ([type], optional) – textual names for the channels. Defaults to None.
  • fs ([type], optional) – sampling rate for the data along tau (used to make times if not given). Defaults to None.
mindaffectBCI.decoder.updateSummaryStatistics.plot_trial(X_TSd, Y_TSy, fs: float = None, ch_names=None, evtlabs=None, outputs=None, times=None, ylabel: str = 'ch + output', suptitle: str = None, block: bool = False)[source]

visualize a single trial with data and stimulus sequences

Parameters:
  • X_TSd ([type]) – raw data sequence
  • Y_TSy ([type]) – raw stimulus sequence
  • fs (float, optional) – sample rate of data and stimulus. Defaults to None.
  • ch_names (list-of-str, optional) – channel names for X. Defaults to None.
mindaffectBCI.decoder.updateSummaryStatistics.testCases()[source]
mindaffectBCI.decoder.updateSummaryStatistics.testComputationMethods()[source]
mindaffectBCI.decoder.updateSummaryStatistics.testCyy2()[source]
mindaffectBCI.decoder.updateSummaryStatistics.testSlicedvsContinuous()[source]
mindaffectBCI.decoder.updateSummaryStatistics.test_compCxx_diag()[source]
mindaffectBCI.decoder.updateSummaryStatistics.test_compCyx_diag()[source]
mindaffectBCI.decoder.updateSummaryStatistics.updateCxx(Cxx, X, stimTimes=None, tau: int = None, wght: float = 1, offset: int = 0, center: bool = False, unitnorm: bool = True)[source]
Parameters:
  • Cxx_dd (ndarray (d,d)) – current data covariance
  • X_TSd (nTrl, nSamp, d) – raw response at sample rate
  • stimTimes_samp (ndarray (nTrl, nEp)) – sample times for start each epoch. Used to detect
  • wght (float) – weight to accumulate this Cxx with the previous data, s.t. Cxx = Cxx_old*wght + Cxx_new. Defaults to 1.
  • center (bool) – flag if center the data before computing covariance? Defaults to True.
Returns:

current data covariance

Return type:

Cxx_dd (ndarray (d,d))

mindaffectBCI.decoder.updateSummaryStatistics.updateCxy(Cxy, X, Y, stimTimes=None, tau=None, wght=1, offset=0, center=False, verb=0, unitnorm=True)[source]
Parameters:
  • X_TSd (nTrl, nSamp, d) – raw response at sample rate
  • Y_TSye (nTrl, nSamp, nY, nE) – event indicator at sample rate
  • = (stimTimes_samp) – overlapping responses
  • Cxy_yetd (nY, nE, tau, d) – current per output ERPs
Returns:

current per output ERPs

Return type:

Cxy_yetd (nY, nE, tau, d)

mindaffectBCI.decoder.updateSummaryStatistics.updateCyy(Cyy, Y, stimTime=None, tau=None, wght=1, offset: float = 0, zeropadded=True, unitnorm=True, perY=True)[source]

Compute the Cyy tensors given new data :param Cyy_yetet: old Cyy info :param Y_TSye: the new stim info to be added

nE=#event-types nY=#possible-outputs nEpoch=#stimulus events to process
Parameters:
  • tau (int) – number of samples in the stimulus response
  • zeropadded (bool) – flag variable length Y are padded with 0s
  • wght (float) – weighting for the new vs. old data
  • unitnorm (bool) – flag if we normalize the Cyy with number epochs
Returns:

Return type:

Cyy_yetet (nY, tau, nE, nE)

mindaffectBCI.decoder.updateSummaryStatistics.updateSummaryStatistics(X, Y, stimTimes=None, Cxx=None, Cxy=None, Cyy=None, badEpThresh=4, halflife_samp=1, cxxp=True, cyyp=True, tau=None, offset=0, center=True, unitnorm=True, zeropadded: bool = True, perY=True)[source]

Compute updated summary statistics (Cxx_dd, Cxy_yetd, Cyy_yetet) for new data in X with event-info Y

Parameters:
  • X_TSd (nTrl, nEp, tau, d) –
    raw response for the current stimulus event
    d=#electrodes tau=#response-samples nEpoch=#stimulus events to process
    OR
    (nTrl, nSamp, d)
  • = (stimTimes_samp) –

    Indicator for which events occured for which outputs OR

    (nTrl, nSamp, nY, nE)
    nE=#event-types nY=#possible-outputs nEpoch=#stimulus events to process
  • = – overlapping responses
  • = int - the length of the impulse response in samples (tau) –
  • offset – int = relative shift of Y w.r.t. X
  • Cxx_dd (d,d) – current data covariance
  • Cxy_yetd (nY, nE, tau, d) – current per output ERPs
  • Cyy_yetet (nY, nE, tau, nE, tau) – current response covariance for each output
  • badEpThresh (float) – threshold for removing bad-data before fitting the summary statistics
  • center (bool) – do we center the X data before computing the summary statistics? (True)
  • halflife_samp (float) – forgetting factor for the updates Note: alpha = exp(log(.5)./(half-life)), half-life = log(.5)/log(alpha)
Returns:

updated data covariance Cxy_yetd (nY, nE, tau, d) : updated per output ERPs Cyy_yetet (nY, nE, tau, nE, tau): updated response covariance for each output

Return type:

Cxx_dd (d,d)

Examples

# Supervised CCA Y = (nEpoch/nSamp, nY, nE) [nE x nY x nEpoch] indicator for each event-type and output of it’s type in each epoch X = (nEpoch/nSamp, tau, d) [d x tau x nEpoch] sliced pre-processed raw data into per-stimulus event responses stimTimes = [nEpoch] sample numbers of the stimulus events

# OR None if X, Y are samples

[Cxx, Cxy, Cyy] = updateSummaryStatistics(X, Y, 3*np.arange(X.shape[0])); [J, w, r]=multipleCCA(Cxx, Cxy, Cyy)

mindaffectBCI.decoder.utils module

class mindaffectBCI.decoder.utils.RingBuffer(maxsize, shape, dtype=<class 'numpy.float32'>)[source]

Bases: object

time efficient linear ring-buffer for storing packed data, e.g. continguous np-arrays

append(x)[source]

add single element to the ring buffer

clear()[source]

empty the ring-buffer and reset to empty

extend(x)[source]

add a group of elements to the ring buffer

shape[source]
unwrap()[source]

get a view on the valid portion of the ring buffer

mindaffectBCI.decoder.utils.block_randomize(true_target, npermute, axis=-3, block_size=None)[source]

make a block random permutaton of the input array Inputs:

npermute: int - number permutations to make true_target: (…, nEp, nY, e): true target value for nTrl trials of length nEp flashes axis : int the axis along which to permute true_target
mindaffectBCI.decoder.utils.butter_sosfilt(X, stopband, fs: float, order: int = 6, axis: int = -2, zi=None, verb=True, ftype='butter')[source]

use a (cascade of) butterworth SOS filter(s) filter X along axis

Parameters:
  • X (np.ndarray) – the data to be filtered
  • stopband ([type]) – the filter band specifications in Hz, as a list of lists of stopbands (given as (low-pass,high-pass)) or pass bands (given as (low-cut,high-cut,’bandpass’))
  • fs (float) – the sampling rate of X
  • order (int, optional) – the desired filter order. Defaults to 6.
  • axis (int, optional) – the axis of X to filter along. Defaults to -2.
  • zi ([type], optional) – the internal filter state – propogate between calls for incremental filtering. Defaults to None.
  • verb (bool, optional) – Verbosity level for logging. Defaults to True.
  • ftype (str, optional) – The type of filter to make, one-of: ‘butter’, ‘bessel’. Defaults to ‘butter’.
Returns:

the filtered version of X sos (np.ndarray): the designed filter coefficients zi (np.ndarray): the filter state for propogation between calls

Return type:

X [np.ndarray]

mindaffectBCI.decoder.utils.equals_subarray(a, pat, axis=-1, match=-1)[source]

efficiently find matches of a 1-d sub-array along axis within an nd-array

mindaffectBCI.decoder.utils.extract_ringbuffer_segment(rb, bgn_ts, end_ts=None)[source]

extract the data between start/end time stamps, from time-stamps contained in the last channel of a nd matrix

mindaffectBCI.decoder.utils.idOutliers(X, thresh=4, axis=-2, verbosity=0)[source]

identify outliers with excessively high power in the input data Inputs:

X:float the data to identify outliers in axis:int (-2) axis of X to sum to get power thresh(float): threshold standard deviation for outlier detection verbosity(int): verbosity level
Returns:bool (X.shape axis==1) indicator for outlying elements epPower:float (X.shape axis==1) power used to identify bad
Return type:badEp
mindaffectBCI.decoder.utils.iir_sosfilt_sos(stopband, fs, order=4, ftype='butter', passband=None, verb=0)[source]

given a set of filter cutoffs return butterworth or bessel sos coefficients

mindaffectBCI.decoder.utils.lab2ind(lab, lab2class=None)[source]

convert a list of labels (as integers) to a class indicator matrix

mindaffectBCI.decoder.utils.randomSummaryStats(d=10, nE=2, tau=10, nY=1)[source]
mindaffectBCI.decoder.utils.robust_mean(X, thresh=(3, 3))[source]

Compute robust mean of values in X, using gaussian outlier criteria

Parameters:
  • X (the data) – the data
  • thresh (2,) – lower and upper threshold in standard deviations
Returns:

the robust mean good (): the indices of the ‘good’ data in X

Return type:

mu ()

mindaffectBCI.decoder.utils.save_butter_sosfilt_coeff(filename=None, stopband=((45, 65), (5.5, 25, 'bandpass')), fs=200, order=6, ftype='butter')[source]

design a butterworth sos filter cascade and save the coefficients

mindaffectBCI.decoder.utils.search_directories_for_file(f, *args)[source]

search a given set of directories for given filename, return 1st match

Parameters:
  • f (str) – filename to search for (or a pattern)
  • () (*args) – set for directory names to look in
Returns:

the first full path to where f is found, or f if not found.

Return type:

f (str)

mindaffectBCI.decoder.utils.sliceData(X, stimTimes_samp, tau=10)[source]
mindaffectBCI.decoder.utils.sliceY(Y, stimTimes_samp, featdim=True)[source]

Y = (nTrl, nSamp, nY, nE) if featdim=True OR Y=(nTrl, nSamp, nY) if featdim=False #(nE x nY x nSamp x nTrl)

mindaffectBCI.decoder.utils.sosfilt_2d_py(sos, X, axis=-2, zi=None)[source]

pure python fallback for second-order-sections filter in case scipy isn’t available

mindaffectBCI.decoder.utils.sosfilt_zi_py(sos)[source]

compute an initial state for a second-order section filter

mindaffectBCI.decoder.utils.sosfilt_zi_warmup(zi, X, axis=-1, sos=None)[source]

Use some initial data to “warmup” a second-order-sections filter to reduce startup artifacts.

Parameters:
  • zi (np.ndarray) – the sos filter, state
  • X ([type]) – the warmup data
  • axis (int, optional) – The filter axis in X. Defaults to -1.
  • sos ([type], optional) – the sos filter coefficients. Defaults to None.
Returns:

the warmed up filter coefficients

Return type:

[np.ndarray]

mindaffectBCI.decoder.utils.testNoSignal(d=10, nE=2, nY=1, isi=5, tau=None, nSamp=10000, nTrl=1)[source]
mindaffectBCI.decoder.utils.testSignal(nTrl=1, d=5, nE=2, nY=30, isi=5, tau=None, offset=0, nSamp=10000, stimthresh=0.6, noise2signal=1, irf=None)[source]
mindaffectBCI.decoder.utils.test_butter_sosfilt()[source]
mindaffectBCI.decoder.utils.test_sosfilt_py()[source]
mindaffectBCI.decoder.utils.testtestSignal()[source]
mindaffectBCI.decoder.utils.unwrap(x, range=None)[source]

unwrap a list of numbers to correct for truncation due to limited bit-resolution, e.g. time-stamps stored in 24bit integers

mindaffectBCI.decoder.utils.unwrap_test()[source]
mindaffectBCI.decoder.utils.upsample_codebook(trlen, cb, ep_idx, stim_dur_samp, offset_samp=(0, 0))[source]

upsample a codebook definition to sample rate Inputs:

trlen : (int) length after up-sampling cb : (nTr, nEp, …) the codebook ep_idx : (nTr, nEp) the indices of the codebook entries stim_dur_samp: (int) the amount of time the cb entry is held for offset_samp : (2,):int the offset for the stimulus in the upsampled trlen data
Outputs:
Y : ( nTrl, trlen, …) the up-sampled codebook
mindaffectBCI.decoder.utils.window_axis(a, winsz, axis=0, step=1, prependwindowdim=False)[source]

efficient view-based slicing of equal-sized equally-spaced windows along a selected axis of a numpy nd-array

mindaffectBCI.decoder.utils.zero_outliers(X, Y, badEpThresh=4, badEpChThresh=None, verbosity=0)[source]

identify and zero-out bad/outlying data

Inputs:

X = (nTrl, nSamp, d) Y = (nTrl, nSamp, nY, nE) OR (nTrl, nSamp, nE)

nE=#event-types nY=#possible-outputs nEpoch=#stimulus events to process

mindaffectBCI.decoder.zscore2Ptgt_softmax module

mindaffectBCI.decoder.zscore2Ptgt_softmax.calibrate_softmaxscale(f, validTgt=None, scales=(0.01, 0.02, 0.05, 0.1, 0.2, 0.3, 0.4, 0.5, 1, 1.5, 2, 2.5, 3, 3.5, 4, 5, 7, 10, 15, 20, 30), MINP=0.01, marginalizemodels=True, marginalizedecis=False, eta=0.05, error_weight=2)[source]

attempt to calibrate the scale for a softmax decoder to return calibrated probabilities

Parameters:
  • f ((nM,)nTrl,nDecis,nY) – normalized accumulated scores]
  • validTgt (bool (nM,)nTrl,nY) – which targets are valid in which trials
  • (list (scales) – int): set of possible soft-max scales to try
  • MINP (float) – minimium P-value. We clip the true-target p-val to this level as a way of forcing the fit to concentrate on getting the p-val right when high, rather than over penalizing when it’s wrong
Returns:

slope for softmax to return calibrated probabilities

Return type:

softmaxscale (float)

mindaffectBCI.decoder.zscore2Ptgt_softmax.entropy(p, axis=-1)[source]
mindaffectBCI.decoder.zscore2Ptgt_softmax.marginalize_scores(f, axis, prior=None, keepdims=False)[source]

marginalize the output scores to remove nuisance parameters, e.g. decis-pts, models.

Parameters:
  • f (np.ndarray (nModel,nTrial,nDecisPts,nOutput)) – the scores
  • axis ([listInt]) – the axis of f to marginalize over
  • prior ([type], optional) – prior over the dimesions of f. Defaults to None.
  • keepdims (bool, optional) – flag if we keep or compress the dims of f. Defaults to False.
Returns:

(np.ndarray): the marginalized f scores

Return type:

f

mindaffectBCI.decoder.zscore2Ptgt_softmax.mkTestFy(nY, nM, nEp, nTrl, sigstr, startup_lag)[source]
mindaffectBCI.decoder.zscore2Ptgt_softmax.softmax(f, axis=-1, validTgt=None)[source]

simple softmax over final dim of input array, with compensation for missing inputs with validTgt mask.

mindaffectBCI.decoder.zscore2Ptgt_softmax.softmax_nout_corr(n)[source]

approximate correction factor for probabilities out of soft-max to correct for number of outputs

mindaffectBCI.decoder.zscore2Ptgt_softmax.testcase(nY=10, nM=4, nEp=340, nTrl=500, sigstr=0.4, normSum=True, centFy=True, detrendFy=True, marginalizemodels=True, marginalizedecis=False, bwdAccumulate=False, nEpochCorrection=20, priorweight=100.0, startup_lag=0.1)[source]
mindaffectBCI.decoder.zscore2Ptgt_softmax.visPtgt(Fy, normSum, centFy, detrendFy, bwdAccumulate, marginalizemodels, marginalizedecis, nEpochCorrection, priorweight, minDecisLen=-1)[source]
mindaffectBCI.decoder.zscore2Ptgt_softmax.zscore2Ptgt_softmax(f, softmaxscale: float = 2, prior: numpy.ndarray = None, validTgt=None, marginalizemodels: bool = True, marginalizedecis: bool = False, peroutputmodel: bool = True)[source]

convert normalized output scores into target probabilities

Parameters:
  • f (nM,nTrl,nDecis,nY) – normalized accumulated scores
  • softmaxscale (float, optional) – slope to scale from scores to probabilities. Defaults to 2.
  • validtgtTrl (bool nM,nTrl,nY) – which targets are valid in which trials
  • peroutputmode (bool, optional) – assume if nM==nY that we have 1 model per output. Defaults to True.
  • prior ([nM,nTrl,nDecis,nY]) – prior probabilities over the different dimesions of f. e.g. if want a prior over Models should be shape (nM,1,1,1), for a prior over outputs (nY,). Defaults to None.
Returns:

target probability for each trial (if marginalizemodels and marginalizedecis is True)

Return type:

Ptgt (nTrl,nY)

Module contents