pyntbci.classifiers.eCCA

class pyntbci.classifiers.eCCA(lags: None | NDArray, fs: int, cycle_size: float = None, template_metric: str = 'mean', score_metric: str = 'correlation', cca_channels: list[int] = None, gamma_x: float | list[float] | NDArray = None, gamma_t: float | list[float] | NDArray = None, latency: NDArray = None, ensemble: bool = False, n_components: int = 1, squeeze_components: bool = True, alpha_x: float = None, alpha_t: float = None, running: bool = False)[source]

ERP CCA classifier. Also called the “reference” method [1]. It computes ERPs as templates for full sequences and performs a CCA for spatial filtering.

Parameters:

lags (None | NDArray) – A vector of latencies in seconds per class relative to the first stimulus if stimuli are circularly shifted versions of the first stimulus, or None if all stimuli are different or this circular shift feature should be ignored.
fs (int) – The sampling frequency of the EEG data in Hz.
cycle_size (float (default: None)) – The time that one cycle of the code takes in seconds. If None, takes the full data length.
template_metric (str (default: "mean")) – Metric to use to compute templates: mean, median, ocsvm.
score_metric (str (default: "correlation")) – Metric to use to compute the overlap of templates and single-trials during testing: correlation, Euclidean, inner.
cca_channels (list[int] (default: None)) – A list of channel indexes that need to be included in the estimation of a spatial filter at the template side of the CCA, i.e. CCA(X, T[:, cca_channels, :]). If None is given, all channels are used.
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_t (float | list[float] | NDArray (default: None)) – Regularization on the covariance matrix for CCA for all or each individual parameter along T (channels). If None, no regularization is applied. The gamma_t ranges from 0 (no regularization) to 1 (full regularization).
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 few trials per class or many channels/features. If this occurs, set gamma_x/gamma_t or alpha_x/alpha_t to regularize the covariance matrix.
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_t (float (default: None)) – Amount of variance to retain in computing the inverse of the covariance matrix of T. If None, all variance.
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 filter’s running covariance from CCA(running=True), and the template’s running mean, instead of discarding them), so a model can be trained gradually as more trials become available. Requires lags to be set (a fixed, known-upfront class count and a single, un-split running template – see lags above), template_metric=”mean” (the only template metric with an exact incremental update), and ensemble=False. Unlike rCCA(running=True), this is only an approximation of the equivalent batch fit, not exact: the (running) template is itself used as the CCA fit’s target on every call, so earlier calls see an earlier, less complete estimate of it than later calls do; it converges towards the batch result as more trials accumulate, but is not expected to equal it. 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).

classes_

The classes that can be predicted, of shape (n_classes). Equal to numpy.arange(len(lags)) if lags is set (i.e., all circularly shifted classes can be predicted, whether or not they were observed in y during fit), otherwise the sorted unique labels observed in y.

Type:: NDArray

cca_

The CCA used to fit the spatial 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

T_

The template matrix representing the expected responses of shape (n_classes, n_components, n_samples).

Type:: NDArray

References

decision_function(X: NDArray, running: bool = False, reset: bool = False) → NDArray[source]

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. 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[source]

The training procedure to fit eCCA 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), i.e., the index of the attended code.

Returns:

self – Returns the instance itself.

Return type:

ClassifierMixin

get_T(n_samples: int = None) → NDArray[source]

Get the templates.

Parameters:: n_samples (int (default: None)) – The number of samples requested. If None, one code cycle is given.
Returns:: T – The templates of shape (n_classes, n_components, n_samples).
Return type:: NDArray

predict(X: NDArray, running: bool = False, reset: bool = False) → NDArray[source]

The testing procedure to apply eCCA 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_decision_function_request(*, reset: bool | None | str = '$UNCHANGED$', running: bool | None | str = '$UNCHANGED$') → eCCA

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_predict_request(*, reset: bool | None | str = '$UNCHANGED$', running: bool | None | str = '$UNCHANGED$') → eCCA

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$') → eCCA

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