Cross-system transfer tutorial: masked-mean MDM with groups="device" (route metadata columns to pipelines)

docs/source/whats_new.rst

@@ -22,6 +22,7 @@ Version 1.8.0 (2026-10-06)
 
 Enhancements
 ~~~~~~~~~~~~
+- Add the tutorial :ref:`sphx_glr_auto_examples_how_to_benchmark_plot_cross_system_transfer_maskedmean.py`: cross-system transfer with a minimum distance to masked Riemannian mean, on datasets recorded with different montages and sampling rates, pooled in a :class:`~moabb.datasets.compound_dataset.CompoundDataset` and evaluated with :class:`~moabb.evaluations.CrossSubjectEvaluation` (``cv_class=LeaveOneGroupOut, groups="device"``). To support it, the evaluations route any metadata column of the training trials (``device``, ``dataset``, ``subject``...) to the pipeline steps that request it with scikit-learn metadata routing (``set_fit_request(device=True)``), and :class:`~moabb.datasets.fake.FakeDataset` takes a ``device`` (:gh:`1305` by `Quentin Barthelemy`_).
 - The metadata returned by :meth:`moabb.paradigms.base.BaseParadigm.get_data` has two new columns: ``dataset``, the code of the dataset each trial comes from (for a :class:`~moabb.datasets.compound_dataset.CompoundDataset`, the dataset the subject comes from), and ``device``, the recording device. ``device`` is the canonical name of ``METADATA.acquisition.hardware`` given by :func:`moabb.datasets.metadata.devices.canonical_device` (the 107 free-text descriptions map to 30 devices, e.g. every spelling of the g.tec g.USBamp; ``"unknown"`` when the dataset gives none); :class:`moabb.datasets.Peters2026` returns the DSI-24 or DSI-Flex of each visit. ``CrossSubjectEvaluation(cv_class=LeaveOneGroupOut, groups="dataset")`` holds out one dataset at a time and ``groups="device"`` one device at a time, and :class:`~moabb.evaluations.CrossDatasetSplitter` works on paradigm output (:gh:`1328` by `Bruno Aristimunha`_).
 - :meth:`moabb.paradigms.base.BaseParadigm.get_data` no longer fails when the recordings it stacks have different channels or numbers of samples, e.g. datasets with different montages or sampling rates pooled in a :class:`~moabb.datasets.compound_dataset.CompoundDataset`: it returns a nested object array of shape ``(n_trials,)`` holding each trial's ``(n_channels, n_times)`` array, and the evaluations accept it, so leave-one-dataset-out runs with :class:`~moabb.evaluations.CrossSubjectEvaluation` and ``cv_class=LeaveOneGroupOut``. Recordings of one shape still give a regular array; ``return_epochs=True`` raises a clear error for such recordings, as ``mne.Epochs`` cannot hold them (:gh:`1327` by `Bruno Aristimunha`_).
 - Add opt-in ``PurgedEpochKFold`` for chronological within-recording ERP folds with exact half-open raw-window purging. Pass sample timing and recording identity explicitly as integer-backed ``groups``; evaluation and preprocessing defaults remain unchanged. Continuous-recording filtering can still leak across folds (:gh:`280`, :gh:`1329` by `lindicaphxag-tech`_).
@@ -95,6 +96,7 @@ Requirements
 
 Bugs
 ~~~~
+- Fix the evaluations returning each result several times when datasets share a processing pipeline (e.g. :class:`~moabb.datasets.fake.FakeDataset` instances that differ only in their channels): ``process`` collected the whole results group of the pipeline for every dataset, instead of the rows of that dataset (:gh:`1305` by `Quentin Barthelemy`_).
 - Fix :class:`moabb.datasets.HefmiIch2025` returning subjects made of other people's sessions. The figshare file names carry no subject (``1_epo.mat``, ``2_epo.mat``, ``3_epo.mat``), and the loader grouped the EEG epoch files by figshare upload order, starting a new subject at every ``1_epo.mat``: 23 of its 37 subjects mixed sessions of two to four people, 31 of the 37 people were split over two or three subjects, and subjects had up to 6 sessions. Subjects and sessions now follow the depositor's folders, which the ``folder_structure`` of the figshare record (article 28955456, version 4) gives for every file and which the article's ZIP uses: subjects 1-17 are ``epo_data/Normals/EEG/subject1`` to ``subject17`` (healthy controls), subjects 18-37 are ``epo_data/Patients/EEG/subject1`` to ``subject20`` (ICH patients), and session ``str(k - 1)`` is the file ``<k>_epo.mat``: 98 sessions (1-3 per subject, consecutive runs of one visit) and 2,940 trials instead of the 3,330 the metadata declared. The creation times in the files' MAT headers agree with these folders. The loader ships the mapping with the size and MD5 of every file, checks each file against them, and stores the files under the depositor's paths; the NEMAR deposit ``nm000347``, which files the epochs under the former subjects, is no longer declared. **Delete cached HefmiIch2025 epochs and saved results computed before this fix and recompute them:** MOABB has no per-dataset cache version, so a cache built with the former grouping is otherwise reused as is. The previously downloaded ``subNN_k_epo.mat`` files and ``manifest.json`` in ``MNE-hefmiich2025-data`` are no longer read and can be deleted (:gh:`1326` by `Bruno Aristimunha`_).
 - Fix the evaluations training and scoring filter-bank pipelines on the first band only: since 1.4.0 (:gh:`774`), :class:`moabb.evaluations.base.BaseEvaluation` passed ``get_data`` the processing pipeline of the first filter alone, so with :class:`moabb.paradigms.FilterBankLeftRightImagery`, :class:`moabb.paradigms.FilterBankMotorImagery` or :class:`moabb.paradigms.FilterBankSSVEP` the data reaching an array pipeline had one band instead of one per filter (shape ``(n_trials, n_channels, n_times, 1)``). FBCSP and the SSVEP MDM, TS + LR and TS + SVM pipelines scored well below their published values (Nakanishi2015 SSVEP TS + LR 0.26 instead of 0.87; with every band, 0.89). Epoch-based pipelines (TRCA, TDCA, CCA, deep learning) were not affected. Results of filter-bank pipelines computed with MOABB 1.4.0 to 1.7.2 must be recomputed (:gh:`1291` by `Bruno Aristimunha`_).
 - :class:`moabb.datasets.BNCI2015_004` names its five mental tasks again (word association, mental subtraction, spatial navigation, right hand and feet imagery, coded 1-5 as in the .mat files) and epochs the imagery period [3, 10] s; since v1.5 the events were those of another dataset, the window covered the fixation cross, and :class:`moabb.paradigms.MotorImagery` rejected the dataset (:gh:`1323` by `Bruno Aristimunha`_)