From 632c81959f6f8d9a600ba3d12348611f96a32940 Mon Sep 17 00:00:00 2001
From: Genuster <genusterok@gmail.com>
Date: Thu, 22 May 2025 16:24:09 +0300
Subject: [PATCH 01/59] assert_allclose for base ged for csp, spoc, ssd and
 xdawn

---
 mne/decoding/base.py       |  86 +++++++++-
 mne/decoding/covs_ged.py   | 318 +++++++++++++++++++++++++++++++++++++
 mne/decoding/csp.py        |  64 +++++++-
 mne/decoding/ged.py        | 227 ++++++++++++++++++++++++++
 mne/decoding/mod_ged.py    |  69 ++++++++
 mne/decoding/ssd.py        |  38 ++++-
 mne/preprocessing/xdawn.py |  40 ++++-
 7 files changed, 833 insertions(+), 9 deletions(-)
 create mode 100644 mne/decoding/covs_ged.py
 create mode 100644 mne/decoding/ged.py
 create mode 100644 mne/decoding/mod_ged.py

diff --git a/mne/decoding/base.py b/mne/decoding/base.py
index f73cd976fe3..3737f11960a 100644
--- a/mne/decoding/base.py
+++ b/mne/decoding/base.py
@@ -22,7 +22,91 @@
 from sklearn.utils import check_array, check_X_y, indexable
 
 from ..parallel import parallel_func
-from ..utils import _pl, logger, verbose, warn
+from ..utils import _pl, logger, pinv, verbose, warn
+from .ged import _get_ssd_rank, _handle_restr_map, _smart_ajd, _smart_ged
+from .transformer import MNETransformerMixin
+
+
+class GEDTransformer(MNETransformerMixin, BaseEstimator):
+    """..."""
+
+    def __init__(
+        self,
+        n_filters,
+        cov_callable,
+        cov_params,
+        mod_ged_callable,
+        mod_params,
+        dec_type="single",
+        restr_map=None,
+        R_func=None,
+    ):
+        self.n_filters = n_filters
+        self.cov_callable = cov_callable
+        self.cov_params = cov_params
+        self.mod_ged_callable = mod_ged_callable
+        self.mod_params = mod_params
+        self.dec_type = dec_type
+        self.restr_map = restr_map
+        self.R_func = R_func
+
+    def fit(self, X, y=None):
+        """..."""
+        covs, C_ref, info, rank, kwargs = self.cov_callable(X, y, **self.cov_params)
+        if self.dec_type == "single":
+            if len(covs) > 2:
+                sample_weights = kwargs["sample_weights"]
+                restr_map = _handle_restr_map(C_ref, self.restr_map, info, rank)
+                evecs = _smart_ajd(covs, restr_map, weights=sample_weights)
+                evals = None
+            else:
+                S = covs[0]
+                R = covs[1]
+                if self.restr_map == "ssd":
+                    rank = _get_ssd_rank(S, R, info, rank)
+                    mult_order = "ssd"
+                else:
+                    mult_order = None
+                restr_map = _handle_restr_map(C_ref, self.restr_map, info, rank)
+                evals, evecs = _smart_ged(
+                    S, R, restr_map, R_func=self.R_func, mult_order=mult_order
+                )
+
+            evals, evecs = self.mod_ged_callable(
+                evals, evecs, covs, **self.mod_params, **kwargs
+            )
+            self.evals_ = evals
+            self.filters_ = evecs.T
+            if self.restr_map == "ssd":
+                self.patterns_ = np.linalg.pinv(evecs)
+            else:
+                self.patterns_ = pinv(evecs)
+
+        elif self.dec_type == "multi":
+            self.classes_ = np.unique(y)
+            R = covs[-1]
+            restr_map = _handle_restr_map(C_ref, self.restr_map, info, rank)
+            all_evals, all_evecs, all_patterns = list(), list(), list()
+            for i in range(len(self.classes_)):
+                S = covs[i]
+                evals, evecs = _smart_ged(S, R, restr_map, R_func=self.R_func)
+
+                evals, evecs = self.mod_ged_callable(
+                    evals, evecs, covs, **self.mod_params, **kwargs
+                )
+                all_evals.append(evals)
+                all_evecs.append(evecs.T)
+                all_patterns.append(np.linalg.pinv(evecs))
+            self.evals_ = np.array(all_evals)
+            self.filters_ = np.array(all_evecs)
+            self.patterns_ = np.array(all_patterns)
+
+        return self
+
+    def transform(self, X):
+        """..."""
+        X = np.dot(self.filters_, X)
+        return X
 
 
 class LinearModel(MetaEstimatorMixin, BaseEstimator):
diff --git a/mne/decoding/covs_ged.py b/mne/decoding/covs_ged.py
new file mode 100644
index 00000000000..3df65d8107f
--- /dev/null
+++ b/mne/decoding/covs_ged.py
@@ -0,0 +1,318 @@
+"""Covariance estimation for GED transformers."""
+
+# Authors: The MNE-Python contributors.
+# License: BSD-3-Clause
+# Copyright the MNE-Python contributors.
+
+import numpy as np
+import scipy.linalg
+
+from .._fiff.meas_info import Info, create_info
+from .._fiff.pick import _picks_to_idx
+from ..cov import Covariance, _compute_rank_raw_array, _regularized_covariance
+from ..filter import filter_data
+from ..utils import pinv
+
+
+def _concat_cov(x_class, *, cov_kind, log_rank, reg, cov_method_params, rank, info):
+    """Concatenate epochs before computing the covariance."""
+    _, n_channels, _ = x_class.shape
+
+    x_class = x_class.transpose(1, 0, 2).reshape(n_channels, -1)
+    cov = _regularized_covariance(
+        x_class,
+        reg=reg,
+        method_params=cov_method_params,
+        rank=rank,
+        info=info,
+        cov_kind=cov_kind,
+        log_rank=log_rank,
+        log_ch_type="data",
+    )
+    weight = x_class.shape[0]
+
+    return cov, weight
+
+
+def _epoch_cov(x_class, *, cov_kind, log_rank, reg, cov_method_params, rank, info):
+    """Mean of per-epoch covariances."""
+    cov = sum(
+        _regularized_covariance(
+            this_X,
+            reg=reg,
+            method_params=cov_method_params,
+            rank=rank,
+            info=info,
+            cov_kind=cov_kind,
+            log_rank=log_rank and ii == 0,
+            log_ch_type="data",
+        )
+        for ii, this_X in enumerate(x_class)
+    )
+    cov /= len(x_class)
+    weight = len(x_class)
+
+    return cov, weight
+
+
+def _csp_estimate(X, y, reg, cov_method_params, cov_est, rank, norm_trace):
+    _, n_channels, _ = X.shape
+    classes_ = np.unique(y)
+    if cov_est == "concat":
+        cov_estimator = _concat_cov
+    elif cov_est == "epoch":
+        cov_estimator = _epoch_cov
+    # Someday we could allow the user to pass this, then we wouldn't need to convert
+    # but in the meantime they can use a pipeline with a scaler
+    _info = create_info(n_channels, 1000.0, "mag")
+    if isinstance(rank, dict):
+        _rank = {"mag": sum(rank.values())}
+    else:
+        _rank = _compute_rank_raw_array(
+            X.transpose(1, 0, 2).reshape(X.shape[1], -1),
+            _info,
+            rank=rank,
+            scalings=None,
+            log_ch_type="data",
+        )
+
+    covs = []
+    sample_weights = []
+    for ci, this_class in enumerate(classes_):
+        cov, weight = cov_estimator(
+            X[y == this_class],
+            cov_kind=f"class={this_class}",
+            log_rank=ci == 0,
+            reg=reg,
+            cov_method_params=cov_method_params,
+            rank=_rank,
+            info=_info,
+        )
+
+        if norm_trace:
+            cov /= np.trace(cov)
+
+        covs.append(cov)
+        sample_weights.append(weight)
+
+    covs = np.stack(covs)
+    C_ref = covs.mean(0)
+
+    return covs, C_ref, _info, _rank, dict(sample_weights=np.array(sample_weights))
+
+
+def _construct_signal_from_epochs(epochs, events, sfreq, tmin):
+    """Reconstruct pseudo continuous signal from epochs."""
+    n_epochs, n_channels, n_times = epochs.shape
+    tmax = tmin + n_times / float(sfreq)
+    start = np.min(events[:, 0]) + int(tmin * sfreq)
+    stop = np.max(events[:, 0]) + int(tmax * sfreq) + 1
+
+    n_samples = stop - start
+    n_epochs, n_channels, n_times = epochs.shape
+    events_pos = events[:, 0] - events[0, 0]
+
+    raw = np.zeros((n_channels, n_samples))
+    for idx in range(n_epochs):
+        onset = events_pos[idx]
+        offset = onset + n_times
+        raw[:, onset:offset] = epochs[idx]
+
+    return raw
+
+
+def _least_square_evoked(epochs_data, events, tmin, sfreq):
+    """Least square estimation of evoked response from epochs data.
+
+    Parameters
+    ----------
+    epochs_data : array, shape (n_channels, n_times)
+        The epochs data to estimate evoked.
+    events : array, shape (n_events, 3)
+        The events typically returned by the read_events function.
+        If some events don't match the events of interest as specified
+        by event_id, they will be ignored.
+    tmin : float
+        Start time before event.
+    sfreq : float
+        Sampling frequency.
+
+    Returns
+    -------
+    evokeds : array, shape (n_class, n_components, n_times)
+        An concatenated array of evoked data for each event type.
+    toeplitz : array, shape (n_class * n_components, n_channels)
+        An concatenated array of toeplitz matrix for each event type.
+    """
+    n_epochs, n_channels, n_times = epochs_data.shape
+    tmax = tmin + n_times / float(sfreq)
+
+    # Deal with shuffled epochs
+    events = events.copy()
+    events[:, 0] -= events[0, 0] + int(tmin * sfreq)
+
+    # Construct raw signal
+    raw = _construct_signal_from_epochs(epochs_data, events, sfreq, tmin)
+
+    # Compute the independent evoked responses per condition, while correcting
+    # for event overlaps.
+    n_min, n_max = int(tmin * sfreq), int(tmax * sfreq)
+    window = n_max - n_min
+    n_samples = raw.shape[1]
+    toeplitz = list()
+    classes = np.unique(events[:, 2])
+    for ii, this_class in enumerate(classes):
+        # select events by type
+        sel = events[:, 2] == this_class
+
+        # build toeplitz matrix
+        trig = np.zeros((n_samples,))
+        ix_trig = (events[sel, 0]) + n_min
+        trig[ix_trig] = 1
+        toeplitz.append(scipy.linalg.toeplitz(trig[0:window], trig))
+
+    # Concatenate toeplitz
+    toeplitz = np.array(toeplitz)
+    X = np.concatenate(toeplitz)
+
+    # least square estimation
+    predictor = np.dot(pinv(np.dot(X, X.T)), X)
+    evokeds = np.dot(predictor, raw.T)
+    evokeds = np.transpose(np.vsplit(evokeds, len(classes)), (0, 2, 1))
+    return evokeds, toeplitz
+
+
+def _xdawn_estimate(
+    X,
+    y,
+    reg,
+    cov_method_params,
+    R=None,
+    events=None,
+    tmin=0,
+    sfreq=1,
+    info=None,
+    rank="full",
+):
+    if not isinstance(X, np.ndarray) or X.ndim != 3:
+        raise ValueError("X must be 3D ndarray")
+
+    classes = np.unique(y)
+
+    # XXX Eventually this could be made to deal with rank deficiency properly
+    # by exposing this "rank" parameter, but this will require refactoring
+    # the linalg.eigh call to operate in the lower-dimension
+    # subspace, then project back out.
+
+    # Retrieve or compute whitening covariance
+    if R is None:
+        R = _regularized_covariance(
+            np.hstack(X), reg, cov_method_params, info, rank=rank
+        )
+    elif isinstance(R, Covariance):
+        R = R.data
+    if not isinstance(R, np.ndarray) or (
+        not np.array_equal(R.shape, np.tile(X.shape[1], 2))
+    ):
+        raise ValueError(
+            "R must be None, a covariance instance, "
+            "or an array of shape (n_chans, n_chans)"
+        )
+
+    # Get prototype events
+    if events is not None:
+        evokeds, toeplitzs = _least_square_evoked(X, events, tmin, sfreq)
+    else:
+        evokeds, toeplitzs = list(), list()
+        for c in classes:
+            # Prototyped response for each class
+            evokeds.append(np.mean(X[y == c, :, :], axis=0))
+            toeplitzs.append(1.0)
+
+    covs = []
+    for evo, toeplitz in zip(evokeds, toeplitzs):
+        # Estimate covariance matrix of the prototype response
+        evo = np.dot(evo, toeplitz)
+        evo_cov = _regularized_covariance(evo, reg, cov_method_params, info, rank=rank)
+        covs.append(evo_cov)
+
+    covs.append(R)
+    covs = np.stack(covs)
+    C_ref = None
+    rank = None
+    info = None
+    return covs, C_ref, info, rank, dict()
+
+
+def _ssd_estimate(
+    X,
+    y,
+    reg,
+    cov_method_params,
+    info,
+    picks,
+    filt_params_signal,
+    filt_params_noise,
+    rank,
+):
+    if isinstance(info, Info):
+        sfreq = info["sfreq"]
+    elif isinstance(info, float):  # special case, mostly for testing
+        sfreq = info
+        info = create_info(X.shape[-2], sfreq, ch_types="eeg")
+    picks = _picks_to_idx(info, picks, none="data", exclude="bads")
+    X_aux = X[..., picks, :]
+    X_signal = filter_data(X_aux, sfreq, **filt_params_signal)
+    X_noise = filter_data(X_aux, sfreq, **filt_params_noise)
+    X_noise -= X_signal
+    if X.ndim == 3:
+        X_signal = np.hstack(X_signal)
+        X_noise = np.hstack(X_noise)
+
+    # prevent rank change when computing cov with rank='full'
+    S = _regularized_covariance(
+        X_signal,
+        reg=reg,
+        method_params=cov_method_params,
+        rank="full",
+        info=info,
+    )
+    R = _regularized_covariance(
+        X_noise,
+        reg=reg,
+        method_params=cov_method_params,
+        rank="full",
+        info=info,
+    )
+    covs = [S, R]
+    C_ref = S
+    return covs, C_ref, info, rank, dict()
+
+
+def _spoc_estimate(X, y, reg, cov_method_params, rank):
+    # Normalize target variable
+    target = y.astype(np.float64)
+    target -= target.mean()
+    target /= target.std()
+
+    n_epochs, n_channels = X.shape[:2]
+
+    # Estimate single trial covariance
+    covs = np.empty((n_epochs, n_channels, n_channels))
+    for ii, epoch in enumerate(X):
+        covs[ii] = _regularized_covariance(
+            epoch,
+            reg=reg,
+            method_params=cov_method_params,
+            rank=rank,
+            log_ch_type="data",
+            log_rank=ii == 0,
+        )
+
+    S = np.mean(covs * target[:, np.newaxis, np.newaxis], axis=0)
+    R = covs.mean(0)
+
+    covs = [S, R]
+    C_ref = None
+    info = None
+    return covs, C_ref, info, rank, dict()
diff --git a/mne/decoding/csp.py b/mne/decoding/csp.py
index ea38fd58ca3..883004467ee 100644
--- a/mne/decoding/csp.py
+++ b/mne/decoding/csp.py
@@ -6,7 +6,6 @@
 
 import numpy as np
 from scipy.linalg import eigh
-from sklearn.base import BaseEstimator
 from sklearn.utils.validation import check_is_fitted
 
 from .._fiff.meas_info import create_info
@@ -20,11 +19,13 @@
     fill_doc,
     pinv,
 )
-from .transformer import MNETransformerMixin
+from .base import GEDTransformer
+from .covs_ged import _csp_estimate, _spoc_estimate
+from .mod_ged import _csp_mod, _spoc_mod
 
 
 @fill_doc
-class CSP(MNETransformerMixin, BaseEstimator):
+class CSP(GEDTransformer):
     """M/EEG signal decomposition using the Common Spatial Patterns (CSP).
 
     This class can be used as a supervised decomposition to estimate spatial
@@ -124,6 +125,26 @@ def __init__(
         self.cov_method_params = cov_method_params
         self.component_order = component_order
 
+        cov_params = dict(
+            reg=reg,
+            cov_method_params=cov_method_params,
+            cov_est=cov_est,
+            rank=rank,
+            norm_trace=norm_trace,
+        )
+
+        mod_params = dict(evecs_order=component_order)
+        super().__init__(
+            n_components,
+            _csp_estimate,
+            cov_params,
+            _csp_mod,
+            mod_params,
+            dec_type="single",
+            restr_map="restricting",
+            R_func=sum,
+        )
+
     def _validate_params(self, *, y):
         _validate_type(self.n_components, int, "n_components")
         if hasattr(self, "cov_est"):
@@ -191,6 +212,16 @@ def fit(self, X, y):
         self.filters_ = eigen_vectors.T
         self.patterns_ = pinv(eigen_vectors)
 
+        old_filters = self.filters_
+        old_patterns = self.patterns_
+        super().fit(X, y)
+        if self.evals_ is None:
+            assert eigen_values is None
+        else:
+            np.testing.assert_allclose(eigen_values[ix], self.evals_)
+        np.testing.assert_allclose(old_filters, self.filters_)
+        np.testing.assert_allclose(old_patterns, self.patterns_)
+
         pick_filters = self.filters_[: self.n_components]
         X = np.asarray([np.dot(pick_filters, epoch) for epoch in X])
 
@@ -857,6 +888,25 @@ def __init__(
             rank=rank,
             cov_method_params=cov_method_params,
         )
+
+        cov_params = dict(
+            reg=reg,
+            cov_method_params=cov_method_params,
+            rank=rank,
+        )
+
+        mod_params = dict()
+        super(CSP, self).__init__(
+            n_components,
+            _spoc_estimate,
+            cov_params,
+            _spoc_mod,
+            mod_params,
+            dec_type="single",
+            restr_map=None,
+            R_func=None,
+        )
+
         # Covariance estimation have to be done on the single epoch level,
         # unlike CSP where covariance estimation can also be achieved through
         # concatenation of all epochs from the same class.
@@ -919,6 +969,14 @@ def fit(self, X, y):
         self.patterns_ = pinv(evecs).T  # n_channels x n_channels
         self.filters_ = evecs  # n_channels x n_channels
 
+        old_filters = self.filters_
+        old_patterns = self.patterns_
+        super(CSP, self).fit(X, y)
+
+        np.testing.assert_allclose(evals[ix], self.evals_)
+        np.testing.assert_allclose(old_filters, self.filters_)
+        np.testing.assert_allclose(old_patterns, self.patterns_)
+
         pick_filters = self.filters_[: self.n_components]
         X = np.asarray([np.dot(pick_filters, epoch) for epoch in X])
 
diff --git a/mne/decoding/ged.py b/mne/decoding/ged.py
new file mode 100644
index 00000000000..5e505f8be9a
--- /dev/null
+++ b/mne/decoding/ged.py
@@ -0,0 +1,227 @@
+# Authors: The MNE-Python contributors.
+# License: BSD-3-Clause
+# Copyright the MNE-Python contributors.
+
+import numpy as np
+import scipy.linalg
+
+from ..cov import Covariance, _smart_eigh, compute_whitener
+from ..defaults import _handle_default
+from ..rank import compute_rank
+from ..utils import _verbose_safe_false, logger
+
+
+def _handle_restr_map(C_ref, restr_map, info, rank):
+    if C_ref is None or restr_map is None:
+        return None
+    if restr_map == "whitening":
+        projs = info["projs"]
+        C_ref_cov = Covariance(C_ref, info.ch_names, info["bads"], projs, 0)
+        restr_map = compute_whitener(C_ref_cov, info, rank=rank, pca=True)
+    elif restr_map == "ssd":
+        restr_map = _get_ssd_whitener(C_ref, rank)
+    elif restr_map == "restricting":
+        restr_map = _get_restricting_map(C_ref, info, rank)
+    elif isinstance(restr_map, callable):
+        pass
+    else:
+        raise ValueError(
+            "restr_map should either be callable or one of whitening, ssd, restricting"
+        )
+    return restr_map
+
+
+def _smart_ged(S, R, restr_map, R_func=None, mult_order=None):
+    """..."""
+    if restr_map is None:
+        evals, evecs = scipy.linalg.eigh(S, R)
+        return evals, evecs
+
+    if mult_order == "ssd":
+        S_restr = restr_map @ (S @ restr_map.T)
+        R_restr = restr_map @ (R @ restr_map.T)
+    else:
+        S_restr = restr_map @ S @ restr_map.T
+        R_restr = restr_map @ R @ restr_map.T
+    if R_func is not None:
+        R_restr = R_func([S_restr, R_restr])
+    evals, evecs_restr = scipy.linalg.eigh(S_restr, R_restr)
+    evecs = restr_map.T @ evecs_restr
+
+    return evals, evecs
+
+
+def _ajd_pham(X, eps=1e-6, max_iter=15):
+    """Approximate joint diagonalization based on Pham's algorithm.
+
+    This is a direct implementation of the PHAM's AJD algorithm [1].
+
+    Parameters
+    ----------
+    X : ndarray, shape (n_epochs, n_channels, n_channels)
+        A set of covariance matrices to diagonalize.
+    eps : float, default 1e-6
+        The tolerance for stopping criterion.
+    max_iter : int, default 1000
+        The maximum number of iteration to reach convergence.
+
+    Returns
+    -------
+    V : ndarray, shape (n_channels, n_channels)
+        The diagonalizer.
+    D : ndarray, shape (n_epochs, n_channels, n_channels)
+        The set of quasi diagonal matrices.
+
+    References
+    ----------
+    .. [1] Pham, Dinh Tuan. "Joint approximate diagonalization of positive
+           definite Hermitian matrices." SIAM Journal on Matrix Analysis and
+           Applications 22, no. 4 (2001): 1136-1152.
+
+    """
+    # Adapted from http://github.com/alexandrebarachant/pyRiemann
+    n_epochs = X.shape[0]
+
+    # Reshape input matrix
+    A = np.concatenate(X, axis=0).T
+
+    # Init variables
+    n_times, n_m = A.shape
+    V = np.eye(n_times)
+    epsilon = n_times * (n_times - 1) * eps
+
+    for it in range(max_iter):
+        decr = 0
+        for ii in range(1, n_times):
+            for jj in range(ii):
+                Ii = np.arange(ii, n_m, n_times)
+                Ij = np.arange(jj, n_m, n_times)
+
+                c1 = A[ii, Ii]
+                c2 = A[jj, Ij]
+
+                g12 = np.mean(A[ii, Ij] / c1)
+                g21 = np.mean(A[ii, Ij] / c2)
+
+                omega21 = np.mean(c1 / c2)
+                omega12 = np.mean(c2 / c1)
+                omega = np.sqrt(omega12 * omega21)
+
+                tmp = np.sqrt(omega21 / omega12)
+                tmp1 = (tmp * g12 + g21) / (omega + 1)
+                tmp2 = (tmp * g12 - g21) / max(omega - 1, 1e-9)
+
+                h12 = tmp1 + tmp2
+                h21 = np.conj((tmp1 - tmp2) / tmp)
+
+                decr += n_epochs * (g12 * np.conj(h12) + g21 * h21) / 2.0
+
+                tmp = 1 + 1.0j * 0.5 * np.imag(h12 * h21)
+                tmp = np.real(tmp + np.sqrt(tmp**2 - h12 * h21))
+                tau = np.array([[1, -h12 / tmp], [-h21 / tmp, 1]])
+
+                A[[ii, jj], :] = np.dot(tau, A[[ii, jj], :])
+                tmp = np.c_[A[:, Ii], A[:, Ij]]
+                tmp = np.reshape(tmp, (n_times * n_epochs, 2), order="F")
+                tmp = np.dot(tmp, tau.T)
+
+                tmp = np.reshape(tmp, (n_times, n_epochs * 2), order="F")
+                A[:, Ii] = tmp[:, :n_epochs]
+                A[:, Ij] = tmp[:, n_epochs:]
+                V[[ii, jj], :] = np.dot(tau, V[[ii, jj], :])
+        if decr < epsilon:
+            break
+    D = np.reshape(A, (n_times, -1, n_times)).transpose(1, 0, 2)
+    return V, D
+
+
+def _smart_ajd(covs, restr_map, weights):
+    covs = np.array([restr_map @ cov @ restr_map.T for cov in covs], float)
+    evecs_restr, D = _ajd_pham(covs)
+    evecs = _normalize_eigenvectors(evecs_restr.T, covs, weights)
+    evecs = restr_map.T @ evecs
+    return evecs
+
+
+def _get_restricting_map(C, info, rank):
+    _, ref_evecs, mask = _smart_eigh(
+        C,
+        info,
+        rank,
+        proj_subspace=True,
+        do_compute_rank=False,
+        log_ch_type="data",
+    )
+    restr_map = ref_evecs[mask]
+    return restr_map
+
+
+def _normalize_eigenvectors(evecs, covs, sample_weights):
+    # Here we apply an euclidean mean. See pyRiemann for other metrics
+    mean_cov = np.average(covs, axis=0, weights=sample_weights)
+
+    for ii in range(evecs.shape[1]):
+        tmp = np.dot(np.dot(evecs[:, ii].T, mean_cov), evecs[:, ii])
+        evecs[:, ii] /= np.sqrt(tmp)
+    return evecs
+
+
+def _get_ssd_rank(S, R, info, rank):
+    # find ranks of covariance matrices
+    rank_signal = list(
+        compute_rank(
+            Covariance(
+                S,
+                info.ch_names,
+                list(),
+                list(),
+                0,
+                verbose=_verbose_safe_false(),
+            ),
+            rank,
+            _handle_default("scalings_cov_rank", None),
+            info,
+        ).values()
+    )[0]
+    rank_noise = list(
+        compute_rank(
+            Covariance(
+                R,
+                info.ch_names,
+                list(),
+                list(),
+                0,
+                verbose=_verbose_safe_false(),
+            ),
+            rank,
+            _handle_default("scalings_cov_rank", None),
+            info,
+        ).values()
+    )[0]
+    rank = np.min([rank_signal, rank_noise])  # should be identical
+    return rank
+
+
+def _get_ssd_whitener(S, rank):
+    """Perform dimensionality reduction on the covariance matrices."""
+    n_channels = S.shape[0]
+    if rank < n_channels:
+        eigvals, eigvects = scipy.linalg.eigh(S)
+        # sort in descending order
+        ix = np.argsort(eigvals)[::-1]
+        eigvals = eigvals[ix]
+        eigvects = eigvects[:, ix]
+        # compute rank subspace projection matrix
+        rank_proj = np.matmul(
+            eigvects[:, :rank], np.eye(rank) * (eigvals[:rank] ** -0.5)
+        )
+        logger.info(
+            "Projecting covariance of %i channels to %i rank subspace",
+            n_channels,
+            rank,
+        )
+    else:
+        rank_proj = np.eye(n_channels)
+        logger.info("Preserving covariance rank (%i)", rank)
+
+    return rank_proj.T
diff --git a/mne/decoding/mod_ged.py b/mne/decoding/mod_ged.py
new file mode 100644
index 00000000000..ad3dc031f16
--- /dev/null
+++ b/mne/decoding/mod_ged.py
@@ -0,0 +1,69 @@
+"""Eigenvalue eigenvector modifiers for GED transformers."""
+
+# Authors: The MNE-Python contributors.
+# License: BSD-3-Clause
+# Copyright the MNE-Python contributors.
+
+import numpy as np
+
+
+def _compute_mutual_info(covs, sample_weights, evecs):
+    class_probas = sample_weights / sample_weights.sum()
+
+    mutual_info = []
+    for jj in range(evecs.shape[1]):
+        aa, bb = 0, 0
+        for cov, prob in zip(covs, class_probas):
+            tmp = np.dot(np.dot(evecs[:, jj].T, cov), evecs[:, jj])
+            aa += prob * np.log(np.sqrt(tmp))
+            bb += prob * (tmp**2 - 1)
+        mi = -(aa + (3.0 / 16) * (bb**2))
+        mutual_info.append(mi)
+
+    return mutual_info
+
+
+def _csp_mod(evals, evecs, covs, evecs_order, sample_weights):
+    n_classes = sample_weights.shape[0]
+    if evecs_order == "mutual_info" and n_classes > 2:
+        mutual_info = _compute_mutual_info(covs, sample_weights, evecs)
+        ix = np.argsort(mutual_info)[::-1]
+    elif evecs_order == "mutual_info" and n_classes == 2:
+        ix = np.argsort(np.abs(evals - 0.5))[::-1]
+    elif evecs_order == "alternate" and n_classes == 2:
+        i = np.argsort(evals)
+        ix = np.empty_like(i)
+        ix[1::2] = i[: len(i) // 2]
+        ix[0::2] = i[len(i) // 2 :][::-1]
+    if evals is not None:
+        evals = evals[ix]
+    evecs = evecs[:, ix]
+    return evals, evecs
+
+
+def _xdawn_mod(evals, evecs, covs=None):
+    evals, evecs = _sort_descending(evals, evecs)
+    evecs /= np.linalg.norm(evecs, axis=0)
+    return evals, evecs
+
+
+def _ssd_mod(evals, evecs, covs=None):
+    evals, evecs = _sort_descending(evals, evecs)
+    return evals, evecs
+
+
+def _spoc_mod(evals, evecs, covs=None):
+    evals = evals.real
+    evecs = evecs.real
+    evals, evecs = _sort_descending(evals, evecs, by_abs=True)
+    return evals, evecs
+
+
+def _sort_descending(evals, evecs, by_abs=False):
+    if by_abs:
+        ix = np.argsort(np.abs(evals))[::-1]
+    else:
+        ix = np.argsort(evals)[::-1]
+    evals = evals[ix]
+    evecs = evecs[:, ix]
+    return evals, evecs
diff --git a/mne/decoding/ssd.py b/mne/decoding/ssd.py
index 111ded9f274..367be7038d3 100644
--- a/mne/decoding/ssd.py
+++ b/mne/decoding/ssd.py
@@ -4,7 +4,6 @@
 
 import numpy as np
 from scipy.linalg import eigh
-from sklearn.base import BaseEstimator
 from sklearn.utils.validation import check_is_fitted
 
 from .._fiff.meas_info import Info, create_info
@@ -21,11 +20,13 @@
     fill_doc,
     logger,
 )
-from .transformer import MNETransformerMixin
+from .base import GEDTransformer
+from .covs_ged import _ssd_estimate
+from .mod_ged import _ssd_mod
 
 
 @fill_doc
-class SSD(MNETransformerMixin, BaseEstimator):
+class SSD(GEDTransformer):
     """
     Signal decomposition using the Spatio-Spectral Decomposition (SSD).
 
@@ -118,6 +119,28 @@ def __init__(
         self.cov_method_params = cov_method_params
         self.rank = rank
 
+        cov_params = dict(
+            reg=reg,
+            cov_method_params=cov_method_params,
+            info=info,
+            picks=picks,
+            filt_params_signal=filt_params_signal,
+            filt_params_noise=filt_params_noise,
+            rank=rank,
+        )
+
+        mod_params = dict()
+        super().__init__(
+            n_components,
+            _ssd_estimate,
+            cov_params,
+            _ssd_mod,
+            mod_params,
+            dec_type="single",
+            restr_map="ssd",
+            R_func=None,
+        )
+
     def _validate_params(self, X):
         if isinstance(self.info, float):  # special case, mostly for testing
             self.sfreq_ = self.info
@@ -240,6 +263,15 @@ def fit(self, X, y=None):
         self.filters_ = np.matmul(rank_proj, eigvects_[:, ix])
         self.patterns_ = np.linalg.pinv(self.filters_)
 
+        old_filters = self.filters_
+        old_patterns = self.patterns_
+        super().fit(X, y)
+        self.filters_ = self.filters_.T
+
+        np.testing.assert_allclose(self.eigvals_, self.evals_)
+        np.testing.assert_allclose(old_filters, self.filters_)
+        np.testing.assert_allclose(old_patterns, self.patterns_)
+
         # We assume that ordering by spectral ratio is more important
         # than the initial ordering. This ordering should be also learned when
         # fitting.
diff --git a/mne/preprocessing/xdawn.py b/mne/preprocessing/xdawn.py
index 606b49370df..f794e404f46 100644
--- a/mne/preprocessing/xdawn.py
+++ b/mne/preprocessing/xdawn.py
@@ -7,7 +7,9 @@
 
 from .._fiff.pick import _pick_data_channels, pick_info
 from ..cov import Covariance, _regularized_covariance
-from ..decoding import BaseEstimator, TransformerMixin
+from ..decoding.base import GEDTransformer
+from ..decoding.covs_ged import _xdawn_estimate
+from ..decoding.mod_ged import _xdawn_mod
 from ..epochs import BaseEpochs
 from ..evoked import Evoked, EvokedArray
 from ..io import BaseRaw
@@ -212,7 +214,7 @@ def _fit_xdawn(
     return filters, patterns, evokeds
 
 
-class _XdawnTransformer(BaseEstimator, TransformerMixin):
+class _XdawnTransformer(GEDTransformer):
     """Implementation of the Xdawn Algorithm compatible with scikit-learn.
 
     Xdawn is a spatial filtering method designed to improve the signal
@@ -259,6 +261,20 @@ def __init__(self, n_components=2, reg=None, signal_cov=None, method_params=None
         self.reg = reg
         self.method_params = method_params
 
+        cov_params = dict(reg=reg, cov_method_params=method_params, R=signal_cov)
+
+        mod_params = dict()
+        super().__init__(
+            n_components,
+            _xdawn_estimate,
+            cov_params,
+            _xdawn_mod,
+            mod_params,
+            dec_type="multi",
+            restr_map=None,
+            R_func=None,
+        )
+
     def fit(self, X, y=None):
         """Fit Xdawn spatial filters.
 
@@ -286,6 +302,26 @@ def fit(self, X, y=None):
             signal_cov=self.signal_cov,
             method_params=self.method_params,
         )
+        old_filters = self.filters_
+        old_patterns = self.patterns_
+        super().fit(X, y)
+        self.filters_ = np.concatenate(
+            [
+                self.filters_[i, : self.n_components]
+                for i in range(self.filters_.shape[0])
+            ],
+            axis=0,
+        )
+        self.patterns_ = np.concatenate(
+            [
+                self.patterns_[i, : self.n_components]
+                for i in range(self.patterns_.shape[0])
+            ],
+            axis=0,
+        )
+        np.testing.assert_allclose(old_filters, self.filters_)
+        np.testing.assert_allclose(old_patterns, self.patterns_)
+
         return self
 
     def transform(self, X):

From 7c072d15f7a7ce7440f20a444d884f5c4e9da007 Mon Sep 17 00:00:00 2001
From: Genuster <genusterok@gmail.com>
Date: Thu, 22 May 2025 16:35:21 +0300
Subject: [PATCH 02/59] update _epoch_cov logging following merge

---
 mne/decoding/covs_ged.py | 9 ++++++++-
 1 file changed, 8 insertions(+), 1 deletion(-)

diff --git a/mne/decoding/covs_ged.py b/mne/decoding/covs_ged.py
index 3df65d8107f..89e87f48820 100644
--- a/mne/decoding/covs_ged.py
+++ b/mne/decoding/covs_ged.py
@@ -11,7 +11,7 @@
 from .._fiff.pick import _picks_to_idx
 from ..cov import Covariance, _compute_rank_raw_array, _regularized_covariance
 from ..filter import filter_data
-from ..utils import pinv
+from ..utils import _verbose_safe_false, logger, pinv
 
 
 def _concat_cov(x_class, *, cov_kind, log_rank, reg, cov_method_params, rank, info):
@@ -36,6 +36,12 @@ def _concat_cov(x_class, *, cov_kind, log_rank, reg, cov_method_params, rank, in
 
 def _epoch_cov(x_class, *, cov_kind, log_rank, reg, cov_method_params, rank, info):
     """Mean of per-epoch covariances."""
+    name = reg if isinstance(reg, str) else "empirical"
+    name += " with shrinkage" if isinstance(reg, float) else ""
+    logger.info(
+        f"Estimating {cov_kind + (' ' if cov_kind else '')}"
+        f"covariance (average over epochs; {name.upper()})"
+    )
     cov = sum(
         _regularized_covariance(
             this_X,
@@ -46,6 +52,7 @@ def _epoch_cov(x_class, *, cov_kind, log_rank, reg, cov_method_params, rank, inf
             cov_kind=cov_kind,
             log_rank=log_rank and ii == 0,
             log_ch_type="data",
+            verbose=_verbose_safe_false(),
         )
         for ii, this_X in enumerate(x_class)
     )

From 211d23f6cb1b9eaed2cf0b62d598ef7c36e5fdc7 Mon Sep 17 00:00:00 2001
From: Genuster <genusterok@gmail.com>
Date: Thu, 22 May 2025 17:53:51 +0300
Subject: [PATCH 03/59] add a few preliminary docstrings

---
 mne/decoding/base.py | 58 +++++++++++++++++++++++++++++++++++++++++++-
 mne/decoding/ged.py  | 31 ++++++++++++++++++++---
 2 files changed, 85 insertions(+), 4 deletions(-)

diff --git a/mne/decoding/base.py b/mne/decoding/base.py
index 3737f11960a..d00b02b8391 100644
--- a/mne/decoding/base.py
+++ b/mne/decoding/base.py
@@ -28,7 +28,63 @@
 
 
 class GEDTransformer(MNETransformerMixin, BaseEstimator):
-    """..."""
+    """M/EEG signal decomposition using the generalized eigenvalue decomposition (GED).
+
+    Given two channel covariance matrices S and R, the goal is to find spatial filters
+    that maximise contrast between S and R.
+
+    Parameters
+    ----------
+    n_filters : int
+        The number of spatial filters to decompose M/EEG signals.
+    cov_callable : callable
+        Function used to estimate covariances and reference matrix (C_ref) from the
+        data.
+    cov_params : dict
+        Parameters passed to cov_callable.
+    mod_ged_callable : callable
+        Function used to modify (e.g. sort or normalize) generalized
+        eigenvalues and eigenvectors.
+    mod_params : dict
+        Parameters passed to mod_ged_callable.
+    dec_type : "single" | "multi"
+        When "single" and cov_callable returns > 2 covariances,
+        approximate joint diagonalization based on Pham's algorithm
+        will be used instead of GED.
+        When 'multi', GED is performed separately for each class, i.e. each covariance
+        (except the last) returned by cov_callable is decomposed with the last
+        covariance. In this case, number of covariances should be number of classes + 1.
+        Defaults to "single".
+    restr_map : "restricting" | "whitening" | "ssd" | None
+        Restricting transformation for covariance matrices before performing GED.
+        If "restricting" only restriction to the principal subspace of the C_ref
+        will be performed.
+        If "whitening", covariance matrices will be additionally rescaled according
+        to the whitening for the C_ref.
+        If "ssd", perform simplified version of "whitening",
+        preserved for compatibility.
+        If None, no restriction will be applied. Defaults to None.
+    R_func : callable | None
+        If provided GED will be performed on (S, R_func(S,R)).
+
+    Attributes
+    ----------
+    evals_ : ndarray, shape (n_channels)
+        If fit, generalized eigenvalues used to decompose S and R, else None.
+    filters_ :  ndarray, shape (n_channels or less, n_channels)
+        If fit, spatial filters (unmixing matrix) used to decompose the data,
+        else None.
+    patterns_ : ndarray, shape (n_channels or less, n_channels)
+        If fit, spatial patterns (mixing matrix) used to restore M/EEG signals,
+        else None.
+
+    See Also
+    --------
+    CSP
+    SPoC
+    SSD
+    mne.preprocessing.Xdawn
+    """
 
     def __init__(
         self,
diff --git a/mne/decoding/ged.py b/mne/decoding/ged.py
index 5e505f8be9a..d71db4aa2f8 100644
--- a/mne/decoding/ged.py
+++ b/mne/decoding/ged.py
@@ -12,6 +12,11 @@
 
 
 def _handle_restr_map(C_ref, restr_map, info, rank):
+    """Get restricting map to C_ref rank-dimensional principal subspace.
+
+    Returns matrix of shape (rank, n_chs) used to restrict or
+    restrict+rescale (whiten) covariances matrices.
+    """
     if C_ref is None or restr_map is None:
         return None
     if restr_map == "whitening":
@@ -31,8 +36,15 @@ def _handle_restr_map(C_ref, restr_map, info, rank):
     return restr_map
 
 
-def _smart_ged(S, R, restr_map, R_func=None, mult_order=None):
-    """..."""
+def _smart_ged(S, R, restr_map=None, R_func=None, mult_order=None):
+    """Perform smart generalized eigenvalue decomposition (GED) of S and R.
+
+    If restr_map is provided S and R will be restricted to the principal subspace
+    of a reference matrix with rank r (see _handle_restr_map), then GED is performed
+    on the restricted S and R and then generalized eigenvectors are transformed back
+    to the original space. The g-eigenvectors matrix is of shape (n_chs, r).
+    If callable R_func is provided the GED will be performed on (S, R_func(S,R))
+    """
     if restr_map is None:
         evals, evecs = scipy.linalg.eigh(S, R)
         return evals, evecs
@@ -135,7 +147,19 @@ def _ajd_pham(X, eps=1e-6, max_iter=15):
     return V, D
 
 
-def _smart_ajd(covs, restr_map, weights):
+def _smart_ajd(covs, restr_map=None, weights=None):
+    """Perform smart approximate joint diagonalization.
+
+    If restr_map is provided all the cov matrices will be restricted to the
+    principal subspace of a reference matrix with rank r (see _handle_restr_map),
+    then GED is performed on the restricted S and R and then generalized eigenvectors
+    are transformed back to the original space.
+    The matrix of generalized eigenvectors is of shape (n_chs, r).
+    """
+    if restr_map is None:
+        evecs, D = _ajd_pham(covs)
+        return evecs
+
     covs = np.array([restr_map @ cov @ restr_map.T for cov in covs], float)
     evecs_restr, D = _ajd_pham(covs)
     evecs = _normalize_eigenvectors(evecs_restr.T, covs, weights)
@@ -144,6 +168,7 @@ def _smart_ajd(covs, restr_map, weights):
 
 
 def _get_restricting_map(C, info, rank):
+    """Get map restricting covariance to rank-dimensional principal subspace of C."""
     _, ref_evecs, mask = _smart_eigh(
         C,
         info,

From 0d58c8d567b34454b594c05570e75cedbe6766fe Mon Sep 17 00:00:00 2001
From: Genuster <genusterok@gmail.com>
Date: Thu, 22 May 2025 19:43:38 +0300
Subject: [PATCH 04/59] bump rtol/atol for spoc

---
 mne/decoding/csp.py | 4 ++--
 1 file changed, 2 insertions(+), 2 deletions(-)

diff --git a/mne/decoding/csp.py b/mne/decoding/csp.py
index 1d378a66b3e..51ac2ce0c0c 100644
--- a/mne/decoding/csp.py
+++ b/mne/decoding/csp.py
@@ -982,8 +982,8 @@ def fit(self, X, y):
         super(CSP, self).fit(X, y)
 
         np.testing.assert_allclose(evals[ix], self.evals_)
-        np.testing.assert_allclose(old_filters, self.filters_)
-        np.testing.assert_allclose(old_patterns, self.patterns_)
+        np.testing.assert_allclose(old_filters, self.filters_, rtol=1e-6, atol=1e-7)
+        np.testing.assert_allclose(old_patterns, self.patterns_, rtol=1e-6, atol=1e-7)
 
         pick_filters = self.filters_[: self.n_components]
         X = np.asarray([np.dot(pick_filters, epoch) for epoch in X])

From 2a1c5cb27467962e7a505d6cb5012afcc3c64edc Mon Sep 17 00:00:00 2001
From: Genuster <genusterok@gmail.com>
Date: Thu, 29 May 2025 22:23:39 +0300
Subject: [PATCH 05/59] Add big sklearn compliance test

---
 mne/decoding/base.py           |  81 +++++++++++++++++----
 mne/decoding/covs_ged.py       |  22 ++++++
 mne/decoding/csp.py            |   4 +-
 mne/decoding/ged.py            |  69 ++++++------------
 mne/decoding/ssd.py            |   2 +-
 mne/decoding/tests/test_ged.py | 124 +++++++++++++++++++++++++++++++++
 mne/preprocessing/xdawn.py     |   2 +-
 7 files changed, 241 insertions(+), 63 deletions(-)
 create mode 100644 mne/decoding/tests/test_ged.py

diff --git a/mne/decoding/base.py b/mne/decoding/base.py
index d00b02b8391..ac4700b53ed 100644
--- a/mne/decoding/base.py
+++ b/mne/decoding/base.py
@@ -8,11 +8,11 @@
 import numbers
 
 import numpy as np
+import scipy.linalg
 from sklearn import model_selection as models
 from sklearn.base import (  # noqa: F401
     BaseEstimator,
     MetaEstimatorMixin,
-    TransformerMixin,
     clone,
     is_classifier,
 )
@@ -20,10 +20,11 @@
 from sklearn.metrics import check_scoring
 from sklearn.model_selection import KFold, StratifiedKFold, check_cv
 from sklearn.utils import check_array, check_X_y, indexable
+from sklearn.utils.validation import check_is_fitted
 
 from ..parallel import parallel_func
 from ..utils import _pl, logger, pinv, verbose, warn
-from .ged import _get_ssd_rank, _handle_restr_map, _smart_ajd, _smart_ged
+from .ged import _handle_restr_map, _smart_ajd, _smart_ged
 from .transformer import MNETransformerMixin
 
 
@@ -55,7 +56,7 @@ class GEDTransformer(MNETransformerMixin, BaseEstimator):
         (except the last) returned by cov_callable is decomposed with the last
         covariance. In this case, number of covariances should be number of classes + 1.
         Defaults to "single".
-    restr_map : "restricting" | "whitening" | "ssd" | None
+    restr_type : "restricting" | "whitening" | "ssd" | None
         Restricting transformation for covariance matrices before performing GED.
         If "restricting" only restriction to the principal subspace of the C_ref
         will be performed.
@@ -94,7 +95,7 @@ def __init__(
         mod_ged_callable,
         mod_params,
         dec_type="single",
-        restr_map=None,
+        restr_type=None,
         R_func=None,
     ):
         self.n_filters = n_filters
@@ -103,27 +104,35 @@ def __init__(
         self.mod_ged_callable = mod_ged_callable
         self.mod_params = mod_params
         self.dec_type = dec_type
-        self.restr_map = restr_map
+        self.restr_type = restr_type
         self.R_func = R_func
 
     def fit(self, X, y=None):
         """..."""
+        X, y = self._check_data(
+            X,
+            y=y,
+            fit=True,
+            return_y=True,
+            atleast_3d=False if self.restr_type == "ssd" else True,
+        )
         covs, C_ref, info, rank, kwargs = self.cov_callable(X, y, **self.cov_params)
+        self._validate_covariances(covs + [C_ref])
         if self.dec_type == "single":
             if len(covs) > 2:
+                covs = np.array(covs)
                 sample_weights = kwargs["sample_weights"]
-                restr_map = _handle_restr_map(C_ref, self.restr_map, info, rank)
+                restr_map = _handle_restr_map(C_ref, self.restr_type, info, rank)
                 evecs = _smart_ajd(covs, restr_map, weights=sample_weights)
                 evals = None
             else:
                 S = covs[0]
                 R = covs[1]
-                if self.restr_map == "ssd":
-                    rank = _get_ssd_rank(S, R, info, rank)
+                if self.restr_type == "ssd":
                     mult_order = "ssd"
                 else:
                     mult_order = None
-                restr_map = _handle_restr_map(C_ref, self.restr_map, info, rank)
+                restr_map = _handle_restr_map(C_ref, self.restr_type, info, rank)
                 evals, evecs = _smart_ged(
                     S, R, restr_map, R_func=self.R_func, mult_order=mult_order
                 )
@@ -133,7 +142,7 @@ def fit(self, X, y=None):
             )
             self.evals_ = evals
             self.filters_ = evecs.T
-            if self.restr_map == "ssd":
+            if self.restr_type == "ssd":
                 self.patterns_ = np.linalg.pinv(evecs)
             else:
                 self.patterns_ = pinv(evecs)
@@ -141,11 +150,18 @@ def fit(self, X, y=None):
         elif self.dec_type == "multi":
             self.classes_ = np.unique(y)
             R = covs[-1]
-            restr_map = _handle_restr_map(C_ref, self.restr_map, info, rank)
+            if self.restr_type == "ssd":
+                mult_order = "ssd"
+            else:
+                mult_order = None
+            restr_map = _handle_restr_map(C_ref, self.restr_type, info, rank)
             all_evals, all_evecs, all_patterns = list(), list(), list()
             for i in range(len(self.classes_)):
                 S = covs[i]
-                evals, evecs = _smart_ged(S, R, restr_map, R_func=self.R_func)
+
+                evals, evecs = _smart_ged(
+                    S, R, restr_map, R_func=self.R_func, mult_order=mult_order
+                )
 
                 evals, evecs = self.mod_ged_callable(
                     evals, evecs, covs, **self.mod_params, **kwargs
@@ -161,9 +177,48 @@ def fit(self, X, y=None):
 
     def transform(self, X):
         """..."""
-        X = np.dot(self.filters_, X)
+        check_is_fitted(self, "filters_")
+        X = self._check_data(X)
+        if self.dec_type == "single":
+            pick_filters = self.filters_[: self.n_filters]
+        elif self.dec_type == "multi":
+            pick_filters = np.concatenate(
+                [
+                    self.filters_[i, : self.n_filters]
+                    for i in range(self.filters_.shape[0])
+                ],
+                axis=0,
+            )
+        X = np.asarray([pick_filters @ epoch for epoch in X])
         return X
 
+    def _validate_covariances(self, covs):
+        for cov in covs:
+            if cov is None:
+                continue
+            is_sym = scipy.linalg.issymmetric(cov, rtol=1e-10, atol=1e-11)
+            if not is_sym:
+                raise ValueError(
+                    "One of covariances or C_ref is not symmetric, "
+                    "check your cov_callable"
+                )
+            if not np.all(np.linalg.eigvals(cov) >= 0):
+                ValueError(
+                    "One of covariances or C_ref has negative eigenvalues, "
+                    "check your cov_callable"
+                )
+
+    def __sklearn_tags__(self):
+        """Tag the transformer."""
+        tags = super().__sklearn_tags__()
+        tags.estimator_type = "transformer"
+        # Can be a transformer where S and R covs are not based on y classes.
+        tags.target_tags.required = False
+        tags.target_tags.one_d_labels = True
+        tags.input_tags.two_d_array = True
+        tags.input_tags.three_d_array = True
+        return tags
+
 
 class LinearModel(MetaEstimatorMixin, BaseEstimator):
     """Compute and store patterns from linear models.
diff --git a/mne/decoding/covs_ged.py b/mne/decoding/covs_ged.py
index 89e87f48820..f40e9fefcf3 100644
--- a/mne/decoding/covs_ged.py
+++ b/mne/decoding/covs_ged.py
@@ -10,7 +10,9 @@
 from .._fiff.meas_info import Info, create_info
 from .._fiff.pick import _picks_to_idx
 from ..cov import Covariance, _compute_rank_raw_array, _regularized_covariance
+from ..defaults import _handle_default
 from ..filter import filter_data
+from ..rank import compute_rank
 from ..utils import _verbose_safe_false, logger, pinv
 
 
@@ -293,6 +295,26 @@ def _ssd_estimate(
     )
     covs = [S, R]
     C_ref = S
+
+    all_ranks = list()
+    for cov in covs:
+        r = list(
+            compute_rank(
+                Covariance(
+                    cov,
+                    info.ch_names,
+                    list(),
+                    list(),
+                    0,
+                    verbose=_verbose_safe_false(),
+                ),
+                rank,
+                _handle_default("scalings_cov_rank", None),
+                info,
+            ).values()
+        )[0]
+    all_ranks.append(r)
+    rank = np.min(all_ranks)
     return covs, C_ref, info, rank, dict()
 
 
diff --git a/mne/decoding/csp.py b/mne/decoding/csp.py
index 51ac2ce0c0c..80e1d9c8f47 100644
--- a/mne/decoding/csp.py
+++ b/mne/decoding/csp.py
@@ -142,7 +142,7 @@ def __init__(
             _csp_mod,
             mod_params,
             dec_type="single",
-            restr_map="restricting",
+            restr_type="restricting",
             R_func=sum,
         )
 
@@ -911,7 +911,7 @@ def __init__(
             _spoc_mod,
             mod_params,
             dec_type="single",
-            restr_map=None,
+            restr_type=None,
             R_func=None,
         )
 
diff --git a/mne/decoding/ged.py b/mne/decoding/ged.py
index d71db4aa2f8..cabf23bccbb 100644
--- a/mne/decoding/ged.py
+++ b/mne/decoding/ged.py
@@ -6,28 +6,26 @@
 import scipy.linalg
 
 from ..cov import Covariance, _smart_eigh, compute_whitener
-from ..defaults import _handle_default
-from ..rank import compute_rank
-from ..utils import _verbose_safe_false, logger
+from ..utils import logger
 
 
-def _handle_restr_map(C_ref, restr_map, info, rank):
+def _handle_restr_map(C_ref, restr_type, info, rank):
     """Get restricting map to C_ref rank-dimensional principal subspace.
 
     Returns matrix of shape (rank, n_chs) used to restrict or
     restrict+rescale (whiten) covariances matrices.
     """
-    if C_ref is None or restr_map is None:
+    if C_ref is None or restr_type is None:
         return None
-    if restr_map == "whitening":
+    if restr_type == "whitening":
         projs = info["projs"]
         C_ref_cov = Covariance(C_ref, info.ch_names, info["bads"], projs, 0)
-        restr_map = compute_whitener(C_ref_cov, info, rank=rank, pca=True)
-    elif restr_map == "ssd":
+        restr_map = compute_whitener(C_ref_cov, info, rank=rank, pca=True)[0]
+    elif restr_type == "ssd":
         restr_map = _get_ssd_whitener(C_ref, rank)
-    elif restr_map == "restricting":
+    elif restr_type == "restricting":
         restr_map = _get_restricting_map(C_ref, info, rank)
-    elif isinstance(restr_map, callable):
+    elif isinstance(restr_type, callable):
         pass
     else:
         raise ValueError(
@@ -147,6 +145,15 @@ def _ajd_pham(X, eps=1e-6, max_iter=15):
     return V, D
 
 
+def _is_all_pos_def(covs):
+    for cov in covs:
+        try:
+            _ = scipy.linalg.cholesky(cov)
+        except np.linalg.LinAlgError:
+            return False
+    return True
+
+
 def _smart_ajd(covs, restr_map=None, weights=None):
     """Perform smart approximate joint diagonalization.
 
@@ -157,6 +164,12 @@ def _smart_ajd(covs, restr_map=None, weights=None):
     The matrix of generalized eigenvectors is of shape (n_chs, r).
     """
     if restr_map is None:
+        is_all_pos_def = _is_all_pos_def(covs)
+        if not is_all_pos_def:
+            raise ValueError(
+                "If C_ref is not provided by covariance estimator, "
+                "all the covs should be positive definite"
+            )
         evecs, D = _ajd_pham(covs)
         return evecs
 
@@ -191,42 +204,6 @@ def _normalize_eigenvectors(evecs, covs, sample_weights):
     return evecs
 
 
-def _get_ssd_rank(S, R, info, rank):
-    # find ranks of covariance matrices
-    rank_signal = list(
-        compute_rank(
-            Covariance(
-                S,
-                info.ch_names,
-                list(),
-                list(),
-                0,
-                verbose=_verbose_safe_false(),
-            ),
-            rank,
-            _handle_default("scalings_cov_rank", None),
-            info,
-        ).values()
-    )[0]
-    rank_noise = list(
-        compute_rank(
-            Covariance(
-                R,
-                info.ch_names,
-                list(),
-                list(),
-                0,
-                verbose=_verbose_safe_false(),
-            ),
-            rank,
-            _handle_default("scalings_cov_rank", None),
-            info,
-        ).values()
-    )[0]
-    rank = np.min([rank_signal, rank_noise])  # should be identical
-    return rank
-
-
 def _get_ssd_whitener(S, rank):
     """Perform dimensionality reduction on the covariance matrices."""
     n_channels = S.shape[0]
diff --git a/mne/decoding/ssd.py b/mne/decoding/ssd.py
index 367be7038d3..b8e0a060fb0 100644
--- a/mne/decoding/ssd.py
+++ b/mne/decoding/ssd.py
@@ -137,7 +137,7 @@ def __init__(
             _ssd_mod,
             mod_params,
             dec_type="single",
-            restr_map="ssd",
+            restr_type="ssd",
             R_func=None,
         )
 
diff --git a/mne/decoding/tests/test_ged.py b/mne/decoding/tests/test_ged.py
new file mode 100644
index 00000000000..cfc1c4abf81
--- /dev/null
+++ b/mne/decoding/tests/test_ged.py
@@ -0,0 +1,124 @@
+# Authors: The MNE-Python contributors.
+# License: BSD-3-Clause
+# Copyright the MNE-Python contributors.
+
+
+import functools
+
+import numpy as np
+import pytest
+
+pytest.importorskip("sklearn")
+
+
+from sklearn.model_selection import ParameterGrid
+from sklearn.utils.estimator_checks import parametrize_with_checks
+
+from mne import compute_rank, create_info
+from mne._fiff.proj import make_eeg_average_ref_proj
+from mne.cov import Covariance, _regularized_covariance
+from mne.decoding.base import GEDTransformer
+
+
+def _mock_info(n_channels):
+    info = create_info(n_channels, 1000.0, "eeg")
+    avg_eeg_projector = make_eeg_average_ref_proj(info=info, activate=False)
+    info["projs"].append(avg_eeg_projector)
+    return info
+
+
+def _get_min_rank(covs, info):
+    min_rank = dict(
+        eeg=min(
+            list(
+                compute_rank(
+                    Covariance(
+                        cov,
+                        info.ch_names,
+                        list(),
+                        list(),
+                        0,
+                        # verbose=_verbose_safe_false(),
+                    ),
+                    rank=None,
+                    # _handle_default("scalings_cov_rank", None),
+                    info=info,
+                ).values()
+            )[0]
+            for cov in covs
+        )
+    )
+    return min_rank
+
+
+def _mock_cov_callable(X, y, cov_method_params=None):
+    if cov_method_params is None:
+        cov_method_params = dict()
+    n_epochs, n_channels, n_times = X.shape
+
+    # To pass sklearn check:
+    if n_channels == 1:
+        n_channels = 2
+        X = np.tile(X, (1, n_channels, 1))
+
+    # To make covariance estimation sensible
+    if n_times == 1:
+        n_times = n_channels
+        X = np.tile(X, (1, 1, n_channels))
+
+    classes = np.unique(y)
+    covs, sample_weights = list(), list()
+    for ci, this_class in enumerate(classes):
+        class_data = X[y == this_class]
+        class_data = class_data.transpose(1, 0, 2).reshape(n_channels, -1)
+        cov = _regularized_covariance(class_data, **cov_method_params)
+        covs.append(cov)
+        sample_weights.append(class_data.shape[0])
+
+    ref_data = X.transpose(1, 0, 2).reshape(n_channels, -1)
+    C_ref = _regularized_covariance(ref_data, **cov_method_params)
+    info = _mock_info(n_channels)
+    rank = _get_min_rank(covs, info)
+    kwargs = dict()
+
+    # To pass sklearn check:
+    if len(covs) == 1:
+        covs.append(covs[0])
+
+    elif len(covs) > 2:
+        kwargs["sample_weights"] = sample_weights
+    return covs, C_ref, info, rank, kwargs
+
+
+def _mock_mod_ged_callable(evals, evecs, covs, **kwargs):
+    if evals is not None:
+        ix = np.argsort(evals)[::-1]
+        evals = evals[ix]
+        evecs = evecs[:, ix]
+    return evals, evecs
+
+
+param_grid = dict(
+    n_filters=[4],
+    cov_callable=[_mock_cov_callable],
+    cov_params=[
+        dict(cov_method_params=dict(reg="empirical")),
+    ],
+    mod_ged_callable=[_mock_mod_ged_callable],
+    mod_params=[dict()],
+    dec_type=["single", "multi"],
+    restr_type=[
+        "restricting",
+        "whitening",
+    ],  # Not covering "ssd" here because its tests work with 2D data.
+    R_func=[functools.partial(np.sum, axis=0)],
+)
+
+ged_estimators = [GEDTransformer(**p) for p in ParameterGrid(param_grid)]
+
+
+@pytest.mark.slowtest
+@parametrize_with_checks(ged_estimators)
+def test_sklearn_compliance(estimator, check):
+    """Test GEDTransformer compliance with sklearn."""
+    check(estimator)
diff --git a/mne/preprocessing/xdawn.py b/mne/preprocessing/xdawn.py
index f794e404f46..5ccc397a087 100644
--- a/mne/preprocessing/xdawn.py
+++ b/mne/preprocessing/xdawn.py
@@ -271,7 +271,7 @@ def __init__(self, n_components=2, reg=None, signal_cov=None, method_params=None
             _xdawn_mod,
             mod_params,
             dec_type="multi",
-            restr_map=None,
+            restr_type=None,
             R_func=None,
         )
 

From 6e8b3aa7dd5ba37f68b84729573c3c1e439582da Mon Sep 17 00:00:00 2001
From: Genuster <genusterok@gmail.com>
Date: Mon, 2 Jun 2025 19:30:46 +0300
Subject: [PATCH 06/59] add __sklearn_tags__ to vulture's whitelist

---
 tools/vulture_allowlist.py | 1 +
 1 file changed, 1 insertion(+)

diff --git a/tools/vulture_allowlist.py b/tools/vulture_allowlist.py
index 9d0e215ee80..08623cf14b8 100644
--- a/tools/vulture_allowlist.py
+++ b/tools/vulture_allowlist.py
@@ -43,6 +43,7 @@
 _._more_tags
 _.multi_class
 _.preserves_dtype
+_.__sklearn_tags__
 deep
 
 # Backward compat or rarely used

From b2e24eae398bf6567176054d0f3a7e0bab7174df Mon Sep 17 00:00:00 2001
From: Genuster <genusterok@gmail.com>
Date: Mon, 2 Jun 2025 19:43:05 +0300
Subject: [PATCH 07/59] calm vulture down per attribute

---
 tools/vulture_allowlist.py | 4 +++-
 1 file changed, 3 insertions(+), 1 deletion(-)

diff --git a/tools/vulture_allowlist.py b/tools/vulture_allowlist.py
index 08623cf14b8..32ee1091131 100644
--- a/tools/vulture_allowlist.py
+++ b/tools/vulture_allowlist.py
@@ -43,7 +43,9 @@
 _._more_tags
 _.multi_class
 _.preserves_dtype
-_.__sklearn_tags__
+_.one_d_labels
+_.two_d_array
+_.three_d_array
 deep
 
 # Backward compat or rarely used

From fbd585e83e5264cbaa1a9fb919c062cafbfea4c2 Mon Sep 17 00:00:00 2001
From: Genuster <genusterok@gmail.com>
Date: Mon, 2 Jun 2025 20:01:28 +0300
Subject: [PATCH 08/59] put the TransformerMixin back

---
 mne/decoding/base.py | 1 +
 1 file changed, 1 insertion(+)

diff --git a/mne/decoding/base.py b/mne/decoding/base.py
index ac4700b53ed..bd84c937311 100644
--- a/mne/decoding/base.py
+++ b/mne/decoding/base.py
@@ -13,6 +13,7 @@
 from sklearn.base import (  # noqa: F401
     BaseEstimator,
     MetaEstimatorMixin,
+    TransformerMixin,
     clone,
     is_classifier,
 )

From d142bd04048cc306ddc2415bdc9b72c2ab297ffc Mon Sep 17 00:00:00 2001
From: Genuster <genusterok@gmail.com>
Date: Mon, 2 Jun 2025 22:29:52 +0300
Subject: [PATCH 09/59] fix validation of covariances

---
 mne/decoding/base.py     | 5 +++--
 mne/decoding/covs_ged.py | 1 -
 2 files changed, 3 insertions(+), 3 deletions(-)

diff --git a/mne/decoding/base.py b/mne/decoding/base.py
index bd84c937311..ef1e3367857 100644
--- a/mne/decoding/base.py
+++ b/mne/decoding/base.py
@@ -118,10 +118,11 @@ def fit(self, X, y=None):
             atleast_3d=False if self.restr_type == "ssd" else True,
         )
         covs, C_ref, info, rank, kwargs = self.cov_callable(X, y, **self.cov_params)
-        self._validate_covariances(covs + [C_ref])
+        covs = np.stack(covs)
+        self._validate_covariances(covs)
+        self._validate_covariances([C_ref])
         if self.dec_type == "single":
             if len(covs) > 2:
-                covs = np.array(covs)
                 sample_weights = kwargs["sample_weights"]
                 restr_map = _handle_restr_map(C_ref, self.restr_type, info, rank)
                 evecs = _smart_ajd(covs, restr_map, weights=sample_weights)
diff --git a/mne/decoding/covs_ged.py b/mne/decoding/covs_ged.py
index f40e9fefcf3..627b7ebc900 100644
--- a/mne/decoding/covs_ged.py
+++ b/mne/decoding/covs_ged.py
@@ -246,7 +246,6 @@ def _xdawn_estimate(
         covs.append(evo_cov)
 
     covs.append(R)
-    covs = np.stack(covs)
     C_ref = None
     rank = None
     info = None

From 679636605a282e500a74da5b09f80ff2cbbc2a39 Mon Sep 17 00:00:00 2001
From: Genuster <genusterok@gmail.com>
Date: Wed, 4 Jun 2025 01:37:00 +0300
Subject: [PATCH 10/59] add gedtranformer tests with audvis dataset

---
 mne/decoding/tests/test_ged.py | 153 ++++++++++++++++++++++++++++++++-
 1 file changed, 151 insertions(+), 2 deletions(-)

diff --git a/mne/decoding/tests/test_ged.py b/mne/decoding/tests/test_ged.py
index cfc1c4abf81..10f11b765c0 100644
--- a/mne/decoding/tests/test_ged.py
+++ b/mne/decoding/tests/test_ged.py
@@ -2,8 +2,8 @@
 # License: BSD-3-Clause
 # Copyright the MNE-Python contributors.
 
-
 import functools
+from pathlib import Path
 
 import numpy as np
 import pytest
@@ -12,12 +12,22 @@
 
 
 from sklearn.model_selection import ParameterGrid
+from sklearn.utils._testing import assert_allclose
 from sklearn.utils.estimator_checks import parametrize_with_checks
 
-from mne import compute_rank, create_info
+from mne import Epochs, compute_rank, create_info, pick_types, read_events
 from mne._fiff.proj import make_eeg_average_ref_proj
 from mne.cov import Covariance, _regularized_covariance
 from mne.decoding.base import GEDTransformer
+from mne.decoding.ged import _get_restricting_map, _smart_ajd, _smart_ged
+from mne.io import read_raw
+
+data_dir = Path(__file__).parents[2] / "io" / "tests" / "data"
+raw_fname = data_dir / "test_raw.fif"
+event_name = data_dir / "test-eve.fif"
+tmin, tmax = -0.1, 0.2
+# if stop is too small pca may fail in some cases, but we're okay on this file
+start, stop = 0, 8
 
 
 def _mock_info(n_channels):
@@ -122,3 +132,142 @@ def _mock_mod_ged_callable(evals, evecs, covs, **kwargs):
 def test_sklearn_compliance(estimator, check):
     """Test GEDTransformer compliance with sklearn."""
     check(estimator)
+
+
+def _get_X_y(event_id):
+    raw = read_raw(raw_fname, preload=False)
+    events = read_events(event_name)
+    picks = pick_types(
+        raw.info, meg=True, stim=False, ecg=False, eog=False, exclude="bads"
+    )
+    picks = picks[2:12:3]  # subselect channels -> disable proj!
+    raw.add_proj([], remove_existing=True)
+    epochs = Epochs(
+        raw,
+        events,
+        event_id,
+        tmin,
+        tmax,
+        picks=picks,
+        baseline=(None, 0),
+        preload=True,
+        proj=False,
+    )
+    X = epochs.get_data(copy=False)
+    y = epochs.events[:, -1]
+    return X, y
+
+
+def test_ged_binary_cov():
+    """Test GEDTransformer on audvis dataset with two covariances."""
+    event_id = dict(aud_l=1, vis_l=3)
+    X, y = _get_X_y(event_id)
+    # Test "single" decomposition
+    covs, C_ref, info, rank, kwargs = _mock_cov_callable(X, y)
+    S, R = covs[0], covs[1]
+    restr_map = _get_restricting_map(C_ref, info, rank)
+    evals, evecs = _smart_ged(S, R, restr_map=restr_map, R_func=None)
+    actual_evals, actual_evecs = _mock_mod_ged_callable(evals, evecs, [S, R], **kwargs)
+    actual_filters = actual_evecs.T
+
+    ged = GEDTransformer(
+        n_filters=4,
+        cov_callable=_mock_cov_callable,
+        cov_params=dict(),
+        mod_ged_callable=_mock_mod_ged_callable,
+        mod_params=dict(),
+        dec_type="single",
+        restr_type="restricting",
+        R_func=None,
+    )
+    ged.fit(X, y)
+    desired_evals = ged.evals_
+    desired_filters = ged.filters_
+
+    assert_allclose(actual_evals, desired_evals)
+    assert_allclose(actual_filters, desired_filters)
+
+    # Test "multi" decomposition (loop), restr_map can be reused
+    all_evals, all_evecs = list(), list()
+    for i in range(len(covs)):
+        S = covs[i]
+        evals, evecs = _smart_ged(S, R, restr_map)
+        evals, evecs = _mock_mod_ged_callable(evals, evecs, covs)
+        all_evals.append(evals)
+        all_evecs.append(evecs.T)
+    actual_evals = np.array(all_evals)
+    actual_filters = np.array(all_evecs)
+
+    ged = GEDTransformer(
+        n_filters=4,
+        cov_callable=_mock_cov_callable,
+        cov_params=dict(),
+        mod_ged_callable=_mock_mod_ged_callable,
+        mod_params=dict(),
+        dec_type="multi",
+        restr_type="restricting",
+        R_func=None,
+    )
+    ged.fit(X, y)
+    desired_evals = ged.evals_
+    desired_filters = ged.filters_
+
+    assert_allclose(actual_evals, desired_evals)
+    assert_allclose(actual_filters, desired_filters)
+
+
+def test_ged_multicov():
+    """Test GEDTransformer on audvis dataset with multiple covariances."""
+    event_id = dict(aud_l=1, aud_r=2, vis_l=3, vis_r=4)
+    X, y = _get_X_y(event_id)
+    # Test "single" decomposition for multicov (AJD)
+    covs, C_ref, info, rank, kwargs = _mock_cov_callable(X, y)
+    restr_map = _get_restricting_map(C_ref, info, rank)
+    evecs = _smart_ajd(covs, restr_map=restr_map)
+    evals = None
+    _, actual_evecs = _mock_mod_ged_callable(evals, evecs, covs, **kwargs)
+    actual_filters = actual_evecs.T
+
+    ged = GEDTransformer(
+        n_filters=4,
+        cov_callable=_mock_cov_callable,
+        cov_params=dict(),
+        mod_ged_callable=_mock_mod_ged_callable,
+        mod_params=dict(),
+        dec_type="single",
+        restr_type="restricting",
+        R_func=None,
+    )
+    ged.fit(X, y)
+    desired_filters = ged.filters_
+
+    assert_allclose(actual_filters, desired_filters)
+
+    # Test "multi" decomposition for multicov (loop)
+    R = covs[-1]
+    all_evals, all_evecs = list(), list()
+    for i in range(len(covs)):
+        S = covs[i]
+        evals, evecs = _smart_ged(S, R, restr_map)
+        evals, evecs = _mock_mod_ged_callable(evals, evecs, covs)
+        all_evals.append(evals)
+        all_evecs.append(evecs.T)
+    actual_evals = np.array(all_evals)
+    actual_filters = np.array(all_evecs)
+
+    ged = GEDTransformer(
+        n_filters=4,
+        cov_callable=_mock_cov_callable,
+        cov_params=dict(),
+        mod_ged_callable=_mock_mod_ged_callable,
+        mod_params=dict(),
+        dec_type="multi",
+        restr_type="restricting",
+        R_func=None,
+    )
+    ged.fit(X, y)
+    desired_evals = ged.evals_
+    desired_filters = ged.filters_
+
+    assert_allclose(actual_evals, desired_evals)
+    assert_allclose(actual_filters, desired_filters)

From 7a291b1f02a306d90d01fbdeadc88d8264ea8323 Mon Sep 17 00:00:00 2001
From: Genuster <genusterok@gmail.com>
Date: Wed, 4 Jun 2025 21:41:42 +0300
Subject: [PATCH 11/59] fixes following Eric's comments

---
 mne/decoding/{covs_ged.py => _covs_ged.py} | 86 +---------------------
 mne/decoding/{mod_ged.py => _mod_ged.py}   |  0
 mne/decoding/base.py                       |  2 +-
 mne/decoding/csp.py                        |  8 +-
 mne/decoding/ged.py                        | 86 +---------------------
 mne/decoding/ssd.py                        |  8 +-
 mne/decoding/tests/test_ged.py             | 12 +--
 mne/preprocessing/xdawn.py                 |  8 +-
 8 files changed, 24 insertions(+), 186 deletions(-)
 rename mne/decoding/{covs_ged.py => _covs_ged.py} (72%)
 rename mne/decoding/{mod_ged.py => _mod_ged.py} (100%)

diff --git a/mne/decoding/covs_ged.py b/mne/decoding/_covs_ged.py
similarity index 72%
rename from mne/decoding/covs_ged.py
rename to mne/decoding/_covs_ged.py
index 627b7ebc900..3914a929770 100644
--- a/mne/decoding/covs_ged.py
+++ b/mne/decoding/_covs_ged.py
@@ -5,7 +5,6 @@
 # Copyright the MNE-Python contributors.
 
 import numpy as np
-import scipy.linalg
 
 from .._fiff.meas_info import Info, create_info
 from .._fiff.pick import _picks_to_idx
@@ -13,7 +12,7 @@
 from ..defaults import _handle_default
 from ..filter import filter_data
 from ..rank import compute_rank
-from ..utils import _verbose_safe_false, logger, pinv
+from ..utils import _verbose_safe_false, logger
 
 
 def _concat_cov(x_class, *, cov_kind, log_rank, reg, cov_method_params, rank, info):
@@ -110,87 +109,6 @@ def _csp_estimate(X, y, reg, cov_method_params, cov_est, rank, norm_trace):
     return covs, C_ref, _info, _rank, dict(sample_weights=np.array(sample_weights))
 
 
-def _construct_signal_from_epochs(epochs, events, sfreq, tmin):
-    """Reconstruct pseudo continuous signal from epochs."""
-    n_epochs, n_channels, n_times = epochs.shape
-    tmax = tmin + n_times / float(sfreq)
-    start = np.min(events[:, 0]) + int(tmin * sfreq)
-    stop = np.max(events[:, 0]) + int(tmax * sfreq) + 1
-
-    n_samples = stop - start
-    n_epochs, n_channels, n_times = epochs.shape
-    events_pos = events[:, 0] - events[0, 0]
-
-    raw = np.zeros((n_channels, n_samples))
-    for idx in range(n_epochs):
-        onset = events_pos[idx]
-        offset = onset + n_times
-        raw[:, onset:offset] = epochs[idx]
-
-    return raw
-
-
-def _least_square_evoked(epochs_data, events, tmin, sfreq):
-    """Least square estimation of evoked response from epochs data.
-
-    Parameters
-    ----------
-    epochs_data : array, shape (n_channels, n_times)
-        The epochs data to estimate evoked.
-    events : array, shape (n_events, 3)
-        The events typically returned by the read_events function.
-        If some events don't match the events of interest as specified
-        by event_id, they will be ignored.
-    tmin : float
-        Start time before event.
-    sfreq : float
-        Sampling frequency.
-
-    Returns
-    -------
-    evokeds : array, shape (n_class, n_components, n_times)
-        An concatenated array of evoked data for each event type.
-    toeplitz : array, shape (n_class * n_components, n_channels)
-        An concatenated array of toeplitz matrix for each event type.
-    """
-    n_epochs, n_channels, n_times = epochs_data.shape
-    tmax = tmin + n_times / float(sfreq)
-
-    # Deal with shuffled epochs
-    events = events.copy()
-    events[:, 0] -= events[0, 0] + int(tmin * sfreq)
-
-    # Construct raw signal
-    raw = _construct_signal_from_epochs(epochs_data, events, sfreq, tmin)
-
-    # Compute the independent evoked responses per condition, while correcting
-    # for event overlaps.
-    n_min, n_max = int(tmin * sfreq), int(tmax * sfreq)
-    window = n_max - n_min
-    n_samples = raw.shape[1]
-    toeplitz = list()
-    classes = np.unique(events[:, 2])
-    for ii, this_class in enumerate(classes):
-        # select events by type
-        sel = events[:, 2] == this_class
-
-        # build toeplitz matrix
-        trig = np.zeros((n_samples,))
-        ix_trig = (events[sel, 0]) + n_min
-        trig[ix_trig] = 1
-        toeplitz.append(scipy.linalg.toeplitz(trig[0:window], trig))
-
-    # Concatenate toeplitz
-    toeplitz = np.array(toeplitz)
-    X = np.concatenate(toeplitz)
-
-    # least square estimation
-    predictor = np.dot(pinv(np.dot(X, X.T)), X)
-    evokeds = np.dot(predictor, raw.T)
-    evokeds = np.transpose(np.vsplit(evokeds, len(classes)), (0, 2, 1))
-    return evokeds, toeplitz
-
-
 def _xdawn_estimate(
     X,
     y,
@@ -203,6 +121,8 @@ def _xdawn_estimate(
     info=None,
     rank="full",
 ):
+    from ..preprocessing.xdawn import _least_square_evoked
+
     if not isinstance(X, np.ndarray) or X.ndim != 3:
         raise ValueError("X must be 3D ndarray")
 
diff --git a/mne/decoding/mod_ged.py b/mne/decoding/_mod_ged.py
similarity index 100%
rename from mne/decoding/mod_ged.py
rename to mne/decoding/_mod_ged.py
diff --git a/mne/decoding/base.py b/mne/decoding/base.py
index ef1e3367857..f8b83f71ddc 100644
--- a/mne/decoding/base.py
+++ b/mne/decoding/base.py
@@ -29,7 +29,7 @@
 from .transformer import MNETransformerMixin
 
 
-class GEDTransformer(MNETransformerMixin, BaseEstimator):
+class _GEDTransformer(MNETransformerMixin, BaseEstimator):
     """M/EEG signal decomposition using the generalized eigenvalue decomposition (GED).
 
     Given two channel covariance matrices S and R, the goal is to find spatial filters
diff --git a/mne/decoding/csp.py b/mne/decoding/csp.py
index 80e1d9c8f47..53678ee827f 100644
--- a/mne/decoding/csp.py
+++ b/mne/decoding/csp.py
@@ -20,13 +20,13 @@
     logger,
     pinv,
 )
-from .base import GEDTransformer
-from .covs_ged import _csp_estimate, _spoc_estimate
-from .mod_ged import _csp_mod, _spoc_mod
+from ._covs_ged import _csp_estimate, _spoc_estimate
+from ._mod_ged import _csp_mod, _spoc_mod
+from .base import _GEDTransformer
 
 
 @fill_doc
-class CSP(GEDTransformer):
+class CSP(_GEDTransformer):
     """M/EEG signal decomposition using the Common Spatial Patterns (CSP).
 
     This class can be used as a supervised decomposition to estimate spatial
diff --git a/mne/decoding/ged.py b/mne/decoding/ged.py
index cabf23bccbb..68f11f9b1c4 100644
--- a/mne/decoding/ged.py
+++ b/mne/decoding/ged.py
@@ -61,90 +61,6 @@ def _smart_ged(S, R, restr_map=None, R_func=None, mult_order=None):
     return evals, evecs
 
 
-def _ajd_pham(X, eps=1e-6, max_iter=15):
-    """Approximate joint diagonalization based on Pham's algorithm.
-
-    This is a direct implementation of the PHAM's AJD algorithm [1].
-
-    Parameters
-    ----------
-    X : ndarray, shape (n_epochs, n_channels, n_channels)
-        A set of covariance matrices to diagonalize.
-    eps : float, default 1e-6
-        The tolerance for stopping criterion.
-    max_iter : int, default 1000
-        The maximum number of iteration to reach convergence.
-
-    Returns
-    -------
-    V : ndarray, shape (n_channels, n_channels)
-        The diagonalizer.
-    D : ndarray, shape (n_epochs, n_channels, n_channels)
-        The set of quasi diagonal matrices.
-
-    References
-    ----------
-    .. [1] Pham, Dinh Tuan. "Joint approximate diagonalization of positive
-           definite Hermitian matrices." SIAM Journal on Matrix Analysis and
-           Applications 22, no. 4 (2001): 1136-1152.
-
-    """
-    # Adapted from http://github.com/alexandrebarachant/pyRiemann
-    n_epochs = X.shape[0]
-
-    # Reshape input matrix
-    A = np.concatenate(X, axis=0).T
-
-    # Init variables
-    n_times, n_m = A.shape
-    V = np.eye(n_times)
-    epsilon = n_times * (n_times - 1) * eps
-
-    for it in range(max_iter):
-        decr = 0
-        for ii in range(1, n_times):
-            for jj in range(ii):
-                Ii = np.arange(ii, n_m, n_times)
-                Ij = np.arange(jj, n_m, n_times)
-
-                c1 = A[ii, Ii]
-                c2 = A[jj, Ij]
-
-                g12 = np.mean(A[ii, Ij] / c1)
-                g21 = np.mean(A[ii, Ij] / c2)
-
-                omega21 = np.mean(c1 / c2)
-                omega12 = np.mean(c2 / c1)
-                omega = np.sqrt(omega12 * omega21)
-
-                tmp = np.sqrt(omega21 / omega12)
-                tmp1 = (tmp * g12 + g21) / (omega + 1)
-                tmp2 = (tmp * g12 - g21) / max(omega - 1, 1e-9)
-
-                h12 = tmp1 + tmp2
-                h21 = np.conj((tmp1 - tmp2) / tmp)
-
-                decr += n_epochs * (g12 * np.conj(h12) + g21 * h21) / 2.0
-
-                tmp = 1 + 1.0j * 0.5 * np.imag(h12 * h21)
-                tmp = np.real(tmp + np.sqrt(tmp**2 - h12 * h21))
-                tau = np.array([[1, -h12 / tmp], [-h21 / tmp, 1]])
-
-                A[[ii, jj], :] = np.dot(tau, A[[ii, jj], :])
-                tmp = np.c_[A[:, Ii], A[:, Ij]]
-                tmp = np.reshape(tmp, (n_times * n_epochs, 2), order="F")
-                tmp = np.dot(tmp, tau.T)
-
-                tmp = np.reshape(tmp, (n_times, n_epochs * 2), order="F")
-                A[:, Ii] = tmp[:, :n_epochs]
-                A[:, Ij] = tmp[:, n_epochs:]
-                V[[ii, jj], :] = np.dot(tau, V[[ii, jj], :])
-        if decr < epsilon:
-            break
-    D = np.reshape(A, (n_times, -1, n_times)).transpose(1, 0, 2)
-    return V, D
-
-
 def _is_all_pos_def(covs):
     for cov in covs:
         try:
@@ -163,6 +79,8 @@ def _smart_ajd(covs, restr_map=None, weights=None):
     are transformed back to the original space.
     The matrix of generalized eigenvectors is of shape (n_chs, r).
     """
+    from .csp import _ajd_pham
+
     if restr_map is None:
         is_all_pos_def = _is_all_pos_def(covs)
         if not is_all_pos_def:
diff --git a/mne/decoding/ssd.py b/mne/decoding/ssd.py
index b8e0a060fb0..7c2c8a3d7ac 100644
--- a/mne/decoding/ssd.py
+++ b/mne/decoding/ssd.py
@@ -20,13 +20,13 @@
     fill_doc,
     logger,
 )
-from .base import GEDTransformer
-from .covs_ged import _ssd_estimate
-from .mod_ged import _ssd_mod
+from ._covs_ged import _ssd_estimate
+from ._mod_ged import _ssd_mod
+from .base import _GEDTransformer
 
 
 @fill_doc
-class SSD(GEDTransformer):
+class SSD(_GEDTransformer):
     """
     Signal decomposition using the Spatio-Spectral Decomposition (SSD).
 
diff --git a/mne/decoding/tests/test_ged.py b/mne/decoding/tests/test_ged.py
index 10f11b765c0..b72369404cf 100644
--- a/mne/decoding/tests/test_ged.py
+++ b/mne/decoding/tests/test_ged.py
@@ -18,7 +18,7 @@
 from mne import Epochs, compute_rank, create_info, pick_types, read_events
 from mne._fiff.proj import make_eeg_average_ref_proj
 from mne.cov import Covariance, _regularized_covariance
-from mne.decoding.base import GEDTransformer
+from mne.decoding.base import _GEDTransformer
 from mne.decoding.ged import _get_restricting_map, _smart_ajd, _smart_ged
 from mne.io import read_raw
 
@@ -124,7 +124,7 @@ def _mock_mod_ged_callable(evals, evecs, covs, **kwargs):
     R_func=[functools.partial(np.sum, axis=0)],
 )
 
-ged_estimators = [GEDTransformer(**p) for p in ParameterGrid(param_grid)]
+ged_estimators = [_GEDTransformer(**p) for p in ParameterGrid(param_grid)]
 
 
 @pytest.mark.slowtest
@@ -170,7 +170,7 @@ def test_ged_binary_cov():
     actual_evals, actual_evecs = _mock_mod_ged_callable(evals, evecs, [S, R], **kwargs)
     actual_filters = actual_evecs.T
 
-    ged = GEDTransformer(
+    ged = _GEDTransformer(
         n_filters=4,
         cov_callable=_mock_cov_callable,
         cov_params=dict(),
@@ -198,7 +198,7 @@ def test_ged_binary_cov():
     actual_evals = np.array(all_evals)
     actual_filters = np.array(all_evecs)
 
-    ged = GEDTransformer(
+    ged = _GEDTransformer(
         n_filters=4,
         cov_callable=_mock_cov_callable,
         cov_params=dict(),
@@ -228,7 +228,7 @@ def test_ged_multicov():
     _, actual_evecs = _mock_mod_ged_callable(evals, evecs, covs, **kwargs)
     actual_filters = actual_evecs.T
 
-    ged = GEDTransformer(
+    ged = _GEDTransformer(
         n_filters=4,
         cov_callable=_mock_cov_callable,
         cov_params=dict(),
@@ -255,7 +255,7 @@ def test_ged_multicov():
     actual_evals = np.array(all_evals)
     actual_filters = np.array(all_evecs)
 
-    ged = GEDTransformer(
+    ged = _GEDTransformer(
         n_filters=4,
         cov_callable=_mock_cov_callable,
         cov_params=dict(),
diff --git a/mne/preprocessing/xdawn.py b/mne/preprocessing/xdawn.py
index 5ccc397a087..d7775a87705 100644
--- a/mne/preprocessing/xdawn.py
+++ b/mne/preprocessing/xdawn.py
@@ -7,9 +7,9 @@
 
 from .._fiff.pick import _pick_data_channels, pick_info
 from ..cov import Covariance, _regularized_covariance
-from ..decoding.base import GEDTransformer
-from ..decoding.covs_ged import _xdawn_estimate
-from ..decoding.mod_ged import _xdawn_mod
+from ..decoding._covs_ged import _xdawn_estimate
+from ..decoding._mod_ged import _xdawn_mod
+from ..decoding.base import _GEDTransformer
 from ..epochs import BaseEpochs
 from ..evoked import Evoked, EvokedArray
 from ..io import BaseRaw
@@ -214,7 +214,7 @@ def _fit_xdawn(
     return filters, patterns, evokeds
 
 
-class _XdawnTransformer(GEDTransformer):
+class _XdawnTransformer(_GEDTransformer):
     """Implementation of the Xdawn Algorithm compatible with scikit-learn.
 
     Xdawn is a spatial filtering method designed to improve the signal

From 7c867ecc83a409da5915d7062bab53a061035fac Mon Sep 17 00:00:00 2001
From: Genuster <genusterok@gmail.com>
Date: Wed, 4 Jun 2025 23:20:56 +0300
Subject: [PATCH 12/59] document shapes

---
 mne/decoding/base.py       |  9 ++-------
 mne/decoding/csp.py        |  1 +
 mne/decoding/ssd.py        |  2 ++
 mne/preprocessing/xdawn.py | 25 +++++++++++++------------
 4 files changed, 18 insertions(+), 19 deletions(-)

diff --git a/mne/decoding/base.py b/mne/decoding/base.py
index f8b83f71ddc..645a5d09b9d 100644
--- a/mne/decoding/base.py
+++ b/mne/decoding/base.py
@@ -184,12 +184,8 @@ def transform(self, X):
         if self.dec_type == "single":
             pick_filters = self.filters_[: self.n_filters]
         elif self.dec_type == "multi":
-            pick_filters = np.concatenate(
-                [
-                    self.filters_[i, : self.n_filters]
-                    for i in range(self.filters_.shape[0])
-                ],
-                axis=0,
+            pick_filters = self.filters_[:, : self.n_filters, :].reshape(
+                -1, self.filters_.shape[2]
             )
         X = np.asarray([pick_filters @ epoch for epoch in X])
         return X
@@ -213,7 +209,6 @@ def _validate_covariances(self, covs):
     def __sklearn_tags__(self):
         """Tag the transformer."""
         tags = super().__sklearn_tags__()
-        tags.estimator_type = "transformer"
         # Can be a transformer where S and R covs are not based on y classes.
         tags.target_tags.required = False
         tags.target_tags.one_d_labels = True
diff --git a/mne/decoding/csp.py b/mne/decoding/csp.py
index 53678ee827f..47d40ef1b1e 100644
--- a/mne/decoding/csp.py
+++ b/mne/decoding/csp.py
@@ -216,6 +216,7 @@ def fit(self, X, y):
         old_filters = self.filters_
         old_patterns = self.patterns_
         super().fit(X, y)
+        # AJD returns evals_ as None.
         if self.evals_ is None:
             assert eigen_values is None
         else:
diff --git a/mne/decoding/ssd.py b/mne/decoding/ssd.py
index 7c2c8a3d7ac..25df128860f 100644
--- a/mne/decoding/ssd.py
+++ b/mne/decoding/ssd.py
@@ -266,6 +266,8 @@ def fit(self, X, y=None):
         old_filters = self.filters_
         old_patterns = self.patterns_
         super().fit(X, y)
+        # SSD, as opposed to CSP and Xdawn stores filters as (n_chs, n_components)
+        # So need to transpose into (n_components, n_chs)
         self.filters_ = self.filters_.T
 
         np.testing.assert_allclose(self.eigvals_, self.evals_)
diff --git a/mne/preprocessing/xdawn.py b/mne/preprocessing/xdawn.py
index d7775a87705..5d0e52cd7d8 100644
--- a/mne/preprocessing/xdawn.py
+++ b/mne/preprocessing/xdawn.py
@@ -305,19 +305,20 @@ def fit(self, X, y=None):
         old_filters = self.filters_
         old_patterns = self.patterns_
         super().fit(X, y)
-        self.filters_ = np.concatenate(
-            [
-                self.filters_[i, : self.n_components]
-                for i in range(self.filters_.shape[0])
-            ],
-            axis=0,
+        # Xdawn performs separate GED for each class.
+        # filters_ returned by _fit_xdawn are subset per
+        # n_components and then appended and are of shape
+        # (n_classes*n_components, n_chs).
+        # GEDTransformer creates new dimension per class without subsetting
+        # for easier analysis and visualisations.
+        # So it needs to be performed post-hoc to conform with Xdawn.
+        # The shape returned by GED here is (n_classes, n_evecs, n_chs)
+        # Need to transform and subset into (n_classes*n_components, n_chs)
+        self.filters_ = self.filters_[:, : self.n_components, :].reshape(
+            -1, self.filters_.shape[2]
         )
-        self.patterns_ = np.concatenate(
-            [
-                self.patterns_[i, : self.n_components]
-                for i in range(self.patterns_.shape[0])
-            ],
-            axis=0,
+        self.patterns_ = self.patterns_[:, : self.n_components, :].reshape(
+            -1, self.patterns_.shape[2]
         )
         np.testing.assert_allclose(old_filters, self.filters_)
         np.testing.assert_allclose(old_patterns, self.patterns_)

From e1e8d6d3a5b1735a386678678ba97377ebc455a1 Mon Sep 17 00:00:00 2001
From: Genuster <genusterok@gmail.com>
Date: Fri, 6 Jun 2025 16:13:25 +0300
Subject: [PATCH 13/59] another small test for GEDtransformer

---
 mne/decoding/base.py           |  2 +-
 mne/decoding/tests/test_ged.py | 21 +++++++++++++++++++++
 2 files changed, 22 insertions(+), 1 deletion(-)

diff --git a/mne/decoding/base.py b/mne/decoding/base.py
index 645a5d09b9d..3daddfef399 100644
--- a/mne/decoding/base.py
+++ b/mne/decoding/base.py
@@ -201,7 +201,7 @@ def _validate_covariances(self, covs):
                     "check your cov_callable"
                 )
             if not np.all(np.linalg.eigvals(cov) >= 0):
-                ValueError(
+                raise ValueError(
                     "One of covariances or C_ref has negative eigenvalues, "
                     "check your cov_callable"
                 )
diff --git a/mne/decoding/tests/test_ged.py b/mne/decoding/tests/test_ged.py
index b72369404cf..efb962341c8 100644
--- a/mne/decoding/tests/test_ged.py
+++ b/mne/decoding/tests/test_ged.py
@@ -271,3 +271,24 @@ def test_ged_multicov():
 
     assert_allclose(actual_evals, desired_evals)
     assert_allclose(actual_filters, desired_filters)
+
+
+def test_ged_invalid_cov():
+    """Test _validate_covariances raises proper errors."""
+    ged = _GEDTransformer(
+        n_filters=1,
+        cov_callable=_mock_cov_callable,
+        cov_params=dict(),
+        mod_ged_callable=_mock_mod_ged_callable,
+        mod_params=dict(),
+        dec_type="single",
+        restr_type=None,
+        R_func=None,
+    )
+    asymm_cov = np.array([[1, 2, 3], [4, 5, 6], [7, 8, 9]])
+    with pytest.raises(ValueError):
+        ged._validate_covariances([asymm_cov, None])
+
+    negsemidef_cov = np.array([[-2, 0, 0], [0, -1, 0], [0, 0, -3]])
+    with pytest.raises(ValueError):
+        ged._validate_covariances([negsemidef_cov, None])

From 5edc6fa01836f55c104783c850c013539317327f Mon Sep 17 00:00:00 2001
From: Genuster <genusterok@gmail.com>
Date: Fri, 6 Jun 2025 16:15:32 +0300
Subject: [PATCH 14/59] change name of restricting map to restricting matrix

---
 mne/decoding/base.py           | 14 ++++-----
 mne/decoding/ged.py            | 52 +++++++++++++++++-----------------
 mne/decoding/tests/test_ged.py | 16 +++++------
 3 files changed, 41 insertions(+), 41 deletions(-)

diff --git a/mne/decoding/base.py b/mne/decoding/base.py
index 3daddfef399..96516383f18 100644
--- a/mne/decoding/base.py
+++ b/mne/decoding/base.py
@@ -25,7 +25,7 @@
 
 from ..parallel import parallel_func
 from ..utils import _pl, logger, pinv, verbose, warn
-from .ged import _handle_restr_map, _smart_ajd, _smart_ged
+from .ged import _handle_restr_mat, _smart_ajd, _smart_ged
 from .transformer import MNETransformerMixin
 
 
@@ -124,8 +124,8 @@ def fit(self, X, y=None):
         if self.dec_type == "single":
             if len(covs) > 2:
                 sample_weights = kwargs["sample_weights"]
-                restr_map = _handle_restr_map(C_ref, self.restr_type, info, rank)
-                evecs = _smart_ajd(covs, restr_map, weights=sample_weights)
+                restr_mat = _handle_restr_mat(C_ref, self.restr_type, info, rank)
+                evecs = _smart_ajd(covs, restr_mat, weights=sample_weights)
                 evals = None
             else:
                 S = covs[0]
@@ -134,9 +134,9 @@ def fit(self, X, y=None):
                     mult_order = "ssd"
                 else:
                     mult_order = None
-                restr_map = _handle_restr_map(C_ref, self.restr_type, info, rank)
+                restr_mat = _handle_restr_mat(C_ref, self.restr_type, info, rank)
                 evals, evecs = _smart_ged(
-                    S, R, restr_map, R_func=self.R_func, mult_order=mult_order
+                    S, R, restr_mat, R_func=self.R_func, mult_order=mult_order
                 )
 
             evals, evecs = self.mod_ged_callable(
@@ -156,13 +156,13 @@ def fit(self, X, y=None):
                 mult_order = "ssd"
             else:
                 mult_order = None
-            restr_map = _handle_restr_map(C_ref, self.restr_type, info, rank)
+            restr_mat = _handle_restr_mat(C_ref, self.restr_type, info, rank)
             all_evals, all_evecs, all_patterns = list(), list(), list()
             for i in range(len(self.classes_)):
                 S = covs[i]
 
                 evals, evecs = _smart_ged(
-                    S, R, restr_map, R_func=self.R_func, mult_order=mult_order
+                    S, R, restr_mat, R_func=self.R_func, mult_order=mult_order
                 )
 
                 evals, evecs = self.mod_ged_callable(
diff --git a/mne/decoding/ged.py b/mne/decoding/ged.py
index 68f11f9b1c4..75dbb757eb6 100644
--- a/mne/decoding/ged.py
+++ b/mne/decoding/ged.py
@@ -9,8 +9,8 @@
 from ..utils import logger
 
 
-def _handle_restr_map(C_ref, restr_type, info, rank):
-    """Get restricting map to C_ref rank-dimensional principal subspace.
+def _handle_restr_mat(C_ref, restr_type, info, rank):
+    """Get restricting matrix to C_ref rank-dimensional principal subspace.
 
     Returns matrix of shape (rank, n_chs) used to restrict or
     restrict+rescale (whiten) covariances matrices.
@@ -20,43 +20,43 @@ def _handle_restr_map(C_ref, restr_type, info, rank):
     if restr_type == "whitening":
         projs = info["projs"]
         C_ref_cov = Covariance(C_ref, info.ch_names, info["bads"], projs, 0)
-        restr_map = compute_whitener(C_ref_cov, info, rank=rank, pca=True)[0]
+        restr_mat = compute_whitener(C_ref_cov, info, rank=rank, pca=True)[0]
     elif restr_type == "ssd":
-        restr_map = _get_ssd_whitener(C_ref, rank)
+        restr_mat = _get_ssd_whitener(C_ref, rank)
     elif restr_type == "restricting":
-        restr_map = _get_restricting_map(C_ref, info, rank)
+        restr_mat = _get_restr_mat(C_ref, info, rank)
     elif isinstance(restr_type, callable):
         pass
     else:
         raise ValueError(
-            "restr_map should either be callable or one of whitening, ssd, restricting"
+            "restr_type should either be callable or one of whitening, ssd, restricting"
         )
-    return restr_map
+    return restr_mat
 
 
-def _smart_ged(S, R, restr_map=None, R_func=None, mult_order=None):
+def _smart_ged(S, R, restr_mat=None, R_func=None, mult_order=None):
     """Perform smart generalized eigenvalue decomposition (GED) of S and R.
 
-    If restr_map is provided S and R will be restricted to the principal subspace
-    of a reference matrix with rank r (see _handle_restr_map), then GED is performed
+    If restr_mat is provided S and R will be restricted to the principal subspace
+    of a reference matrix with rank r (see _handle_restr_mat), then GED is performed
     on the restricted S and R and then generalized eigenvectors are transformed back
     to the original space. The g-eigenvectors matrix is of shape (n_chs, r).
     If callable R_func is provided the GED will be performed on (S, R_func(S,R))
     """
-    if restr_map is None:
+    if restr_mat is None:
         evals, evecs = scipy.linalg.eigh(S, R)
         return evals, evecs
 
     if mult_order == "ssd":
-        S_restr = restr_map @ (S @ restr_map.T)
-        R_restr = restr_map @ (R @ restr_map.T)
+        S_restr = restr_mat @ (S @ restr_mat.T)
+        R_restr = restr_mat @ (R @ restr_mat.T)
     else:
-        S_restr = restr_map @ S @ restr_map.T
-        R_restr = restr_map @ R @ restr_map.T
+        S_restr = restr_mat @ S @ restr_mat.T
+        R_restr = restr_mat @ R @ restr_mat.T
     if R_func is not None:
         R_restr = R_func([S_restr, R_restr])
     evals, evecs_restr = scipy.linalg.eigh(S_restr, R_restr)
-    evecs = restr_map.T @ evecs_restr
+    evecs = restr_mat.T @ evecs_restr
 
     return evals, evecs
 
@@ -70,18 +70,18 @@ def _is_all_pos_def(covs):
     return True
 
 
-def _smart_ajd(covs, restr_map=None, weights=None):
+def _smart_ajd(covs, restr_mat=None, weights=None):
     """Perform smart approximate joint diagonalization.
 
-    If restr_map is provided all the cov matrices will be restricted to the
-    principal subspace of a reference matrix with rank r (see _handle_restr_map),
+    If restr_mat is provided all the cov matrices will be restricted to the
+    principal subspace of a reference matrix with rank r (see _handle_restr_mat),
     then GED is performed on the restricted S and R and then generalized eigenvectors
     are transformed back to the original space.
     The matrix of generalized eigenvectors is of shape (n_chs, r).
     """
     from .csp import _ajd_pham
 
-    if restr_map is None:
+    if restr_mat is None:
         is_all_pos_def = _is_all_pos_def(covs)
         if not is_all_pos_def:
             raise ValueError(
@@ -91,15 +91,15 @@ def _smart_ajd(covs, restr_map=None, weights=None):
         evecs, D = _ajd_pham(covs)
         return evecs
 
-    covs = np.array([restr_map @ cov @ restr_map.T for cov in covs], float)
+    covs = np.array([restr_mat @ cov @ restr_mat.T for cov in covs], float)
     evecs_restr, D = _ajd_pham(covs)
     evecs = _normalize_eigenvectors(evecs_restr.T, covs, weights)
-    evecs = restr_map.T @ evecs
+    evecs = restr_mat.T @ evecs
     return evecs
 
 
-def _get_restricting_map(C, info, rank):
-    """Get map restricting covariance to rank-dimensional principal subspace of C."""
+def _get_restr_mat(C, info, rank):
+    """Get matrix restricting covariance to rank-dimensional principal subspace of C."""
     _, ref_evecs, mask = _smart_eigh(
         C,
         info,
@@ -108,8 +108,8 @@ def _get_restricting_map(C, info, rank):
         do_compute_rank=False,
         log_ch_type="data",
     )
-    restr_map = ref_evecs[mask]
-    return restr_map
+    restr_mat = ref_evecs[mask]
+    return restr_mat
 
 
 def _normalize_eigenvectors(evecs, covs, sample_weights):
diff --git a/mne/decoding/tests/test_ged.py b/mne/decoding/tests/test_ged.py
index efb962341c8..21d3a96f871 100644
--- a/mne/decoding/tests/test_ged.py
+++ b/mne/decoding/tests/test_ged.py
@@ -19,7 +19,7 @@
 from mne._fiff.proj import make_eeg_average_ref_proj
 from mne.cov import Covariance, _regularized_covariance
 from mne.decoding.base import _GEDTransformer
-from mne.decoding.ged import _get_restricting_map, _smart_ajd, _smart_ged
+from mne.decoding.ged import _get_restr_mat, _smart_ajd, _smart_ged
 from mne.io import read_raw
 
 data_dir = Path(__file__).parents[2] / "io" / "tests" / "data"
@@ -165,8 +165,8 @@ def test_ged_binary_cov():
     # Test "single" decomposition
     covs, C_ref, info, rank, kwargs = _mock_cov_callable(X, y)
     S, R = covs[0], covs[1]
-    restr_map = _get_restricting_map(C_ref, info, rank)
-    evals, evecs = _smart_ged(S, R, restr_map=restr_map, R_func=None)
+    restr_mat = _get_restr_mat(C_ref, info, rank)
+    evals, evecs = _smart_ged(S, R, restr_mat=restr_mat, R_func=None)
     actual_evals, actual_evecs = _mock_mod_ged_callable(evals, evecs, [S, R], **kwargs)
     actual_filters = actual_evecs.T
 
@@ -187,11 +187,11 @@ def test_ged_binary_cov():
     assert_allclose(actual_evals, desired_evals)
     assert_allclose(actual_filters, desired_filters)
 
-    # Test "multi" decomposition (loop), restr_map can be reused
+    # Test "multi" decomposition (loop), restr_mat can be reused
     all_evals, all_evecs = list(), list()
     for i in range(len(covs)):
         S = covs[i]
-        evals, evecs = _smart_ged(S, R, restr_map)
+        evals, evecs = _smart_ged(S, R, restr_mat)
         evals, evecs = _mock_mod_ged_callable(evals, evecs, covs)
         all_evals.append(evals)
         all_evecs.append(evecs.T)
@@ -222,8 +222,8 @@ def test_ged_multicov():
     X, y = _get_X_y(event_id)
     # Test "single" decomposition for multicov (AJD)
     covs, C_ref, info, rank, kwargs = _mock_cov_callable(X, y)
-    restr_map = _get_restricting_map(C_ref, info, rank)
-    evecs = _smart_ajd(covs, restr_map=restr_map)
+    restr_mat = _get_restr_mat(C_ref, info, rank)
+    evecs = _smart_ajd(covs, restr_mat=restr_mat)
     evals = None
     _, actual_evecs = _mock_mod_ged_callable(evals, evecs, covs, **kwargs)
     actual_filters = actual_evecs.T
@@ -248,7 +248,7 @@ def test_ged_multicov():
     all_evals, all_evecs = list(), list()
     for i in range(len(covs)):
         S = covs[i]
-        evals, evecs = _smart_ged(S, R, restr_map)
+        evals, evecs = _smart_ged(S, R, restr_mat)
         evals, evecs = _mock_mod_ged_callable(evals, evecs, covs)
         all_evals.append(evals)
         all_evecs.append(evecs.T)

From 89fb1411ce28c607388d26dce7da548c431db614 Mon Sep 17 00:00:00 2001
From: Genuster <genusterok@gmail.com>
Date: Fri, 6 Jun 2025 18:50:43 +0300
Subject: [PATCH 15/59] a few more ged tests

---
 mne/decoding/base.py           | 18 ++++++++---------
 mne/decoding/ged.py            | 33 +++++++++++++++++++++---------
 mne/decoding/tests/test_ged.py | 37 +++++++++++++++++++++++++++++-----
 3 files changed, 64 insertions(+), 24 deletions(-)

diff --git a/mne/decoding/base.py b/mne/decoding/base.py
index 96516383f18..1d8e240f621 100644
--- a/mne/decoding/base.py
+++ b/mne/decoding/base.py
@@ -8,7 +8,6 @@
 import numbers
 
 import numpy as np
-import scipy.linalg
 from sklearn import model_selection as models
 from sklearn.base import (  # noqa: F401
     BaseEstimator,
@@ -25,7 +24,7 @@
 
 from ..parallel import parallel_func
 from ..utils import _pl, logger, pinv, verbose, warn
-from .ged import _handle_restr_mat, _smart_ajd, _smart_ged
+from .ged import _handle_restr_mat, _is_cov_symm_pos_semidef, _smart_ajd, _smart_ged
 from .transformer import MNETransformerMixin
 
 
@@ -194,15 +193,14 @@ def _validate_covariances(self, covs):
         for cov in covs:
             if cov is None:
                 continue
-            is_sym = scipy.linalg.issymmetric(cov, rtol=1e-10, atol=1e-11)
-            if not is_sym:
+            # XXX: A lot of mne.decoding classes use mne.cov._regularized_covariance.
+            # Depending on the data it sometimes returns negative semidefinite matrices.
+            # So adding the validation of positive semidefinitiveness
+            # will require overhauling covariance estimation first.
+            is_cov = _is_cov_symm_pos_semidef(cov, check_pos_semidef=False)
+            if not is_cov:
                 raise ValueError(
-                    "One of covariances or C_ref is not symmetric, "
-                    "check your cov_callable"
-                )
-            if not np.all(np.linalg.eigvals(cov) >= 0):
-                raise ValueError(
-                    "One of covariances or C_ref has negative eigenvalues, "
+                    "One of covariances is not symmetric (or positive semidefinite), "
                     "check your cov_callable"
                 )
 
diff --git a/mne/decoding/ged.py b/mne/decoding/ged.py
index 75dbb757eb6..4627c89514d 100644
--- a/mne/decoding/ged.py
+++ b/mne/decoding/ged.py
@@ -25,8 +25,8 @@ def _handle_restr_mat(C_ref, restr_type, info, rank):
         restr_mat = _get_ssd_whitener(C_ref, rank)
     elif restr_type == "restricting":
         restr_mat = _get_restr_mat(C_ref, info, rank)
-    elif isinstance(restr_type, callable):
-        pass
+    elif callable(restr_type):
+        restr_mat = restr_type
     else:
         raise ValueError(
             "restr_type should either be callable or one of whitening, ssd, restricting"
@@ -61,15 +61,30 @@ def _smart_ged(S, R, restr_mat=None, R_func=None, mult_order=None):
     return evals, evecs
 
 
-def _is_all_pos_def(covs):
-    for cov in covs:
-        try:
-            _ = scipy.linalg.cholesky(cov)
-        except np.linalg.LinAlgError:
-            return False
+def _is_cov_symm_pos_semidef(
+    cov, rtol=1e-10, atol=1e-11, eval_tol=1e-15, check_pos_semidef=True
+):
+    is_symm = scipy.linalg.issymmetric(cov, rtol=rtol, atol=atol)
+    if not is_symm:
+        return False
+
+    if check_pos_semidef:
+        # numerically slightly negative evals are considered 0
+        is_pos_semidef = np.all(scipy.linalg.eigvalsh(cov) >= -eval_tol)
+        return is_pos_semidef
+
     return True
 
 
+def _is_cov_pos_def(cov, eval_tol=1e-15):
+    is_symm = _is_cov_symm_pos_semidef(cov, check_pos_semidef=False)
+    if not is_symm:
+        return False
+    # numerically slightly positive evals are considered 0
+    is_pos_def = np.all(scipy.linalg.eigvalsh(cov) > eval_tol)
+    return is_pos_def
+
+
 def _smart_ajd(covs, restr_mat=None, weights=None):
     """Perform smart approximate joint diagonalization.
 
@@ -82,7 +97,7 @@ def _smart_ajd(covs, restr_mat=None, weights=None):
     from .csp import _ajd_pham
 
     if restr_mat is None:
-        is_all_pos_def = _is_all_pos_def(covs)
+        is_all_pos_def = all([_is_cov_pos_def(cov) for cov in covs])
         if not is_all_pos_def:
             raise ValueError(
                 "If C_ref is not provided by covariance estimator, "
diff --git a/mne/decoding/tests/test_ged.py b/mne/decoding/tests/test_ged.py
index 21d3a96f871..f8db73ad070 100644
--- a/mne/decoding/tests/test_ged.py
+++ b/mne/decoding/tests/test_ged.py
@@ -19,7 +19,13 @@
 from mne._fiff.proj import make_eeg_average_ref_proj
 from mne.cov import Covariance, _regularized_covariance
 from mne.decoding.base import _GEDTransformer
-from mne.decoding.ged import _get_restr_mat, _smart_ajd, _smart_ged
+from mne.decoding.ged import (
+    _get_restr_mat,
+    _handle_restr_mat,
+    _is_cov_pos_def,
+    _smart_ajd,
+    _smart_ged,
+)
 from mne.io import read_raw
 
 data_dir = Path(__file__).parents[2] / "io" / "tests" / "data"
@@ -286,9 +292,30 @@ def test_ged_invalid_cov():
         R_func=None,
     )
     asymm_cov = np.array([[1, 2, 3], [4, 5, 6], [7, 8, 9]])
-    with pytest.raises(ValueError):
+    with pytest.raises(ValueError, match="not symmetric"):
         ged._validate_covariances([asymm_cov, None])
 
-    negsemidef_cov = np.array([[-2, 0, 0], [0, -1, 0], [0, 0, -3]])
-    with pytest.raises(ValueError):
-        ged._validate_covariances([negsemidef_cov, None])
+
+def test__handle_restr_mat_invalid_restr_type():
+    """Test _handle_restr_mat raises correct error when wrong restr_type."""
+    C_ref = np.eye(3)
+    with pytest.raises(ValueError, match="restr_type"):
+        _handle_restr_mat(C_ref, restr_type="blah", info=None, rank=None)
+
+
+def test__is_cov_pos_def():
+    """Test _is_cov_pos_def works."""
+    sing_pos_semidef = np.array([[1.0, 2.0, 3.0], [2.0, 4.0, 6.0], [3.0, 6.0, 9.0]])
+    pos_def = np.array([[5.0, 1.0, 1.0], [1.0, 6.0, 2.0], [1.0, 2.0, 7.0]])
+    assert not _is_cov_pos_def(sing_pos_semidef)
+    assert _is_cov_pos_def(pos_def)
+
+
+def test__smart_ajd_when_restr_mat_is_none():
+    """Test _smart_ajd raises ValueError when restr_mat is None."""
+    sing_pos_semidef = np.array([[1.0, 2.0, 3.0], [2.0, 4.0, 6.0], [3.0, 6.0, 9.0]])
+    pos_def1 = np.array([[5.0, 1.0, 1.0], [1.0, 6.0, 2.0], [1.0, 2.0, 7.0]])
+    pos_def2 = np.array([[10, 1, 2], [1, 12, 3], [2, 3, 15]])
+    bad_covs = [sing_pos_semidef, pos_def1, pos_def2]
+    with pytest.raises(ValueError, match="positive definite"):
+        _smart_ajd(bad_covs, restr_mat=None, weights=None)

From 3986c996a317ae46a538308368d43e2f22e2a9c4 Mon Sep 17 00:00:00 2001
From: Genuster <genusterok@gmail.com>
Date: Fri, 6 Jun 2025 18:58:48 +0300
Subject: [PATCH 16/59] fix multiplication order in original SSD

---
 mne/decoding/base.py | 16 ++--------------
 mne/decoding/ged.py  | 10 +++-------
 mne/decoding/ssd.py  |  4 ++--
 3 files changed, 7 insertions(+), 23 deletions(-)

diff --git a/mne/decoding/base.py b/mne/decoding/base.py
index 1d8e240f621..acb0566f655 100644
--- a/mne/decoding/base.py
+++ b/mne/decoding/base.py
@@ -129,14 +129,8 @@ def fit(self, X, y=None):
             else:
                 S = covs[0]
                 R = covs[1]
-                if self.restr_type == "ssd":
-                    mult_order = "ssd"
-                else:
-                    mult_order = None
                 restr_mat = _handle_restr_mat(C_ref, self.restr_type, info, rank)
-                evals, evecs = _smart_ged(
-                    S, R, restr_mat, R_func=self.R_func, mult_order=mult_order
-                )
+                evals, evecs = _smart_ged(S, R, restr_mat, R_func=self.R_func)
 
             evals, evecs = self.mod_ged_callable(
                 evals, evecs, covs, **self.mod_params, **kwargs
@@ -151,18 +145,12 @@ def fit(self, X, y=None):
         elif self.dec_type == "multi":
             self.classes_ = np.unique(y)
             R = covs[-1]
-            if self.restr_type == "ssd":
-                mult_order = "ssd"
-            else:
-                mult_order = None
             restr_mat = _handle_restr_mat(C_ref, self.restr_type, info, rank)
             all_evals, all_evecs, all_patterns = list(), list(), list()
             for i in range(len(self.classes_)):
                 S = covs[i]
 
-                evals, evecs = _smart_ged(
-                    S, R, restr_mat, R_func=self.R_func, mult_order=mult_order
-                )
+                evals, evecs = _smart_ged(S, R, restr_mat, R_func=self.R_func)
 
                 evals, evecs = self.mod_ged_callable(
                     evals, evecs, covs, **self.mod_params, **kwargs
diff --git a/mne/decoding/ged.py b/mne/decoding/ged.py
index 4627c89514d..b176b3ad3fd 100644
--- a/mne/decoding/ged.py
+++ b/mne/decoding/ged.py
@@ -34,7 +34,7 @@ def _handle_restr_mat(C_ref, restr_type, info, rank):
     return restr_mat
 
 
-def _smart_ged(S, R, restr_mat=None, R_func=None, mult_order=None):
+def _smart_ged(S, R, restr_mat=None, R_func=None):
     """Perform smart generalized eigenvalue decomposition (GED) of S and R.
 
     If restr_mat is provided S and R will be restricted to the principal subspace
@@ -47,12 +47,8 @@ def _smart_ged(S, R, restr_mat=None, R_func=None, mult_order=None):
         evals, evecs = scipy.linalg.eigh(S, R)
         return evals, evecs
 
-    if mult_order == "ssd":
-        S_restr = restr_mat @ (S @ restr_mat.T)
-        R_restr = restr_mat @ (R @ restr_mat.T)
-    else:
-        S_restr = restr_mat @ S @ restr_mat.T
-        R_restr = restr_mat @ R @ restr_mat.T
+    S_restr = restr_mat @ S @ restr_mat.T
+    R_restr = restr_mat @ R @ restr_mat.T
     if R_func is not None:
         R_restr = R_func([S_restr, R_restr])
     evals, evecs_restr = scipy.linalg.eigh(S_restr, R_restr)
diff --git a/mne/decoding/ssd.py b/mne/decoding/ssd.py
index 25df128860f..117bd45689b 100644
--- a/mne/decoding/ssd.py
+++ b/mne/decoding/ssd.py
@@ -460,6 +460,6 @@ def _dimensionality_reduction(cov_signal, cov_noise, info, rank):
         logger.info("Preserving covariance rank (%i)", rank)
 
     # project covariance matrices to rank subspace
-    cov_signal = np.matmul(rank_proj.T, np.matmul(cov_signal, rank_proj))
-    cov_noise = np.matmul(rank_proj.T, np.matmul(cov_noise, rank_proj))
+    cov_signal = rank_proj.T @ cov_signal @ rank_proj
+    cov_noise = rank_proj.T @ cov_noise @ rank_proj
     return cov_signal, cov_noise, rank_proj

From 11b038f4446d139752b53aae03ff87bc55d8c7fb Mon Sep 17 00:00:00 2001
From: Genuster <genusterok@gmail.com>
Date: Fri, 6 Jun 2025 23:17:02 +0300
Subject: [PATCH 17/59] add assert_allclose to xdawn and csp transform methods.

---
 mne/decoding/base.py           | 20 +++++++++++++-------
 mne/decoding/csp.py            | 14 ++++++++------
 mne/decoding/tests/test_ged.py | 12 ++++++------
 mne/preprocessing/xdawn.py     |  6 ++++++
 4 files changed, 33 insertions(+), 19 deletions(-)

diff --git a/mne/decoding/base.py b/mne/decoding/base.py
index acb0566f655..1b4bd665d1e 100644
--- a/mne/decoding/base.py
+++ b/mne/decoding/base.py
@@ -36,7 +36,7 @@ class _GEDTransformer(MNETransformerMixin, BaseEstimator):
 
     Parameters
     ----------
-    n_filters : int
+    n_components : int
         The number of spatial filters to decompose M/EEG signals.
     cov_callable : callable
         Function used to estimate covariances and reference matrix (C_ref) from the
@@ -89,7 +89,7 @@ class _GEDTransformer(MNETransformerMixin, BaseEstimator):
 
     def __init__(
         self,
-        n_filters,
+        n_components,
         cov_callable,
         cov_params,
         mod_ged_callable,
@@ -98,7 +98,7 @@ def __init__(
         restr_type=None,
         R_func=None,
     ):
-        self.n_filters = n_filters
+        self.n_components = n_components
         self.cov_callable = cov_callable
         self.cov_params = cov_params
         self.mod_ged_callable = mod_ged_callable
@@ -169,12 +169,18 @@ def transform(self, X):
         check_is_fitted(self, "filters_")
         X = self._check_data(X)
         if self.dec_type == "single":
-            pick_filters = self.filters_[: self.n_filters]
+            pick_filters = self.filters_[: self.n_components]
         elif self.dec_type == "multi":
-            pick_filters = self.filters_[:, : self.n_filters, :].reshape(
-                -1, self.filters_.shape[2]
+            # XXX: Hack to assert_allclose in Xdawn's transform.
+            # Will be removed when overhauling xdawn.
+            if hasattr(self, "new_filters_"):
+                filters = self.new_filters_
+            else:
+                filters = self.filters_
+            pick_filters = filters[:, : self.n_components, :].reshape(
+                -1, filters.shape[2]
             )
-        X = np.asarray([pick_filters @ epoch for epoch in X])
+        X = pick_filters @ X
         return X
 
     def _validate_covariances(self, covs):
diff --git a/mne/decoding/csp.py b/mne/decoding/csp.py
index 47d40ef1b1e..e72adaa0196 100644
--- a/mne/decoding/csp.py
+++ b/mne/decoding/csp.py
@@ -136,11 +136,11 @@ def __init__(
 
         mod_params = dict(evecs_order=component_order)
         super().__init__(
-            n_components,
-            _csp_estimate,
-            cov_params,
-            _csp_mod,
-            mod_params,
+            n_components=n_components,
+            cov_callable=_csp_estimate,
+            cov_params=cov_params,
+            mod_ged_callable=_csp_mod,
+            mod_params=mod_params,
             dec_type="single",
             restr_type="restricting",
             R_func=sum,
@@ -254,9 +254,11 @@ def transform(self, X):
         """
         check_is_fitted(self, "filters_")
         X = self._check_data(X)
+        orig_X = X.copy()
         pick_filters = self.filters_[: self.n_components]
         X = np.asarray([np.dot(pick_filters, epoch) for epoch in X])
-
+        ged_X = super().transform(orig_X)
+        np.testing.assert_allclose(X, ged_X)
         # compute features (mean band power)
         if self.transform_into == "average_power":
             X = (X**2).mean(axis=2)
diff --git a/mne/decoding/tests/test_ged.py b/mne/decoding/tests/test_ged.py
index f8db73ad070..433f28003ce 100644
--- a/mne/decoding/tests/test_ged.py
+++ b/mne/decoding/tests/test_ged.py
@@ -115,7 +115,7 @@ def _mock_mod_ged_callable(evals, evecs, covs, **kwargs):
 
 
 param_grid = dict(
-    n_filters=[4],
+    n_components=[4],
     cov_callable=[_mock_cov_callable],
     cov_params=[
         dict(cov_method_params=dict(reg="empirical")),
@@ -177,7 +177,7 @@ def test_ged_binary_cov():
     actual_filters = actual_evecs.T
 
     ged = _GEDTransformer(
-        n_filters=4,
+        n_components=4,
         cov_callable=_mock_cov_callable,
         cov_params=dict(),
         mod_ged_callable=_mock_mod_ged_callable,
@@ -205,7 +205,7 @@ def test_ged_binary_cov():
     actual_filters = np.array(all_evecs)
 
     ged = _GEDTransformer(
-        n_filters=4,
+        n_components=4,
         cov_callable=_mock_cov_callable,
         cov_params=dict(),
         mod_ged_callable=_mock_mod_ged_callable,
@@ -235,7 +235,7 @@ def test_ged_multicov():
     actual_filters = actual_evecs.T
 
     ged = _GEDTransformer(
-        n_filters=4,
+        n_components=4,
         cov_callable=_mock_cov_callable,
         cov_params=dict(),
         mod_ged_callable=_mock_mod_ged_callable,
@@ -262,7 +262,7 @@ def test_ged_multicov():
     actual_filters = np.array(all_evecs)
 
     ged = _GEDTransformer(
-        n_filters=4,
+        n_components=4,
         cov_callable=_mock_cov_callable,
         cov_params=dict(),
         mod_ged_callable=_mock_mod_ged_callable,
@@ -282,7 +282,7 @@ def test_ged_multicov():
 def test_ged_invalid_cov():
     """Test _validate_covariances raises proper errors."""
     ged = _GEDTransformer(
-        n_filters=1,
+        n_components=1,
         cov_callable=_mock_cov_callable,
         cov_params=dict(),
         mod_ged_callable=_mock_mod_ged_callable,
diff --git a/mne/preprocessing/xdawn.py b/mne/preprocessing/xdawn.py
index 5d0e52cd7d8..45681c8387c 100644
--- a/mne/preprocessing/xdawn.py
+++ b/mne/preprocessing/xdawn.py
@@ -305,6 +305,9 @@ def fit(self, X, y=None):
         old_filters = self.filters_
         old_patterns = self.patterns_
         super().fit(X, y)
+
+        # Hack for assert_allclose in transform
+        self.new_filters_ = self.filters_.copy()
         # Xdawn performs separate GED for each class.
         # filters_ returned by _fit_xdawn are subset per
         # n_components and then appended and are of shape
@@ -339,6 +342,7 @@ def transform(self, X):
             The transformed data.
         """
         X, _ = self._check_Xy(X)
+        orig_X = X.copy()
 
         # Check size
         if self.filters_.shape[1] != X.shape[1]:
@@ -350,6 +354,8 @@ def transform(self, X):
         # Transform
         X = np.dot(self.filters_, X)
         X = X.transpose((1, 0, 2))
+        ged_X = super().transform(orig_X)
+        np.testing.assert_allclose(X, ged_X)
         return X
 
     def inverse_transform(self, X):

From 25e1ae32f3b6e227fa44718ee3946b64099cd801 Mon Sep 17 00:00:00 2001
From: Genuster <genusterok@gmail.com>
Date: Sat, 7 Jun 2025 00:06:11 +0300
Subject: [PATCH 18/59] more ged tests

---
 mne/decoding/ged.py            | 13 +++----
 mne/decoding/tests/test_ged.py | 68 +++++++++++++++++++++++++++++-----
 2 files changed, 64 insertions(+), 17 deletions(-)

diff --git a/mne/decoding/ged.py b/mne/decoding/ged.py
index b176b3ad3fd..ad3a90e25c4 100644
--- a/mne/decoding/ged.py
+++ b/mne/decoding/ged.py
@@ -25,8 +25,6 @@ def _handle_restr_mat(C_ref, restr_type, info, rank):
         restr_mat = _get_ssd_whitener(C_ref, rank)
     elif restr_type == "restricting":
         restr_mat = _get_restr_mat(C_ref, info, rank)
-    elif callable(restr_type):
-        restr_mat = restr_type
     else:
         raise ValueError(
             "restr_type should either be callable or one of whitening, ssd, restricting"
@@ -102,11 +100,12 @@ def _smart_ajd(covs, restr_mat=None, weights=None):
         evecs, D = _ajd_pham(covs)
         return evecs
 
-    covs = np.array([restr_mat @ cov @ restr_mat.T for cov in covs], float)
-    evecs_restr, D = _ajd_pham(covs)
-    evecs = _normalize_eigenvectors(evecs_restr.T, covs, weights)
-    evecs = restr_mat.T @ evecs
-    return evecs
+    else:
+        covs = np.array([restr_mat @ cov @ restr_mat.T for cov in covs], float)
+        evecs_restr, D = _ajd_pham(covs)
+        evecs = _normalize_eigenvectors(evecs_restr.T, covs, weights)
+        evecs = restr_mat.T @ evecs
+        return evecs
 
 
 def _get_restr_mat(C, info, rank):
diff --git a/mne/decoding/tests/test_ged.py b/mne/decoding/tests/test_ged.py
index 433f28003ce..d4dd7b1ad2f 100644
--- a/mne/decoding/tests/test_ged.py
+++ b/mne/decoding/tests/test_ged.py
@@ -23,6 +23,7 @@
     _get_restr_mat,
     _handle_restr_mat,
     _is_cov_pos_def,
+    _is_cov_symm_pos_semidef,
     _smart_ajd,
     _smart_ged,
 )
@@ -67,7 +68,7 @@ def _get_min_rank(covs, info):
     return min_rank
 
 
-def _mock_cov_callable(X, y, cov_method_params=None):
+def _mock_cov_callable(X, y, cov_method_params=None, compute_C_ref=True):
     if cov_method_params is None:
         cov_method_params = dict()
     n_epochs, n_channels, n_times = X.shape
@@ -92,7 +93,10 @@ def _mock_cov_callable(X, y, cov_method_params=None):
         sample_weights.append(class_data.shape[0])
 
     ref_data = X.transpose(1, 0, 2).reshape(n_channels, -1)
-    C_ref = _regularized_covariance(ref_data, **cov_method_params)
+    if compute_C_ref:
+        C_ref = _regularized_covariance(ref_data, **cov_method_params)
+    else:
+        C_ref = None
     info = _mock_info(n_channels)
     rank = _get_min_rank(covs, info)
     kwargs = dict()
@@ -123,10 +127,12 @@ def _mock_mod_ged_callable(evals, evecs, covs, **kwargs):
     mod_ged_callable=[_mock_mod_ged_callable],
     mod_params=[dict()],
     dec_type=["single", "multi"],
+    # XXX: Not covering "ssd" here because test_ssd.py works with 2D data.
+    # Need to fix its tests first.
     restr_type=[
         "restricting",
         "whitening",
-    ],  # Not covering "ssd" here because its tests work with 2D data.
+    ],
     R_func=[functools.partial(np.sum, axis=0)],
 )
 
@@ -159,7 +165,7 @@ def _get_X_y(event_id):
         preload=True,
         proj=False,
     )
-    X = epochs.get_data(copy=False)
+    X = epochs.get_data(copy=False, units=dict(eeg="uV", grad="fT/cm", mag="fT"))
     y = epochs.events[:, -1]
     return X, y
 
@@ -226,7 +232,7 @@ def test_ged_multicov():
     """Test GEDTransformer on audvis dataset with multiple covariances."""
     event_id = dict(aud_l=1, aud_r=2, vis_l=3, vis_r=4)
     X, y = _get_X_y(event_id)
-    # Test "single" decomposition for multicov (AJD)
+    # Test "single" decomposition for multicov (AJD) with C_ref
     covs, C_ref, info, rank, kwargs = _mock_cov_callable(X, y)
     restr_mat = _get_restr_mat(C_ref, info, rank)
     evecs = _smart_ajd(covs, restr_mat=restr_mat)
@@ -278,6 +284,31 @@ def test_ged_multicov():
     assert_allclose(actual_evals, desired_evals)
     assert_allclose(actual_filters, desired_filters)
 
+    # Test "single" decomposition for multicov (AJD) without C_ref
+    covs, C_ref, info, rank, kwargs = _mock_cov_callable(
+        X, y, cov_method_params=dict(reg="oas"), compute_C_ref=False
+    )
+    covs = np.stack(covs)
+    evecs = _smart_ajd(covs, restr_mat=None)
+    evals = None
+    _, actual_evecs = _mock_mod_ged_callable(evals, evecs, covs, **kwargs)
+    actual_filters = actual_evecs.T
+
+    ged = _GEDTransformer(
+        n_components=4,
+        cov_callable=_mock_cov_callable,
+        cov_params=dict(cov_method_params=dict(reg="oas"), compute_C_ref=False),
+        mod_ged_callable=_mock_mod_ged_callable,
+        mod_params=dict(),
+        dec_type="single",
+        restr_type="restricting",
+        R_func=None,
+    )
+    ged.fit(X, y)
+    desired_filters = ged.filters_
+
+    assert_allclose(actual_filters, desired_filters)
+
 
 def test_ged_invalid_cov():
     """Test _validate_covariances raises proper errors."""
@@ -303,19 +334,36 @@ def test__handle_restr_mat_invalid_restr_type():
         _handle_restr_mat(C_ref, restr_type="blah", info=None, rank=None)
 
 
+def test_cov_validators():
+    """Test that covariance validators indeed validate."""
+    asymm = np.array([[1, 2, 3], [4, 5, 6], [7, 8, 9]])
+    sing_pos_semidef = np.array([[1, 2, 3], [2, 4, 6], [3, 6, 9]])
+    pos_def = np.array([[5, 1, 1], [1, 6, 2], [1, 2, 7]])
+
+    assert not _is_cov_symm_pos_semidef(asymm)
+    assert _is_cov_symm_pos_semidef(sing_pos_semidef)
+    assert _is_cov_symm_pos_semidef(pos_def)
+
+    assert not _is_cov_pos_def(asymm)
+    assert not _is_cov_pos_def(sing_pos_semidef)
+    assert _is_cov_pos_def(pos_def)
+
+
 def test__is_cov_pos_def():
     """Test _is_cov_pos_def works."""
-    sing_pos_semidef = np.array([[1.0, 2.0, 3.0], [2.0, 4.0, 6.0], [3.0, 6.0, 9.0]])
-    pos_def = np.array([[5.0, 1.0, 1.0], [1.0, 6.0, 2.0], [1.0, 2.0, 7.0]])
+    asymm = np.array([[1, 2, 3], [4, 5, 6], [7, 8, 9]])
+    sing_pos_semidef = np.array([[1, 2, 3], [2, 4, 6], [3, 6, 9]])
+    pos_def = np.array([[5, 1, 1], [1, 6, 2], [1, 2, 7]])
+    assert not _is_cov_pos_def(asymm)
     assert not _is_cov_pos_def(sing_pos_semidef)
     assert _is_cov_pos_def(pos_def)
 
 
 def test__smart_ajd_when_restr_mat_is_none():
     """Test _smart_ajd raises ValueError when restr_mat is None."""
-    sing_pos_semidef = np.array([[1.0, 2.0, 3.0], [2.0, 4.0, 6.0], [3.0, 6.0, 9.0]])
-    pos_def1 = np.array([[5.0, 1.0, 1.0], [1.0, 6.0, 2.0], [1.0, 2.0, 7.0]])
+    sing_pos_semidef = np.array([[1, 2, 3], [2, 4, 6], [3, 6, 9]])
+    pos_def1 = np.array([[5, 1, 1], [1, 6, 2], [1, 2, 7]])
     pos_def2 = np.array([[10, 1, 2], [1, 12, 3], [2, 3, 15]])
-    bad_covs = [sing_pos_semidef, pos_def1, pos_def2]
+    bad_covs = np.stack([sing_pos_semidef, pos_def1, pos_def2])
     with pytest.raises(ValueError, match="positive definite"):
         _smart_ajd(bad_covs, restr_mat=None, weights=None)

From 6bbc459bfc9b7cf4d327c4eb42354966a5af0c92 Mon Sep 17 00:00:00 2001
From: Genuster <genusterok@gmail.com>
Date: Tue, 10 Jun 2025 15:45:39 +0300
Subject: [PATCH 19/59] clean up _xdawn_estimate

---
 mne/decoding/_covs_ged.py | 28 +++++-----------------------
 1 file changed, 5 insertions(+), 23 deletions(-)

diff --git a/mne/decoding/_covs_ged.py b/mne/decoding/_covs_ged.py
index 3914a929770..ed9a5ce2502 100644
--- a/mne/decoding/_covs_ged.py
+++ b/mne/decoding/_covs_ged.py
@@ -115,17 +115,9 @@ def _xdawn_estimate(
     reg,
     cov_method_params,
     R=None,
-    events=None,
-    tmin=0,
-    sfreq=1,
     info=None,
     rank="full",
 ):
-    from ..preprocessing.xdawn import _least_square_evoked
-
-    if not isinstance(X, np.ndarray) or X.ndim != 3:
-        raise ValueError("X must be 3D ndarray")
-
     classes = np.unique(y)
 
     # XXX Eventually this could be made to deal with rank deficiency properly
@@ -140,23 +132,13 @@ def _xdawn_estimate(
         )
     elif isinstance(R, Covariance):
         R = R.data
-    if not isinstance(R, np.ndarray) or (
-        not np.array_equal(R.shape, np.tile(X.shape[1], 2))
-    ):
-        raise ValueError(
-            "R must be None, a covariance instance, "
-            "or an array of shape (n_chans, n_chans)"
-        )
 
     # Get prototype events
-    if events is not None:
-        evokeds, toeplitzs = _least_square_evoked(X, events, tmin, sfreq)
-    else:
-        evokeds, toeplitzs = list(), list()
-        for c in classes:
-            # Prototyped response for each class
-            evokeds.append(np.mean(X[y == c, :, :], axis=0))
-            toeplitzs.append(1.0)
+    evokeds, toeplitzs = list(), list()
+    for c in classes:
+        # Prototyped response for each class
+        evokeds.append(np.mean(X[y == c, :, :], axis=0))
+        toeplitzs.append(1.0)
 
     covs = []
     for evo, toeplitz in zip(evokeds, toeplitzs):

From 029691b9b59cfd0b7181737a2e4df72fe096caca Mon Sep 17 00:00:00 2001
From: Genuster <genusterok@gmail.com>
Date: Tue, 10 Jun 2025 16:27:45 +0300
Subject: [PATCH 20/59] add _validate_params for _XdawnTransformer

---
 mne/preprocessing/xdawn.py | 22 ++++++++++++++++++++--
 1 file changed, 20 insertions(+), 2 deletions(-)

diff --git a/mne/preprocessing/xdawn.py b/mne/preprocessing/xdawn.py
index 45681c8387c..a94be56528b 100644
--- a/mne/preprocessing/xdawn.py
+++ b/mne/preprocessing/xdawn.py
@@ -2,6 +2,8 @@
 # License: BSD-3-Clause
 # Copyright the MNE-Python contributors.
 
+from collections.abc import Mapping
+
 import numpy as np
 from scipy import linalg
 
@@ -13,7 +15,7 @@
 from ..epochs import BaseEpochs
 from ..evoked import Evoked, EvokedArray
 from ..io import BaseRaw
-from ..utils import _check_option, logger, pinv
+from ..utils import _check_option, _validate_type, logger, pinv
 
 
 def _construct_signal_from_epochs(epochs, events, sfreq, tmin):
@@ -275,6 +277,22 @@ def __init__(self, n_components=2, reg=None, signal_cov=None, method_params=None
             R_func=None,
         )
 
+    def _validate_params(self, X):
+        _validate_type(self.n_components, int, "n_components")
+
+        # reg is validated in _regularized_covariance
+
+        if self.signal_cov is not None:
+            if isinstance(self.signal_cov, Covariance):
+                self.signal_cov = self.signal_cov.data
+            elif not isinstance(self.signal_cov, np.ndarray):
+                raise ValueError("signal_cov should be mne.Covariance or np.ndarray")
+            if not np.array_equal(self.signal_cov.shape, np.tile(X.shape[1], 2)):
+                raise ValueError(
+                    "signal_cov data should be of shape (n_channels, n_channels)"
+                )
+        _validate_type(self.method_params, (Mapping, None))
+
     def fit(self, X, y=None):
         """Fit Xdawn spatial filters.
 
@@ -291,7 +309,7 @@ def fit(self, X, y=None):
             The Xdawn instance.
         """
         X, y = self._check_Xy(X, y)
-
+        self._validate_params(X)
         # Main function
         self.classes_ = np.unique(y)
         self.filters_, self.patterns_, _ = _fit_xdawn(

From f38ce7d32423089eed62cefe4eb60b1650310f0c Mon Sep 17 00:00:00 2001
From: Genuster <7503709+Genuster@users.noreply.github.com>
Date: Fri, 13 Jun 2025 13:09:49 +0300
Subject: [PATCH 21/59] review suggestions

Co-authored-by: Eric Larson <larson.eric.d@gmail.com>
---
 mne/decoding/_covs_ged.py      |  3 +--
 mne/decoding/base.py           | 10 ++++++----
 mne/decoding/csp.py            |  5 +----
 mne/decoding/tests/test_ged.py |  6 ------
 mne/preprocessing/xdawn.py     |  2 --
 5 files changed, 8 insertions(+), 18 deletions(-)

diff --git a/mne/decoding/_covs_ged.py b/mne/decoding/_covs_ged.py
index ed9a5ce2502..46c82715d4b 100644
--- a/mne/decoding/_covs_ged.py
+++ b/mne/decoding/_covs_ged.py
@@ -30,9 +30,8 @@ def _concat_cov(x_class, *, cov_kind, log_rank, reg, cov_method_params, rank, in
         log_rank=log_rank,
         log_ch_type="data",
     )
-    weight = x_class.shape[0]
 
-    return cov, weight
+    return cov, n_channels  # the weight here is just the number of channels
 
 
 def _epoch_cov(x_class, *, cov_kind, log_rank, reg, cov_method_params, rank, info):
diff --git a/mne/decoding/base.py b/mne/decoding/base.py
index 1b4bd665d1e..64eee7fc514 100644
--- a/mne/decoding/base.py
+++ b/mne/decoding/base.py
@@ -46,7 +46,7 @@ class _GEDTransformer(MNETransformerMixin, BaseEstimator):
     mod_ged_callable : callable
         Function used to modify (e.g. sort or normalize) generalized
         eigenvalues and eigenvectors.
-    mod_params : dict
+    mod_params : dict | None
         Parameters passed to mod_ged_callable.
     dec_type : "single" | "multi"
         When "single" and cov_callable returns > 2 covariances,
@@ -93,7 +93,8 @@ def __init__(
         cov_callable,
         cov_params,
         mod_ged_callable,
-        mod_params,
+        *,
+        mod_params=None,
         dec_type="single",
         restr_type=None,
         R_func=None,
@@ -120,6 +121,7 @@ def fit(self, X, y=None):
         covs = np.stack(covs)
         self._validate_covariances(covs)
         self._validate_covariances([C_ref])
+        mod_params = self.mod_params if self.mod_params is not None else dict()
         if self.dec_type == "single":
             if len(covs) > 2:
                 sample_weights = kwargs["sample_weights"]
@@ -133,7 +135,7 @@ def fit(self, X, y=None):
                 evals, evecs = _smart_ged(S, R, restr_mat, R_func=self.R_func)
 
             evals, evecs = self.mod_ged_callable(
-                evals, evecs, covs, **self.mod_params, **kwargs
+                evals, evecs, covs, **mod_params, **kwargs
             )
             self.evals_ = evals
             self.filters_ = evecs.T
@@ -153,7 +155,7 @@ def fit(self, X, y=None):
                 evals, evecs = _smart_ged(S, R, restr_mat, R_func=self.R_func)
 
                 evals, evecs = self.mod_ged_callable(
-                    evals, evecs, covs, **self.mod_params, **kwargs
+                    evals, evecs, covs, **mod_params, **kwargs
                 )
                 all_evals.append(evals)
                 all_evecs.append(evecs.T)
diff --git a/mne/decoding/csp.py b/mne/decoding/csp.py
index e72adaa0196..3b3e83c7905 100644
--- a/mne/decoding/csp.py
+++ b/mne/decoding/csp.py
@@ -134,13 +134,12 @@ def __init__(
             norm_trace=norm_trace,
         )
 
-        mod_params = dict(evecs_order=component_order)
         super().__init__(
             n_components=n_components,
             cov_callable=_csp_estimate,
             cov_params=cov_params,
             mod_ged_callable=_csp_mod,
-            mod_params=mod_params,
+            mod_params=dict(evecs_order=component_order),
             dec_type="single",
             restr_type="restricting",
             R_func=sum,
@@ -906,13 +905,11 @@ def __init__(
             rank=rank,
         )
 
-        mod_params = dict()
         super(CSP, self).__init__(
             n_components,
             _spoc_estimate,
             cov_params,
             _spoc_mod,
-            mod_params,
             dec_type="single",
             restr_type=None,
             R_func=None,
diff --git a/mne/decoding/tests/test_ged.py b/mne/decoding/tests/test_ged.py
index d4dd7b1ad2f..ec0aa7b18c7 100644
--- a/mne/decoding/tests/test_ged.py
+++ b/mne/decoding/tests/test_ged.py
@@ -187,7 +187,6 @@ def test_ged_binary_cov():
         cov_callable=_mock_cov_callable,
         cov_params=dict(),
         mod_ged_callable=_mock_mod_ged_callable,
-        mod_params=dict(),
         dec_type="single",
         restr_type="restricting",
         R_func=None,
@@ -215,7 +214,6 @@ def test_ged_binary_cov():
         cov_callable=_mock_cov_callable,
         cov_params=dict(),
         mod_ged_callable=_mock_mod_ged_callable,
-        mod_params=dict(),
         dec_type="multi",
         restr_type="restricting",
         R_func=None,
@@ -245,7 +243,6 @@ def test_ged_multicov():
         cov_callable=_mock_cov_callable,
         cov_params=dict(),
         mod_ged_callable=_mock_mod_ged_callable,
-        mod_params=dict(),
         dec_type="single",
         restr_type="restricting",
         R_func=None,
@@ -272,7 +269,6 @@ def test_ged_multicov():
         cov_callable=_mock_cov_callable,
         cov_params=dict(),
         mod_ged_callable=_mock_mod_ged_callable,
-        mod_params=dict(),
         dec_type="multi",
         restr_type="restricting",
         R_func=None,
@@ -299,7 +295,6 @@ def test_ged_multicov():
         cov_callable=_mock_cov_callable,
         cov_params=dict(cov_method_params=dict(reg="oas"), compute_C_ref=False),
         mod_ged_callable=_mock_mod_ged_callable,
-        mod_params=dict(),
         dec_type="single",
         restr_type="restricting",
         R_func=None,
@@ -317,7 +312,6 @@ def test_ged_invalid_cov():
         cov_callable=_mock_cov_callable,
         cov_params=dict(),
         mod_ged_callable=_mock_mod_ged_callable,
-        mod_params=dict(),
         dec_type="single",
         restr_type=None,
         R_func=None,
diff --git a/mne/preprocessing/xdawn.py b/mne/preprocessing/xdawn.py
index a94be56528b..cd9b2a0ee2f 100644
--- a/mne/preprocessing/xdawn.py
+++ b/mne/preprocessing/xdawn.py
@@ -265,13 +265,11 @@ def __init__(self, n_components=2, reg=None, signal_cov=None, method_params=None
 
         cov_params = dict(reg=reg, cov_method_params=method_params, R=signal_cov)
 
-        mod_params = dict()
         super().__init__(
             n_components,
             _xdawn_estimate,
             cov_params,
             _xdawn_mod,
-            mod_params,
             dec_type="multi",
             restr_type=None,
             R_func=None,

From 11c31f7fba3c31adb75d5f79fa253cdec100f441 Mon Sep 17 00:00:00 2001
From: Genuster <genusterok@gmail.com>
Date: Fri, 13 Jun 2025 13:37:14 +0300
Subject: [PATCH 22/59] address Eric's suggestions

---
 mne/decoding/{ged.py => _ged.py} |  0
 mne/decoding/base.py             | 12 +++++------
 mne/decoding/csp.py              | 23 ++++++++-------------
 mne/decoding/ssd.py              | 17 +++++++---------
 mne/decoding/tests/test_ged.py   | 35 ++++++++------------------------
 mne/preprocessing/xdawn.py       | 15 +++++++-------
 6 files changed, 36 insertions(+), 66 deletions(-)
 rename mne/decoding/{ged.py => _ged.py} (100%)

diff --git a/mne/decoding/ged.py b/mne/decoding/_ged.py
similarity index 100%
rename from mne/decoding/ged.py
rename to mne/decoding/_ged.py
diff --git a/mne/decoding/base.py b/mne/decoding/base.py
index 64eee7fc514..cd5717fa10f 100644
--- a/mne/decoding/base.py
+++ b/mne/decoding/base.py
@@ -24,7 +24,7 @@
 
 from ..parallel import parallel_func
 from ..utils import _pl, logger, pinv, verbose, warn
-from .ged import _handle_restr_mat, _is_cov_symm_pos_semidef, _smart_ajd, _smart_ged
+from ._ged import _handle_restr_mat, _is_cov_symm_pos_semidef, _smart_ajd, _smart_ged
 from .transformer import MNETransformerMixin
 
 
@@ -40,9 +40,9 @@ class _GEDTransformer(MNETransformerMixin, BaseEstimator):
         The number of spatial filters to decompose M/EEG signals.
     cov_callable : callable
         Function used to estimate covariances and reference matrix (C_ref) from the
-        data.
-    cov_params : dict
-        Parameters passed to cov_callable.
+        data. It should accept only X and y as arguments and return covs, C_ref, info,
+        rank and additional kwargs passed further to mod_ged_callable.
+        C_ref, info, rank can be None, while kwargs can be empty dict.
     mod_ged_callable : callable
         Function used to modify (e.g. sort or normalize) generalized
         eigenvalues and eigenvectors.
@@ -91,7 +91,6 @@ def __init__(
         self,
         n_components,
         cov_callable,
-        cov_params,
         mod_ged_callable,
         *,
         mod_params=None,
@@ -101,7 +100,6 @@ def __init__(
     ):
         self.n_components = n_components
         self.cov_callable = cov_callable
-        self.cov_params = cov_params
         self.mod_ged_callable = mod_ged_callable
         self.mod_params = mod_params
         self.dec_type = dec_type
@@ -117,7 +115,7 @@ def fit(self, X, y=None):
             return_y=True,
             atleast_3d=False if self.restr_type == "ssd" else True,
         )
-        covs, C_ref, info, rank, kwargs = self.cov_callable(X, y, **self.cov_params)
+        covs, C_ref, info, rank, kwargs = self.cov_callable(X, y)
         covs = np.stack(covs)
         self._validate_covariances(covs)
         self._validate_covariances([C_ref])
diff --git a/mne/decoding/csp.py b/mne/decoding/csp.py
index 3b3e83c7905..689333f977b 100644
--- a/mne/decoding/csp.py
+++ b/mne/decoding/csp.py
@@ -3,6 +3,7 @@
 # Copyright the MNE-Python contributors.
 
 import copy as cp
+from functools import partial
 
 import numpy as np
 from scipy.linalg import eigh
@@ -126,21 +127,19 @@ def __init__(
         self.cov_method_params = cov_method_params
         self.component_order = component_order
 
-        cov_params = dict(
+        cov_callable = partial(
+            _csp_estimate,
             reg=reg,
             cov_method_params=cov_method_params,
             cov_est=cov_est,
             rank=rank,
             norm_trace=norm_trace,
         )
-
         super().__init__(
             n_components=n_components,
-            cov_callable=_csp_estimate,
-            cov_params=cov_params,
+            cov_callable=cov_callable,
             mod_ged_callable=_csp_mod,
             mod_params=dict(evecs_order=component_order),
-            dec_type="single",
             restr_type="restricting",
             R_func=sum,
         )
@@ -899,20 +898,16 @@ def __init__(
             cov_method_params=cov_method_params,
         )
 
-        cov_params = dict(
+        cov_callable = partial(
+            _spoc_estimate,
             reg=reg,
             cov_method_params=cov_method_params,
             rank=rank,
         )
-
         super(CSP, self).__init__(
-            n_components,
-            _spoc_estimate,
-            cov_params,
-            _spoc_mod,
-            dec_type="single",
-            restr_type=None,
-            R_func=None,
+            n_components=n_components,
+            cov_callable=cov_callable,
+            mod_ged_callable=_spoc_mod,
         )
 
         # Covariance estimation have to be done on the single epoch level,
diff --git a/mne/decoding/ssd.py b/mne/decoding/ssd.py
index 117bd45689b..c8ee0a9eb64 100644
--- a/mne/decoding/ssd.py
+++ b/mne/decoding/ssd.py
@@ -2,6 +2,8 @@
 # License: BSD-3-Clause
 # Copyright the MNE-Python contributors.
 
+from functools import partial
+
 import numpy as np
 from scipy.linalg import eigh
 from sklearn.utils.validation import check_is_fitted
@@ -119,7 +121,8 @@ def __init__(
         self.cov_method_params = cov_method_params
         self.rank = rank
 
-        cov_params = dict(
+        cov_callable = partial(
+            _ssd_estimate,
             reg=reg,
             cov_method_params=cov_method_params,
             info=info,
@@ -128,17 +131,11 @@ def __init__(
             filt_params_noise=filt_params_noise,
             rank=rank,
         )
-
-        mod_params = dict()
         super().__init__(
-            n_components,
-            _ssd_estimate,
-            cov_params,
-            _ssd_mod,
-            mod_params,
-            dec_type="single",
+            n_components=n_components,
+            cov_callable=cov_callable,
+            mod_ged_callable=_ssd_mod,
             restr_type="ssd",
-            R_func=None,
         )
 
     def _validate_params(self, X):
diff --git a/mne/decoding/tests/test_ged.py b/mne/decoding/tests/test_ged.py
index ec0aa7b18c7..b97ece68a29 100644
--- a/mne/decoding/tests/test_ged.py
+++ b/mne/decoding/tests/test_ged.py
@@ -2,7 +2,7 @@
 # License: BSD-3-Clause
 # Copyright the MNE-Python contributors.
 
-import functools
+from functools import partial
 from pathlib import Path
 
 import numpy as np
@@ -18,8 +18,7 @@
 from mne import Epochs, compute_rank, create_info, pick_types, read_events
 from mne._fiff.proj import make_eeg_average_ref_proj
 from mne.cov import Covariance, _regularized_covariance
-from mne.decoding.base import _GEDTransformer
-from mne.decoding.ged import (
+from mne.decoding._ged import (
     _get_restr_mat,
     _handle_restr_mat,
     _is_cov_pos_def,
@@ -27,6 +26,7 @@
     _smart_ajd,
     _smart_ged,
 )
+from mne.decoding.base import _GEDTransformer
 from mne.io import read_raw
 
 data_dir = Path(__file__).parents[2] / "io" / "tests" / "data"
@@ -120,12 +120,8 @@ def _mock_mod_ged_callable(evals, evecs, covs, **kwargs):
 
 param_grid = dict(
     n_components=[4],
-    cov_callable=[_mock_cov_callable],
-    cov_params=[
-        dict(cov_method_params=dict(reg="empirical")),
-    ],
+    cov_callable=[partial(_mock_cov_callable, cov_method_params=dict(reg="empirical"))],
     mod_ged_callable=[_mock_mod_ged_callable],
-    mod_params=[dict()],
     dec_type=["single", "multi"],
     # XXX: Not covering "ssd" here because test_ssd.py works with 2D data.
     # Need to fix its tests first.
@@ -133,7 +129,7 @@ def _mock_mod_ged_callable(evals, evecs, covs, **kwargs):
         "restricting",
         "whitening",
     ],
-    R_func=[functools.partial(np.sum, axis=0)],
+    R_func=[partial(np.sum, axis=0)],
 )
 
 ged_estimators = [_GEDTransformer(**p) for p in ParameterGrid(param_grid)]
@@ -185,11 +181,8 @@ def test_ged_binary_cov():
     ged = _GEDTransformer(
         n_components=4,
         cov_callable=_mock_cov_callable,
-        cov_params=dict(),
         mod_ged_callable=_mock_mod_ged_callable,
-        dec_type="single",
         restr_type="restricting",
-        R_func=None,
     )
     ged.fit(X, y)
     desired_evals = ged.evals_
@@ -212,11 +205,9 @@ def test_ged_binary_cov():
     ged = _GEDTransformer(
         n_components=4,
         cov_callable=_mock_cov_callable,
-        cov_params=dict(),
         mod_ged_callable=_mock_mod_ged_callable,
         dec_type="multi",
         restr_type="restricting",
-        R_func=None,
     )
     ged.fit(X, y)
     desired_evals = ged.evals_
@@ -241,11 +232,8 @@ def test_ged_multicov():
     ged = _GEDTransformer(
         n_components=4,
         cov_callable=_mock_cov_callable,
-        cov_params=dict(),
         mod_ged_callable=_mock_mod_ged_callable,
-        dec_type="single",
         restr_type="restricting",
-        R_func=None,
     )
     ged.fit(X, y)
     desired_filters = ged.filters_
@@ -267,11 +255,9 @@ def test_ged_multicov():
     ged = _GEDTransformer(
         n_components=4,
         cov_callable=_mock_cov_callable,
-        cov_params=dict(),
         mod_ged_callable=_mock_mod_ged_callable,
         dec_type="multi",
         restr_type="restricting",
-        R_func=None,
     )
     ged.fit(X, y)
     desired_evals = ged.evals_
@@ -292,12 +278,11 @@ def test_ged_multicov():
 
     ged = _GEDTransformer(
         n_components=4,
-        cov_callable=_mock_cov_callable,
-        cov_params=dict(cov_method_params=dict(reg="oas"), compute_C_ref=False),
+        cov_callable=partial(
+            _mock_cov_callable, cov_method_params=dict(reg="oas"), compute_C_ref=False
+        ),
         mod_ged_callable=_mock_mod_ged_callable,
-        dec_type="single",
         restr_type="restricting",
-        R_func=None,
     )
     ged.fit(X, y)
     desired_filters = ged.filters_
@@ -310,11 +295,7 @@ def test_ged_invalid_cov():
     ged = _GEDTransformer(
         n_components=1,
         cov_callable=_mock_cov_callable,
-        cov_params=dict(),
         mod_ged_callable=_mock_mod_ged_callable,
-        dec_type="single",
-        restr_type=None,
-        R_func=None,
     )
     asymm_cov = np.array([[1, 2, 3], [4, 5, 6], [7, 8, 9]])
     with pytest.raises(ValueError, match="not symmetric"):
diff --git a/mne/preprocessing/xdawn.py b/mne/preprocessing/xdawn.py
index cd9b2a0ee2f..9bab875ed6c 100644
--- a/mne/preprocessing/xdawn.py
+++ b/mne/preprocessing/xdawn.py
@@ -3,6 +3,7 @@
 # Copyright the MNE-Python contributors.
 
 from collections.abc import Mapping
+from functools import partial
 
 import numpy as np
 from scipy import linalg
@@ -263,16 +264,14 @@ def __init__(self, n_components=2, reg=None, signal_cov=None, method_params=None
         self.reg = reg
         self.method_params = method_params
 
-        cov_params = dict(reg=reg, cov_method_params=method_params, R=signal_cov)
-
+        cov_callable = partial(
+            _xdawn_estimate, reg=reg, cov_method_params=method_params, R=signal_cov
+        )
         super().__init__(
-            n_components,
-            _xdawn_estimate,
-            cov_params,
-            _xdawn_mod,
+            n_components=n_components,
+            cov_callable=cov_callable,
+            mod_ged_callable=_xdawn_mod,
             dec_type="multi",
-            restr_type=None,
-            R_func=None,
         )
 
     def _validate_params(self, X):

From 85fb50fa9e438293b4feab0e5b604b418de55480 Mon Sep 17 00:00:00 2001
From: Genuster <genusterok@gmail.com>
Date: Fri, 13 Jun 2025 13:49:43 +0300
Subject: [PATCH 23/59] add default no op for mod_ged_callable

---
 mne/decoding/_mod_ged.py |  4 ++++
 mne/decoding/base.py     | 19 ++++++++++---------
 2 files changed, 14 insertions(+), 9 deletions(-)

diff --git a/mne/decoding/_mod_ged.py b/mne/decoding/_mod_ged.py
index ad3dc031f16..5b03c7feab4 100644
--- a/mne/decoding/_mod_ged.py
+++ b/mne/decoding/_mod_ged.py
@@ -67,3 +67,7 @@ def _sort_descending(evals, evecs, by_abs=False):
     evals = evals[ix]
     evecs = evecs[:, ix]
     return evals, evecs
+
+
+def _no_op_mod(evals, evecs, *args, **kwargs):
+    return evals, evecs
diff --git a/mne/decoding/base.py b/mne/decoding/base.py
index cd5717fa10f..9a5910e486e 100644
--- a/mne/decoding/base.py
+++ b/mne/decoding/base.py
@@ -25,6 +25,7 @@
 from ..parallel import parallel_func
 from ..utils import _pl, logger, pinv, verbose, warn
 from ._ged import _handle_restr_mat, _is_cov_symm_pos_semidef, _smart_ajd, _smart_ged
+from ._mod_ged import _no_op_mod
 from .transformer import MNETransformerMixin
 
 
@@ -43,11 +44,10 @@ class _GEDTransformer(MNETransformerMixin, BaseEstimator):
         data. It should accept only X and y as arguments and return covs, C_ref, info,
         rank and additional kwargs passed further to mod_ged_callable.
         C_ref, info, rank can be None, while kwargs can be empty dict.
-    mod_ged_callable : callable
+    mod_ged_callable : callable | None
         Function used to modify (e.g. sort or normalize) generalized
-        eigenvalues and eigenvectors.
-    mod_params : dict | None
-        Parameters passed to mod_ged_callable.
+        eigenvalues and eigenvectors. If None, evals and evecs will be ordered according
+        to :func:`~scipy.linalg.eigh` default. Defaults to None
     dec_type : "single" | "multi"
         When "single" and cov_callable returns > 2 covariances,
         approximate joint diagonalization based on Pham's algorithm
@@ -91,8 +91,8 @@ def __init__(
         self,
         n_components,
         cov_callable,
-        mod_ged_callable,
         *,
+        mod_ged_callable=None,
         mod_params=None,
         dec_type="single",
         restr_type=None,
@@ -120,6 +120,9 @@ def fit(self, X, y=None):
         self._validate_covariances(covs)
         self._validate_covariances([C_ref])
         mod_params = self.mod_params if self.mod_params is not None else dict()
+        mod_ged_callable = (
+            self.mod_ged_callable if self.mod_ged_callable is not None else _no_op_mod
+        )
         if self.dec_type == "single":
             if len(covs) > 2:
                 sample_weights = kwargs["sample_weights"]
@@ -132,9 +135,7 @@ def fit(self, X, y=None):
                 restr_mat = _handle_restr_mat(C_ref, self.restr_type, info, rank)
                 evals, evecs = _smart_ged(S, R, restr_mat, R_func=self.R_func)
 
-            evals, evecs = self.mod_ged_callable(
-                evals, evecs, covs, **mod_params, **kwargs
-            )
+            evals, evecs = mod_ged_callable(evals, evecs, covs, **mod_params, **kwargs)
             self.evals_ = evals
             self.filters_ = evecs.T
             if self.restr_type == "ssd":
@@ -152,7 +153,7 @@ def fit(self, X, y=None):
 
                 evals, evecs = _smart_ged(S, R, restr_mat, R_func=self.R_func)
 
-                evals, evecs = self.mod_ged_callable(
+                evals, evecs = mod_ged_callable(
                     evals, evecs, covs, **mod_params, **kwargs
                 )
                 all_evals.append(evals)

From 3c7df083e894791e86fb40c7643043a689029c5c Mon Sep 17 00:00:00 2001
From: Genuster <genusterok@gmail.com>
Date: Fri, 13 Jun 2025 14:02:14 +0300
Subject: [PATCH 24/59] replace mod_params with partial as well

---
 mne/decoding/base.py | 21 ++++++++++-----------
 mne/decoding/csp.py  |  4 ++--
 2 files changed, 12 insertions(+), 13 deletions(-)

diff --git a/mne/decoding/base.py b/mne/decoding/base.py
index 9a5910e486e..70c42f8d940 100644
--- a/mne/decoding/base.py
+++ b/mne/decoding/base.py
@@ -46,8 +46,10 @@ class _GEDTransformer(MNETransformerMixin, BaseEstimator):
         C_ref, info, rank can be None, while kwargs can be empty dict.
     mod_ged_callable : callable | None
         Function used to modify (e.g. sort or normalize) generalized
-        eigenvalues and eigenvectors. If None, evals and evecs will be ordered according
-        to :func:`~scipy.linalg.eigh` default. Defaults to None
+        eigenvalues and eigenvectors. It should accept as arguments evals, evecs
+        and also covs and optional kwargs returned by cov_callable. It should return
+        only sorted and/or modified evals and evecs. If None, evals and evecs will be
+        ordered according to :func:`~scipy.linalg.eigh` default. Defaults to None
     dec_type : "single" | "multi"
         When "single" and cov_callable returns > 2 covariances,
         approximate joint diagonalization based on Pham's algorithm
@@ -93,7 +95,6 @@ def __init__(
         cov_callable,
         *,
         mod_ged_callable=None,
-        mod_params=None,
         dec_type="single",
         restr_type=None,
         R_func=None,
@@ -101,7 +102,6 @@ def __init__(
         self.n_components = n_components
         self.cov_callable = cov_callable
         self.mod_ged_callable = mod_ged_callable
-        self.mod_params = mod_params
         self.dec_type = dec_type
         self.restr_type = restr_type
         self.R_func = R_func
@@ -119,15 +119,16 @@ def fit(self, X, y=None):
         covs = np.stack(covs)
         self._validate_covariances(covs)
         self._validate_covariances([C_ref])
-        mod_params = self.mod_params if self.mod_params is not None else dict()
         mod_ged_callable = (
             self.mod_ged_callable if self.mod_ged_callable is not None else _no_op_mod
         )
         if self.dec_type == "single":
             if len(covs) > 2:
-                sample_weights = kwargs["sample_weights"]
+                weights = (
+                    kwargs["sample_weights"] if "sample_weights" in kwargs else None
+                )
                 restr_mat = _handle_restr_mat(C_ref, self.restr_type, info, rank)
-                evecs = _smart_ajd(covs, restr_mat, weights=sample_weights)
+                evecs = _smart_ajd(covs, restr_mat, weights=weights)
                 evals = None
             else:
                 S = covs[0]
@@ -135,7 +136,7 @@ def fit(self, X, y=None):
                 restr_mat = _handle_restr_mat(C_ref, self.restr_type, info, rank)
                 evals, evecs = _smart_ged(S, R, restr_mat, R_func=self.R_func)
 
-            evals, evecs = mod_ged_callable(evals, evecs, covs, **mod_params, **kwargs)
+            evals, evecs = mod_ged_callable(evals, evecs, covs, **kwargs)
             self.evals_ = evals
             self.filters_ = evecs.T
             if self.restr_type == "ssd":
@@ -153,9 +154,7 @@ def fit(self, X, y=None):
 
                 evals, evecs = _smart_ged(S, R, restr_mat, R_func=self.R_func)
 
-                evals, evecs = mod_ged_callable(
-                    evals, evecs, covs, **mod_params, **kwargs
-                )
+                evals, evecs = mod_ged_callable(evals, evecs, covs, **kwargs)
                 all_evals.append(evals)
                 all_evecs.append(evecs.T)
                 all_patterns.append(np.linalg.pinv(evecs))
diff --git a/mne/decoding/csp.py b/mne/decoding/csp.py
index 689333f977b..c55e5e726d4 100644
--- a/mne/decoding/csp.py
+++ b/mne/decoding/csp.py
@@ -135,11 +135,11 @@ def __init__(
             rank=rank,
             norm_trace=norm_trace,
         )
+        mod_ged_callable = partial(_csp_mod, evecs_order=component_order)
         super().__init__(
             n_components=n_components,
             cov_callable=cov_callable,
-            mod_ged_callable=_csp_mod,
-            mod_params=dict(evecs_order=component_order),
+            mod_ged_callable=mod_ged_callable,
             restr_type="restricting",
             R_func=sum,
         )

From 9c7c7117b26151f947c91bfc83bb64829f1d2058 Mon Sep 17 00:00:00 2001
From: Genuster <genusterok@gmail.com>
Date: Fri, 13 Jun 2025 15:23:42 +0300
Subject: [PATCH 25/59] add ged entry in the implementation details

---
 doc/_includes/ged.rst                | 98 ++++++++++++++++++++++++++++
 doc/documentation/implementation.rst |  8 +++
 doc/references.bib                   | 12 ++++
 3 files changed, 118 insertions(+)
 create mode 100644 doc/_includes/ged.rst

diff --git a/doc/_includes/ged.rst b/doc/_includes/ged.rst
new file mode 100644
index 00000000000..ae2c3706bf7
--- /dev/null
+++ b/doc/_includes/ged.rst
@@ -0,0 +1,98 @@
+:orphan:
+
+Generalized eigendecomposition in decoding
+==========================================
+
+.. NOTE: part of this file is included in doc/overview/implementation.rst.
+   Changes here are reflected there. If you want to link to this content, link
+   to :ref:`ged` to link to that section of the implementation.rst page.
+   The next line is a target for :start-after: so we can omit the title from
+   the include:
+   ged-begin-content
+
+This section describes the mathematical formulation and application of
+Generalized Eigendecomposition (GED), often used in spatial filtering
+and source separation algorithms, such as :class:`mne.decoding.CSP`, 
+:class:`mne.decoding.SPoC`, :class:`mne.decoding.SSD` and 
+:class:`mne.preprocessing.Xdawn`.
+
+The core principle of GED is to find a set of channel weights (spatial filter) 
+that maximizes the ratio of signal power between two data features. 
+These features are defined by the researcher and are represented by two covariance matrices: 
+a "signal" matrix :math:`S` and a "reference" matrix :math:`R`. 
+For example, :math:`S` could be the covariance of data from a task time interval, 
+and :math:`S` could be the covariance from a baseline time interval. For more details see :footcite:`Cohen2022`.
+
+Algebraic formulation of GED
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+
+A few definitions first: 
+Let :math:`n \in \mathbb{N}^+` be a number of channels.
+Let :math:`\text{Symm}_n(\mathbb{R}) \subset M_n(\mathbb{R})` be a vector space of real symmetric matrices.
+Let :math:`S^n_+, S^n_{++} \subset \text{Symm}_n(\mathbb{R})` be sets of real positive semidefinite and positive definite matrices, respectively.
+Let :math:`S, R \in S^n_+` be covariance matrices estimated from electrophysiological data :math:`X_S \in M_{n \times t_S}(\mathbb{R})` and :math:`X_R \in M_{n \times t_R}(\mathbb{R})`.
+
+GED (or simultaneous diagonalization by congruence) of :math:`S` and :math:`R` 
+is possible when :math:`R` is full rank (and thus :math:`R \in S^n_{++}`):
+
+.. math::
+
+   SW = RWD,
+
+where :math:`W \in M_n(\mathbb{R})` is an invertible matrix of eigenvectors 
+of :math:`(S, R)` and :math:`D` is a diagonal matrix of eigenvalues :math:`\lambda_i`.
+
+Each eigenvector :math:`\mathbf{w} \in W` is a spatial filter that solves 
+an optimization problem of the form:
+
+.. math::
+
+   \operatorname{argmax}_{\mathbf{w}} \frac{\mathbf{w}^t S \mathbf{w}}{\mathbf{w}^t R \mathbf{w}}
+
+That is, using spatial filters :math:`W` on time-series :math:`X \in M_{n \times t}(\mathbb{R})`:
+
+.. math::
+
+   \mathbf{A} = W^t X,
+
+results in "activation" time-series :math:`A` of the estimated "sources", 
+such that the ratio of their variances, 
+:math:`\frac{\text{Var}(\mathbf{w}^T X_S)}{\text{Var}(\mathbf{w}^T X_R)} = \frac{\mathbf{w}^T S \mathbf{w}}{\mathbf{w}^T R \mathbf{w}}`, 
+is sequentially maximized spatial filters :math:`\mathbf{w}_i`, sorted according to :math:`\lambda_i`.
+
+GED in the principal subspace
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+Unfortunately, :math:`R` might not be full rank depending on the data :math:`X_R` (for example due to average reference, removed PCA/ICA components, etc.). 
+In such cases, GED can be performed on :math:`S` and :math:`R` in the principal subspace :math:`Q = \operatorname{Im}(C_{ref}) \subset \mathbb{R}^n` of some reference 
+covariance :math:`C_{ref}` (in Common Spatial Pattern (CSP) algorithm, for example, :math:`C_{ref}=\frac{1}{2}(S+R)` and GED is performed on S and R'=S+R). 
+
+More formally: 
+Let :math:`r \leq n` be a rank of :math:`C \in S^n_+`. 
+Let :math:`Q=\operatorname{Im}(C_{ref})` be a principal subspace of :math:`C_{ref}`. 
+Let :math:`P \in M_{n \times r}(\mathbb{R})` be formed by orthonormal basis of :math:`Q`.
+Let :math:`f:M_n(\mathbb{R}) \to M_r(\mathbb{R})` be a "restricting" linear map, that restricts matrix :math:`A` to :math:`Q`: :math:`A|_Q = P^t A P`.
+
+Then, the GED of :math:`S` and :math:`R` in the principal subspace :math:`Q` of :math:`C_{ref}` is performed as follows:
+
+1. :math:`S` and :math:`R` are restricted to :math:`Q`:
+   :math:`S|_Q = f(S) = P^t S P` and :math:`R|_Q = f(R) = P^t R P`
+2. GED is performed on :math:`S|_Q` and :math:`R|_Q`:
+   :math:`S|_Q W|_Q = R|_Q W|_Q D`
+3. Eigenvectors :math:`W_Q` of :math:`(S|_Q, R|_Q)` are transformed back to :math:`\mathbb{R}^n` by:
+   :math:`W = P W|_Q \in \mathbb{R}^{n \times r}` to obtain :math:`r` spatial filters.
+
+In addition to restriction, :math:`S` and :math:`R` can be rescaled based on the whitened :math:`C_{ref}`. 
+In this case the whitening map :math:`f_{wh}:M_n(\mathbb{R}) \to M_r(\mathbb{R})`, 
+:math:`A \mapsto P_{wh}^t A P_{wh}` both restricts matrix :math:`A` to :math:`Q` and rescales it according to :math:`\Lambda^{-1/2}`, 
+where :math:`\Lambda` is a diagonal matrix of eigenvalues of :math:`C_{ref}` and :math:`P_{wh} = P \Lambda^{-1/2}`.
+
+In MNE-Python, the matrix :math:`P` of the restricting map can be obtained using
+::
+
+    _, evecs, mask = mne.cov._smart_eigh(..., proj_subspace=True, ...)
+    restr_mat = ref_evecs[mask]
+
+while :math:`P_{wh}` using:
+::
+
+    restr_mat = compute_whitener(..., pca=True, ...)
\ No newline at end of file
diff --git a/doc/documentation/implementation.rst b/doc/documentation/implementation.rst
index ebae0201f7a..49fe31bac9c 100644
--- a/doc/documentation/implementation.rst
+++ b/doc/documentation/implementation.rst
@@ -124,6 +124,14 @@ Morphing and averaging source estimates
    :start-after: morph-begin-content
 
 
+.. _ged:
+
+Generalized eigendecomposition in decoding
+^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
+
+.. include:: ../_includes/ged.rst
+   :start-after: ged-begin-content
+
 References
 ^^^^^^^^^^
 .. footbibliography::
diff --git a/doc/references.bib b/doc/references.bib
index f0addb5f3b2..3b7ddf6dc04 100644
--- a/doc/references.bib
+++ b/doc/references.bib
@@ -282,6 +282,18 @@ @article{Cohen2019
   year = {2019}
 }
 
+@article{Cohen2022,
+author = {Cohen, Michael X},
+doi = {10.1016/j.neuroimage.2021.118809},
+journal = {NeuroImage},
+pages = {118809},
+title = {A tutorial on generalized eigendecomposition for denoising, contrast enhancement, and dimension reduction in multichannel electrophysiology},
+volume = {247},
+year = {2022},
+issn = {1053-8119},
+
+}
+
 @article{CohenHosaka1976,
   author = {Cohen, David and Hosaka, Hidehiro},
   doi = {10.1016/S0022-0736(76)80041-6},

From 95544c5935b3d78f8f2e314b3bfb094989ffb9c6 Mon Sep 17 00:00:00 2001
From: Genuster <genusterok@gmail.com>
Date: Fri, 13 Jun 2025 17:51:09 +0300
Subject: [PATCH 26/59] add feature to perform GED in the principal subspace
 for xdawn

---
 mne/decoding/_covs_ged.py  | 10 ++-----
 mne/decoding/_ged.py       |  3 +--
 mne/decoding/base.py       | 20 ++++++++++++++
 mne/preprocessing/xdawn.py | 55 +++++++++++++++++++++++++++++++++++---
 4 files changed, 75 insertions(+), 13 deletions(-)

diff --git a/mne/decoding/_covs_ged.py b/mne/decoding/_covs_ged.py
index 46c82715d4b..36ca9630317 100644
--- a/mne/decoding/_covs_ged.py
+++ b/mne/decoding/_covs_ged.py
@@ -119,11 +119,6 @@ def _xdawn_estimate(
 ):
     classes = np.unique(y)
 
-    # XXX Eventually this could be made to deal with rank deficiency properly
-    # by exposing this "rank" parameter, but this will require refactoring
-    # the linalg.eigh call to operate in the lower-dimension
-    # subspace, then project back out.
-
     # Retrieve or compute whitening covariance
     if R is None:
         R = _regularized_covariance(
@@ -147,9 +142,8 @@ def _xdawn_estimate(
         covs.append(evo_cov)
 
     covs.append(R)
-    C_ref = None
-    rank = None
-    info = None
+    C_ref = R
+    rank = rank if isinstance(rank, dict) else None
     return covs, C_ref, info, rank, dict()
 
 
diff --git a/mne/decoding/_ged.py b/mne/decoding/_ged.py
index ad3a90e25c4..3ab1a7a0aed 100644
--- a/mne/decoding/_ged.py
+++ b/mne/decoding/_ged.py
@@ -18,8 +18,7 @@ def _handle_restr_mat(C_ref, restr_type, info, rank):
     if C_ref is None or restr_type is None:
         return None
     if restr_type == "whitening":
-        projs = info["projs"]
-        C_ref_cov = Covariance(C_ref, info.ch_names, info["bads"], projs, 0)
+        C_ref_cov = Covariance(C_ref, info.ch_names, info["bads"], info["projs"], 0)
         restr_mat = compute_whitener(C_ref_cov, info, rank=rank, pca=True)[0]
     elif restr_type == "ssd":
         restr_mat = _get_ssd_whitener(C_ref, rank)
diff --git a/mne/decoding/base.py b/mne/decoding/base.py
index 70c42f8d940..c3130a015d4 100644
--- a/mne/decoding/base.py
+++ b/mne/decoding/base.py
@@ -22,6 +22,8 @@
 from sklearn.utils import check_array, check_X_y, indexable
 from sklearn.utils.validation import check_is_fitted
 
+from .._fiff.meas_info import create_info
+from ..cov import _compute_rank_raw_array
 from ..parallel import parallel_func
 from ..utils import _pl, logger, pinv, verbose, warn
 from ._ged import _handle_restr_mat, _is_cov_symm_pos_semidef, _smart_ajd, _smart_ged
@@ -122,6 +124,24 @@ def fit(self, X, y=None):
         mod_ged_callable = (
             self.mod_ged_callable if self.mod_ged_callable is not None else _no_op_mod
         )
+
+        # If restriction to be done, info and rank should exist.
+        if self.restr_type is not None and C_ref is not None:
+            if info is None:
+                # use mag instead of eeg to avoid the cov EEG projection warning
+                info = create_info(C_ref.shape[0], 1000.0, "mag")
+                if isinstance(rank, dict):
+                    rank = dict(mag=sum(rank.values()))
+
+            if rank is None:
+                rank = _compute_rank_raw_array(
+                    np.hstack(X),
+                    info,
+                    rank=None,
+                    scalings=None,
+                    log_ch_type="data",
+                )
+
         if self.dec_type == "single":
             if len(covs) > 2:
                 weights = (
diff --git a/mne/preprocessing/xdawn.py b/mne/preprocessing/xdawn.py
index 9bab875ed6c..d1ba9102196 100644
--- a/mne/preprocessing/xdawn.py
+++ b/mne/preprocessing/xdawn.py
@@ -8,6 +8,7 @@
 import numpy as np
 from scipy import linalg
 
+from .._fiff.meas_info import Info
 from .._fiff.pick import _pick_data_channels, pick_info
 from ..cov import Covariance, _regularized_covariance
 from ..decoding._covs_ged import _xdawn_estimate
@@ -246,6 +247,30 @@ class _XdawnTransformer(_GEDTransformer):
         Parameters to pass to :func:`mne.compute_covariance`.
 
         .. versionadded:: 0.16
+    restr_type : "restricting" | "whitening" | None
+        Restricting transformation for covariance matrices before performing
+        generalized eigendecomposition.
+        If "restricting" only restriction to the principal subspace of signal_cov
+        will be performed.
+        If "whitening", covariance matrices will be additionally rescaled according
+        to the whitening for the signal_cov.
+        If None, no restriction will be applied. Defaults to None.
+
+        .. versionadded:: 1.10
+    info : mne.Info | None
+        The mne.Info object with information about the sensors and methods of
+        measurement used for covariance estimation and generalized
+        eigendecomposition.
+        If None, one channel type and no projections will be assumed and if
+        rank is dict, it will be sum of ranks per channel type.
+        Defaults to None.
+
+        .. versionadded:: 1.10
+    %(rank)s
+        Defaults to "full".
+
+        .. versionadded:: 1.10
+
 
     Attributes
     ----------
@@ -257,21 +282,39 @@ class _XdawnTransformer(_GEDTransformer):
         The Xdawn patterns used to restore the signals for each event type.
     """
 
-    def __init__(self, n_components=2, reg=None, signal_cov=None, method_params=None):
+    def __init__(
+        self,
+        n_components=2,
+        reg=None,
+        signal_cov=None,
+        method_params=None,
+        restr_type=None,
+        info=None,
+        rank="full",
+    ):
         """Init."""
         self.n_components = n_components
         self.signal_cov = signal_cov
         self.reg = reg
         self.method_params = method_params
+        self.restr_type = restr_type
+        self.info = info
+        self.rank = rank
 
         cov_callable = partial(
-            _xdawn_estimate, reg=reg, cov_method_params=method_params, R=signal_cov
+            _xdawn_estimate,
+            reg=reg,
+            cov_method_params=method_params,
+            R=signal_cov,
+            info=info,
+            rank=rank,
         )
         super().__init__(
             n_components=n_components,
             cov_callable=cov_callable,
             mod_ged_callable=_xdawn_mod,
             dec_type="multi",
+            restr_type=restr_type,
         )
 
     def _validate_params(self, X):
@@ -288,7 +331,13 @@ def _validate_params(self, X):
                 raise ValueError(
                     "signal_cov data should be of shape (n_channels, n_channels)"
                 )
-        _validate_type(self.method_params, (Mapping, None))
+        _validate_type(self.method_params, (Mapping, None), "method_params")
+        _check_option(
+            "restr_type",
+            self.restr_type,
+            ("restricting", "whitening", None),
+        )
+        _validate_type(self.info, (Info, None), "info")
 
     def fit(self, X, y=None):
         """Fit Xdawn spatial filters.

From 875508901ef3b61a05a8685bc1bb7e92a1d3b7ed Mon Sep 17 00:00:00 2001
From: Genuster <genusterok@gmail.com>
Date: Fri, 13 Jun 2025 18:24:41 +0300
Subject: [PATCH 27/59] add option for CSP to select restr_type and provide
 info

---
 mne/decoding/_covs_ged.py | 47 ++++++++++++++++++++++++++-------------
 mne/decoding/base.py      | 26 +++++-----------------
 mne/decoding/csp.py       | 35 +++++++++++++++++++++++++++--
 3 files changed, 69 insertions(+), 39 deletions(-)

diff --git a/mne/decoding/_covs_ged.py b/mne/decoding/_covs_ged.py
index 36ca9630317..3f893be4b1d 100644
--- a/mne/decoding/_covs_ged.py
+++ b/mne/decoding/_covs_ged.py
@@ -15,7 +15,7 @@
 from ..utils import _verbose_safe_false, logger
 
 
-def _concat_cov(x_class, *, cov_kind, log_rank, reg, cov_method_params, rank, info):
+def _concat_cov(x_class, *, cov_kind, log_rank, reg, cov_method_params, info, rank):
     """Concatenate epochs before computing the covariance."""
     _, n_channels, _ = x_class.shape
 
@@ -34,7 +34,7 @@ def _concat_cov(x_class, *, cov_kind, log_rank, reg, cov_method_params, rank, in
     return cov, n_channels  # the weight here is just the number of channels
 
 
-def _epoch_cov(x_class, *, cov_kind, log_rank, reg, cov_method_params, rank, info):
+def _epoch_cov(x_class, *, cov_kind, log_rank, reg, cov_method_params, info, rank):
     """Mean of per-epoch covariances."""
     name = reg if isinstance(reg, str) else "empirical"
     name += " with shrinkage" if isinstance(reg, float) else ""
@@ -62,22 +62,29 @@ def _epoch_cov(x_class, *, cov_kind, log_rank, reg, cov_method_params, rank, inf
     return cov, weight
 
 
-def _csp_estimate(X, y, reg, cov_method_params, cov_est, rank, norm_trace):
+def _handle_info_rank(X, info, rank):
+    if info is None:
+        # use mag instead of eeg to avoid the cov EEG projection warning
+        info = create_info(X.shape[1], 1000.0, "mag")
+        if isinstance(rank, dict):
+            rank = dict(mag=sum(rank.values()))
+
+    return info, rank
+
+
+def _csp_estimate(X, y, reg, cov_method_params, cov_est, info, rank, norm_trace):
     _, n_channels, _ = X.shape
     classes_ = np.unique(y)
     if cov_est == "concat":
         cov_estimator = _concat_cov
     elif cov_est == "epoch":
         cov_estimator = _epoch_cov
-    # Someday we could allow the user to pass this, then we wouldn't need to convert
-    # but in the meantime they can use a pipeline with a scaler
-    _info = create_info(n_channels, 1000.0, "mag")
-    if isinstance(rank, dict):
-        _rank = {"mag": sum(rank.values())}
-    else:
-        _rank = _compute_rank_raw_array(
-            X.transpose(1, 0, 2).reshape(X.shape[1], -1),
-            _info,
+
+    info, rank = _handle_info_rank(X, info, rank)
+    if not isinstance(rank, dict):
+        rank = _compute_rank_raw_array(
+            np.hstack(X),
+            info,
             rank=rank,
             scalings=None,
             log_ch_type="data",
@@ -92,8 +99,8 @@ def _csp_estimate(X, y, reg, cov_method_params, cov_est, rank, norm_trace):
             log_rank=ci == 0,
             reg=reg,
             cov_method_params=cov_method_params,
-            rank=_rank,
-            info=_info,
+            info=info,
+            rank=rank,
         )
 
         if norm_trace:
@@ -105,7 +112,7 @@ def _csp_estimate(X, y, reg, cov_method_params, cov_est, rank, norm_trace):
     covs = np.stack(covs)
     C_ref = covs.mean(0)
 
-    return covs, C_ref, _info, _rank, dict(sample_weights=np.array(sample_weights))
+    return covs, C_ref, info, rank, dict(sample_weights=np.array(sample_weights))
 
 
 def _xdawn_estimate(
@@ -118,6 +125,7 @@ def _xdawn_estimate(
     rank="full",
 ):
     classes = np.unique(y)
+    info, rank = _handle_info_rank(X, info, rank)
 
     # Retrieve or compute whitening covariance
     if R is None:
@@ -143,7 +151,14 @@ def _xdawn_estimate(
 
     covs.append(R)
     C_ref = R
-    rank = rank if isinstance(rank, dict) else None
+    if not isinstance(rank, dict):
+        rank = _compute_rank_raw_array(
+            np.hstack(X),
+            info,
+            rank=rank,
+            scalings=None,
+            log_ch_type="data",
+        )
     return covs, C_ref, info, rank, dict()
 
 
diff --git a/mne/decoding/base.py b/mne/decoding/base.py
index c3130a015d4..3cc0de6f13e 100644
--- a/mne/decoding/base.py
+++ b/mne/decoding/base.py
@@ -22,8 +22,6 @@
 from sklearn.utils import check_array, check_X_y, indexable
 from sklearn.utils.validation import check_is_fitted
 
-from .._fiff.meas_info import create_info
-from ..cov import _compute_rank_raw_array
 from ..parallel import parallel_func
 from ..utils import _pl, logger, pinv, verbose, warn
 from ._ged import _handle_restr_mat, _is_cov_symm_pos_semidef, _smart_ajd, _smart_ged
@@ -70,7 +68,7 @@ class _GEDTransformer(MNETransformerMixin, BaseEstimator):
         preserved for compatibility.
         If None, no restriction will be applied. Defaults to None.
     R_func : callable | None
-        If provided GED will be performed on (S, R_func(S,R)).
+        If provided, GED will be performed on (S, R_func(S,R)).
 
     Attributes
     ----------
@@ -88,7 +86,10 @@ class _GEDTransformer(MNETransformerMixin, BaseEstimator):
     CSP
     SPoC
     SSD
-    mne.preprocessing.Xdawn
+
+    Notes
+    -----
+    .. versionadded:: 1.10
     """
 
     def __init__(
@@ -125,23 +126,6 @@ def fit(self, X, y=None):
             self.mod_ged_callable if self.mod_ged_callable is not None else _no_op_mod
         )
 
-        # If restriction to be done, info and rank should exist.
-        if self.restr_type is not None and C_ref is not None:
-            if info is None:
-                # use mag instead of eeg to avoid the cov EEG projection warning
-                info = create_info(C_ref.shape[0], 1000.0, "mag")
-                if isinstance(rank, dict):
-                    rank = dict(mag=sum(rank.values()))
-
-            if rank is None:
-                rank = _compute_rank_raw_array(
-                    np.hstack(X),
-                    info,
-                    rank=None,
-                    scalings=None,
-                    log_ch_type="data",
-                )
-
         if self.dec_type == "single":
             if len(covs) > 2:
                 weights = (
diff --git a/mne/decoding/csp.py b/mne/decoding/csp.py
index c55e5e726d4..8f169ee7e1b 100644
--- a/mne/decoding/csp.py
+++ b/mne/decoding/csp.py
@@ -9,7 +9,7 @@
 from scipy.linalg import eigh
 from sklearn.utils.validation import check_is_fitted
 
-from .._fiff.meas_info import create_info
+from .._fiff.meas_info import Info, create_info
 from ..cov import _compute_rank_raw_array, _regularized_covariance, _smart_eigh
 from ..defaults import _BORDER_DEFAULT, _EXTRAPOLATE_DEFAULT, _INTERPOLATION_DEFAULT
 from ..evoked import EvokedArray
@@ -70,6 +70,26 @@ class CSP(_GEDTransformer):
         Parameters to pass to :func:`mne.compute_covariance`.
 
         .. versionadded:: 0.16
+
+    restr_type : "restricting" | "whitening" | None
+        Restricting transformation for covariance matrices before performing
+        generalized eigendecomposition.
+        If "restricting" only restriction to the principal subspace of signal_cov
+        will be performed.
+        If "whitening", covariance matrices will be additionally rescaled according
+        to the whitening for the signal_cov.
+        If None, no restriction will be applied. Defaults to "restricting".
+
+        .. versionadded:: 1.10
+    info : mne.Info | None
+        The mne.Info object with information about the sensors and methods of
+        measurement used for covariance estimation and generalized
+        eigendecomposition.
+        If None, one channel type and no projections will be assumed and if
+        rank is dict, it will be sum of ranks per channel type.
+        Defaults to None.
+
+        .. versionadded:: 1.10
     %(rank_none)s
 
         .. versionadded:: 0.17
@@ -113,11 +133,14 @@ def __init__(
         transform_into="average_power",
         norm_trace=False,
         cov_method_params=None,
+        restr_type="restricting",
+        info=None,
         rank=None,
         component_order="mutual_info",
     ):
         # Init default CSP
         self.n_components = n_components
+        self.info = info
         self.rank = rank
         self.reg = reg
         self.cov_est = cov_est
@@ -126,12 +149,14 @@ def __init__(
         self.norm_trace = norm_trace
         self.cov_method_params = cov_method_params
         self.component_order = component_order
+        self.restr_type = restr_type
 
         cov_callable = partial(
             _csp_estimate,
             reg=reg,
             cov_method_params=cov_method_params,
             cov_est=cov_est,
+            info=info,
             rank=rank,
             norm_trace=norm_trace,
         )
@@ -140,7 +165,7 @@ def __init__(
             n_components=n_components,
             cov_callable=cov_callable,
             mod_ged_callable=mod_ged_callable,
-            restr_type="restricting",
+            restr_type=restr_type,
             R_func=sum,
         )
 
@@ -172,6 +197,12 @@ def _validate_params(self, *, y):
         n_classes = len(self.classes_)
         if n_classes < 2:
             raise ValueError(f"n_classes must be >= 2, but got {n_classes} class")
+        _check_option(
+            "restr_type",
+            self.restr_type,
+            ("restricting", "whitening", None),
+        )
+        _validate_type(self.info, (Info, None), "info")
 
     def fit(self, X, y):
         """Estimate the CSP decomposition on epochs.

From 87a246606696020ef08984724d0c497d9b56c568 Mon Sep 17 00:00:00 2001
From: Genuster <genusterok@gmail.com>
Date: Fri, 13 Jun 2025 18:44:40 +0300
Subject: [PATCH 28/59] add restr_type for SCoP and SSD

---
 mne/decoding/_covs_ged.py | 14 +++++++++++---
 mne/decoding/csp.py       | 25 +++++++++++++++++++++++++
 mne/decoding/ssd.py       | 15 ++++++++++++++-
 3 files changed, 50 insertions(+), 4 deletions(-)

diff --git a/mne/decoding/_covs_ged.py b/mne/decoding/_covs_ged.py
index 3f893be4b1d..4fb56761e2b 100644
--- a/mne/decoding/_covs_ged.py
+++ b/mne/decoding/_covs_ged.py
@@ -227,7 +227,8 @@ def _ssd_estimate(
     return covs, C_ref, info, rank, dict()
 
 
-def _spoc_estimate(X, y, reg, cov_method_params, rank):
+def _spoc_estimate(X, y, reg, cov_method_params, info, rank):
+    info, rank = _handle_info_rank(X, info, rank)
     # Normalize target variable
     target = y.astype(np.float64)
     target -= target.mean()
@@ -251,6 +252,13 @@ def _spoc_estimate(X, y, reg, cov_method_params, rank):
     R = covs.mean(0)
 
     covs = [S, R]
-    C_ref = None
-    info = None
+    C_ref = R
+    if not isinstance(rank, dict):
+        rank = _compute_rank_raw_array(
+            np.hstack(X),
+            info,
+            rank=rank,
+            scalings=None,
+            log_ch_type="data",
+        )
     return covs, C_ref, info, rank, dict()
diff --git a/mne/decoding/csp.py b/mne/decoding/csp.py
index 8f169ee7e1b..b261ffd8ebb 100644
--- a/mne/decoding/csp.py
+++ b/mne/decoding/csp.py
@@ -884,6 +884,25 @@ class SPoC(CSP):
         Parameters to pass to :func:`mne.compute_covariance`.
 
         .. versionadded:: 0.16
+    restr_type : "restricting" | "whitening" | None
+        Restricting transformation for covariance matrices before performing
+        generalized eigendecomposition.
+        If "restricting" only restriction to the principal subspace of signal_cov
+        will be performed.
+        If "whitening", covariance matrices will be additionally rescaled according
+        to the whitening for the signal_cov.
+        If None, no restriction will be applied. Defaults to None.
+
+        .. versionadded:: 1.10
+    info : mne.Info | None
+        The mne.Info object with information about the sensors and methods of
+        measurement used for covariance estimation and generalized
+        eigendecomposition.
+        If None, one channel type and no projections will be assumed and if
+        rank is dict, it will be sum of ranks per channel type.
+        Defaults to None.
+
+        .. versionadded:: 1.10
     %(rank_none)s
 
         .. versionadded:: 0.17
@@ -915,6 +934,8 @@ def __init__(
         log=None,
         transform_into="average_power",
         cov_method_params=None,
+        restr_type=None,
+        info=None,
         rank=None,
     ):
         """Init of SPoC."""
@@ -925,6 +946,8 @@ def __init__(
             cov_est="epoch",
             norm_trace=False,
             transform_into=transform_into,
+            restr_type=restr_type,
+            info=info,
             rank=rank,
             cov_method_params=cov_method_params,
         )
@@ -933,12 +956,14 @@ def __init__(
             _spoc_estimate,
             reg=reg,
             cov_method_params=cov_method_params,
+            info=info,
             rank=rank,
         )
         super(CSP, self).__init__(
             n_components=n_components,
             cov_callable=cov_callable,
             mod_ged_callable=_spoc_mod,
+            restr_type=restr_type,
         )
 
         # Covariance estimation have to be done on the single epoch level,
diff --git a/mne/decoding/ssd.py b/mne/decoding/ssd.py
index c8ee0a9eb64..ef80bf3bdd9 100644
--- a/mne/decoding/ssd.py
+++ b/mne/decoding/ssd.py
@@ -74,6 +74,17 @@ class SSD(_GEDTransformer):
     cov_method_params : dict | None (default None)
         As in :class:`mne.decoding.SPoC`
         The default is None.
+    restr_type : "restricting" | "whitening" | "ssd" | None
+        Restricting transformation for covariance matrices before performing
+        generalized eigendecomposition.
+        If "restricting" only restriction to the principal subspace of signal_cov
+        will be performed.
+        If "whitening", covariance matrices will be additionally rescaled according
+        to the whitening for the signal_cov.
+        If "ssd", simplified version of "whitening" is performed.
+        If None, no restriction will be applied. Defaults to "ssd".
+
+        .. versionadded:: 1.10
     rank : None | dict | ‘info’ | ‘full’
         As in :class:`mne.decoding.SPoC`
         This controls the rank computation that can be read from the
@@ -106,6 +117,7 @@ def __init__(
         return_filtered=False,
         n_fft=None,
         cov_method_params=None,
+        restr_type="ssd",
         rank=None,
     ):
         """Initialize instance."""
@@ -119,6 +131,7 @@ def __init__(
         self.return_filtered = return_filtered
         self.n_fft = n_fft
         self.cov_method_params = cov_method_params
+        self.restr_type = restr_type
         self.rank = rank
 
         cov_callable = partial(
@@ -135,7 +148,7 @@ def __init__(
             n_components=n_components,
             cov_callable=cov_callable,
             mod_ged_callable=_ssd_mod,
-            restr_type="ssd",
+            restr_type=restr_type,
         )
 
     def _validate_params(self, X):

From 969a73ea7b8d12b51cf8ade28d3c57c39c1a78e6 Mon Sep 17 00:00:00 2001
From: Genuster <genusterok@gmail.com>
Date: Fri, 13 Jun 2025 19:12:19 +0300
Subject: [PATCH 29/59] fix SSD's filters_ shape inconsistency

---
 mne/decoding/ssd.py | 13 ++++++-------
 1 file changed, 6 insertions(+), 7 deletions(-)

diff --git a/mne/decoding/ssd.py b/mne/decoding/ssd.py
index ef80bf3bdd9..faa90ca0d96 100644
--- a/mne/decoding/ssd.py
+++ b/mne/decoding/ssd.py
@@ -95,9 +95,9 @@ class SSD(_GEDTransformer):
 
     Attributes
     ----------
-    filters_ : array, shape (n_channels, n_components)
+    filters_ : array, shape (n_channels or less, n_channels)
         The spatial filters to be multiplied with the signal.
-    patterns_ : array, shape (n_components, n_channels)
+    patterns_ : array, shape (n_channels or less, n_channels)
         The patterns for reconstructing the signal from the filtered data.
 
     References
@@ -272,13 +272,12 @@ def fit(self, X, y=None):
         # project back to sensor space
         self.filters_ = np.matmul(rank_proj, eigvects_[:, ix])
         self.patterns_ = np.linalg.pinv(self.filters_)
+        # Need to unify with Xdawn and CSP as they store it as (n_components, n_chs)
+        self.filters_ = self.filters_.T
 
         old_filters = self.filters_
         old_patterns = self.patterns_
         super().fit(X, y)
-        # SSD, as opposed to CSP and Xdawn stores filters as (n_chs, n_components)
-        # So need to transpose into (n_components, n_chs)
-        self.filters_ = self.filters_.T
 
         np.testing.assert_allclose(self.eigvals_, self.evals_)
         np.testing.assert_allclose(old_filters, self.filters_)
@@ -287,7 +286,7 @@ def fit(self, X, y=None):
         # We assume that ordering by spectral ratio is more important
         # than the initial ordering. This ordering should be also learned when
         # fitting.
-        X_ssd = self.filters_.T @ X[..., self.picks_, :]
+        X_ssd = self.filters_ @ X[..., self.picks_, :]
         sorter_spec = slice(None)
         if self.sort_by_spectral_ratio:
             _, sorter_spec = self.get_spectral_ratio(ssd_sources=X_ssd)
@@ -315,7 +314,7 @@ def transform(self, X):
         if self.return_filtered:
             X_aux = X[..., self.picks_, :]
             X = filter_data(X_aux, self.sfreq_, **self.filt_params_signal)
-        X_ssd = self.filters_.T @ X[..., self.picks_, :]
+        X_ssd = self.filters_ @ X[..., self.picks_, :]
         X_ssd = X_ssd[..., self.sorter_spec_, :][..., : self.n_components, :]
         return X_ssd
 

From 526637211637d4819b8a6fe86365d0e8cc00c42a Mon Sep 17 00:00:00 2001
From: Genuster <genusterok@gmail.com>
Date: Fri, 13 Jun 2025 19:16:51 +0300
Subject: [PATCH 30/59] use mne's pinv in SSD and Xdawn instead of
 np.linalg.pinv

---
 mne/decoding/base.py       | 7 ++-----
 mne/decoding/ssd.py        | 3 ++-
 mne/preprocessing/xdawn.py | 2 +-
 3 files changed, 5 insertions(+), 7 deletions(-)

diff --git a/mne/decoding/base.py b/mne/decoding/base.py
index 3cc0de6f13e..fa37c1c39eb 100644
--- a/mne/decoding/base.py
+++ b/mne/decoding/base.py
@@ -143,10 +143,7 @@ def fit(self, X, y=None):
             evals, evecs = mod_ged_callable(evals, evecs, covs, **kwargs)
             self.evals_ = evals
             self.filters_ = evecs.T
-            if self.restr_type == "ssd":
-                self.patterns_ = np.linalg.pinv(evecs)
-            else:
-                self.patterns_ = pinv(evecs)
+            self.patterns_ = pinv(evecs)
 
         elif self.dec_type == "multi":
             self.classes_ = np.unique(y)
@@ -161,7 +158,7 @@ def fit(self, X, y=None):
                 evals, evecs = mod_ged_callable(evals, evecs, covs, **kwargs)
                 all_evals.append(evals)
                 all_evecs.append(evecs.T)
-                all_patterns.append(np.linalg.pinv(evecs))
+                all_patterns.append(pinv(evecs))
             self.evals_ = np.array(all_evals)
             self.filters_ = np.array(all_evecs)
             self.patterns_ = np.array(all_patterns)
diff --git a/mne/decoding/ssd.py b/mne/decoding/ssd.py
index faa90ca0d96..97a4b73270f 100644
--- a/mne/decoding/ssd.py
+++ b/mne/decoding/ssd.py
@@ -21,6 +21,7 @@
     _verbose_safe_false,
     fill_doc,
     logger,
+    pinv,
 )
 from ._covs_ged import _ssd_estimate
 from ._mod_ged import _ssd_mod
@@ -271,7 +272,7 @@ def fit(self, X, y=None):
         self.eigvals_ = eigvals_[ix]
         # project back to sensor space
         self.filters_ = np.matmul(rank_proj, eigvects_[:, ix])
-        self.patterns_ = np.linalg.pinv(self.filters_)
+        self.patterns_ = pinv(self.filters_)
         # Need to unify with Xdawn and CSP as they store it as (n_components, n_chs)
         self.filters_ = self.filters_.T
 
diff --git a/mne/preprocessing/xdawn.py b/mne/preprocessing/xdawn.py
index d1ba9102196..3e9bc806158 100644
--- a/mne/preprocessing/xdawn.py
+++ b/mne/preprocessing/xdawn.py
@@ -208,7 +208,7 @@ def _fit_xdawn(
             )
         evecs = evecs[:, np.argsort(evals)[::-1]]  # sort eigenvectors
         evecs /= np.apply_along_axis(np.linalg.norm, 0, evecs)
-        _patterns = np.linalg.pinv(evecs.T)
+        _patterns = pinv(evecs.T)
         filters.append(evecs[:, :n_components].T)
         patterns.append(_patterns[:, :n_components].T)
 

From 726c5008c6f2285fc2f1d6e357d4849146d661d7 Mon Sep 17 00:00:00 2001
From: Genuster <genusterok@gmail.com>
Date: Fri, 13 Jun 2025 19:28:10 +0300
Subject: [PATCH 31/59] move mne.preprocessing._XdawnTransformer to decoding
 and make it public

---
 mne/decoding/xdawn.py                 | 266 ++++++++++++++++++++++++++
 mne/preprocessing/tests/test_xdawn.py |  25 +--
 mne/preprocessing/xdawn.py            | 261 +------------------------
 3 files changed, 282 insertions(+), 270 deletions(-)
 create mode 100644 mne/decoding/xdawn.py

diff --git a/mne/decoding/xdawn.py b/mne/decoding/xdawn.py
new file mode 100644
index 00000000000..546fbb2e55e
--- /dev/null
+++ b/mne/decoding/xdawn.py
@@ -0,0 +1,266 @@
+# Authors: The MNE-Python contributors.
+# License: BSD-3-Clause
+# Copyright the MNE-Python contributors.
+
+from collections.abc import Mapping
+from functools import partial
+
+import numpy as np
+
+from .._fiff.meas_info import Info
+from ..cov import Covariance
+from ..decoding._covs_ged import _xdawn_estimate
+from ..decoding._mod_ged import _xdawn_mod
+from ..decoding.base import _GEDTransformer
+from ..utils import _check_option, _validate_type
+
+
+class XdawnTransformer(_GEDTransformer):
+    """Implementation of the Xdawn Algorithm compatible with scikit-learn.
+
+    Xdawn is a spatial filtering method designed to improve the signal
+    to signal + noise ratio (SSNR) of the event related responses. Xdawn was
+    originally designed for P300 evoked potential by enhancing the target
+    response with respect to the non-target response. This implementation is a
+    generalization to any type of event related response.
+
+    .. note:: _XdawnTransformer does not correct for epochs overlap. To correct
+              overlaps see ``Xdawn``.
+
+    Parameters
+    ----------
+    n_components : int (default 2)
+        The number of components to decompose the signals.
+    reg : float | str | None (default None)
+        If not None (same as ``'empirical'``, default), allow
+        regularization for covariance estimation.
+        If float, shrinkage is used (0 <= shrinkage <= 1).
+        For str options, ``reg`` will be passed to ``method`` to
+        :func:`mne.compute_covariance`.
+    signal_cov : None | Covariance | array, shape (n_channels, n_channels)
+        The signal covariance used for whitening of the data.
+        if None, the covariance is estimated from the epochs signal.
+    method_params : dict | None
+        Parameters to pass to :func:`mne.compute_covariance`.
+
+        .. versionadded:: 0.16
+    restr_type : "restricting" | "whitening" | None
+        Restricting transformation for covariance matrices before performing
+        generalized eigendecomposition.
+        If "restricting" only restriction to the principal subspace of signal_cov
+        will be performed.
+        If "whitening", covariance matrices will be additionally rescaled according
+        to the whitening for the signal_cov.
+        If None, no restriction will be applied. Defaults to None.
+
+        .. versionadded:: 1.10
+    info : mne.Info | None
+        The mne.Info object with information about the sensors and methods of
+        measurement used for covariance estimation and generalized
+        eigendecomposition.
+        If None, one channel type and no projections will be assumed and if
+        rank is dict, it will be sum of ranks per channel type.
+        Defaults to None.
+
+        .. versionadded:: 1.10
+    %(rank)s
+        Defaults to "full".
+
+        .. versionadded:: 1.10
+
+
+    Attributes
+    ----------
+    classes_ : array, shape (n_classes)
+        The event indices of the classes.
+    filters_ : array, shape (n_channels, n_channels)
+        The Xdawn components used to decompose the data for each event type.
+    patterns_ : array, shape (n_channels, n_channels)
+        The Xdawn patterns used to restore the signals for each event type.
+    """
+
+    def __init__(
+        self,
+        n_components=2,
+        reg=None,
+        signal_cov=None,
+        method_params=None,
+        restr_type=None,
+        info=None,
+        rank="full",
+    ):
+        """Init."""
+        self.n_components = n_components
+        self.signal_cov = signal_cov
+        self.reg = reg
+        self.method_params = method_params
+        self.restr_type = restr_type
+        self.info = info
+        self.rank = rank
+
+        cov_callable = partial(
+            _xdawn_estimate,
+            reg=reg,
+            cov_method_params=method_params,
+            R=signal_cov,
+            info=info,
+            rank=rank,
+        )
+        super().__init__(
+            n_components=n_components,
+            cov_callable=cov_callable,
+            mod_ged_callable=_xdawn_mod,
+            dec_type="multi",
+            restr_type=restr_type,
+        )
+
+    def _validate_params(self, X):
+        _validate_type(self.n_components, int, "n_components")
+
+        # reg is validated in _regularized_covariance
+
+        if self.signal_cov is not None:
+            if isinstance(self.signal_cov, Covariance):
+                self.signal_cov = self.signal_cov.data
+            elif not isinstance(self.signal_cov, np.ndarray):
+                raise ValueError("signal_cov should be mne.Covariance or np.ndarray")
+            if not np.array_equal(self.signal_cov.shape, np.tile(X.shape[1], 2)):
+                raise ValueError(
+                    "signal_cov data should be of shape (n_channels, n_channels)"
+                )
+        _validate_type(self.method_params, (Mapping, None), "method_params")
+        _check_option(
+            "restr_type",
+            self.restr_type,
+            ("restricting", "whitening", None),
+        )
+        _validate_type(self.info, (Info, None), "info")
+
+    def fit(self, X, y=None):
+        """Fit Xdawn spatial filters.
+
+        Parameters
+        ----------
+        X : array, shape (n_epochs, n_channels, n_samples)
+            The target data.
+        y : array, shape (n_epochs,) | None
+            The target labels. If None, Xdawn fit on the average evoked.
+
+        Returns
+        -------
+        self : Xdawn instance
+            The Xdawn instance.
+        """
+        from ..preprocessing.xdawn import _fit_xdawn
+
+        X, y = self._check_Xy(X, y)
+        self._validate_params(X)
+        # Main function
+        self.classes_ = np.unique(y)
+        self.filters_, self.patterns_, _ = _fit_xdawn(
+            X,
+            y,
+            n_components=self.n_components,
+            reg=self.reg,
+            signal_cov=self.signal_cov,
+            method_params=self.method_params,
+        )
+        old_filters = self.filters_
+        old_patterns = self.patterns_
+        super().fit(X, y)
+
+        # Hack for assert_allclose in transform
+        self.new_filters_ = self.filters_.copy()
+        # Xdawn performs separate GED for each class.
+        # filters_ returned by _fit_xdawn are subset per
+        # n_components and then appended and are of shape
+        # (n_classes*n_components, n_chs).
+        # GEDTransformer creates new dimension per class without subsetting
+        # for easier analysis and visualisations.
+        # So it needs to be performed post-hoc to conform with Xdawn.
+        # The shape returned by GED here is (n_classes, n_evecs, n_chs)
+        # Need to transform and subset into (n_classes*n_components, n_chs)
+        self.filters_ = self.filters_[:, : self.n_components, :].reshape(
+            -1, self.filters_.shape[2]
+        )
+        self.patterns_ = self.patterns_[:, : self.n_components, :].reshape(
+            -1, self.patterns_.shape[2]
+        )
+        np.testing.assert_allclose(old_filters, self.filters_)
+        np.testing.assert_allclose(old_patterns, self.patterns_)
+
+        return self
+
+    def transform(self, X):
+        """Transform data with spatial filters.
+
+        Parameters
+        ----------
+        X : array, shape (n_epochs, n_channels, n_samples)
+            The target data.
+
+        Returns
+        -------
+        X : array, shape (n_epochs, n_components * n_classes, n_samples)
+            The transformed data.
+        """
+        X, _ = self._check_Xy(X)
+        orig_X = X.copy()
+
+        # Check size
+        if self.filters_.shape[1] != X.shape[1]:
+            raise ValueError(
+                f"X must have {self.filters_.shape[1]} channels, got {X.shape[1]} "
+                "instead."
+            )
+
+        # Transform
+        X = np.dot(self.filters_, X)
+        X = X.transpose((1, 0, 2))
+        ged_X = super().transform(orig_X)
+        np.testing.assert_allclose(X, ged_X)
+        return X
+
+    def inverse_transform(self, X):
+        """Remove selected components from the signal.
+
+        Given the unmixing matrix, transform data, zero out components,
+        and inverse transform the data. This procedure will reconstruct
+        the signals from which the dynamics described by the excluded
+        components is subtracted.
+
+        Parameters
+        ----------
+        X : array, shape (n_epochs, n_components * n_classes, n_times)
+            The transformed data.
+
+        Returns
+        -------
+        X : array, shape (n_epochs, n_channels * n_classes, n_times)
+            The inverse transform data.
+        """
+        # Check size
+        X, _ = self._check_Xy(X)
+        n_epochs, n_comp, n_times = X.shape
+        if n_comp != (self.n_components * len(self.classes_)):
+            raise ValueError(
+                f"X must have {self.n_components * len(self.classes_)} components, "
+                f"got {n_comp} instead."
+            )
+
+        # Transform
+        return np.dot(self.patterns_.T, X).transpose(1, 0, 2)
+
+    def _check_Xy(self, X, y=None):
+        """Check X and y types and dimensions."""
+        # Check data
+        if not isinstance(X, np.ndarray) or X.ndim != 3:
+            raise ValueError(
+                "X must be an array of shape (n_epochs, n_channels, n_samples)."
+            )
+        if y is None:
+            y = np.ones(len(X))
+        y = np.asarray(y)
+        if len(X) != len(y):
+            raise ValueError("X and y must have the same length")
+        return X, y
diff --git a/mne/preprocessing/tests/test_xdawn.py b/mne/preprocessing/tests/test_xdawn.py
index c30fd5dcfd9..a233695795f 100644
--- a/mne/preprocessing/tests/test_xdawn.py
+++ b/mne/preprocessing/tests/test_xdawn.py
@@ -22,7 +22,8 @@
 
 pytest.importorskip("sklearn")
 
-from mne.preprocessing.xdawn import Xdawn, _XdawnTransformer  # noqa: E402
+from mne.decoding.xdawn import XdawnTransformer
+from mne.preprocessing.xdawn import Xdawn  # noqa: E402
 
 base_dir = Path(__file__).parents[2] / "io" / "tests" / "data"
 raw_fname = base_dir / "test_raw.fif"
@@ -236,7 +237,7 @@ def test_xdawn_regularization():
 
 
 def test_XdawnTransformer():
-    """Test _XdawnTransformer."""
+    """Test XdawnTransformer."""
     pytest.importorskip("sklearn")
     # Get data
     raw, events, picks = _get_data()
@@ -255,37 +256,37 @@ def test_XdawnTransformer():
     X = epochs._data
     y = epochs.events[:, -1]
     # Fit
-    xdt = _XdawnTransformer()
+    xdt = XdawnTransformer()
     xdt.fit(X, y)
     pytest.raises(ValueError, xdt.fit, X, y[1:])
     pytest.raises(ValueError, xdt.fit, "foo")
 
     # Provide covariance object
     signal_cov = compute_raw_covariance(raw, picks=picks)
-    xdt = _XdawnTransformer(signal_cov=signal_cov)
+    xdt = XdawnTransformer(signal_cov=signal_cov)
     xdt.fit(X, y)
     # Provide ndarray
     signal_cov = np.eye(len(picks))
-    xdt = _XdawnTransformer(signal_cov=signal_cov)
+    xdt = XdawnTransformer(signal_cov=signal_cov)
     xdt.fit(X, y)
     # Provide ndarray of bad shape
     signal_cov = np.eye(len(picks) - 1)
-    xdt = _XdawnTransformer(signal_cov=signal_cov)
+    xdt = XdawnTransformer(signal_cov=signal_cov)
     pytest.raises(ValueError, xdt.fit, X, y)
     # Provide another type
     signal_cov = 42
-    xdt = _XdawnTransformer(signal_cov=signal_cov)
+    xdt = XdawnTransformer(signal_cov=signal_cov)
     pytest.raises(ValueError, xdt.fit, X, y)
 
     # Fit with y as None
-    xdt = _XdawnTransformer()
+    xdt = XdawnTransformer()
     xdt.fit(X)
 
-    # Compare xdawn and _XdawnTransformer
+    # Compare xdawn and XdawnTransformer
     xd = Xdawn(correct_overlap=False)
     xd.fit(epochs)
 
-    xdt = _XdawnTransformer()
+    xdt = XdawnTransformer()
     xdt.fit(X, y)
     assert_array_almost_equal(
         xd.filters_["cond2"][:2, :], xdt.filters_.reshape(2, 2, 8)[0]
@@ -363,7 +364,7 @@ def test_xdawn_decoding_performance():
     epochs, mixing_mat = _simulate_erplike_mixed_data(n_epochs=100)
     y = epochs.events[:, 2]
 
-    # results of Xdawn and _XdawnTransformer should match
+    # results of Xdawn and XdawnTransformer should match
     xdawn_pipe = make_pipeline(
         Xdawn(n_components=n_xdawn_comps),
         Vectorizer(),
@@ -371,7 +372,7 @@ def test_xdawn_decoding_performance():
         LogisticRegression(solver="liblinear"),
     )
     xdawn_trans_pipe = make_pipeline(
-        _XdawnTransformer(n_components=n_xdawn_comps),
+        XdawnTransformer(n_components=n_xdawn_comps),
         Vectorizer(),
         MinMaxScaler(),
         LogisticRegression(solver="liblinear"),
diff --git a/mne/preprocessing/xdawn.py b/mne/preprocessing/xdawn.py
index 3e9bc806158..f20572c8c63 100644
--- a/mne/preprocessing/xdawn.py
+++ b/mne/preprocessing/xdawn.py
@@ -2,22 +2,16 @@
 # License: BSD-3-Clause
 # Copyright the MNE-Python contributors.
 
-from collections.abc import Mapping
-from functools import partial
-
 import numpy as np
 from scipy import linalg
 
-from .._fiff.meas_info import Info
 from .._fiff.pick import _pick_data_channels, pick_info
 from ..cov import Covariance, _regularized_covariance
-from ..decoding._covs_ged import _xdawn_estimate
-from ..decoding._mod_ged import _xdawn_mod
-from ..decoding.base import _GEDTransformer
+from ..decoding.xdawn import XdawnTransformer
 from ..epochs import BaseEpochs
 from ..evoked import Evoked, EvokedArray
 from ..io import BaseRaw
-from ..utils import _check_option, _validate_type, logger, pinv
+from ..utils import _check_option, logger, pinv
 
 
 def _construct_signal_from_epochs(epochs, events, sfreq, tmin):
@@ -218,256 +212,7 @@ def _fit_xdawn(
     return filters, patterns, evokeds
 
 
-class _XdawnTransformer(_GEDTransformer):
-    """Implementation of the Xdawn Algorithm compatible with scikit-learn.
-
-    Xdawn is a spatial filtering method designed to improve the signal
-    to signal + noise ratio (SSNR) of the event related responses. Xdawn was
-    originally designed for P300 evoked potential by enhancing the target
-    response with respect to the non-target response. This implementation is a
-    generalization to any type of event related response.
-
-    .. note:: _XdawnTransformer does not correct for epochs overlap. To correct
-              overlaps see ``Xdawn``.
-
-    Parameters
-    ----------
-    n_components : int (default 2)
-        The number of components to decompose the signals.
-    reg : float | str | None (default None)
-        If not None (same as ``'empirical'``, default), allow
-        regularization for covariance estimation.
-        If float, shrinkage is used (0 <= shrinkage <= 1).
-        For str options, ``reg`` will be passed to ``method`` to
-        :func:`mne.compute_covariance`.
-    signal_cov : None | Covariance | array, shape (n_channels, n_channels)
-        The signal covariance used for whitening of the data.
-        if None, the covariance is estimated from the epochs signal.
-    method_params : dict | None
-        Parameters to pass to :func:`mne.compute_covariance`.
-
-        .. versionadded:: 0.16
-    restr_type : "restricting" | "whitening" | None
-        Restricting transformation for covariance matrices before performing
-        generalized eigendecomposition.
-        If "restricting" only restriction to the principal subspace of signal_cov
-        will be performed.
-        If "whitening", covariance matrices will be additionally rescaled according
-        to the whitening for the signal_cov.
-        If None, no restriction will be applied. Defaults to None.
-
-        .. versionadded:: 1.10
-    info : mne.Info | None
-        The mne.Info object with information about the sensors and methods of
-        measurement used for covariance estimation and generalized
-        eigendecomposition.
-        If None, one channel type and no projections will be assumed and if
-        rank is dict, it will be sum of ranks per channel type.
-        Defaults to None.
-
-        .. versionadded:: 1.10
-    %(rank)s
-        Defaults to "full".
-
-        .. versionadded:: 1.10
-
-
-    Attributes
-    ----------
-    classes_ : array, shape (n_classes)
-        The event indices of the classes.
-    filters_ : array, shape (n_channels, n_channels)
-        The Xdawn components used to decompose the data for each event type.
-    patterns_ : array, shape (n_channels, n_channels)
-        The Xdawn patterns used to restore the signals for each event type.
-    """
-
-    def __init__(
-        self,
-        n_components=2,
-        reg=None,
-        signal_cov=None,
-        method_params=None,
-        restr_type=None,
-        info=None,
-        rank="full",
-    ):
-        """Init."""
-        self.n_components = n_components
-        self.signal_cov = signal_cov
-        self.reg = reg
-        self.method_params = method_params
-        self.restr_type = restr_type
-        self.info = info
-        self.rank = rank
-
-        cov_callable = partial(
-            _xdawn_estimate,
-            reg=reg,
-            cov_method_params=method_params,
-            R=signal_cov,
-            info=info,
-            rank=rank,
-        )
-        super().__init__(
-            n_components=n_components,
-            cov_callable=cov_callable,
-            mod_ged_callable=_xdawn_mod,
-            dec_type="multi",
-            restr_type=restr_type,
-        )
-
-    def _validate_params(self, X):
-        _validate_type(self.n_components, int, "n_components")
-
-        # reg is validated in _regularized_covariance
-
-        if self.signal_cov is not None:
-            if isinstance(self.signal_cov, Covariance):
-                self.signal_cov = self.signal_cov.data
-            elif not isinstance(self.signal_cov, np.ndarray):
-                raise ValueError("signal_cov should be mne.Covariance or np.ndarray")
-            if not np.array_equal(self.signal_cov.shape, np.tile(X.shape[1], 2)):
-                raise ValueError(
-                    "signal_cov data should be of shape (n_channels, n_channels)"
-                )
-        _validate_type(self.method_params, (Mapping, None), "method_params")
-        _check_option(
-            "restr_type",
-            self.restr_type,
-            ("restricting", "whitening", None),
-        )
-        _validate_type(self.info, (Info, None), "info")
-
-    def fit(self, X, y=None):
-        """Fit Xdawn spatial filters.
-
-        Parameters
-        ----------
-        X : array, shape (n_epochs, n_channels, n_samples)
-            The target data.
-        y : array, shape (n_epochs,) | None
-            The target labels. If None, Xdawn fit on the average evoked.
-
-        Returns
-        -------
-        self : Xdawn instance
-            The Xdawn instance.
-        """
-        X, y = self._check_Xy(X, y)
-        self._validate_params(X)
-        # Main function
-        self.classes_ = np.unique(y)
-        self.filters_, self.patterns_, _ = _fit_xdawn(
-            X,
-            y,
-            n_components=self.n_components,
-            reg=self.reg,
-            signal_cov=self.signal_cov,
-            method_params=self.method_params,
-        )
-        old_filters = self.filters_
-        old_patterns = self.patterns_
-        super().fit(X, y)
-
-        # Hack for assert_allclose in transform
-        self.new_filters_ = self.filters_.copy()
-        # Xdawn performs separate GED for each class.
-        # filters_ returned by _fit_xdawn are subset per
-        # n_components and then appended and are of shape
-        # (n_classes*n_components, n_chs).
-        # GEDTransformer creates new dimension per class without subsetting
-        # for easier analysis and visualisations.
-        # So it needs to be performed post-hoc to conform with Xdawn.
-        # The shape returned by GED here is (n_classes, n_evecs, n_chs)
-        # Need to transform and subset into (n_classes*n_components, n_chs)
-        self.filters_ = self.filters_[:, : self.n_components, :].reshape(
-            -1, self.filters_.shape[2]
-        )
-        self.patterns_ = self.patterns_[:, : self.n_components, :].reshape(
-            -1, self.patterns_.shape[2]
-        )
-        np.testing.assert_allclose(old_filters, self.filters_)
-        np.testing.assert_allclose(old_patterns, self.patterns_)
-
-        return self
-
-    def transform(self, X):
-        """Transform data with spatial filters.
-
-        Parameters
-        ----------
-        X : array, shape (n_epochs, n_channels, n_samples)
-            The target data.
-
-        Returns
-        -------
-        X : array, shape (n_epochs, n_components * n_classes, n_samples)
-            The transformed data.
-        """
-        X, _ = self._check_Xy(X)
-        orig_X = X.copy()
-
-        # Check size
-        if self.filters_.shape[1] != X.shape[1]:
-            raise ValueError(
-                f"X must have {self.filters_.shape[1]} channels, got {X.shape[1]} "
-                "instead."
-            )
-
-        # Transform
-        X = np.dot(self.filters_, X)
-        X = X.transpose((1, 0, 2))
-        ged_X = super().transform(orig_X)
-        np.testing.assert_allclose(X, ged_X)
-        return X
-
-    def inverse_transform(self, X):
-        """Remove selected components from the signal.
-
-        Given the unmixing matrix, transform data, zero out components,
-        and inverse transform the data. This procedure will reconstruct
-        the signals from which the dynamics described by the excluded
-        components is subtracted.
-
-        Parameters
-        ----------
-        X : array, shape (n_epochs, n_components * n_classes, n_times)
-            The transformed data.
-
-        Returns
-        -------
-        X : array, shape (n_epochs, n_channels * n_classes, n_times)
-            The inverse transform data.
-        """
-        # Check size
-        X, _ = self._check_Xy(X)
-        n_epochs, n_comp, n_times = X.shape
-        if n_comp != (self.n_components * len(self.classes_)):
-            raise ValueError(
-                f"X must have {self.n_components * len(self.classes_)} components, "
-                f"got {n_comp} instead."
-            )
-
-        # Transform
-        return np.dot(self.patterns_.T, X).transpose(1, 0, 2)
-
-    def _check_Xy(self, X, y=None):
-        """Check X and y types and dimensions."""
-        # Check data
-        if not isinstance(X, np.ndarray) or X.ndim != 3:
-            raise ValueError(
-                "X must be an array of shape (n_epochs, n_channels, n_samples)."
-            )
-        if y is None:
-            y = np.ones(len(X))
-        y = np.asarray(y)
-        if len(X) != len(y):
-            raise ValueError("X and y must have the same length")
-        return X, y
-
-
-class Xdawn(_XdawnTransformer):
+class Xdawn(XdawnTransformer):
     """Implementation of the Xdawn Algorithm.
 
     Xdawn :footcite:`RivetEtAl2009,RivetEtAl2011` is a spatial

From 8e8bf3f631236ac99612905facb41160718dab03 Mon Sep 17 00:00:00 2001
From: Genuster <genusterok@gmail.com>
Date: Fri, 13 Jun 2025 20:04:19 +0300
Subject: [PATCH 32/59] fix docstring

---
 mne/decoding/ssd.py | 4 ++--
 1 file changed, 2 insertions(+), 2 deletions(-)

diff --git a/mne/decoding/ssd.py b/mne/decoding/ssd.py
index 97a4b73270f..b03f259d03e 100644
--- a/mne/decoding/ssd.py
+++ b/mne/decoding/ssd.py
@@ -96,9 +96,9 @@ class SSD(_GEDTransformer):
 
     Attributes
     ----------
-    filters_ : array, shape (n_channels or less, n_channels)
+    filters_ : array, shape (``n_channels or less``, n_channels)
         The spatial filters to be multiplied with the signal.
-    patterns_ : array, shape (n_channels or less, n_channels)
+    patterns_ : array, shape (``n_channels or less``, n_channels)
         The patterns for reconstructing the signal from the filtered data.
 
     References

From a3745462b4455fd5c2e261f42b18b857f54db0d3 Mon Sep 17 00:00:00 2001
From: Genuster <genusterok@gmail.com>
Date: Fri, 13 Jun 2025 23:50:26 +0300
Subject: [PATCH 33/59] fix some terminological imprecisions in the
 implementation details

---
 doc/_includes/ged.rst | 37 +++++++++++++++++++++++--------------
 1 file changed, 23 insertions(+), 14 deletions(-)

diff --git a/doc/_includes/ged.rst b/doc/_includes/ged.rst
index ae2c3706bf7..8f5fc17131c 100644
--- a/doc/_includes/ged.rst
+++ b/doc/_includes/ged.rst
@@ -69,30 +69,39 @@ covariance :math:`C_{ref}` (in Common Spatial Pattern (CSP) algorithm, for examp
 More formally: 
 Let :math:`r \leq n` be a rank of :math:`C \in S^n_+`. 
 Let :math:`Q=\operatorname{Im}(C_{ref})` be a principal subspace of :math:`C_{ref}`. 
-Let :math:`P \in M_{n \times r}(\mathbb{R})` be formed by orthonormal basis of :math:`Q`.
-Let :math:`f:M_n(\mathbb{R}) \to M_r(\mathbb{R})` be a "restricting" linear map, that restricts matrix :math:`A` to :math:`Q`: :math:`A|_Q = P^t A P`.
+Let :math:`P \in M_{n \times r}(\mathbb{R})` be an isometry formed by orthonormal basis of :math:`Q`.
+Let :math:`f:S^n_+ \to S^r_+`, :math:`A \mapsto P^t A P` be a "restricting" map, that restricts quadratic form 
+:math:`q_A:\mathbb{R}^n \to \mathbb{R}` to :math:`q_{A|_Q}:\mathbb{R}^n \to \mathbb{R}` (in practical terms, :math:`q_A` maps 
+spatial filters to variance of the spatially filtered data :math:`X_A`).
 
 Then, the GED of :math:`S` and :math:`R` in the principal subspace :math:`Q` of :math:`C_{ref}` is performed as follows:
 
-1. :math:`S` and :math:`R` are restricted to :math:`Q`:
-   :math:`S|_Q = f(S) = P^t S P` and :math:`R|_Q = f(R) = P^t R P`
-2. GED is performed on :math:`S|_Q` and :math:`R|_Q`:
-   :math:`S|_Q W|_Q = R|_Q W|_Q D`
-3. Eigenvectors :math:`W_Q` of :math:`(S|_Q, R|_Q)` are transformed back to :math:`\mathbb{R}^n` by:
-   :math:`W = P W|_Q \in \mathbb{R}^{n \times r}` to obtain :math:`r` spatial filters.
+1. :math:`S` and :math:`R` are transformed to :math:`S_Q = f(S) = P^t S P` and :math:`R_Q = f(R) = P^t R P`, 
+   such that :math:`S_Q` and :math:`R_Q` are matrix representations of restricted :math:`q_{S|_Q}` and :math:`q_{R|_Q}`.
+2. GED is performed on :math:`S_Q` and :math:`R_Q`: :math:`S_Q W_Q = R_Q W_Q D`.
+3. Eigenvectors :math:`W_Q` of :math:`(S_Q, R_Q)` are transformed back to :math:`\mathbb{R}^n` 
+   by :math:`W = P W_Q \in \mathbb{R}^{n \times r}` to obtain :math:`r` spatial filters.
 
-In addition to restriction, :math:`S` and :math:`R` can be rescaled based on the whitened :math:`C_{ref}`. 
-In this case the whitening map :math:`f_{wh}:M_n(\mathbb{R}) \to M_r(\mathbb{R})`, 
-:math:`A \mapsto P_{wh}^t A P_{wh}` both restricts matrix :math:`A` to :math:`Q` and rescales it according to :math:`\Lambda^{-1/2}`, 
-where :math:`\Lambda` is a diagonal matrix of eigenvalues of :math:`C_{ref}` and :math:`P_{wh} = P \Lambda^{-1/2}`.
+Note that the solution to the original optimization problem is preserved:
+
+.. math::
+
+   \frac{\mathbf{w_Q}^t S_Q \mathbf{w_Q}}{\mathbf{w_Q}^t R_Q \mathbf{w_Q}}= \frac{\mathbf{w_Q}^t (P^t S P) \mathbf{w_Q}}{\mathbf{w_Q}^t (P^t R P) 
+   \mathbf{w_Q}} = \frac{\mathbf{w}^t S \mathbf{w}}{\mathbf{w}^t R \mathbf{w}} = \lambda
+
+
+In addition to restriction, :math:`q_S` and :math:`q_R` can be rescaled based on the whitened :math:`C_{ref}`. 
+In this case the whitening map :math:`f_{wh}:S^n_+ \to S^r_+`, 
+:math:`A \mapsto P_{wh}^t A P_{wh}` transforms :math:`A` into matrix representation of :math:`q_{A|Q}` rescaled according to :math:`\Lambda^{-1/2}`, 
+where :math:`\Lambda` is a diagonal matrix of eigenvalues of :math:`C_{ref}` and so :math:`P_{wh} = P \Lambda^{-1/2}`.
 
 In MNE-Python, the matrix :math:`P` of the restricting map can be obtained using
 ::
 
-    _, evecs, mask = mne.cov._smart_eigh(..., proj_subspace=True, ...)
+    _, ref_evecs, mask = mne.cov._smart_eigh(C_ref, ..., proj_subspace=True, ...)
     restr_mat = ref_evecs[mask]
 
 while :math:`P_{wh}` using:
 ::
 
-    restr_mat = compute_whitener(..., pca=True, ...)
\ No newline at end of file
+    restr_mat = compute_whitener(C_ref, ..., pca=True, ...)
\ No newline at end of file

From 226abf4c04465a21e240e2f2ffd6165f87326f2c Mon Sep 17 00:00:00 2001
From: Genuster <genusterok@gmail.com>
Date: Sun, 15 Jun 2025 14:03:06 +0300
Subject: [PATCH 34/59] add parameter validation for gedtransformer

---
 mne/decoding/base.py | 66 ++++++++++++++++++++++++++++++++++++++------
 1 file changed, 58 insertions(+), 8 deletions(-)

diff --git a/mne/decoding/base.py b/mne/decoding/base.py
index fa37c1c39eb..18157c758db 100644
--- a/mne/decoding/base.py
+++ b/mne/decoding/base.py
@@ -6,6 +6,8 @@
 
 import datetime as dt
 import numbers
+from functools import partial
+from inspect import Parameter, signature
 
 import numpy as np
 from sklearn import model_selection as models
@@ -23,7 +25,7 @@
 from sklearn.utils.validation import check_is_fitted
 
 from ..parallel import parallel_func
-from ..utils import _pl, logger, pinv, verbose, warn
+from ..utils import _check_option, _pl, _validate_type, logger, pinv, verbose, warn
 from ._ged import _handle_restr_mat, _is_cov_symm_pos_semidef, _smart_ajd, _smart_ged
 from ._mod_ged import _no_op_mod
 from .transformer import MNETransformerMixin
@@ -37,19 +39,21 @@ class _GEDTransformer(MNETransformerMixin, BaseEstimator):
 
     Parameters
     ----------
-    n_components : int
+    n_components : int | None
         The number of spatial filters to decompose M/EEG signals.
+        If None, all of the components will be used for transformation.
+        Defaults to None.
     cov_callable : callable
         Function used to estimate covariances and reference matrix (C_ref) from the
-        data. It should accept only X and y as arguments and return covs, C_ref, info,
-        rank and additional kwargs passed further to mod_ged_callable.
-        C_ref, info, rank can be None, while kwargs can be empty dict.
+        data. The only required arguments should be 'X' and optionally 'y'. The function
+        should return covs, C_ref, info, rank and additional kwargs passed further
+        to mod_ged_callable. C_ref, info, rank can be None and kwargs can be empty dict.
     mod_ged_callable : callable | None
         Function used to modify (e.g. sort or normalize) generalized
         eigenvalues and eigenvectors. It should accept as arguments evals, evecs
         and also covs and optional kwargs returned by cov_callable. It should return
         only sorted and/or modified evals and evecs. If None, evals and evecs will be
-        ordered according to :func:`~scipy.linalg.eigh` default. Defaults to None
+        ordered according to :func:`~scipy.linalg.eigh` default. Defaults to None.
     dec_type : "single" | "multi"
         When "single" and cov_callable returns > 2 covariances,
         approximate joint diagonalization based on Pham's algorithm
@@ -68,7 +72,9 @@ class _GEDTransformer(MNETransformerMixin, BaseEstimator):
         preserved for compatibility.
         If None, no restriction will be applied. Defaults to None.
     R_func : callable | None
-        If provided, GED will be performed on (S, R_func(S,R)).
+        If provided, GED will be performed on (S, R_func([S,R])). When dec_type is
+        "single", R_func applicable only if two covariances returned by cov_callable.
+        If None, GED is performed on (S, R). Defaults to None.
 
     Attributes
     ----------
@@ -94,9 +100,9 @@ class _GEDTransformer(MNETransformerMixin, BaseEstimator):
 
     def __init__(
         self,
-        n_components,
         cov_callable,
         *,
+        n_components=None,
         mod_ged_callable=None,
         dec_type="single",
         restr_type=None,
@@ -118,6 +124,7 @@ def fit(self, X, y=None):
             return_y=True,
             atleast_3d=False if self.restr_type == "ssd" else True,
         )
+        self._validate_ged_params()
         covs, C_ref, info, rank, kwargs = self.cov_callable(X, y)
         covs = np.stack(covs)
         self._validate_covariances(covs)
@@ -184,6 +191,49 @@ def transform(self, X):
         X = pick_filters @ X
         return X
 
+    def _validate_required_args(self, func, desired_required_args):
+        sig = signature(func)
+        actual_required_args = [
+            param.name
+            for param in sig.parameters.values()
+            if param.default is Parameter.empty
+        ]
+        func_name = func.func.__name__ if isinstance(func, partial) else func.__name__
+        if not all(arg in desired_required_args for arg in actual_required_args):
+            raise ValueError(
+                f"Invalid required arguments for '{func_name}'. "
+                f"The only allowed required arguments are {desired_required_args}, "
+                f"but got {actual_required_args} instead."
+            )
+
+    def _validate_ged_params(self):
+        # Naming is GED-specific so that the validation is still executed
+        # when child classes run super().fit()
+
+        _validate_type(self.n_components, (int, None), "n_components")
+        if self.n_components is not None and self.n_components <= 0:
+            raise ValueError(
+                "Invalid value for the 'n_components' parameter. "
+                "Allowed are positive integers or None, "
+                "but got a non-positive integer instead."
+            )
+
+        self._validate_required_args(
+            self.cov_callable, desired_required_args=["X", "y"]
+        )
+
+        _check_option(
+            "dec_type",
+            self.dec_type,
+            ("single", "multi"),
+        )
+
+        _check_option(
+            "restr_type",
+            self.restr_type,
+            ("restricting", "whitening", "ssd", None),
+        )
+
     def _validate_covariances(self, covs):
         for cov in covs:
             if cov is None:

From 3da326632fa2e7bcc3ba6e8f489d11c3980a7b48 Mon Sep 17 00:00:00 2001
From: Genuster <genusterok@gmail.com>
Date: Sun, 15 Jun 2025 14:04:54 +0300
Subject: [PATCH 35/59] slightly improve validation in csp and ssd

---
 mne/decoding/csp.py | 22 ++++++++--------------
 mne/decoding/ssd.py |  2 ++
 2 files changed, 10 insertions(+), 14 deletions(-)

diff --git a/mne/decoding/csp.py b/mne/decoding/csp.py
index b261ffd8ebb..61de2320efa 100644
--- a/mne/decoding/csp.py
+++ b/mne/decoding/csp.py
@@ -2,6 +2,7 @@
 # License: BSD-3-Clause
 # Copyright the MNE-Python contributors.
 
+import collections.abc as abc
 import copy as cp
 from functools import partial
 
@@ -197,12 +198,14 @@ def _validate_params(self, *, y):
         n_classes = len(self.classes_)
         if n_classes < 2:
             raise ValueError(f"n_classes must be >= 2, but got {n_classes} class")
-        _check_option(
-            "restr_type",
-            self.restr_type,
-            ("restricting", "whitening", None),
-        )
+        elif n_classes > 2 and self.component_order == "alternate":
+            raise ValueError(
+                "component_order='alternate' requires two classes, but data contains "
+                f"{n_classes} classes; use component_order='mutual_info' instead."
+            )
+        _validate_type(self.rank, (dict, None, str), "rank")
         _validate_type(self.info, (Info, None), "info")
+        _validate_type(self.cov_method_params, (abc.Mapping, None), "cov_method_params")
 
     def fit(self, X, y):
         """Estimate the CSP decomposition on epochs.
@@ -221,15 +224,6 @@ def fit(self, X, y):
         """
         X, y = self._check_data(X, y=y, fit=True, return_y=True)
         self._validate_params(y=y)
-        n_classes = len(self.classes_)
-        if n_classes > 2 and self.component_order == "alternate":
-            raise ValueError(
-                "component_order='alternate' requires two classes, but data contains "
-                f"{n_classes} classes; use component_order='mutual_info' instead."
-            )
-
-        # Convert rank to one that will run
-        _validate_type(self.rank, (dict, None, str), "rank")
 
         covs, sample_weights = self._compute_covariance_matrices(X, y)
         eigen_vectors, eigen_values = self._decompose_covs(covs, sample_weights)
diff --git a/mne/decoding/ssd.py b/mne/decoding/ssd.py
index b03f259d03e..07c9902cb19 100644
--- a/mne/decoding/ssd.py
+++ b/mne/decoding/ssd.py
@@ -2,6 +2,7 @@
 # License: BSD-3-Clause
 # Copyright the MNE-Python contributors.
 
+import collections.abc as abc
 from functools import partial
 
 import numpy as np
@@ -200,6 +201,7 @@ def _validate_params(self, X):
                     "At this point SSD only supports fitting "
                     f"single channel types. Your info has {len(ch_types)} types."
                 )
+        _validate_type(self.cov_method_params, (abc.Mapping, None), "cov_method_params")
 
     def _check_X(self, X, *, y=None, fit=False):
         """Check input data."""

From 4f5d4361a9030239a64201ca4f7ce065c5da1845 Mon Sep 17 00:00:00 2001
From: Genuster <genusterok@gmail.com>
Date: Sun, 15 Jun 2025 14:05:17 +0300
Subject: [PATCH 36/59] rename xdawntranformer's method_params to
 cov_method_params for consistency

---
 mne/decoding/xdawn.py      | 21 ++++++++-------------
 mne/preprocessing/xdawn.py |  2 +-
 2 files changed, 9 insertions(+), 14 deletions(-)

diff --git a/mne/decoding/xdawn.py b/mne/decoding/xdawn.py
index 546fbb2e55e..8f5a11bec8e 100644
--- a/mne/decoding/xdawn.py
+++ b/mne/decoding/xdawn.py
@@ -2,7 +2,7 @@
 # License: BSD-3-Clause
 # Copyright the MNE-Python contributors.
 
-from collections.abc import Mapping
+import collections.abc as abc
 from functools import partial
 
 import numpy as np
@@ -12,7 +12,7 @@
 from ..decoding._covs_ged import _xdawn_estimate
 from ..decoding._mod_ged import _xdawn_mod
 from ..decoding.base import _GEDTransformer
-from ..utils import _check_option, _validate_type
+from ..utils import _validate_type
 
 
 class XdawnTransformer(_GEDTransformer):
@@ -40,7 +40,7 @@ class XdawnTransformer(_GEDTransformer):
     signal_cov : None | Covariance | array, shape (n_channels, n_channels)
         The signal covariance used for whitening of the data.
         if None, the covariance is estimated from the epochs signal.
-    method_params : dict | None
+    cov_method_params : dict | None
         Parameters to pass to :func:`mne.compute_covariance`.
 
         .. versionadded:: 0.16
@@ -84,7 +84,7 @@ def __init__(
         n_components=2,
         reg=None,
         signal_cov=None,
-        method_params=None,
+        cov_method_params=None,
         restr_type=None,
         info=None,
         rank="full",
@@ -93,7 +93,7 @@ def __init__(
         self.n_components = n_components
         self.signal_cov = signal_cov
         self.reg = reg
-        self.method_params = method_params
+        self.cov_method_params = cov_method_params
         self.restr_type = restr_type
         self.info = info
         self.rank = rank
@@ -101,7 +101,7 @@ def __init__(
         cov_callable = partial(
             _xdawn_estimate,
             reg=reg,
-            cov_method_params=method_params,
+            cov_method_params=cov_method_params,
             R=signal_cov,
             info=info,
             rank=rank,
@@ -128,12 +128,7 @@ def _validate_params(self, X):
                 raise ValueError(
                     "signal_cov data should be of shape (n_channels, n_channels)"
                 )
-        _validate_type(self.method_params, (Mapping, None), "method_params")
-        _check_option(
-            "restr_type",
-            self.restr_type,
-            ("restricting", "whitening", None),
-        )
+        _validate_type(self.cov_method_params, (abc.Mapping, None), "cov_method_params")
         _validate_type(self.info, (Info, None), "info")
 
     def fit(self, X, y=None):
@@ -163,7 +158,7 @@ def fit(self, X, y=None):
             n_components=self.n_components,
             reg=self.reg,
             signal_cov=self.signal_cov,
-            method_params=self.method_params,
+            method_params=self.cov_method_params,
         )
         old_filters = self.filters_
         old_patterns = self.patterns_
diff --git a/mne/preprocessing/xdawn.py b/mne/preprocessing/xdawn.py
index f20572c8c63..fd061323a36 100644
--- a/mne/preprocessing/xdawn.py
+++ b/mne/preprocessing/xdawn.py
@@ -335,7 +335,7 @@ def fit(self, epochs, y=None):
             events=events,
             tmin=tmin,
             sfreq=sfreq,
-            method_params=self.method_params,
+            method_params=self.cov_method_params,
             info=use_info,
         )
 

From 5e12465bbcbbfcf0e326964146245585d198f147 Mon Sep 17 00:00:00 2001
From: Genuster <genusterok@gmail.com>
Date: Fri, 20 Jun 2025 18:49:19 +0300
Subject: [PATCH 37/59] add picks test for ssd

---
 mne/decoding/_covs_ged.py      | 13 ++++---
 mne/decoding/ssd.py            | 15 ++++----
 mne/decoding/tests/test_ssd.py | 69 +++++++++++++++++++++++++++++++++-
 3 files changed, 83 insertions(+), 14 deletions(-)

diff --git a/mne/decoding/_covs_ged.py b/mne/decoding/_covs_ged.py
index 4fb56761e2b..cf2b48fd3d1 100644
--- a/mne/decoding/_covs_ged.py
+++ b/mne/decoding/_covs_ged.py
@@ -7,7 +7,7 @@
 import numpy as np
 
 from .._fiff.meas_info import Info, create_info
-from .._fiff.pick import _picks_to_idx
+from .._fiff.pick import _picks_to_idx, pick_info
 from ..cov import Covariance, _compute_rank_raw_array, _regularized_covariance
 from ..defaults import _handle_default
 from ..filter import filter_data
@@ -178,8 +178,8 @@ def _ssd_estimate(
     elif isinstance(info, float):  # special case, mostly for testing
         sfreq = info
         info = create_info(X.shape[-2], sfreq, ch_types="eeg")
-    picks = _picks_to_idx(info, picks, none="data", exclude="bads")
-    X_aux = X[..., picks, :]
+    picks_ = _picks_to_idx(info, picks, none="data", exclude="bads")
+    X_aux = X[..., picks_, :]
     X_signal = filter_data(X_aux, sfreq, **filt_params_signal)
     X_noise = filter_data(X_aux, sfreq, **filt_params_noise)
     X_noise -= X_signal
@@ -188,19 +188,20 @@ def _ssd_estimate(
         X_noise = np.hstack(X_noise)
 
     # prevent rank change when computing cov with rank='full'
+    picked_info = pick_info(info, picks_)
     S = _regularized_covariance(
         X_signal,
         reg=reg,
         method_params=cov_method_params,
         rank="full",
-        info=info,
+        info=picked_info,
     )
     R = _regularized_covariance(
         X_noise,
         reg=reg,
         method_params=cov_method_params,
         rank="full",
-        info=info,
+        info=picked_info,
     )
     covs = [S, R]
     C_ref = S
@@ -211,7 +212,7 @@ def _ssd_estimate(
             compute_rank(
                 Covariance(
                     cov,
-                    info.ch_names,
+                    picked_info.ch_names,
                     list(),
                     list(),
                     0,
diff --git a/mne/decoding/ssd.py b/mne/decoding/ssd.py
index 07c9902cb19..cd49b07c92b 100644
--- a/mne/decoding/ssd.py
+++ b/mne/decoding/ssd.py
@@ -10,7 +10,7 @@
 from sklearn.utils.validation import check_is_fitted
 
 from .._fiff.meas_info import Info, create_info
-from .._fiff.pick import _picks_to_idx
+from .._fiff.pick import _picks_to_idx, pick_info
 from ..cov import Covariance, _regularized_covariance
 from ..defaults import _handle_default
 from ..filter import filter_data
@@ -248,24 +248,25 @@ def fit(self, X, y=None):
             X_noise = np.hstack(X_noise)
 
         # prevent rank change when computing cov with rank='full'
+        picked_info = pick_info(info, self.picks_)
         cov_signal = _regularized_covariance(
             X_signal,
             reg=self.reg,
             method_params=self.cov_method_params,
             rank="full",
-            info=info,
+            info=picked_info,
         )
         cov_noise = _regularized_covariance(
             X_noise,
             reg=self.reg,
             method_params=self.cov_method_params,
             rank="full",
-            info=info,
+            info=picked_info,
         )
 
         # project cov to rank subspace
         cov_signal, cov_noise, rank_proj = _dimensionality_reduction(
-            cov_signal, cov_noise, info, self.rank
+            cov_signal, cov_noise, picked_info, self.rank
         )
 
         eigvals_, eigvects_ = eigh(cov_signal, cov_noise)
@@ -314,10 +315,10 @@ def transform(self, X):
         """
         check_is_fitted(self, "filters_")
         X = self._check_X(X)
+        X_aux = X[..., self.picks_, :]
         if self.return_filtered:
-            X_aux = X[..., self.picks_, :]
-            X = filter_data(X_aux, self.sfreq_, **self.filt_params_signal)
-        X_ssd = self.filters_ @ X[..., self.picks_, :]
+            X_aux = filter_data(X_aux, self.sfreq_, **self.filt_params_signal)
+        X_ssd = self.filters_ @ X_aux
         X_ssd = X_ssd[..., self.sorter_spec_, :][..., : self.n_components, :]
         return X_ssd
 
diff --git a/mne/decoding/tests/test_ssd.py b/mne/decoding/tests/test_ssd.py
index b6cdfc472c3..74337badc7a 100644
--- a/mne/decoding/tests/test_ssd.py
+++ b/mne/decoding/tests/test_ssd.py
@@ -3,6 +3,7 @@
 # Copyright the MNE-Python contributors.
 
 import sys
+from pathlib import Path
 
 import numpy as np
 import pytest
@@ -13,7 +14,8 @@
 from sklearn.pipeline import Pipeline
 from sklearn.utils.estimator_checks import parametrize_with_checks
 
-from mne import create_info, io
+from mne import Epochs, create_info, io, pick_types, read_events
+from mne._fiff.pick import _picks_to_idx
 from mne.decoding import CSP
 from mne.decoding.ssd import SSD
 from mne.filter import filter_data
@@ -22,6 +24,13 @@
 freqs_sig = 9, 12
 freqs_noise = 8, 13
 
+data_dir = Path(__file__).parents[2] / "io" / "tests" / "data"
+raw_fname = data_dir / "test_raw.fif"
+event_name = data_dir / "test-eve.fif"
+tmin, tmax = -0.1, 0.2
+event_id = dict(aud_l=1, vis_l=3)
+start, stop = 0, 8
+
 
 def simulate_data(
     freqs_sig=(9, 12),
@@ -486,6 +495,64 @@ def test_non_full_rank_data():
     ssd.fit(X)
 
 
+def test_picks_arg():
+    """Test that picks argument works as expected."""
+    raw = io.read_raw_fif(raw_fname, preload=False)
+    events = read_events(event_name)
+    picks = pick_types(
+        raw.info, meg=True, eeg=True, stim=False, ecg=False, eog=False, exclude="bads"
+    )
+    raw.add_proj([], remove_existing=True)
+    epochs = Epochs(
+        raw,
+        events,
+        event_id,
+        -0.1,
+        1,
+        picks=picks,
+        baseline=(None, 0),
+        preload=True,
+        proj=False,
+    )
+    X = epochs.get_data(copy=False)
+    filt_params_signal = dict(
+        l_freq=freqs_sig[0],
+        h_freq=freqs_sig[1],
+        l_trans_bandwidth=3,
+        h_trans_bandwidth=3,
+    )
+    filt_params_noise = dict(
+        l_freq=freqs_noise[0],
+        h_freq=freqs_noise[1],
+        l_trans_bandwidth=3,
+        h_trans_bandwidth=3,
+    )
+    picks = ["eeg"]
+    info = epochs.info
+    picks_idx = _picks_to_idx(info, picks)
+
+    # Test when return_filtered is False
+    ssd = SSD(
+        info,
+        filt_params_signal,
+        filt_params_noise,
+        picks=picks_idx,
+        return_filtered=False,
+    )
+    ssd.fit(X).transform(X)
+
+    # Test when return_filtered is true
+    ssd = SSD(
+        info,
+        filt_params_signal,
+        filt_params_noise,
+        picks=picks_idx,
+        return_filtered=True,
+        n_fft=64,
+    )
+    ssd.fit(X).transform(X)
+
+
 @pytest.mark.filterwarnings("ignore:.*invalid value encountered in divide.*")
 @pytest.mark.filterwarnings("ignore:.*is longer than.*")
 @parametrize_with_checks(

From 2bfc93152beba52626eb8a7ea8f869f613eaea1a Mon Sep 17 00:00:00 2001
From: Genuster <genusterok@gmail.com>
Date: Mon, 23 Jun 2025 12:59:45 +0300
Subject: [PATCH 38/59] make ssd store ordered filters instead of sorting in
 transform

---
 mne/decoding/_covs_ged.py | 20 +++++++++++++++++++-
 mne/decoding/_mod_ged.py  | 40 ++++++++++++++++++++++++++++++++++++++-
 mne/decoding/base.py      | 10 ++++++++--
 mne/decoding/ssd.py       | 36 +++++++++++++++++++++++++----------
 4 files changed, 92 insertions(+), 14 deletions(-)

diff --git a/mne/decoding/_covs_ged.py b/mne/decoding/_covs_ged.py
index cf2b48fd3d1..08a455b91c1 100644
--- a/mne/decoding/_covs_ged.py
+++ b/mne/decoding/_covs_ged.py
@@ -169,9 +169,11 @@ def _ssd_estimate(
     cov_method_params,
     info,
     picks,
+    n_fft,
     filt_params_signal,
     filt_params_noise,
     rank,
+    sort_by_spectral_ratio,
 ):
     if isinstance(info, Info):
         sfreq = info["sfreq"]
@@ -225,7 +227,23 @@ def _ssd_estimate(
         )[0]
     all_ranks.append(r)
     rank = np.min(all_ranks)
-    return covs, C_ref, info, rank, dict()
+    freqs_signal = (filt_params_signal["l_freq"], filt_params_signal["h_freq"])
+    freqs_noise = (filt_params_noise["l_freq"], filt_params_noise["h_freq"])
+    n_fft = min(
+        int(n_fft if n_fft is not None else sfreq),
+        X.shape[-1],
+    )
+    kwargs = dict(
+        X=X,
+        picks=picks_,
+        sfreq=sfreq,
+        n_fft=n_fft,
+        freqs_signal=freqs_signal,
+        freqs_noise=freqs_noise,
+        sort_by_spectral_ratio=sort_by_spectral_ratio,
+    )
+
+    return covs, C_ref, info, rank, kwargs
 
 
 def _spoc_estimate(X, y, reg, cov_method_params, info, rank):
diff --git a/mne/decoding/_mod_ged.py b/mne/decoding/_mod_ged.py
index 5b03c7feab4..c0cf3eedac5 100644
--- a/mne/decoding/_mod_ged.py
+++ b/mne/decoding/_mod_ged.py
@@ -6,6 +6,9 @@
 
 import numpy as np
 
+from ..time_frequency import psd_array_welch
+from ..utils import _time_mask
+
 
 def _compute_mutual_info(covs, sample_weights, evecs):
     class_probas = sample_weights / sample_weights.sum()
@@ -47,8 +50,43 @@ def _xdawn_mod(evals, evecs, covs=None):
     return evals, evecs
 
 
-def _ssd_mod(evals, evecs, covs=None):
+def _get_spectral_ratio(ssd_sources, sfreq, n_fft, freqs_signal, freqs_noise):
+    psd, freqs = psd_array_welch(ssd_sources, sfreq=sfreq, n_fft=n_fft)
+    sig_idx = _time_mask(freqs, *freqs_signal)
+    noise_idx = _time_mask(freqs, *freqs_noise)
+    if psd.ndim == 3:
+        mean_sig = psd[:, :, sig_idx].mean(axis=2).mean(axis=0)
+        mean_noise = psd[:, :, noise_idx].mean(axis=2).mean(axis=0)
+        spec_ratio = mean_sig / mean_noise
+    else:
+        mean_sig = psd[:, sig_idx].mean(axis=1)
+        mean_noise = psd[:, noise_idx].mean(axis=1)
+        spec_ratio = mean_sig / mean_noise
+    sorter_spec = spec_ratio.argsort()[::-1]
+    return spec_ratio, sorter_spec
+
+
+def _ssd_mod(
+    evals,
+    evecs,
+    covs,
+    X,
+    picks,
+    sfreq,
+    n_fft,
+    freqs_signal,
+    freqs_noise,
+    sort_by_spectral_ratio,
+):
     evals, evecs = _sort_descending(evals, evecs)
+    if sort_by_spectral_ratio:
+        filters = evecs.T
+        ssd_sources = filters @ X[..., picks, :]
+        _, sorter_spec = _get_spectral_ratio(
+            ssd_sources, sfreq, n_fft, freqs_signal, freqs_noise
+        )
+        evecs = evecs[:, sorter_spec]
+        evals = evals[sorter_spec]
     return evals, evecs
 
 
diff --git a/mne/decoding/base.py b/mne/decoding/base.py
index 18157c758db..c32fc34f17e 100644
--- a/mne/decoding/base.py
+++ b/mne/decoding/base.py
@@ -175,9 +175,15 @@ def fit(self, X, y=None):
     def transform(self, X):
         """..."""
         check_is_fitted(self, "filters_")
-        X = self._check_data(X)
+        X = self._check_data(X, check_n_features=False)
         if self.dec_type == "single":
-            pick_filters = self.filters_[: self.n_components]
+            # XXX: Hack to assert_allclose in SSD's transform.
+            # Will be removed when overhauling ssd.
+            if hasattr(self, "new_filters_"):
+                filters = self.new_filters_
+            else:
+                filters = self.filters_
+            pick_filters = filters[: self.n_components]
         elif self.dec_type == "multi":
             # XXX: Hack to assert_allclose in Xdawn's transform.
             # Will be removed when overhauling xdawn.
diff --git a/mne/decoding/ssd.py b/mne/decoding/ssd.py
index cd49b07c92b..966a8bbca1a 100644
--- a/mne/decoding/ssd.py
+++ b/mne/decoding/ssd.py
@@ -142,9 +142,11 @@ def __init__(
             cov_method_params=cov_method_params,
             info=info,
             picks=picks,
+            n_fft=n_fft,
             filt_params_signal=filt_params_signal,
             filt_params_noise=filt_params_noise,
             rank=rank,
+            sort_by_spectral_ratio=sort_by_spectral_ratio,
         )
         super().__init__(
             n_components=n_components,
@@ -275,18 +277,10 @@ def fit(self, X, y=None):
         self.eigvals_ = eigvals_[ix]
         # project back to sensor space
         self.filters_ = np.matmul(rank_proj, eigvects_[:, ix])
-        self.patterns_ = pinv(self.filters_)
+
         # Need to unify with Xdawn and CSP as they store it as (n_components, n_chs)
         self.filters_ = self.filters_.T
 
-        old_filters = self.filters_
-        old_patterns = self.patterns_
-        super().fit(X, y)
-
-        np.testing.assert_allclose(self.eigvals_, self.evals_)
-        np.testing.assert_allclose(old_filters, self.filters_)
-        np.testing.assert_allclose(old_patterns, self.patterns_)
-
         # We assume that ordering by spectral ratio is more important
         # than the initial ordering. This ordering should be also learned when
         # fitting.
@@ -295,6 +289,21 @@ def fit(self, X, y=None):
         if self.sort_by_spectral_ratio:
             _, sorter_spec = self.get_spectral_ratio(ssd_sources=X_ssd)
         self.sorter_spec_ = sorter_spec
+
+        # When sort_by_spectral_ratio is True,
+        # filters should be stored according the sorting
+        self.filters_ = self.filters_[sorter_spec]
+        self.eigvals_ = self.eigvals_[sorter_spec]
+        self.patterns_ = pinv(self.filters_.T)
+        old_filters = self.filters_
+        old_patterns = self.patterns_
+        super().fit(X, y)
+        self.new_filters_ = self.filters_
+        self.filters_ = old_filters
+        np.testing.assert_allclose(self.eigvals_, self.evals_)
+        np.testing.assert_allclose(old_filters, self.filters_)
+        np.testing.assert_allclose(old_patterns, self.patterns_)
+
         logger.info("Done.")
         return self
 
@@ -315,11 +324,18 @@ def transform(self, X):
         """
         check_is_fitted(self, "filters_")
         X = self._check_X(X)
+        # For the case where n_epochs dimension is absent.
+        if X.ndim == 2:
+            X = np.expand_dims(X, axis=0)
         X_aux = X[..., self.picks_, :]
         if self.return_filtered:
             X_aux = filter_data(X_aux, self.sfreq_, **self.filt_params_signal)
         X_ssd = self.filters_ @ X_aux
-        X_ssd = X_ssd[..., self.sorter_spec_, :][..., : self.n_components, :]
+        X_ssd = X_ssd[..., : self.n_components, :]
+        X_ssd = X_ssd.squeeze()
+        X_ssd_new = super().transform(X_aux).squeeze()
+        np.testing.assert_allclose(X_ssd, X_ssd_new)
+
         return X_ssd
 
     def fit_transform(self, X, y=None, **fit_params):

From 3a0dd1aee881ba5d37f480cf16478022d5e25cf1 Mon Sep 17 00:00:00 2001
From: Genuster <genusterok@gmail.com>
Date: Wed, 25 Jun 2025 13:27:10 +0300
Subject: [PATCH 39/59] add expected failure for sklearn compliance test

---
 mne/decoding/tests/test_ged.py | 10 +++++++++-
 1 file changed, 9 insertions(+), 1 deletion(-)

diff --git a/mne/decoding/tests/test_ged.py b/mne/decoding/tests/test_ged.py
index b97ece68a29..c37042927af 100644
--- a/mne/decoding/tests/test_ged.py
+++ b/mne/decoding/tests/test_ged.py
@@ -135,8 +135,16 @@ def _mock_mod_ged_callable(evals, evecs, covs, **kwargs):
 ged_estimators = [_GEDTransformer(**p) for p in ParameterGrid(param_grid)]
 
 
+def _expected_failures(estimator):
+    return dict(
+        check_n_features_in_after_fitting=(
+            "in case child class modifies X before calling GED's .transform()"
+        )
+    )
+
+
 @pytest.mark.slowtest
-@parametrize_with_checks(ged_estimators)
+@parametrize_with_checks(ged_estimators, expected_failed_checks=_expected_failures)
 def test_sklearn_compliance(estimator, check):
     """Test GEDTransformer compliance with sklearn."""
     check(estimator)

From 29da3fffa61cc204d40ff4da1263b695124ea09e Mon Sep 17 00:00:00 2001
From: Genuster <genusterok@gmail.com>
Date: Thu, 26 Jun 2025 11:30:51 +0300
Subject: [PATCH 40/59] better solution for the previous fix

---
 mne/decoding/base.py           | 25 +++++++++++++++++--------
 mne/decoding/tests/test_ged.py | 10 +---------
 2 files changed, 18 insertions(+), 17 deletions(-)

diff --git a/mne/decoding/base.py b/mne/decoding/base.py
index c32fc34f17e..bc18156c1e0 100644
--- a/mne/decoding/base.py
+++ b/mne/decoding/base.py
@@ -115,15 +115,22 @@ def __init__(
         self.restr_type = restr_type
         self.R_func = R_func
 
+    _is_base_ged = True
+
+    def __init_subclass__(cls, **kwargs):
+        super().__init_subclass__(**kwargs)
+        cls._is_base_ged = False
+
     def fit(self, X, y=None):
         """..."""
-        X, y = self._check_data(
-            X,
-            y=y,
-            fit=True,
-            return_y=True,
-            atleast_3d=False if self.restr_type == "ssd" else True,
-        )
+        # Let the inheriting transformers check data by themselves
+        if self._is_base_ged:
+            X, y = self._check_data(
+                X,
+                y=y,
+                fit=True,
+                return_y=True,
+            )
         self._validate_ged_params()
         covs, C_ref, info, rank, kwargs = self.cov_callable(X, y)
         covs = np.stack(covs)
@@ -175,7 +182,9 @@ def fit(self, X, y=None):
     def transform(self, X):
         """..."""
         check_is_fitted(self, "filters_")
-        X = self._check_data(X, check_n_features=False)
+        # Let the inheriting transformers check data by themselves
+        if self._is_base_ged:
+            X = self._check_data(X)
         if self.dec_type == "single":
             # XXX: Hack to assert_allclose in SSD's transform.
             # Will be removed when overhauling ssd.
diff --git a/mne/decoding/tests/test_ged.py b/mne/decoding/tests/test_ged.py
index c37042927af..b97ece68a29 100644
--- a/mne/decoding/tests/test_ged.py
+++ b/mne/decoding/tests/test_ged.py
@@ -135,16 +135,8 @@ def _mock_mod_ged_callable(evals, evecs, covs, **kwargs):
 ged_estimators = [_GEDTransformer(**p) for p in ParameterGrid(param_grid)]
 
 
-def _expected_failures(estimator):
-    return dict(
-        check_n_features_in_after_fitting=(
-            "in case child class modifies X before calling GED's .transform()"
-        )
-    )
-
-
 @pytest.mark.slowtest
-@parametrize_with_checks(ged_estimators, expected_failed_checks=_expected_failures)
+@parametrize_with_checks(ged_estimators)
 def test_sklearn_compliance(estimator, check):
     """Test GEDTransformer compliance with sklearn."""
     check(estimator)

From 8d1e656555e047db875144932e559fed436a20bc Mon Sep 17 00:00:00 2001
From: Genuster <genusterok@gmail.com>
Date: Fri, 27 Jun 2025 11:44:38 +0300
Subject: [PATCH 41/59] add temporary xfail for windows pip CIs

---
 mne/decoding/tests/test_ssd.py | 17 +++++++++++++++++
 1 file changed, 17 insertions(+)

diff --git a/mne/decoding/tests/test_ssd.py b/mne/decoding/tests/test_ssd.py
index 74337badc7a..0b21bd589b2 100644
--- a/mne/decoding/tests/test_ssd.py
+++ b/mne/decoding/tests/test_ssd.py
@@ -576,4 +576,21 @@ def test_sklearn_compliance(estimator, check):
     )
     if any(ignore in str(check) for ignore in ignores):
         return
+
+    import os
+    import platform
+
+    failing_checks = (
+        "check_readonly_memmap_input",
+        "check_estimators_fit_returns_self",
+        "check_estimators_overwrite_params",
+    )
+
+    if (
+        platform.system() == "Windows"
+        and os.getenv("MNE_CI_KIND", "") == "pip"
+        and check in failing_checks
+    ):
+        pytest.xfail("Broken on Windows pip CIs")
+
     check(estimator)

From 3761ff49e1dd451a3c8a899f1821ddd2d72bfe24 Mon Sep 17 00:00:00 2001
From: Genuster <genusterok@gmail.com>
Date: Fri, 27 Jun 2025 13:17:19 +0300
Subject: [PATCH 42/59] another try

---
 mne/decoding/tests/test_ssd.py | 9 +++------
 1 file changed, 3 insertions(+), 6 deletions(-)

diff --git a/mne/decoding/tests/test_ssd.py b/mne/decoding/tests/test_ssd.py
index 0b21bd589b2..861a92d8e37 100644
--- a/mne/decoding/tests/test_ssd.py
+++ b/mne/decoding/tests/test_ssd.py
@@ -577,9 +577,6 @@ def test_sklearn_compliance(estimator, check):
     if any(ignore in str(check) for ignore in ignores):
         return
 
-    import os
-    import platform
-
     failing_checks = (
         "check_readonly_memmap_input",
         "check_estimators_fit_returns_self",
@@ -587,9 +584,9 @@ def test_sklearn_compliance(estimator, check):
     )
 
     if (
-        platform.system() == "Windows"
-        and os.getenv("MNE_CI_KIND", "") == "pip"
-        and check in failing_checks
+        # platform.system() == "Windows"
+        # and os.getenv("MNE_CI_KIND", "") == "pip"
+        check in failing_checks
     ):
         pytest.xfail("Broken on Windows pip CIs")
 

From 89036643813bbb36df65be42d26acce40f263294 Mon Sep 17 00:00:00 2001
From: Genuster <7503709+Genuster@users.noreply.github.com>
Date: Fri, 27 Jun 2025 16:38:23 +0300
Subject: [PATCH 43/59] and another

---
 mne/decoding/tests/test_ssd.py | 2 +-
 1 file changed, 1 insertion(+), 1 deletion(-)

diff --git a/mne/decoding/tests/test_ssd.py b/mne/decoding/tests/test_ssd.py
index 861a92d8e37..9de607b0584 100644
--- a/mne/decoding/tests/test_ssd.py
+++ b/mne/decoding/tests/test_ssd.py
@@ -586,7 +586,7 @@ def test_sklearn_compliance(estimator, check):
     if (
         # platform.system() == "Windows"
         # and os.getenv("MNE_CI_KIND", "") == "pip"
-        check in failing_checks
+        any(ignore in str(check) for ignore in failing_checks)
     ):
         pytest.xfail("Broken on Windows pip CIs")
 

From 60d7360b2d962c0c6aa6a594f111d87cb1ab74df Mon Sep 17 00:00:00 2001
From: Genuster <genusterok@gmail.com>
Date: Fri, 27 Jun 2025 20:26:06 +0300
Subject: [PATCH 44/59] add sorter return for _mod_ged functions

---
 mne/decoding/_mod_ged.py       | 23 ++++++++++++++---------
 mne/decoding/base.py           | 12 ++++++++----
 mne/decoding/tests/test_ged.py | 16 ++++++++++------
 3 files changed, 32 insertions(+), 19 deletions(-)

diff --git a/mne/decoding/_mod_ged.py b/mne/decoding/_mod_ged.py
index c0cf3eedac5..4372b938242 100644
--- a/mne/decoding/_mod_ged.py
+++ b/mne/decoding/_mod_ged.py
@@ -41,13 +41,14 @@ def _csp_mod(evals, evecs, covs, evecs_order, sample_weights):
     if evals is not None:
         evals = evals[ix]
     evecs = evecs[:, ix]
-    return evals, evecs
+    sorter = ix
+    return evals, evecs, sorter
 
 
 def _xdawn_mod(evals, evecs, covs=None):
-    evals, evecs = _sort_descending(evals, evecs)
+    evals, evecs, sorter = _sort_descending(evals, evecs)
     evecs /= np.linalg.norm(evecs, axis=0)
-    return evals, evecs
+    return evals, evecs, sorter
 
 
 def _get_spectral_ratio(ssd_sources, sfreq, n_fft, freqs_signal, freqs_noise):
@@ -78,8 +79,10 @@ def _ssd_mod(
     freqs_noise,
     sort_by_spectral_ratio,
 ):
-    evals, evecs = _sort_descending(evals, evecs)
+    evals, evecs, sorter = _sort_descending(evals, evecs)
     if sort_by_spectral_ratio:
+        # We assume that ordering by spectral ratio is more important
+        # than the initial ordering.
         filters = evecs.T
         ssd_sources = filters @ X[..., picks, :]
         _, sorter_spec = _get_spectral_ratio(
@@ -87,14 +90,15 @@ def _ssd_mod(
         )
         evecs = evecs[:, sorter_spec]
         evals = evals[sorter_spec]
-    return evals, evecs
+        sorter = sorter_spec
+    return evals, evecs, sorter
 
 
 def _spoc_mod(evals, evecs, covs=None):
     evals = evals.real
     evecs = evecs.real
-    evals, evecs = _sort_descending(evals, evecs, by_abs=True)
-    return evals, evecs
+    evals, evecs, sorter = _sort_descending(evals, evecs, by_abs=True)
+    return evals, evecs, sorter
 
 
 def _sort_descending(evals, evecs, by_abs=False):
@@ -104,8 +108,9 @@ def _sort_descending(evals, evecs, by_abs=False):
         ix = np.argsort(evals)[::-1]
     evals = evals[ix]
     evecs = evecs[:, ix]
-    return evals, evecs
+    sorter = ix
+    return evals, evecs, sorter
 
 
 def _no_op_mod(evals, evecs, *args, **kwargs):
-    return evals, evecs
+    return evals, evecs, None
diff --git a/mne/decoding/base.py b/mne/decoding/base.py
index bc18156c1e0..603cce731f2 100644
--- a/mne/decoding/base.py
+++ b/mne/decoding/base.py
@@ -52,7 +52,8 @@ class _GEDTransformer(MNETransformerMixin, BaseEstimator):
         Function used to modify (e.g. sort or normalize) generalized
         eigenvalues and eigenvectors. It should accept as arguments evals, evecs
         and also covs and optional kwargs returned by cov_callable. It should return
-        only sorted and/or modified evals and evecs. If None, evals and evecs will be
+        sorted and/or modified evals and evecs and the list of indices according
+        to which the first two were sorted. If None, evals and evecs will be
         ordered according to :func:`~scipy.linalg.eigh` default. Defaults to None.
     dec_type : "single" | "multi"
         When "single" and cov_callable returns > 2 covariances,
@@ -154,7 +155,7 @@ def fit(self, X, y=None):
                 restr_mat = _handle_restr_mat(C_ref, self.restr_type, info, rank)
                 evals, evecs = _smart_ged(S, R, restr_mat, R_func=self.R_func)
 
-            evals, evecs = mod_ged_callable(evals, evecs, covs, **kwargs)
+            evals, evecs, self.sorter_ = mod_ged_callable(evals, evecs, covs, **kwargs)
             self.evals_ = evals
             self.filters_ = evecs.T
             self.patterns_ = pinv(evecs)
@@ -163,16 +164,19 @@ def fit(self, X, y=None):
             self.classes_ = np.unique(y)
             R = covs[-1]
             restr_mat = _handle_restr_mat(C_ref, self.restr_type, info, rank)
-            all_evals, all_evecs, all_patterns = list(), list(), list()
+            all_evals, all_evecs = list(), list()
+            all_patterns, all_sorters = list(), list()
             for i in range(len(self.classes_)):
                 S = covs[i]
 
                 evals, evecs = _smart_ged(S, R, restr_mat, R_func=self.R_func)
 
-                evals, evecs = mod_ged_callable(evals, evecs, covs, **kwargs)
+                evals, evecs, sorter = mod_ged_callable(evals, evecs, covs, **kwargs)
                 all_evals.append(evals)
                 all_evecs.append(evecs.T)
                 all_patterns.append(pinv(evecs))
+                all_sorters.append(sorter)
+            self.sorter_ = np.array(all_sorters)
             self.evals_ = np.array(all_evals)
             self.filters_ = np.array(all_evecs)
             self.patterns_ = np.array(all_patterns)
diff --git a/mne/decoding/tests/test_ged.py b/mne/decoding/tests/test_ged.py
index b97ece68a29..a44405bc1c9 100644
--- a/mne/decoding/tests/test_ged.py
+++ b/mne/decoding/tests/test_ged.py
@@ -111,11 +111,13 @@ def _mock_cov_callable(X, y, cov_method_params=None, compute_C_ref=True):
 
 
 def _mock_mod_ged_callable(evals, evecs, covs, **kwargs):
+    sorter = None
     if evals is not None:
         ix = np.argsort(evals)[::-1]
         evals = evals[ix]
         evecs = evecs[:, ix]
-    return evals, evecs
+        sorter = ix
+    return evals, evecs, sorter
 
 
 param_grid = dict(
@@ -175,7 +177,9 @@ def test_ged_binary_cov():
     S, R = covs[0], covs[1]
     restr_mat = _get_restr_mat(C_ref, info, rank)
     evals, evecs = _smart_ged(S, R, restr_mat=restr_mat, R_func=None)
-    actual_evals, actual_evecs = _mock_mod_ged_callable(evals, evecs, [S, R], **kwargs)
+    actual_evals, actual_evecs, sorter = _mock_mod_ged_callable(
+        evals, evecs, [S, R], **kwargs
+    )
     actual_filters = actual_evecs.T
 
     ged = _GEDTransformer(
@@ -196,7 +200,7 @@ def test_ged_binary_cov():
     for i in range(len(covs)):
         S = covs[i]
         evals, evecs = _smart_ged(S, R, restr_mat)
-        evals, evecs = _mock_mod_ged_callable(evals, evecs, covs)
+        evals, evecs, sorter = _mock_mod_ged_callable(evals, evecs, covs)
         all_evals.append(evals)
         all_evecs.append(evecs.T)
     actual_evals = np.array(all_evals)
@@ -226,7 +230,7 @@ def test_ged_multicov():
     restr_mat = _get_restr_mat(C_ref, info, rank)
     evecs = _smart_ajd(covs, restr_mat=restr_mat)
     evals = None
-    _, actual_evecs = _mock_mod_ged_callable(evals, evecs, covs, **kwargs)
+    _, actual_evecs, _ = _mock_mod_ged_callable(evals, evecs, covs, **kwargs)
     actual_filters = actual_evecs.T
 
     ged = _GEDTransformer(
@@ -246,7 +250,7 @@ def test_ged_multicov():
     for i in range(len(covs)):
         S = covs[i]
         evals, evecs = _smart_ged(S, R, restr_mat)
-        evals, evecs = _mock_mod_ged_callable(evals, evecs, covs)
+        evals, evecs, sorter = _mock_mod_ged_callable(evals, evecs, covs)
         all_evals.append(evals)
         all_evecs.append(evecs.T)
     actual_evals = np.array(all_evals)
@@ -273,7 +277,7 @@ def test_ged_multicov():
     covs = np.stack(covs)
     evecs = _smart_ajd(covs, restr_mat=None)
     evals = None
-    _, actual_evecs = _mock_mod_ged_callable(evals, evecs, covs, **kwargs)
+    _, actual_evecs, _ = _mock_mod_ged_callable(evals, evecs, covs, **kwargs)
     actual_filters = actual_evecs.T
 
     ged = _GEDTransformer(

From f8b8d6b8ae17efa776ce7ab9bfb4f67bbebcd566 Mon Sep 17 00:00:00 2001
From: Genuster <genusterok@gmail.com>
Date: Fri, 27 Jun 2025 20:30:57 +0300
Subject: [PATCH 45/59] (1) clean up csp and remove asserts

---
 mne/decoding/csp.py | 192 ++------------------------------------------
 1 file changed, 5 insertions(+), 187 deletions(-)

diff --git a/mne/decoding/csp.py b/mne/decoding/csp.py
index 61de2320efa..5d5138b582b 100644
--- a/mne/decoding/csp.py
+++ b/mne/decoding/csp.py
@@ -8,18 +8,15 @@
 
 import numpy as np
 from scipy.linalg import eigh
-from sklearn.utils.validation import check_is_fitted
 
-from .._fiff.meas_info import Info, create_info
-from ..cov import _compute_rank_raw_array, _regularized_covariance, _smart_eigh
+from .._fiff.meas_info import Info
+from ..cov import _regularized_covariance
 from ..defaults import _BORDER_DEFAULT, _EXTRAPOLATE_DEFAULT, _INTERPOLATION_DEFAULT
 from ..evoked import EvokedArray
 from ..utils import (
     _check_option,
     _validate_type,
-    _verbose_safe_false,
     fill_doc,
-    logger,
     pinv,
 )
 from ._covs_ged import _csp_estimate, _spoc_estimate
@@ -225,27 +222,9 @@ def fit(self, X, y):
         X, y = self._check_data(X, y=y, fit=True, return_y=True)
         self._validate_params(y=y)
 
-        covs, sample_weights = self._compute_covariance_matrices(X, y)
-        eigen_vectors, eigen_values = self._decompose_covs(covs, sample_weights)
-        ix = self._order_components(
-            covs, sample_weights, eigen_vectors, eigen_values, self.component_order
-        )
-
-        eigen_vectors = eigen_vectors[:, ix]
-
-        self.filters_ = eigen_vectors.T
-        self.patterns_ = pinv(eigen_vectors)
-
-        old_filters = self.filters_
-        old_patterns = self.patterns_
+        # Covariance estimation, GED/AJD
+        # and evecs/evals sorting happen here
         super().fit(X, y)
-        # AJD returns evals_ as None.
-        if self.evals_ is None:
-            assert eigen_values is None
-        else:
-            np.testing.assert_allclose(eigen_values[ix], self.evals_)
-        np.testing.assert_allclose(old_filters, self.filters_)
-        np.testing.assert_allclose(old_patterns, self.patterns_)
 
         pick_filters = self.filters_[: self.n_components]
         X = np.asarray([np.dot(pick_filters, epoch) for epoch in X])
@@ -275,13 +254,8 @@ def transform(self, X):
             If self.transform_into == 'csp_space' then returns the data in CSP
             space and shape is (n_epochs, n_components, n_times).
         """
-        check_is_fitted(self, "filters_")
         X = self._check_data(X)
-        orig_X = X.copy()
-        pick_filters = self.filters_[: self.n_components]
-        X = np.asarray([np.dot(pick_filters, epoch) for epoch in X])
-        ged_X = super().transform(orig_X)
-        np.testing.assert_allclose(X, ged_X)
+        X = super().transform(X)
         # compute features (mean band power)
         if self.transform_into == "average_power":
             X = (X**2).mean(axis=2)
@@ -600,162 +574,6 @@ def plot_filters(
         )
         return fig
 
-    def _compute_covariance_matrices(self, X, y):
-        _, n_channels, _ = X.shape
-
-        if self.cov_est == "concat":
-            cov_estimator = self._concat_cov
-        elif self.cov_est == "epoch":
-            cov_estimator = self._epoch_cov
-
-        # Someday we could allow the user to pass this, then we wouldn't need to convert
-        # but in the meantime they can use a pipeline with a scaler
-        self._info = create_info(n_channels, 1000.0, "mag")
-        if isinstance(self.rank, dict):
-            self._rank = {"mag": sum(self.rank.values())}
-        else:
-            self._rank = _compute_rank_raw_array(
-                X.transpose(1, 0, 2).reshape(X.shape[1], -1),
-                self._info,
-                rank=self.rank,
-                scalings=None,
-                log_ch_type="data",
-            )
-
-        covs = []
-        sample_weights = []
-        for ci, this_class in enumerate(self.classes_):
-            cov, weight = cov_estimator(
-                X[y == this_class],
-                cov_kind=f"class={this_class}",
-                log_rank=ci == 0,
-            )
-
-            if self.norm_trace:
-                cov /= np.trace(cov)
-
-            covs.append(cov)
-            sample_weights.append(weight)
-
-        return np.stack(covs), np.array(sample_weights)
-
-    def _concat_cov(self, x_class, *, cov_kind, log_rank):
-        """Concatenate epochs before computing the covariance."""
-        _, n_channels, _ = x_class.shape
-
-        x_class = x_class.transpose(1, 0, 2).reshape(n_channels, -1)
-        cov = _regularized_covariance(
-            x_class,
-            reg=self.reg,
-            method_params=self.cov_method_params,
-            rank=self._rank,
-            info=self._info,
-            cov_kind=cov_kind,
-            log_rank=log_rank,
-            log_ch_type="data",
-        )
-        weight = x_class.shape[0]
-
-        return cov, weight
-
-    def _epoch_cov(self, x_class, *, cov_kind, log_rank):
-        """Mean of per-epoch covariances."""
-        name = self.reg if isinstance(self.reg, str) else "empirical"
-        name += " with shrinkage" if isinstance(self.reg, float) else ""
-        logger.info(
-            f"Estimating {cov_kind + (' ' if cov_kind else '')}"
-            f"covariance (average over epochs; {name.upper()})"
-        )
-        cov = sum(
-            _regularized_covariance(
-                this_X,
-                reg=self.reg,
-                method_params=self.cov_method_params,
-                rank=self._rank,
-                info=self._info,
-                cov_kind=cov_kind,
-                log_rank=log_rank and ii == 0,
-                log_ch_type="data",
-                verbose=_verbose_safe_false(),
-            )
-            for ii, this_X in enumerate(x_class)
-        )
-        cov /= len(x_class)
-        weight = len(x_class)
-
-        return cov, weight
-
-    def _decompose_covs(self, covs, sample_weights):
-        n_classes = len(covs)
-        n_channels = covs[0].shape[0]
-        assert self._rank is not None  # should happen in _compute_covariance_matrices
-        _, sub_vec, mask = _smart_eigh(
-            covs.mean(0),
-            self._info,
-            self._rank,
-            proj_subspace=True,
-            do_compute_rank=False,
-            log_ch_type="data",
-            verbose=_verbose_safe_false(),
-        )
-        sub_vec = sub_vec[mask]
-        covs = np.array([sub_vec @ cov @ sub_vec.T for cov in covs], float)
-        assert covs[0].shape == (mask.sum(),) * 2
-        if n_classes == 2:
-            eigen_values, eigen_vectors = eigh(covs[0], covs.sum(0))
-        else:
-            # The multiclass case is adapted from
-            # http://github.com/alexandrebarachant/pyRiemann
-            eigen_vectors, D = _ajd_pham(covs)
-            eigen_vectors = self._normalize_eigenvectors(
-                eigen_vectors.T, covs, sample_weights
-            )
-            eigen_values = None
-        # project back
-        eigen_vectors = sub_vec.T @ eigen_vectors
-        assert eigen_vectors.shape == (n_channels, mask.sum())
-        return eigen_vectors, eigen_values
-
-    def _compute_mutual_info(self, covs, sample_weights, eigen_vectors):
-        class_probas = sample_weights / sample_weights.sum()
-
-        mutual_info = []
-        for jj in range(eigen_vectors.shape[1]):
-            aa, bb = 0, 0
-            for cov, prob in zip(covs, class_probas):
-                tmp = np.dot(np.dot(eigen_vectors[:, jj].T, cov), eigen_vectors[:, jj])
-                aa += prob * np.log(np.sqrt(tmp))
-                bb += prob * (tmp**2 - 1)
-            mi = -(aa + (3.0 / 16) * (bb**2))
-            mutual_info.append(mi)
-
-        return mutual_info
-
-    def _normalize_eigenvectors(self, eigen_vectors, covs, sample_weights):
-        # Here we apply an euclidean mean. See pyRiemann for other metrics
-        mean_cov = np.average(covs, axis=0, weights=sample_weights)
-
-        for ii in range(eigen_vectors.shape[1]):
-            tmp = np.dot(np.dot(eigen_vectors[:, ii].T, mean_cov), eigen_vectors[:, ii])
-            eigen_vectors[:, ii] /= np.sqrt(tmp)
-        return eigen_vectors
-
-    def _order_components(
-        self, covs, sample_weights, eigen_vectors, eigen_values, component_order
-    ):
-        n_classes = len(self.classes_)
-        if component_order == "mutual_info" and n_classes > 2:
-            mutual_info = self._compute_mutual_info(covs, sample_weights, eigen_vectors)
-            ix = np.argsort(mutual_info)[::-1]
-        elif component_order == "mutual_info" and n_classes == 2:
-            ix = np.argsort(np.abs(eigen_values - 0.5))[::-1]
-        elif component_order == "alternate" and n_classes == 2:
-            i = np.argsort(eigen_values)
-            ix = np.empty_like(i)
-            ix[1::2] = i[: len(i) // 2]
-            ix[0::2] = i[len(i) // 2 :][::-1]
-        return ix
-
 
 def _ajd_pham(X, eps=1e-6, max_iter=15):
     """Approximate joint diagonalization based on Pham's algorithm.

From 10224fc5c38c3e617eb18a7ba80f9c603fb3a468 Mon Sep 17 00:00:00 2001
From: Genuster <genusterok@gmail.com>
Date: Fri, 27 Jun 2025 20:32:33 +0300
Subject: [PATCH 46/59] (2) clean up spoc and remove asserts

---
 mne/decoding/csp.py | 47 ---------------------------------------------
 1 file changed, 47 deletions(-)

diff --git a/mne/decoding/csp.py b/mne/decoding/csp.py
index 5d5138b582b..2d61f2e0094 100644
--- a/mne/decoding/csp.py
+++ b/mne/decoding/csp.py
@@ -7,17 +7,14 @@
 from functools import partial
 
 import numpy as np
-from scipy.linalg import eigh
 
 from .._fiff.meas_info import Info
-from ..cov import _regularized_covariance
 from ..defaults import _BORDER_DEFAULT, _EXTRAPOLATE_DEFAULT, _INTERPOLATION_DEFAULT
 from ..evoked import EvokedArray
 from ..utils import (
     _check_option,
     _validate_type,
     fill_doc,
-    pinv,
 )
 from ._covs_ged import _csp_estimate, _spoc_estimate
 from ._mod_ged import _csp_mod, _spoc_mod
@@ -802,52 +799,8 @@ def fit(self, X, y):
         X, y = self._check_data(X, y=y, fit=True, return_y=True)
         self._validate_params(y=y)
 
-        # The following code is directly copied from pyRiemann
-
-        # Normalize target variable
-        target = y.astype(np.float64)
-        target -= target.mean()
-        target /= target.std()
-
-        n_epochs, n_channels = X.shape[:2]
-
-        # Estimate single trial covariance
-        covs = np.empty((n_epochs, n_channels, n_channels))
-        for ii, epoch in enumerate(X):
-            covs[ii] = _regularized_covariance(
-                epoch,
-                reg=self.reg,
-                method_params=self.cov_method_params,
-                rank=self.rank,
-                log_ch_type="data",
-                log_rank=ii == 0,
-            )
-
-        C = covs.mean(0)
-        Cz = np.mean(covs * target[:, np.newaxis, np.newaxis], axis=0)
-
-        # solve eigenvalue decomposition
-        evals, evecs = eigh(Cz, C)
-        evals = evals.real
-        evecs = evecs.real
-        # sort vectors
-        ix = np.argsort(np.abs(evals))[::-1]
-
-        # sort eigenvectors
-        evecs = evecs[:, ix].T
-
-        # spatial patterns
-        self.patterns_ = pinv(evecs).T  # n_channels x n_channels
-        self.filters_ = evecs  # n_channels x n_channels
-
-        old_filters = self.filters_
-        old_patterns = self.patterns_
         super(CSP, self).fit(X, y)
 
-        np.testing.assert_allclose(evals[ix], self.evals_)
-        np.testing.assert_allclose(old_filters, self.filters_, rtol=1e-6, atol=1e-7)
-        np.testing.assert_allclose(old_patterns, self.patterns_, rtol=1e-6, atol=1e-7)
-
         pick_filters = self.filters_[: self.n_components]
         X = np.asarray([np.dot(pick_filters, epoch) for epoch in X])
 

From ac077f72ece0889a068fe99beac29073f4958747 Mon Sep 17 00:00:00 2001
From: Genuster <genusterok@gmail.com>
Date: Fri, 27 Jun 2025 20:35:40 +0300
Subject: [PATCH 47/59] (3) clean up xdawn, remove asserts and make it store
 all filters and patterns

---
 mne/decoding/base.py                  | 24 +++++----
 mne/decoding/xdawn.py                 | 77 ++++-----------------------
 mne/preprocessing/tests/test_xdawn.py |  7 ++-
 3 files changed, 30 insertions(+), 78 deletions(-)

diff --git a/mne/decoding/base.py b/mne/decoding/base.py
index 603cce731f2..0a2c6b9c24f 100644
--- a/mne/decoding/base.py
+++ b/mne/decoding/base.py
@@ -198,18 +198,24 @@ def transform(self, X):
                 filters = self.filters_
             pick_filters = filters[: self.n_components]
         elif self.dec_type == "multi":
-            # XXX: Hack to assert_allclose in Xdawn's transform.
-            # Will be removed when overhauling xdawn.
-            if hasattr(self, "new_filters_"):
-                filters = self.new_filters_
-            else:
-                filters = self.filters_
-            pick_filters = filters[:, : self.n_components, :].reshape(
-                -1, filters.shape[2]
-            )
+            pick_filters = self._subset_multi_components()
         X = pick_filters @ X
         return X
 
+    def _subset_multi_components(self, name="filters"):
+        # The shape of stored filters and patterns is
+        # is (n_classes, n_evecs, n_chs)
+        # Transform and subset into (n_classes*n_components, n_chs)
+        if name == "filters":
+            return self.filters_[:, : self.n_components, :].reshape(
+                -1, self.filters_.shape[2]
+            )
+        elif name == "patterns":
+            return self.patterns_[:, : self.n_components, :].reshape(
+                -1, self.patterns_.shape[2]
+            )
+        return None
+
     def _validate_required_args(self, func, desired_required_args):
         sig = signature(func)
         actual_required_args = [
diff --git a/mne/decoding/xdawn.py b/mne/decoding/xdawn.py
index 8f5a11bec8e..fd4b3965589 100644
--- a/mne/decoding/xdawn.py
+++ b/mne/decoding/xdawn.py
@@ -146,43 +146,13 @@ def fit(self, X, y=None):
         self : Xdawn instance
             The Xdawn instance.
         """
-        from ..preprocessing.xdawn import _fit_xdawn
-
-        X, y = self._check_Xy(X, y)
+        X, y = self._check_data(X, y=y, fit=True, return_y=True)
+        # For test purposes
+        if y is None:
+            y = np.ones(len(X))
         self._validate_params(X)
-        # Main function
-        self.classes_ = np.unique(y)
-        self.filters_, self.patterns_, _ = _fit_xdawn(
-            X,
-            y,
-            n_components=self.n_components,
-            reg=self.reg,
-            signal_cov=self.signal_cov,
-            method_params=self.cov_method_params,
-        )
-        old_filters = self.filters_
-        old_patterns = self.patterns_
-        super().fit(X, y)
 
-        # Hack for assert_allclose in transform
-        self.new_filters_ = self.filters_.copy()
-        # Xdawn performs separate GED for each class.
-        # filters_ returned by _fit_xdawn are subset per
-        # n_components and then appended and are of shape
-        # (n_classes*n_components, n_chs).
-        # GEDTransformer creates new dimension per class without subsetting
-        # for easier analysis and visualisations.
-        # So it needs to be performed post-hoc to conform with Xdawn.
-        # The shape returned by GED here is (n_classes, n_evecs, n_chs)
-        # Need to transform and subset into (n_classes*n_components, n_chs)
-        self.filters_ = self.filters_[:, : self.n_components, :].reshape(
-            -1, self.filters_.shape[2]
-        )
-        self.patterns_ = self.patterns_[:, : self.n_components, :].reshape(
-            -1, self.patterns_.shape[2]
-        )
-        np.testing.assert_allclose(old_filters, self.filters_)
-        np.testing.assert_allclose(old_patterns, self.patterns_)
+        super().fit(X, y)
 
         return self
 
@@ -199,21 +169,8 @@ def transform(self, X):
         X : array, shape (n_epochs, n_components * n_classes, n_samples)
             The transformed data.
         """
-        X, _ = self._check_Xy(X)
-        orig_X = X.copy()
-
-        # Check size
-        if self.filters_.shape[1] != X.shape[1]:
-            raise ValueError(
-                f"X must have {self.filters_.shape[1]} channels, got {X.shape[1]} "
-                "instead."
-            )
-
-        # Transform
-        X = np.dot(self.filters_, X)
-        X = X.transpose((1, 0, 2))
-        ged_X = super().transform(orig_X)
-        np.testing.assert_allclose(X, ged_X)
+        X = self._check_data(X)
+        X = super().transform(X)
         return X
 
     def inverse_transform(self, X):
@@ -235,27 +192,13 @@ def inverse_transform(self, X):
             The inverse transform data.
         """
         # Check size
-        X, _ = self._check_Xy(X)
+        X = self._check_data(X, check_n_features=False)
         n_epochs, n_comp, n_times = X.shape
         if n_comp != (self.n_components * len(self.classes_)):
             raise ValueError(
                 f"X must have {self.n_components * len(self.classes_)} components, "
                 f"got {n_comp} instead."
             )
-
+        pick_patterns = self._subset_multi_components(name="patterns")
         # Transform
-        return np.dot(self.patterns_.T, X).transpose(1, 0, 2)
-
-    def _check_Xy(self, X, y=None):
-        """Check X and y types and dimensions."""
-        # Check data
-        if not isinstance(X, np.ndarray) or X.ndim != 3:
-            raise ValueError(
-                "X must be an array of shape (n_epochs, n_channels, n_samples)."
-            )
-        if y is None:
-            y = np.ones(len(X))
-        y = np.asarray(y)
-        if len(X) != len(y):
-            raise ValueError("X and y must have the same length")
-        return X, y
+        return np.dot(pick_patterns.T, X).transpose(1, 0, 2)
diff --git a/mne/preprocessing/tests/test_xdawn.py b/mne/preprocessing/tests/test_xdawn.py
index a233695795f..47585112ba3 100644
--- a/mne/preprocessing/tests/test_xdawn.py
+++ b/mne/preprocessing/tests/test_xdawn.py
@@ -288,8 +288,10 @@ def test_XdawnTransformer():
 
     xdt = XdawnTransformer()
     xdt.fit(X, y)
+    # Subset filters
+    xdt_filters = xdt._subset_multi_components()
     assert_array_almost_equal(
-        xd.filters_["cond2"][:2, :], xdt.filters_.reshape(2, 2, 8)[0]
+        xd.filters_["cond2"][:2, :], xdt_filters.reshape(2, 2, 8)[0]
     )
 
     # Transform testing
@@ -398,7 +400,8 @@ def test_xdawn_decoding_performance():
                 [comps[[0]] for comps in fitted_xdawn.patterns_.values()]
             )
         else:
-            relev_patterns = fitted_xdawn.patterns_[::n_xdawn_comps]
+            pick_patterns = fitted_xdawn._subset_multi_components(name="patterns")
+            relev_patterns = pick_patterns[::n_xdawn_comps]
 
         for i in range(len(relev_patterns)):
             r, _ = stats.pearsonr(relev_patterns[i, :], mixing_mat[0, :])

From e23448cd5c552aa0adebc765e8fc75b7fd84a062 Mon Sep 17 00:00:00 2001
From: Genuster <genusterok@gmail.com>
Date: Fri, 27 Jun 2025 20:44:34 +0300
Subject: [PATCH 48/59] (4) clean up ssd and remove asserts

---
 mne/decoding/_mod_ged.py       |  16 +++
 mne/decoding/base.py           |   8 +-
 mne/decoding/ssd.py            | 179 +--------------------------------
 mne/decoding/tests/test_ssd.py |  44 ++++----
 4 files changed, 44 insertions(+), 203 deletions(-)

diff --git a/mne/decoding/_mod_ged.py b/mne/decoding/_mod_ged.py
index 4372b938242..df917a78ae3 100644
--- a/mne/decoding/_mod_ged.py
+++ b/mne/decoding/_mod_ged.py
@@ -52,6 +52,22 @@ def _xdawn_mod(evals, evecs, covs=None):
 
 
 def _get_spectral_ratio(ssd_sources, sfreq, n_fft, freqs_signal, freqs_noise):
+    """Get the spectal signal-to-noise ratio for each spatial filter.
+
+    Spectral ratio measure for best n_components selection
+    See :footcite:`NikulinEtAl2011`, Eq. (24).
+
+    Returns
+    -------
+    spec_ratio : array, shape (n_channels)
+        Array with the sprectal ratio value for each component.
+    sorter_spec : array, shape (n_channels)
+        Array of indices for sorting spec_ratio.
+
+    References
+    ----------
+    .. footbibliography::
+    """
     psd, freqs = psd_array_welch(ssd_sources, sfreq=sfreq, n_fft=n_fft)
     sig_idx = _time_mask(freqs, *freqs_signal)
     noise_idx = _time_mask(freqs, *freqs_noise)
diff --git a/mne/decoding/base.py b/mne/decoding/base.py
index 0a2c6b9c24f..850df05b2d0 100644
--- a/mne/decoding/base.py
+++ b/mne/decoding/base.py
@@ -190,13 +190,7 @@ def transform(self, X):
         if self._is_base_ged:
             X = self._check_data(X)
         if self.dec_type == "single":
-            # XXX: Hack to assert_allclose in SSD's transform.
-            # Will be removed when overhauling ssd.
-            if hasattr(self, "new_filters_"):
-                filters = self.new_filters_
-            else:
-                filters = self.filters_
-            pick_filters = filters[: self.n_components]
+            pick_filters = self.filters_[: self.n_components]
         elif self.dec_type == "multi":
             pick_filters = self._subset_multi_components()
         X = pick_filters @ X
diff --git a/mne/decoding/ssd.py b/mne/decoding/ssd.py
index 966a8bbca1a..11d4cdbc3bd 100644
--- a/mne/decoding/ssd.py
+++ b/mne/decoding/ssd.py
@@ -6,23 +6,14 @@
 from functools import partial
 
 import numpy as np
-from scipy.linalg import eigh
-from sklearn.utils.validation import check_is_fitted
 
 from .._fiff.meas_info import Info, create_info
-from .._fiff.pick import _picks_to_idx, pick_info
-from ..cov import Covariance, _regularized_covariance
-from ..defaults import _handle_default
+from .._fiff.pick import _picks_to_idx
 from ..filter import filter_data
-from ..rank import compute_rank
-from ..time_frequency import psd_array_welch
 from ..utils import (
-    _time_mask,
     _validate_type,
-    _verbose_safe_false,
     fill_doc,
     logger,
-    pinv,
 )
 from ._covs_ged import _ssd_estimate
 from ._mod_ged import _ssd_mod
@@ -240,69 +231,8 @@ def fit(self, X, y=None):
         else:
             info = create_info(X.shape[-2], self.sfreq_, ch_types="eeg")
         self.picks_ = _picks_to_idx(info, self.picks, none="data", exclude="bads")
-        X_aux = X[..., self.picks_, :]
-
-        X_signal = filter_data(X_aux, self.sfreq_, **self.filt_params_signal)
-        X_noise = filter_data(X_aux, self.sfreq_, **self.filt_params_noise)
-        X_noise -= X_signal
-        if X.ndim == 3:
-            X_signal = np.hstack(X_signal)
-            X_noise = np.hstack(X_noise)
-
-        # prevent rank change when computing cov with rank='full'
-        picked_info = pick_info(info, self.picks_)
-        cov_signal = _regularized_covariance(
-            X_signal,
-            reg=self.reg,
-            method_params=self.cov_method_params,
-            rank="full",
-            info=picked_info,
-        )
-        cov_noise = _regularized_covariance(
-            X_noise,
-            reg=self.reg,
-            method_params=self.cov_method_params,
-            rank="full",
-            info=picked_info,
-        )
-
-        # project cov to rank subspace
-        cov_signal, cov_noise, rank_proj = _dimensionality_reduction(
-            cov_signal, cov_noise, picked_info, self.rank
-        )
 
-        eigvals_, eigvects_ = eigh(cov_signal, cov_noise)
-        # sort in descending order
-        ix = np.argsort(eigvals_)[::-1]
-        self.eigvals_ = eigvals_[ix]
-        # project back to sensor space
-        self.filters_ = np.matmul(rank_proj, eigvects_[:, ix])
-
-        # Need to unify with Xdawn and CSP as they store it as (n_components, n_chs)
-        self.filters_ = self.filters_.T
-
-        # We assume that ordering by spectral ratio is more important
-        # than the initial ordering. This ordering should be also learned when
-        # fitting.
-        X_ssd = self.filters_ @ X[..., self.picks_, :]
-        sorter_spec = slice(None)
-        if self.sort_by_spectral_ratio:
-            _, sorter_spec = self.get_spectral_ratio(ssd_sources=X_ssd)
-        self.sorter_spec_ = sorter_spec
-
-        # When sort_by_spectral_ratio is True,
-        # filters should be stored according the sorting
-        self.filters_ = self.filters_[sorter_spec]
-        self.eigvals_ = self.eigvals_[sorter_spec]
-        self.patterns_ = pinv(self.filters_.T)
-        old_filters = self.filters_
-        old_patterns = self.patterns_
         super().fit(X, y)
-        self.new_filters_ = self.filters_
-        self.filters_ = old_filters
-        np.testing.assert_allclose(self.eigvals_, self.evals_)
-        np.testing.assert_allclose(old_filters, self.filters_)
-        np.testing.assert_allclose(old_patterns, self.patterns_)
 
         logger.info("Done.")
         return self
@@ -322,7 +252,6 @@ def transform(self, X):
         X_ssd : array, shape ([n_epochs, ]n_components, n_times)
             The processed data.
         """
-        check_is_fitted(self, "filters_")
         X = self._check_X(X)
         # For the case where n_epochs dimension is absent.
         if X.ndim == 2:
@@ -330,11 +259,7 @@ def transform(self, X):
         X_aux = X[..., self.picks_, :]
         if self.return_filtered:
             X_aux = filter_data(X_aux, self.sfreq_, **self.filt_params_signal)
-        X_ssd = self.filters_ @ X_aux
-        X_ssd = X_ssd[..., : self.n_components, :]
-        X_ssd = X_ssd.squeeze()
-        X_ssd_new = super().transform(X_aux).squeeze()
-        np.testing.assert_allclose(X_ssd, X_ssd_new)
+        X_ssd = super().transform(X_aux).squeeze()
 
         return X_ssd
 
@@ -363,42 +288,6 @@ def fit_transform(self, X, y=None, **fit_params):
         # use parent TransformerMixin method but with custom docstring
         return super().fit_transform(X, y=y, **fit_params)
 
-    def get_spectral_ratio(self, ssd_sources):
-        """Get the spectal signal-to-noise ratio for each spatial filter.
-
-        Spectral ratio measure for best n_components selection
-        See :footcite:`NikulinEtAl2011`, Eq. (24).
-
-        Parameters
-        ----------
-        ssd_sources : array
-            Data projected to SSD space.
-
-        Returns
-        -------
-        spec_ratio : array, shape (n_channels)
-            Array with the sprectal ratio value for each component.
-        sorter_spec : array, shape (n_channels)
-            Array of indices for sorting spec_ratio.
-
-        References
-        ----------
-        .. footbibliography::
-        """
-        psd, freqs = psd_array_welch(ssd_sources, sfreq=self.sfreq_, n_fft=self.n_fft_)
-        sig_idx = _time_mask(freqs, *self.freqs_signal_)
-        noise_idx = _time_mask(freqs, *self.freqs_noise_)
-        if psd.ndim == 3:
-            mean_sig = psd[:, :, sig_idx].mean(axis=2).mean(axis=0)
-            mean_noise = psd[:, :, noise_idx].mean(axis=2).mean(axis=0)
-            spec_ratio = mean_sig / mean_noise
-        else:
-            mean_sig = psd[:, sig_idx].mean(axis=1)
-            mean_noise = psd[:, noise_idx].mean(axis=1)
-            spec_ratio = mean_sig / mean_noise
-        sorter_spec = spec_ratio.argsort()[::-1]
-        return spec_ratio, sorter_spec
-
     def inverse_transform(self):
         """Not implemented yet."""
         raise NotImplementedError("inverse_transform is not yet available.")
@@ -427,68 +316,6 @@ def apply(self, X):
             The processed data.
         """
         X_ssd = self.transform(X)
-        pick_patterns = self.patterns_[self.sorter_spec_][: self.n_components].T
+        pick_patterns = self.patterns_[: self.n_components].T
         X = pick_patterns @ X_ssd
         return X
-
-
-def _dimensionality_reduction(cov_signal, cov_noise, info, rank):
-    """Perform dimensionality reduction on the covariance matrices."""
-    n_channels = cov_signal.shape[0]
-
-    # find ranks of covariance matrices
-    rank_signal = list(
-        compute_rank(
-            Covariance(
-                cov_signal,
-                info.ch_names,
-                list(),
-                list(),
-                0,
-                verbose=_verbose_safe_false(),
-            ),
-            rank,
-            _handle_default("scalings_cov_rank", None),
-            info,
-        ).values()
-    )[0]
-    rank_noise = list(
-        compute_rank(
-            Covariance(
-                cov_noise,
-                info.ch_names,
-                list(),
-                list(),
-                0,
-                verbose=_verbose_safe_false(),
-            ),
-            rank,
-            _handle_default("scalings_cov_rank", None),
-            info,
-        ).values()
-    )[0]
-    rank = np.min([rank_signal, rank_noise])  # should be identical
-
-    if rank < n_channels:
-        eigvals, eigvects = eigh(cov_signal)
-        # sort in descending order
-        ix = np.argsort(eigvals)[::-1]
-        eigvals = eigvals[ix]
-        eigvects = eigvects[:, ix]
-        # compute rank subspace projection matrix
-        rank_proj = np.matmul(
-            eigvects[:, :rank], np.eye(rank) * (eigvals[:rank] ** -0.5)
-        )
-        logger.info(
-            "Projecting covariance of %i channels to %i rank subspace",
-            n_channels,
-            rank,
-        )
-    else:
-        rank_proj = np.eye(n_channels)
-        logger.info("Preserving covariance rank (%i)", rank)
-
-    # project covariance matrices to rank subspace
-    cov_signal = rank_proj.T @ cov_signal @ rank_proj
-    cov_noise = rank_proj.T @ cov_noise @ rank_proj
-    return cov_signal, cov_noise, rank_proj
diff --git a/mne/decoding/tests/test_ssd.py b/mne/decoding/tests/test_ssd.py
index 9de607b0584..4daecf06459 100644
--- a/mne/decoding/tests/test_ssd.py
+++ b/mne/decoding/tests/test_ssd.py
@@ -17,6 +17,7 @@
 from mne import Epochs, create_info, io, pick_types, read_events
 from mne._fiff.pick import _picks_to_idx
 from mne.decoding import CSP
+from mne.decoding._mod_ged import _get_spectral_ratio
 from mne.decoding.ssd import SSD
 from mne.filter import filter_data
 from mne.time_frequency import psd_array_welch
@@ -228,7 +229,9 @@ def test_ssd():
         sort_by_spectral_ratio=False,
     )
     ssd.fit(X)
-    spec_ratio, sorter_spec = ssd.get_spectral_ratio(ssd.transform(X))
+    spec_ratio, sorter_spec = _get_spectral_ratio(
+        ssd.transform(X), ssd.sfreq_, ssd.n_fft_, ssd.freqs_signal_, ssd.freqs_noise_
+    )
     # since we now that the number of true components is 5, the relative
     # difference should be low for the first 5 components and then increases
     index_diff = np.argmax(-np.diff(spec_ratio))
@@ -311,8 +314,16 @@ def test_ssd_epoched_data():
     ssd.fit(X)
 
     # Check if the 5 first 5 components are the same for both
-    _, sorter_spec_e = ssd_e.get_spectral_ratio(ssd_e.transform(X_e))
-    _, sorter_spec = ssd.get_spectral_ratio(ssd.transform(X))
+    _, sorter_spec_e = _get_spectral_ratio(
+        ssd_e.transform(X_e),
+        ssd_e.sfreq_,
+        ssd_e.n_fft_,
+        ssd_e.freqs_signal_,
+        ssd_e.freqs_noise_,
+    )
+    _, sorter_spec = _get_spectral_ratio(
+        ssd.transform(X), ssd.sfreq_, ssd.n_fft_, ssd.freqs_signal_, ssd.freqs_noise_
+    )
     assert_array_equal(
         sorter_spec_e[:n_components_true], sorter_spec[:n_components_true]
     )
@@ -383,8 +394,12 @@ def test_sorting():
         sort_by_spectral_ratio=False,
     )
     ssd.fit(Xtr)
-    _, sorter_tr = ssd.get_spectral_ratio(ssd.transform(Xtr))
-    _, sorter_te = ssd.get_spectral_ratio(ssd.transform(Xte))
+    _, sorter_tr = _get_spectral_ratio(
+        ssd.transform(Xtr), ssd.sfreq_, ssd.n_fft_, ssd.freqs_signal_, ssd.freqs_noise_
+    )
+    _, sorter_te = _get_spectral_ratio(
+        ssd.transform(Xte), ssd.sfreq_, ssd.n_fft_, ssd.freqs_signal_, ssd.freqs_noise_
+    )
     assert any(sorter_tr != sorter_te)
 
     # check sort_by_spectral_ratio set to True
@@ -398,7 +413,7 @@ def test_sorting():
     ssd.fit(Xtr)
 
     # check sorters
-    sorter_in = ssd.sorter_spec_
+    sorter_in = ssd.sorter_
     ssd = SSD(
         info,
         filt_params_signal,
@@ -407,7 +422,9 @@ def test_sorting():
         sort_by_spectral_ratio=False,
     )
     ssd.fit(Xtr)
-    _, sorter_out = ssd.get_spectral_ratio(ssd.transform(Xtr))
+    _, sorter_out = _get_spectral_ratio(
+        ssd.transform(Xtr), ssd.sfreq_, ssd.n_fft_, ssd.freqs_signal_, ssd.freqs_noise_
+    )
 
     assert all(sorter_in == sorter_out)
 
@@ -577,17 +594,4 @@ def test_sklearn_compliance(estimator, check):
     if any(ignore in str(check) for ignore in ignores):
         return
 
-    failing_checks = (
-        "check_readonly_memmap_input",
-        "check_estimators_fit_returns_self",
-        "check_estimators_overwrite_params",
-    )
-
-    if (
-        # platform.system() == "Windows"
-        # and os.getenv("MNE_CI_KIND", "") == "pip"
-        any(ignore in str(check) for ignore in failing_checks)
-    ):
-        pytest.xfail("Broken on Windows pip CIs")
-
     check(estimator)

From 5c612cbadf0b37ca5779c69cb2f4f97a9be154bd Mon Sep 17 00:00:00 2001
From: Genuster <genusterok@gmail.com>
Date: Fri, 4 Jul 2025 18:44:09 +0300
Subject: [PATCH 49/59] more tests

---
 mne/decoding/tests/test_ged.py | 40 ++++++++++++++++++++++++++++++++++
 1 file changed, 40 insertions(+)

diff --git a/mne/decoding/tests/test_ged.py b/mne/decoding/tests/test_ged.py
index a44405bc1c9..5f413f81aee 100644
--- a/mne/decoding/tests/test_ged.py
+++ b/mne/decoding/tests/test_ged.py
@@ -26,6 +26,7 @@
     _smart_ajd,
     _smart_ged,
 )
+from mne.decoding._mod_ged import _no_op_mod
 from mne.decoding.base import _GEDTransformer
 from mne.io import read_raw
 
@@ -220,6 +221,8 @@ def test_ged_binary_cov():
     assert_allclose(actual_evals, desired_evals)
     assert_allclose(actual_filters, desired_filters)
 
+    assert ged._subset_multi_components(name="foo") is None
+
 
 def test_ged_multicov():
     """Test GEDTransformer on audvis dataset with multiple covariances."""
@@ -294,6 +297,33 @@ def test_ged_multicov():
     assert_allclose(actual_filters, desired_filters)
 
 
+def test_ged_validation_raises():
+    """Test GEDTransofmer validation raises correct errors."""
+    event_id = dict(aud_l=1, vis_l=3)
+    X, y = _get_X_y(event_id)
+
+    ged = _GEDTransformer(
+        n_components=-1,
+        cov_callable=_mock_cov_callable,
+        mod_ged_callable=_mock_mod_ged_callable,
+        restr_type="restricting",
+    )
+    with pytest.raises(ValueError):
+        ged.fit(X, y)
+
+    def _bad_cov_callable(X, y, foo):
+        return X, y, foo
+
+    ged = _GEDTransformer(
+        n_components=1,
+        cov_callable=_bad_cov_callable,
+        mod_ged_callable=_mock_mod_ged_callable,
+        restr_type="restricting",
+    )
+    with pytest.raises(ValueError):
+        ged.fit(X, y)
+
+
 def test_ged_invalid_cov():
     """Test _validate_covariances raises proper errors."""
     ged = _GEDTransformer(
@@ -346,3 +376,13 @@ def test__smart_ajd_when_restr_mat_is_none():
     bad_covs = np.stack([sing_pos_semidef, pos_def1, pos_def2])
     with pytest.raises(ValueError, match="positive definite"):
         _smart_ajd(bad_covs, restr_mat=None, weights=None)
+
+
+def test__no_op_mod():
+    """Test _no_op_mod returns the same evals/evecs objects."""
+    evals = np.array([[1, 2], [3, 4]])
+    evecs = np.array([0, 1])
+    evals_no_op, evecs_no_op, sorter_no_op = _no_op_mod(evals, evecs)
+    assert evals is evals_no_op
+    assert evecs is evecs_no_op
+    assert sorter_no_op is None

From 3c782b3579348368b23c8d1abe42bc2bc7408f8c Mon Sep 17 00:00:00 2001
From: Genuster <genusterok@gmail.com>
Date: Fri, 4 Jul 2025 18:55:15 +0300
Subject: [PATCH 50/59] replace ssd's old whitening with compute_whitener

---
 mne/decoding/_covs_ged.py |  3 ++-
 mne/decoding/_ged.py      | 35 +++++------------------------------
 mne/decoding/base.py      |  6 ++----
 mne/decoding/ssd.py       |  2 +-
 4 files changed, 10 insertions(+), 36 deletions(-)

diff --git a/mne/decoding/_covs_ged.py b/mne/decoding/_covs_ged.py
index 08a455b91c1..074b4c15625 100644
--- a/mne/decoding/_covs_ged.py
+++ b/mne/decoding/_covs_ged.py
@@ -242,7 +242,8 @@ def _ssd_estimate(
         freqs_noise=freqs_noise,
         sort_by_spectral_ratio=sort_by_spectral_ratio,
     )
-
+    rank = dict(eeg=rank)
+    info = picked_info
     return covs, C_ref, info, rank, kwargs
 
 
diff --git a/mne/decoding/_ged.py b/mne/decoding/_ged.py
index 3ab1a7a0aed..c50b8d101e0 100644
--- a/mne/decoding/_ged.py
+++ b/mne/decoding/_ged.py
@@ -6,7 +6,6 @@
 import scipy.linalg
 
 from ..cov import Covariance, _smart_eigh, compute_whitener
-from ..utils import logger
 
 
 def _handle_restr_mat(C_ref, restr_type, info, rank):
@@ -19,14 +18,15 @@ def _handle_restr_mat(C_ref, restr_type, info, rank):
         return None
     if restr_type == "whitening":
         C_ref_cov = Covariance(C_ref, info.ch_names, info["bads"], info["projs"], 0)
-        restr_mat = compute_whitener(C_ref_cov, info, rank=rank, pca=True)[0]
-    elif restr_type == "ssd":
-        restr_mat = _get_ssd_whitener(C_ref, rank)
+        restr_mat = compute_whitener(
+            C_ref_cov, info, rank=rank, pca=True, verbose="error"
+        )[0]
     elif restr_type == "restricting":
         restr_mat = _get_restr_mat(C_ref, info, rank)
     else:
         raise ValueError(
-            "restr_type should either be callable or one of whitening, ssd, restricting"
+            "restr_type should either be callable or one of "
+            "('whitening', 'restricting')"
         )
     return restr_mat
 
@@ -129,28 +129,3 @@ def _normalize_eigenvectors(evecs, covs, sample_weights):
         tmp = np.dot(np.dot(evecs[:, ii].T, mean_cov), evecs[:, ii])
         evecs[:, ii] /= np.sqrt(tmp)
     return evecs
-
-
-def _get_ssd_whitener(S, rank):
-    """Perform dimensionality reduction on the covariance matrices."""
-    n_channels = S.shape[0]
-    if rank < n_channels:
-        eigvals, eigvects = scipy.linalg.eigh(S)
-        # sort in descending order
-        ix = np.argsort(eigvals)[::-1]
-        eigvals = eigvals[ix]
-        eigvects = eigvects[:, ix]
-        # compute rank subspace projection matrix
-        rank_proj = np.matmul(
-            eigvects[:, :rank], np.eye(rank) * (eigvals[:rank] ** -0.5)
-        )
-        logger.info(
-            "Projecting covariance of %i channels to %i rank subspace",
-            n_channels,
-            rank,
-        )
-    else:
-        rank_proj = np.eye(n_channels)
-        logger.info("Preserving covariance rank (%i)", rank)
-
-    return rank_proj.T
diff --git a/mne/decoding/base.py b/mne/decoding/base.py
index 850df05b2d0..c2a30702429 100644
--- a/mne/decoding/base.py
+++ b/mne/decoding/base.py
@@ -63,14 +63,12 @@ class _GEDTransformer(MNETransformerMixin, BaseEstimator):
         (except the last) returned by cov_callable is decomposed with the last
         covariance. In this case, number of covariances should be number of classes + 1.
         Defaults to "single".
-    restr_type : "restricting" | "whitening" | "ssd" | None
+    restr_type : "restricting" | "whitening" | None
         Restricting transformation for covariance matrices before performing GED.
         If "restricting" only restriction to the principal subspace of the C_ref
         will be performed.
         If "whitening", covariance matrices will be additionally rescaled according
         to the whitening for the C_ref.
-        If "ssd", perform simplified version of "whitening",
-        preserved for compatibility.
         If None, no restriction will be applied. Defaults to None.
     R_func : callable | None
         If provided, GED will be performed on (S, R_func([S,R])). When dec_type is
@@ -250,7 +248,7 @@ def _validate_ged_params(self):
         _check_option(
             "restr_type",
             self.restr_type,
-            ("restricting", "whitening", "ssd", None),
+            ("restricting", "whitening", None),
         )
 
     def _validate_covariances(self, covs):
diff --git a/mne/decoding/ssd.py b/mne/decoding/ssd.py
index 11d4cdbc3bd..23cc34a9865 100644
--- a/mne/decoding/ssd.py
+++ b/mne/decoding/ssd.py
@@ -110,7 +110,7 @@ def __init__(
         return_filtered=False,
         n_fft=None,
         cov_method_params=None,
-        restr_type="ssd",
+        restr_type="whitening",
         rank=None,
     ):
         """Initialize instance."""

From 75229101ddf874995a49943d214e33f923b6a896 Mon Sep 17 00:00:00 2001
From: Genuster <genusterok@gmail.com>
Date: Fri, 4 Jul 2025 20:32:32 +0300
Subject: [PATCH 51/59] make XdawnTransformer properly public

---
 doc/api/decoding.rst      | 1 +
 mne/decoding/__init__.pyi | 2 ++
 2 files changed, 3 insertions(+)

diff --git a/doc/api/decoding.rst b/doc/api/decoding.rst
index c844afc470a..788a62b42da 100644
--- a/doc/api/decoding.rst
+++ b/doc/api/decoding.rst
@@ -29,6 +29,7 @@ Decoding
    GeneralizingEstimator
    SPoC
    SSD
+   XdawnTransformer
 
 Functions that assist with decoding and model fitting:
 
diff --git a/mne/decoding/__init__.pyi b/mne/decoding/__init__.pyi
index 2b6c89b2140..6a1e7d8ab89 100644
--- a/mne/decoding/__init__.pyi
+++ b/mne/decoding/__init__.pyi
@@ -17,6 +17,7 @@ __all__ = [
     "TransformerMixin",
     "UnsupervisedSpatialFilter",
     "Vectorizer",
+    "XdawnTransformer",
     "compute_ems",
     "cross_val_multiscore",
     "get_coef",
@@ -43,3 +44,4 @@ from .transformer import (
     UnsupervisedSpatialFilter,
     Vectorizer,
 )
+from .xdawn import XdawnTransformer

From a57934b3027c708ebbc4c23e39af10233d9fa244 Mon Sep 17 00:00:00 2001
From: Genuster <genusterok@gmail.com>
Date: Fri, 4 Jul 2025 20:32:57 +0300
Subject: [PATCH 52/59]  add changelog entry

---
 doc/changes/devel/13259.newfeature.rst | 3 +++
 1 file changed, 3 insertions(+)
 create mode 100644 doc/changes/devel/13259.newfeature.rst

diff --git a/doc/changes/devel/13259.newfeature.rst b/doc/changes/devel/13259.newfeature.rst
new file mode 100644
index 00000000000..d510015e26f
--- /dev/null
+++ b/doc/changes/devel/13259.newfeature.rst
@@ -0,0 +1,3 @@
+Implement GEDTransformer superclass that generalizes 
+:class:`mne.decoding.CSP`, :class:`mne.decoding.SPoC`, :class:`mne.decoding.XdawnTransformer`, 
+:class:`mne.decoding.SSD` and fix related bugs and inconsistencies, by `Gennadiy Belonosov`_.
\ No newline at end of file

From 7951a439fcf992cec62fac604dfd40021f748337 Mon Sep 17 00:00:00 2001
From: Genuster <genusterok@gmail.com>
Date: Fri, 4 Jul 2025 23:39:42 +0300
Subject: [PATCH 53/59] fix xdawntransformer docstring

---
 mne/decoding/xdawn.py | 6 +++---
 1 file changed, 3 insertions(+), 3 deletions(-)

diff --git a/mne/decoding/xdawn.py b/mne/decoding/xdawn.py
index fd4b3965589..aeb09aedb60 100644
--- a/mne/decoding/xdawn.py
+++ b/mne/decoding/xdawn.py
@@ -12,9 +12,10 @@
 from ..decoding._covs_ged import _xdawn_estimate
 from ..decoding._mod_ged import _xdawn_mod
 from ..decoding.base import _GEDTransformer
-from ..utils import _validate_type
+from ..utils import _validate_type, fill_doc
 
 
+@fill_doc
 class XdawnTransformer(_GEDTransformer):
     """Implementation of the Xdawn Algorithm compatible with scikit-learn.
 
@@ -24,7 +25,7 @@ class XdawnTransformer(_GEDTransformer):
     response with respect to the non-target response. This implementation is a
     generalization to any type of event related response.
 
-    .. note:: _XdawnTransformer does not correct for epochs overlap. To correct
+    .. note:: XdawnTransformer does not correct for epochs overlap. To correct
               overlaps see ``Xdawn``.
 
     Parameters
@@ -68,7 +69,6 @@ class XdawnTransformer(_GEDTransformer):
 
         .. versionadded:: 1.10
 
-
     Attributes
     ----------
     classes_ : array, shape (n_classes)

From b3a378d831f6e7f98d26d0cd52204cf158e6947e Mon Sep 17 00:00:00 2001
From: Genuster <genusterok@gmail.com>
Date: Sat, 5 Jul 2025 12:24:19 +0300
Subject: [PATCH 54/59] more docstring adventures

---
 mne/decoding/csp.py   | 2 +-
 mne/decoding/xdawn.py | 8 +++++---
 mne/utils/docs.py     | 1 +
 3 files changed, 7 insertions(+), 4 deletions(-)

diff --git a/mne/decoding/csp.py b/mne/decoding/csp.py
index 2d61f2e0094..7855a9ebe60 100644
--- a/mne/decoding/csp.py
+++ b/mne/decoding/csp.py
@@ -112,7 +112,7 @@ class CSP(_GEDTransformer):
 
     See Also
     --------
-    mne.preprocessing.Xdawn, SPoC
+    XdawnTransformer, SPoC, SSD
 
     References
     ----------
diff --git a/mne/decoding/xdawn.py b/mne/decoding/xdawn.py
index aeb09aedb60..fb9d799ba3f 100644
--- a/mne/decoding/xdawn.py
+++ b/mne/decoding/xdawn.py
@@ -64,8 +64,7 @@ class XdawnTransformer(_GEDTransformer):
         Defaults to None.
 
         .. versionadded:: 1.10
-    %(rank)s
-        Defaults to "full".
+    %(rank_full)s
 
         .. versionadded:: 1.10
 
@@ -77,6 +76,10 @@ class XdawnTransformer(_GEDTransformer):
         The Xdawn components used to decompose the data for each event type.
     patterns_ : array, shape (n_channels, n_channels)
         The Xdawn patterns used to restore the signals for each event type.
+
+    See Also
+    --------
+    CSP, SPoC, SSD
     """
 
     def __init__(
@@ -89,7 +92,6 @@ def __init__(
         info=None,
         rank="full",
     ):
-        """Init."""
         self.n_components = n_components
         self.signal_cov = signal_cov
         self.reg = reg
diff --git a/mne/utils/docs.py b/mne/utils/docs.py
index 82b84e3f570..aea650affc1 100644
--- a/mne/utils/docs.py
+++ b/mne/utils/docs.py
@@ -3695,6 +3695,7 @@ def _reflow_param_docstring(docstring, has_first_line=True, width=75):
 docdict["rank"] = _rank_base
 docdict["rank_info"] = _rank_base + "\n    The default is ``'info'``."
 docdict["rank_none"] = _rank_base + "\n    The default is ``None``."
+docdict["rank_full"] = _rank_base + "\n    The default is ``'full'``."
 
 docdict["raw_epochs"] = """
 raw : Raw object

From 10afd78aa347fb9ee43098935e9388cb1bce8be1 Mon Sep 17 00:00:00 2001
From: Genuster <genusterok@gmail.com>
Date: Sun, 6 Jul 2025 15:10:52 +0300
Subject: [PATCH 55/59] fix docdict order

---
 mne/utils/docs.py | 2 +-
 1 file changed, 1 insertion(+), 1 deletion(-)

diff --git a/mne/utils/docs.py b/mne/utils/docs.py
index cedd9788010..07c47ab7f28 100644
--- a/mne/utils/docs.py
+++ b/mne/utils/docs.py
@@ -3697,9 +3697,9 @@ def _reflow_param_docstring(docstring, has_first_line=True, width=75):
 """
 
 docdict["rank"] = _rank_base
+docdict["rank_full"] = _rank_base + "\n    The default is ``'full'``."
 docdict["rank_info"] = _rank_base + "\n    The default is ``'info'``."
 docdict["rank_none"] = _rank_base + "\n    The default is ``None``."
-docdict["rank_full"] = _rank_base + "\n    The default is ``'full'``."
 
 docdict["raw_epochs"] = """
 raw : Raw object

From 9ec6835166152d55954f2edbf72d8600f8c006e8 Mon Sep 17 00:00:00 2001
From: Genuster <genusterok@gmail.com>
Date: Fri, 11 Jul 2025 12:29:54 +0300
Subject: [PATCH 56/59] make all init arguments have default in ged transformer

---
 mne/decoding/base.py | 3 +--
 1 file changed, 1 insertion(+), 2 deletions(-)

diff --git a/mne/decoding/base.py b/mne/decoding/base.py
index c2a30702429..f207a558bcd 100644
--- a/mne/decoding/base.py
+++ b/mne/decoding/base.py
@@ -99,8 +99,7 @@ class _GEDTransformer(MNETransformerMixin, BaseEstimator):
 
     def __init__(
         self,
-        cov_callable,
-        *,
+        cov_callable=None,
         n_components=None,
         mod_ged_callable=None,
         dec_type="single",

From 2b690ea297ca17ccad335c3c5878bc2c5fba4f82 Mon Sep 17 00:00:00 2001
From: Genuster <genusterok@gmail.com>
Date: Sat, 12 Jul 2025 11:57:30 +0300
Subject: [PATCH 57/59] temporarily skip the problematic test

---
 mne/inverse_sparse/tests/test_mxne_inverse.py | 1 +
 1 file changed, 1 insertion(+)

diff --git a/mne/inverse_sparse/tests/test_mxne_inverse.py b/mne/inverse_sparse/tests/test_mxne_inverse.py
index 9b4e6119d17..28eeb157e67 100644
--- a/mne/inverse_sparse/tests/test_mxne_inverse.py
+++ b/mne/inverse_sparse/tests/test_mxne_inverse.py
@@ -547,6 +547,7 @@ def test_mxne_inverse_sure_synthetic(
     assert np.count_nonzero(active_set, axis=-1) == n_orient * nnz
 
 
+@pytest.mark.skip(reason="weird failure on ubuntu tests, temporary skip.")
 @pytest.mark.slowtest  # slow on Azure
 @testing.requires_testing_data
 def test_mxne_inverse_sure_meg():

From 0117163f115f0aa9c21720d4823a8bd59b2049da Mon Sep 17 00:00:00 2001
From: Genuster <genusterok@gmail.com>
Date: Sat, 12 Jul 2025 15:37:24 +0300
Subject: [PATCH 58/59] unskip the test

---
 mne/inverse_sparse/tests/test_mxne_inverse.py | 22 +++++++++----------
 1 file changed, 10 insertions(+), 12 deletions(-)

diff --git a/mne/inverse_sparse/tests/test_mxne_inverse.py b/mne/inverse_sparse/tests/test_mxne_inverse.py
index 28eeb157e67..0fe0c41a2ac 100644
--- a/mne/inverse_sparse/tests/test_mxne_inverse.py
+++ b/mne/inverse_sparse/tests/test_mxne_inverse.py
@@ -547,10 +547,9 @@ def test_mxne_inverse_sure_synthetic(
     assert np.count_nonzero(active_set, axis=-1) == n_orient * nnz
 
 
-@pytest.mark.skip(reason="weird failure on ubuntu tests, temporary skip.")
 @pytest.mark.slowtest  # slow on Azure
 @testing.requires_testing_data
-def test_mxne_inverse_sure_meg():
+def test_mxne_inverse_sure():
     """Tests SURE criterion for automatic alpha selection on MEG data."""
 
     def data_fun(times):
@@ -559,10 +558,10 @@ def data_fun(times):
         return data
 
     n_dipoles = 2
-    raw = mne.io.read_raw_fif(fname_raw).pick_types("grad", exclude="bads")
-    raw.del_proj()
-    info = raw.info
-    del raw
+    raw = mne.io.read_raw_fif(fname_raw)
+    info = mne.io.read_info(fname_data)
+    with info._unlock():
+        info["projs"] = []
     noise_cov = mne.make_ad_hoc_cov(info)
     label_names = ["Aud-lh", "Aud-rh"]
     labels = [
@@ -573,8 +572,10 @@ def data_fun(times):
         data_path / "MEG" / "sample" / "sample_audvis_trunc-meg-eeg-oct-4-fwd.fif"
     )
     forward = mne.read_forward_solution(fname_fwd)
-    forward = mne.pick_channels_forward(forward, info["ch_names"])
-    times = np.arange(100, dtype=np.float64) / info["sfreq"] - 0.1
+    forward = mne.pick_types_forward(
+        forward, meg="grad", eeg=False, exclude=raw.info["bads"]
+    )
+    times = np.arange(100, dtype=np.float64) / raw.info["sfreq"] - 0.1
     stc = simulate_sparse_stc(
         forward["src"],
         n_dipoles=n_dipoles,
@@ -583,16 +584,13 @@ def data_fun(times):
         labels=labels,
         data_fun=data_fun,
     )
-    assert len(stc.vertices) == 2
-    assert_array_equal(stc.vertices[0], [89259])
-    assert_array_equal(stc.vertices[1], [70279])
     nave = 30
     evoked = simulate_evoked(
         forward, stc, info, noise_cov, nave=nave, use_cps=False, iir_filter=None
     )
     evoked = evoked.crop(tmin=0, tmax=10e-3)
     stc_ = mixed_norm(
-        evoked, forward, noise_cov, loose=0.9, n_mxne_iter=5, depth=0.9, random_state=1
+        evoked, forward, noise_cov, loose=0.9, n_mxne_iter=5, depth=0.9, random_state=0
     )
     assert len(stc_.vertices) == len(stc.vertices) == 2
     for si in range(len(stc_.vertices)):

From b08cf818b79e7b8011cf6e26848ed764c879b530 Mon Sep 17 00:00:00 2001
From: Genuster <genusterok@gmail.com>
Date: Sat, 12 Jul 2025 16:16:25 +0300
Subject: [PATCH 59/59] fix unskip

---
 mne/inverse_sparse/tests/test_mxne_inverse.py | 21 ++++++++++---------
 1 file changed, 11 insertions(+), 10 deletions(-)

diff --git a/mne/inverse_sparse/tests/test_mxne_inverse.py b/mne/inverse_sparse/tests/test_mxne_inverse.py
index 0fe0c41a2ac..9b4e6119d17 100644
--- a/mne/inverse_sparse/tests/test_mxne_inverse.py
+++ b/mne/inverse_sparse/tests/test_mxne_inverse.py
@@ -549,7 +549,7 @@ def test_mxne_inverse_sure_synthetic(
 
 @pytest.mark.slowtest  # slow on Azure
 @testing.requires_testing_data
-def test_mxne_inverse_sure():
+def test_mxne_inverse_sure_meg():
     """Tests SURE criterion for automatic alpha selection on MEG data."""
 
     def data_fun(times):
@@ -558,10 +558,10 @@ def data_fun(times):
         return data
 
     n_dipoles = 2
-    raw = mne.io.read_raw_fif(fname_raw)
-    info = mne.io.read_info(fname_data)
-    with info._unlock():
-        info["projs"] = []
+    raw = mne.io.read_raw_fif(fname_raw).pick_types("grad", exclude="bads")
+    raw.del_proj()
+    info = raw.info
+    del raw
     noise_cov = mne.make_ad_hoc_cov(info)
     label_names = ["Aud-lh", "Aud-rh"]
     labels = [
@@ -572,10 +572,8 @@ def data_fun(times):
         data_path / "MEG" / "sample" / "sample_audvis_trunc-meg-eeg-oct-4-fwd.fif"
     )
     forward = mne.read_forward_solution(fname_fwd)
-    forward = mne.pick_types_forward(
-        forward, meg="grad", eeg=False, exclude=raw.info["bads"]
-    )
-    times = np.arange(100, dtype=np.float64) / raw.info["sfreq"] - 0.1
+    forward = mne.pick_channels_forward(forward, info["ch_names"])
+    times = np.arange(100, dtype=np.float64) / info["sfreq"] - 0.1
     stc = simulate_sparse_stc(
         forward["src"],
         n_dipoles=n_dipoles,
@@ -584,13 +582,16 @@ def data_fun(times):
         labels=labels,
         data_fun=data_fun,
     )
+    assert len(stc.vertices) == 2
+    assert_array_equal(stc.vertices[0], [89259])
+    assert_array_equal(stc.vertices[1], [70279])
     nave = 30
     evoked = simulate_evoked(
         forward, stc, info, noise_cov, nave=nave, use_cps=False, iir_filter=None
     )
     evoked = evoked.crop(tmin=0, tmax=10e-3)
     stc_ = mixed_norm(
-        evoked, forward, noise_cov, loose=0.9, n_mxne_iter=5, depth=0.9, random_state=0
+        evoked, forward, noise_cov, loose=0.9, n_mxne_iter=5, depth=0.9, random_state=1
     )
     assert len(stc_.vertices) == len(stc.vertices) == 2
     for si in range(len(stc_.vertices)):