mindaffectBCI.decoder package¶
Subpackages¶
- mindaffectBCI.decoder.offline package
- Submodules
- mindaffectBCI.decoder.offline.load_brainsonfire module
- mindaffectBCI.decoder.offline.load_brainstream module
- mindaffectBCI.decoder.offline.load_cocktail module
- mindaffectBCI.decoder.offline.load_mTRF_audio module
- mindaffectBCI.decoder.offline.load_mark_EMG module
- mindaffectBCI.decoder.offline.load_mindaffectBCI module
- mindaffectBCI.decoder.offline.load_ninapro_db2 module
- mindaffectBCI.decoder.offline.load_openBMI module
- mindaffectBCI.decoder.offline.load_p300_prn module
- mindaffectBCI.decoder.offline.load_twofinger module
- mindaffectBCI.decoder.offline.read_buffer_offline module
- mindaffectBCI.decoder.offline.read_mindaffectBCI module
- Module contents
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
-
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.
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.
-
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]
-
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.
-
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
-
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
-
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]
-
-
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.
-
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
-
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]
-
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.
-
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 implementedReturns: 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.ccaViewer module¶
-
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.
dataset_generator
(dataset, **kwargs)[source]¶ generator for individual datasets from the given set of datasets
-
mindaffectBCI.decoder.datasets.
lowlands
()[source]¶ generate the directory+filename info for the lowlands noisetagging dataset
-
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.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.
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.
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.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.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.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.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
mindaffectBCI.decoder.model_fitting module¶
-
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
-
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))
-
predict
(X, Y, dedup0=True, prevY=None, offsets=None)[source]¶ Generate predictions with the fitted model for the 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 ([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 fittingReturns: 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)
-
static
-
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
-
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
-
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
-
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.
-
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.
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 eigenvaluessymetric = [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 filtersend # 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.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 eigenvaluessymetric = [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 filtersend # 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.
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.normalizeOutputScores module¶
-
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.
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_streamed module¶
-
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.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.
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.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.scoreOutput module¶
-
mindaffectBCI.decoder.scoreOutput.
convYR
(Y, R, offset=None)[source]¶ compute the convolution of Y with R
-
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.
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.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.
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.sigViewer module¶
-
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.startUtopiaHub module¶
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.timestamp_check module¶
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.
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 processParameters: - 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 processParameters: - 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 processParameters: - 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.
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.
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 processParameters: - 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)
- X_TSd (nTrl, nEp, tau, d) –
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
-
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 levelReturns: 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.
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.
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.
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.
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.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.
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.
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)