Use metadata-aware cv_class directly; add tests and whatsnew

Author: Copilot

docs/source/whats_new.rst

@@ -38,6 +38,7 @@ Enhancements
 - Skip zip extraction in :class:`moabb.datasets.GuttmannFlury2025` when files are already extracted, with ``/scratch`` fallback for NFS filesystems on compute nodes (by `Bruno Aristimunha`_)
 - Re-enable auto-execution of the Riemannian Artifact Rejection tutorial (``examples/advanced_examples/plot_riemannian_artifact_rejection.py``) now that pyRiemann 0.11 is on PyPI with per-potato metrics and ``method_combination`` support on ``PotatoField`` (by `Bruno Aristimunha`_)
 - Use NEMAR as the default download source for datasets with an assigned ``nemar_id``, while preserving existing dataset-specific downloaders as a fallback (by `Bruno Aristimunha`_).
+- Allow a metadata-aware splitter to be passed as ``cv_class`` to :class:`moabb.evaluations.CrossSubjectEvaluation`/:class:`moabb.evaluations.CrossSessionEvaluation` (and the ``CrossSubjectSplitter``/``CrossSessionSplitter`` wrappers). When ``cv_class`` follows the moabb convention (declares ``metadata_columns`` and implements ``split(self, y, metadata)``), it is used directly as the top-level splitter — receiving the full ``metadata`` — instead of being wrapped as the inner groups-CV, enabling metadata-driven folds (e.g. single-target cross-subject folds restricted to one session) through the public ``cv_class``/``cv_kwargs`` API (:gh:`1104` by `Bruno Aristimunha`_)
 
 API changes
 ~~~~~~~~~~~

moabb/evaluations/base.py

@@ -388,7 +388,26 @@ def __init__(
             self.additional_columns = []
 
         if self.cv_class is not None and hasattr(self.cv_class, "metadata_columns"):
+            # ``metadata_columns`` may describe either extra *output* columns an
+            # inner CV produces (e.g. LearningCurveSplitter -> data_size) or the
+            # *input* metadata columns a metadata-aware top-level splitter
+            # consumes (e.g. subject/session). The latter are already core result
+            # columns and must not be stored as extra numeric result columns.
+            reserved_columns = {
+                "time",
+                "dataset",
+                "subject",
+                "session",
+                "n_samples",
+                "n_channels",
+                "pipeline",
+                "n_samples_test",
+                "n_classes",
+                "score",
+            }
             for col in self.cv_class.metadata_columns:
+                if col in reserved_columns:
+                    continue
                 if col not in self.additional_columns:
                     self.additional_columns.append(col)
 

moabb/tests/test_evaluations.py

@@ -8,6 +8,7 @@
 import pandas as pd
 import pytest
 import sklearn.base
+import sklearn.model_selection
 from pyriemann.estimation import Covariances
 from pyriemann.spatialfilters import CSP
 from sklearn.discriminant_analysis import LinearDiscriminantAnalysis as LDA
@@ -483,6 +484,58 @@ def test_incompatibility_error_message(self):
         assert "requires at least 2 sessions" in error_msg
 
 
+def _flatten(x):
+    """Flatten a 3D epochs array to 2D (n_samples, n_features)."""
+    return x.reshape(len(x), -1)
+
+
+class _TargetSubjectSplitter(sklearn.model_selection.BaseCrossValidator):
+    """Metadata-aware top-level splitter (test = target@session, train = others)."""
+
+    metadata_columns = ("subject", "session")
+
+    def __init__(self, target=None, test_session=None):
+        self.target = target
+        self.test_session = test_session
+
+    def _iter_test_masks(self, X=None, y=None, groups=None):
+        raise NotImplementedError
+
+    def get_n_splits(self, metadata):
+        return 1
+
+    def split(self, y, metadata):
+        idx = metadata.index.values
+        test_mask = (metadata["subject"] == self.target) & (
+            metadata["session"] == self.test_session
+        )
+        train_mask = metadata["subject"] != self.target
+        yield idx[train_mask.values], idx[test_mask.values]
+
+
+def test_cross_subject_with_metadata_aware_cv_class():
+    """A metadata-aware splitter passed via cv_class is used directly."""
+    ds = FakeDataset(["left_hand", "right_hand"], n_subjects=3, n_sessions=2, seed=3)
+    evaluation = ev.CrossSubjectEvaluation(
+        paradigm=FakeImageryParadigm(),
+        datasets=[ds],
+        overwrite=True,
+        cv_class=_TargetSubjectSplitter,
+        cv_kwargs={"target": 2, "test_session": "0"},
+    )
+    # subject/session are core columns and must not leak into additional_columns.
+    assert "subject" not in evaluation.additional_columns
+    assert "session" not in evaluation.additional_columns
+
+    pipe = {"flat_lda": make_pipeline(FunctionTransformer(_flatten), LDA())}
+    results = evaluation.process(pipe)
+
+    # Exactly one fold: test = target subject at the requested session.
+    assert len(results) == 1
+    assert {int(s) for s in results["subject"]} == {2}
+    assert set(results["session"]) == {"0"}
+
+
 class TestUtilEvaluation:
     def test_save_model_cv(self):
         model = Dummy()