pyntbci.classifiers.rCCA

class pyntbci.classifiers.rCCA(stimulus: ndarray[Any, dtype[_ScalarType_co]], fs: int, event: str = 'duration', onset_event: bool = False, decoding_length: float | None = None, decoding_stride: float | None = None, encoding_length: float | list[float] | None = None, encoding_stride: float | list[float] | None = None, score_metric: str = 'correlation', latency: ndarray[Any, dtype[_ScalarType_co]] | None = None, ensemble: bool = False, amplitudes: ndarray[Any, dtype[_ScalarType_co]] | None = None, gamma_x: float | list[float] | ndarray[Any, dtype[_ScalarType_co]] | None = None, gamma_m: float | list[float] | ndarray[Any, dtype[_ScalarType_co]] | None = None, cov_estimator_x: BaseEstimator | None = None, cov_estimator_m: BaseEstimator | None = None, n_components: int = 1, squeeze_components: bool = True, alpha_x: float | None = None, alpha_m: float | None = None, tmin: float = 0)

Reconvolution CCA classifier. It performs a spatial and temporal decomposition (reconvolution [3]) within a CCA [4] to perform spatial filtering as well as template prediction [5].

Parameters:

• stimulus (NDArray) – The stimulus used for stimulation of shape (n_classes, n_samples). Should be sampled at fs. One cycle (i.e., one stimulus-repetition) is sufficient.

• fs (int) – The sampling frequency of the EEG data in Hz.

• event (str (default: "duration")) – The event definition to map stimulus to events.

• onset_event (bool (default: False)) – Whether to add an event for the onset of stimulation. Added as last event.

• decoding_length (float (default: None)) – The length of the spectral filter for each data channel in seconds. If None, it is set to 1/fs, equivalent to 1 sample, such that no phase-shifting is performed. thus no (spatio-)spectral filter is learned.

• decoding_stride (float (default: None)) – The stride of the spectral filter for each data channel in seconds. If None, it is set to 1/fs, equivalent to 1 sample, such that no stride is used.

• encoding_length (float | list[float] (default: None)) – The length of the transient response(s) for each of the events in seconds. If None, it is set to 1/fs, equivalent to 1 sample, such that no phase-shifting is performed.

• encoding_stride (float | list[float] (default: None)) – The stride of the transient response(s) for each of the events in seconds. If None, it is set to 1/fs, equivalent to 1 sample, such that no stride is used.

• score_metric (str (default: "correlation")) – Metric to use to compute the overlap of templates and single-trials during testing: correlation, Euclidean.

• latency (NDArray (default: None)) – The raster latencies of each of the classes of shape (n_classes,) that the data/templates need to be corrected for.

• ensemble (bool (default: False)) – Whether to use an ensemble classifier, that is, a separate spatial filter for each class.

• amplitudes (NDArray) – The amplitude of the stimulus of shape (n_classes, n_samples). Should be sampled at fs.

• gamma_x (float | list[float] | NDArray (default: None)) – Regularization on the covariance matrix for CCA for all or each individual parameter along X (channels). If None, no regularization is applied. The gamma_x ranges from 0 (no regularization) to 1 (full regularization).

• gamma_m (float | list[float] NDArray (default: None)) – Regularization on the covariance matrix for CCA for all or each individual parameter along M (samples). If None, no regularization is applied. The gamma_m ranges from 0 (no regularization) to 1 (full regularization).

• cov_estimator_x (BaseEstimator (default: None)) – A BaseEstimator object with a fit method that estimates a covariance matrix of the EEG data, the decoding matrix. If None, a custom empirical covariance is used.

• cov_estimator_m (BaseEstimator (default: None)) – A BaseEstimator object with a fit method that estimates a covariance matrix of the stimulus encoding matrix. If None, a custom empirical covariance is used.

• n_components (int (default: 1)) – The number of CCA components to use.

• squeeze_components (bool (default: True)) – Remove the component dimension when n_components=1.

• alpha_x (float (default: None)) – Amount of variance to retain in computing the inverse of the covariance matrix of X. If None, all variance.

• alpha_m (float (default: None)) – Amount of variance to retain in computing the inverse of the covariance matrix of M. If None, all variance.

• tmin (float (default: 0)) – The start of stimulation in seconds. Can be used if there was a delay in the marker.

cca_

The CCA used to fit the spatial and temporal filters. If ensemble=False, len(cca_)=1, otherwise len(cca_)=n_classes.

Type:

list[TransformerMixin]

w_

The weight vector representing a spatial filter of shape (n_channels, n_components). If ensemble=True, then the shape is (n_channels, n_components, n_classes).

Type:

NDArray

r_

The weight vector representing a temporal filter of shape (n_events * n_event_samples, n_components). If ensemble=True, then the shape is (n_events * n_event_samples, n_components, n_classes).

Type:

NDArray

Ts_

The template matrix representing the expected responses of shape (n_classes, n_components, n_samples) for stimulus cycle 1 (i.e., it includes the onset of stimulation and does not contain the tails of previous cycles).

Type:

NDArray

Tw_

The template matrix representing the expected responses of shape (n_classes, n_components, n_samples) for stimulus cycles 2 and further (i.e., it does not include the onset of stimulation but does include the tails of previous cycles).

Type:

NDArray

References

[3]

Thielen, J., van den Broek, P., Farquhar, J., & Desain, P. (2015). Broad-Band visually evoked potentials: re(con)volution in brain-computer interfacing. PLOS ONE, 10(7), e0133797. doi: 10.1371/journal.pone.0133797

[4]

Thielen, J., Marsman, P., Farquhar, J., & Desain, P. (2017). Re(con)volution: accurate response prediction for broad-band evoked potentials-based brain computer interfaces. Brain-Computer Interface Research: A State-of-the-Art Summary 6, 35-42. doi: 10.1007/978-3-319-64373-1_4

[5]

Thielen, J., Marsman, P., Farquhar, J., & Desain, P. (2021). From full calibration to zero training for a code-modulated visual evoked potentials for brain–computer interface. Journal of Neural Engineering, 18(5), 056007. doi: 10.1088/1741-2552/abecef

decision_function(X: ndarray[Any, dtype[_ScalarType_co]]) → ndarray[Any, dtype[_ScalarType_co]]

Apply the classifier to get classification scores for X.

Parameters:

X (NDArray) – The matrix of EEG data of shape (n_trials, n_channels, n_samples).

Returns:

scores – The similarity scores of shape (n_trials, n_classes, n_components) or (n_trials, n_classes) if n_components=1 and squeeze_components=True.

Return type:

NDArray

fit(X: ndarray[Any, dtype[_ScalarType_co]], y: ndarray[Any, dtype[_ScalarType_co]]) → ClassifierMixin

The training procedure to fit a rCCA on supervised EEG data.

Parameters:

• X (NDArray) – The matrix of EEG data of shape (n_trials, n_channels, n_samples).

• y (NDArray) – The vector of ground-truth labels of the trials in X of shape (n_trials). Note, these denote the index at which to find the associated stimulus!

Returns:

self – Returns the instance itself.

Return type:

ClassifierMixin

get_T(n_samples: int | None = None) → ndarray[Any, dtype[_ScalarType_co]]

Get the templates.

Parameters:

n_samples (int (default: None)) – The number of samples requested. If None, one stimulus cycle is used.

Returns:

T – The templates of shape (n_classes, n_components, n_samples).

Return type:

NDArray

predict(X: ndarray[Any, dtype[_ScalarType_co]]) → ndarray[Any, dtype[_ScalarType_co]]

The testing procedure to apply rCCA to novel EEG data.

Parameters:

X (NDArray) – The matrix of EEG data of shape (n_trials, n_channels, n_samples).

Returns:

y – The predicted labels of shape (n_trials, n_components).

Return type:

NDArray

set_amplitudes(amplitudes: ndarray[Any, dtype[_ScalarType_co]]) → None

Set the amplitudes, and as such change the templates.

Parameters:

amplitudes (NDArray) – The amplitude of the stimulus of shape (n_classes, n_samples). Should be sampled at fs. If None, it is not changed.

set_score_request(*, sample_weight: bool | None | str = '$UNCHANGED$') → rCCA

Request metadata passed to the score method.

Note that this method is only relevant if enable_metadata_routing=True (see sklearn.set_config()). Please see User Guide on how the routing mechanism works.

The options for each parameter are:

• True: metadata is requested, and passed to score if provided. The request is ignored if metadata is not provided.

• False: metadata is not requested and the meta-estimator will not pass it to score.

• None: metadata is not requested, and the meta-estimator will raise an error if the user provides it.

• str: metadata should be passed to the meta-estimator with this given alias instead of the original name.

The default (sklearn.utils.metadata_routing.UNCHANGED) retains the existing request. This allows you to change the request for some parameters and not others.

Added in version 1.3.

Note

This method is only relevant if this estimator is used as a sub-estimator of a meta-estimator, e.g. used inside a Pipeline. Otherwise it has no effect.

Parameters:

sample_weight (str, True, False, or None, default=sklearn.utils.metadata_routing.UNCHANGED) – Metadata routing for sample_weight parameter in score.

Returns:

self – The updated object.

Return type:

object

set_stimulus(stimulus: ndarray[Any, dtype[_ScalarType_co]]) → None

Set the stimulus, and as such change the templates.

Parameters:

stimulus (NDArray) – The stimulus used for stimulation of shape (n_classes, n_samples). Should be sampled at fs. One cycle (i.e., one stimulus-repetition) is sufficient. If None, it is not changed.

set_stimulus_amplitudes(stimulus: ndarray[Any, dtype[_ScalarType_co]], amplitudes: ndarray[Any, dtype[_ScalarType_co]]) → None

Set the stimulus and/or the amplitudes, and as such change the templates.

Parameters:

• stimulus (NDArray) – The stimulus used for stimulation of shape (n_classes, n_samples). Should be sampled at fs. One cycle (i.e., one stimulus-repetition) is sufficient. If None, it is not changed.

• amplitudes (NDArray) – The amplitude of the stimulus of shape (n_classes, n_samples). Should be sampled at fs. If None, it is not changed.