pyntbci.classifiers.rCCA

class pyntbci.classifiers.rCCA(stimulus: NDArray, 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 = None, ensemble: bool = False, amplitudes: NDArray = None, gamma_x: float | list[float] | NDArray = None, gamma_m: float | list[float] | NDArray = None, n_components: int = 1, squeeze_components: bool = True, alpha_x: float = None, alpha_m: float = None, tmin: float = 0, running: bool = False)

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 and 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, inner.

• 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. Note, each filter is then fit on only that class’s trials, so its covariance matrices are estimated from substantially less data than in the non-ensemble case; this can make them singular or too ill-conditioned to invert, especially with a wide encoding matrix (multiple events and/or a long encoding_length) relative to the trial length. If this occurs, set gamma_x/gamma_m or alpha_x/alpha_m to regularize the covariance matrix.

• amplitudes (NDArray (default: None)) – 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).

• 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.

• running (bool (default: False)) – Whether fit() is incremental: if False, each fit() call replaces the previous fit, using only the trials passed to that call. If True, each fit() call instead adds its trials to the ones seen in all previous fit() calls (i.e., keeps the spatial/temporal filter’s running covariance from CCA(running=True) instead of discarding it), so a model can be trained gradually as more trials become available without redoing the full computation on all trials so far. Since rCCA’s templates (Ts_/Tw_) are already always recomputed from the stimulus and the current filter, not the training trials themselves, this is mathematically exact: two calls fit(X1, y1) then fit(X2, y2) give the same filter as one call fit(concat(X1, X2), concat(y1, y2)). Not supported for ensemble=True, since each class’s covariance would then be running on its own, and a class absent from an early batch would otherwise silently never get initialized. To start a new running fit from scratch, use a new instance (or call set_params(running=False) once, fit(), then set_params(running=True) again).

• cca (list[TransformerMixin]) – The CCA used to fit the spatial and temporal filters. If ensemble=False, len(cca_)=1, otherwise len(cca_)=n_classes.

• events (list) – The list of events used to map the stimulus to, as set by set_encoding_matrix().

• w (NDArray) – 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).

• r (NDArray) – 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).

• Ms (NDArray) – The encoding matrix representing the events of shape (n_classes, n_features, n_samples) for stimulus cycle 1 (i.e., it includes the onset of stimulation and does not contain the tails of previous cycles).

• Mw (NDArray) – The encoding matrix representing the events of shape (n_classes, n_features, 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).

• Ts (NDArray) – 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).

• Tw (NDArray) – 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).

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, running: bool = False, reset: bool = False) → NDArray

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). If running=True, this is only the newly observed samples since the previous call (not the full trial), see running below.

• running (bool (default: False)) – Whether to use running (incremental) scoring. If False (default), decision_function behaves exactly as without this parameter: X is the complete trial data seen so far, and everything is recomputed from scratch. If True, X is only the newly observed samples since the previous call, and a running state (kept internally, not a fitted attribute) is reused and updated; this is much cheaper when called repeatedly on a growing trial, e.g. from a dynamic stopping simulation loop, since each call only does O(n_new_samples) work instead of reprocessing the whole trial (this includes decoding_matrix’s spatio- spectral filtering, not just the final score). Use reset=True on the first call of a new running sequence (e.g. for a new trial or a new batch of trials); the running state is otherwise unaffected by (and does not affect) running=False calls, and is cleared by fit(). Only supported for ensemble=False.

• reset (bool (default: False)) – Whether to discard any existing running state before processing this call. Only relevant if running=True; a never-yet-used instance already starts fresh without it, so it only needs to be set explicitly to start a new sequence before the previous one naturally ended.

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. If running=True, this is the cumulative score over all samples observed so far in the running sequence (not just the new chunk).

Return type:

NDArray

fit(X: NDArray, y: NDArray) → 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, running: bool = False, reset: bool = False) → NDArray

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). If running=True, this is only the newly observed samples since the previous call, see decision_function().

• running (bool (default: False)) – Whether to use running (incremental) scoring, see decision_function().

• reset (bool (default: False)) – Whether to discard any existing running state before processing this call, see decision_function().

Returns:

y – The predicted labels of shape (n_trials, n_components) or (n_trials) if n_components=1 and squeeze_components=True.

Return type:

NDArray

set_amplitudes(amplitudes: NDArray) → 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.

set_decision_function_request(*, reset: bool | None | str = '$UNCHANGED$', running: bool | None | str = '$UNCHANGED$') → rCCA

Configure whether metadata should be requested to be passed to the decision_function 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 decision_function 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 decision_function.

• 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:

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

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

Returns:

self – The updated object.

Return type:

object

set_encoding_matrix() → None

Set the encoding matrix.

set_predict_request(*, reset: bool | None | str = '$UNCHANGED$', running: bool | None | str = '$UNCHANGED$') → rCCA

Configure whether metadata should be requested to be passed to the predict 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 predict 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 predict.

• 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:

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

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

Returns:

self – The updated object.

Return type:

object

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) → 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.

set_stimulus_amplitudes(stimulus: NDArray, amplitudes: NDArray) → 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.

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

set_templates() → None

Set the templates.