pyntbci.classifiers.rCCA

class pyntbci.classifiers.rCCA(stimulus: ndarray[tuple[Any, ...], dtype[_ScalarT]], fs: int, event: str = 'duration', onset_event: bool = False, decoding_length: float = None, decoding_stride: float = None, encoding_length: float | list[float] = None, encoding_stride: float | list[float] = None, score_metric: str = 'correlation', latency: ndarray[tuple[Any, ...], dtype[_ScalarT]] = None, ensemble: bool = False, amplitudes: ndarray[tuple[Any, ...], dtype[_ScalarT]] = None, gamma_x: float | list[float] | ndarray[tuple[Any, ...], dtype[_ScalarT]] = None, gamma_m: float | list[float] | ndarray[tuple[Any, ...], dtype[_ScalarT]] = None, cov_estimator_x: BaseEstimator = None, cov_estimator_m: BaseEstimator = None, n_components: int = 1, squeeze_components: bool = True, alpha_x: float = None, alpha_m: float = 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[tuple[Any, ...], dtype[_ScalarT]]) → ndarray[tuple[Any, ...], dtype[_ScalarT]]

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[tuple[Any, ...], dtype[_ScalarT]], y: ndarray[tuple[Any, ...], dtype[_ScalarT]]) → 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

predict(X: ndarray[tuple[Any, ...], dtype[_ScalarT]]) → ndarray[tuple[Any, ...], dtype[_ScalarT]]

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[tuple[Any, ...], dtype[_ScalarT]]) → 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_encoding_matrix() → None

Set the encoding matrix.

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

Configure whether metadata should be requested to be passed to the score method.

Note that this method is only relevant when this estimator is used as a sub-estimator within a meta-estimator and metadata routing is enabled with enable_metadata_routing=True (see sklearn.set_config()). Please check the 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.

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[tuple[Any, ...], dtype[_ScalarT]]) → 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[tuple[Any, ...], dtype[_ScalarT]], amplitudes: ndarray[tuple[Any, ...], dtype[_ScalarT]]) → None

Set the stimulus and 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.

set_templates() → None

Set the templates.