moabb.pipelines.classification.SSVEP_MsetCCA#

class moabb.pipelines.classification.SSVEP_MsetCCA(n_filters=1, n_jobs=1)[source]#

Multi-set Canonical Correlation Analysis (MsetCCA) for SSVEP detection [1].

MsetCCA learns optimal reference signals from training data rather than using predefined sinusoidal references as in standard CCA. It maximizes the correlation among canonical variates from multiple sets of EEG trials recorded at the same stimulus frequency, extracting common SSVEP features.

Mathematical Formulation

Given N_t training trials \mathbf{X}_{n,h} \in \mathbb{R}^{N_c \times N_s} for stimulus frequency f_n, MsetCCA finds spatial filters \mathbf{w}_1, ..., \mathbf{w}_{N_t} that maximize inter-trial correlation.

MAXVAR Objective Function

The optimization problem maximizes the sum of pairwise covariances across trials subject to a variance constraint:

\tilde{\mathbf{w}}_{n,1}, ..., \tilde{\mathbf{w}}_{n,N_t} = \arg\max_{\mathbf{w}_1, ..., \mathbf{w}_{N_t}} \sum_{h_1 \neq h_2}^{N_t} \mathbf{w}_{h_1}^T \mathbf{X}_{n,h_1} \mathbf{X}_{n,h_2}^T \mathbf{w}_{h_2}

subject to:

\frac{1}{N_t} \sum_{h=1}^{N_t} \mathbf{w}_h^T \mathbf{X}_{n,h} \mathbf{X}_{n,h}^T \mathbf{w}_h = 1

Generalized Eigenvalue Problem

The optimization transforms into a generalized eigenvalue problem. Let \mathbf{Y}_n be the concatenation of whitened trials stacked as [\mathbf{X}_{n,1}; \mathbf{X}_{n,2}; ...; \mathbf{X}_{n,N_t}]:

(\mathbf{R}_n - \mathbf{S}_n) \mathbf{w} = \lambda \mathbf{S}_n \mathbf{w}

where:

  • \mathbf{R}_n = \mathbf{Y}_n \mathbf{Y}_n^T is the total covariance matrix

  • \mathbf{S}_n is the block-diagonal matrix containing within-trial covariances

The eigenvectors corresponding to the largest eigenvalues give the optimal spatial filters.

Whitening Preprocessing

Before solving the eigenvalue problem, each trial is whitened using:

\tilde{\mathbf{X}} = \mathbf{V} \mathbf{X}, \quad \mathbf{V} = \mathbf{\Lambda}^{-1/2} \mathbf{U}^T

where \mathbf{U} \mathbf{\Lambda} \mathbf{U}^T is the eigendecomposition of the covariance matrix of \mathbf{X}.

Reference Signal (Template) Construction

For each stimulus frequency f_n, the optimized reference signal is the average of spatially filtered training trials:

\mathbf{Y}_n^{\text{ref}} = \frac{1}{N_t} \sum_{h=1}^{N_t} \mathbf{W}_h^T \tilde{\mathbf{X}}_{n,h}

where \mathbf{W}_h contains the spatial filters for trial h.

Classification Rule

For a test signal \mathbf{X}, CCA is computed between the test data and each reference signal \mathbf{Y}_n^{\text{ref}}:

\rho_n = \max_{\mathbf{w}_x, \mathbf{w}_y} \text{corr}(\mathbf{X}^T \mathbf{w}_x, (\mathbf{Y}_n^{\text{ref}})^T \mathbf{w}_y)

The predicted class is: \hat{f} = \arg\max_n \rho_n

Parameters:

  • n_filters (int, default=1) – Number of spatial filters (eigenvectors) to extract from the MAXVAR solution. Corresponds to the dimensionality of the learned reference signals. Higher values may capture more variance but risk overfitting.

  • n_jobs (int, default=1) – Number of parallel jobs for whitening computation. Use -1 to use all available cores.

classes_#

Encoded class labels (0 to n_classes-1).

Type:

ndarray of shape (n_classes,)

freqs_#

List of stimulus frequency labels from training data.

Type:

list of str

one_hot_#

Mapping from frequency strings to encoded class labels.

Type:

dict

le_#

Fitted label encoder for frequency strings.

Type:

LabelEncoder

Ym#

Dictionary mapping encoded class labels to optimized reference signals \mathbf{Y}_n^{\text{ref}} of shape (n_filters, n_times).

Type:

dict

References

[1]

Zhang, Y., Zhou, G., Jin, J., Wang, X., and Cichocki, A. (2014). Frequency recognition in SSVEP-based BCI using multiset canonical correlation analysis. International Journal of Neural Systems, 24(04), 1450013. https://doi.org/10.1142/S0129065714500130

See also

SSVEP_CCA

Standard CCA using sinusoidal references.

SSVEP_TRCA

Task-related component analysis for SSVEP.

Notes

Added in version 0.5.0.

Changed in version 1.1.1: Fixed label encoding to match paradigm output. Fixed template computation to use averaging instead of concatenation, matching the original algorithm.

fit(X, y, sample_weight=None)[source]#

Compute the optimized reference signal at each stimulus frequency.

Parameters:

  • X (MNE Epochs) – The training data as MNE Epochs object.

  • y (np.ndarray of shape (n_trials,)) – The target labels for each trial.

Returns:

self – Instance of classifier.

Return type:

SSVEP_MsetCCA object

predict(X)[source]#

Predict is made by taking the maximum correlation coefficient.

Parameters:

X (MNE Epochs) – The data to predict as MNE Epochs object.

Returns:

y – Predicted labels.

Return type:

list of int

predict_proba(X)[source]#

Probability could be computed from the correlation coefficient.

Parameters:

X (MNE Epochs) – The data to predict as MNE Epochs object.

Returns:

P – Probability of each class for each trial.

Return type:

ndarray of shape (n_trials, n_classes)

set_fit_request(*, sample_weight: bool | None | str = '$UNCHANGED$') → SSVEP_MsetCCA[source]#

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

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

Returns:

self – The updated object.

Return type:

object

set_score_request(*, sample_weight: bool | None | str = '$UNCHANGED$') → SSVEP_MsetCCA[source]#

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