ENH: add interpolate_to method

doc/references.bib

@@ -2504,3 +2504,11 @@ @article{OyamaEtAl2015
 	year = {2015},
 	pages = {24--36},
 }
+
+@inproceedings{MellotEtAl2024,
+	title = {Physics-informed and Unsupervised Riemannian Domain Adaptation for Machine Learning on Heterogeneous EEG Datasets},
+	author = {Mellot, Apolline and Collas, Antoine and Chevallier, Sylvain and Engemann, Denis and Gramfort, Alexandre},
+	booktitle = {Proceedings of the 32nd European Signal Processing Conference (EUSIPCO)},
+	year = {2024},
+	address = {Lyon, France}
+}

examples/preprocessing/interpolate_to.py

@@ -0,0 +1,65 @@
+"""
+.. _ex-interpolate-to-any-montage:
+
+======================================================
+Interpolate EEG data to any montage
+======================================================
+
+This example demonstrates how to interpolate EEG channels to match a given montage.
+This can be useful for standardizing
+EEG channel layouts across different datasets (see :footcite:`MellotEtAl2024`).
+
+- Using the field interpolation for EEG data.
+- Using the target montage "biosemi16".
+
+In this example, the data from the original EEG channels will be
+interpolated onto the positions defined by the "biosemi16" montage.
+"""
+
+# Authors: Antoine Collas <[email protected]>
+# License: BSD-3-Clause
+# Copyright the MNE-Python contributors.
+
+import matplotlib.pyplot as plt
+
+import mne
+from mne.channels import make_standard_montage
+from mne.datasets import sample
+
+print(__doc__)
+
+# %%
+# Load EEG data
+data_path = sample.data_path()
+eeg_file_path = data_path / "MEG" / "sample" / "sample_audvis-ave.fif"
+evoked = mne.read_evokeds(eeg_file_path, condition="Left Auditory", baseline=(None, 0))
+
+# Select only EEG channels
+evoked.pick("eeg")
+
+# Plot the original EEG layout
+evoked.plot(exclude=[], picks="eeg")
+
+# %%
+# Define the target montage
+standard_montage = make_standard_montage("biosemi16")
+
+# %%
+# Use interpolate_to to project EEG data to the standard montage
+evoked_interpolated = evoked.copy().interpolate_to(standard_montage)
+
+# Plot the interpolated EEG layout
+evoked_interpolated.plot(exclude=[], picks="eeg")
+
+# %%
+# Comparing before and after interpolation
+fig, axs = plt.subplots(2, 1, figsize=(8, 6), constrained_layout=True)
+evoked.plot(exclude=[], picks="eeg", axes=axs[0], show=False)
+axs[0].set_title("Original EEG Layout")
+evoked_interpolated.plot(exclude=[], picks="eeg", axes=axs[1], show=False)
+axs[1].set_title("Interpolated to Standard 1020 Montage")
+
+# %%
+# References
+# ----------
+# .. footbibliography::

mne/channels/channels.py

@@ -950,6 +950,80 @@ def interpolate_bads(
 
         return self
 
+    def interpolate_to(self, montage, method="MNE", reg=0.0):
+        """Interpolate data onto a new montage.
+
+        Parameters
+        ----------
+        montage : DigMontage
+            The target montage containing channel positions to interpolate onto.
+        method : str
+            The interpolation method to use. 'MNE' by default.
+        reg : float
+            The regularization parameter for the interpolation method (if applicable).
+
+        Returns
+        -------
+        inst : instance of Raw, Epochs, or Evoked
+            The instance with updated channel locations and data.
+
+        Notes
+        -----
+        This method is useful for standardizing EEG layouts across datasets.
+
+        .. versionadded:: 1.10.0
+        """
+        from ..forward._field_interpolation import _map_meg_or_eeg_channels
+
+        # Ensure data is loaded
+        _check_preload(self, "interpolation")
+
+        # Extract positions and data for EEG channels
+        picks_from = pick_types(self.info, meg=False, eeg=True, exclude=[])
+        if len(picks_from) == 0:
+            raise ValueError("No EEG channels available for interpolation.")
+
+        # Get original data
+        data_orig = self.get_data(picks=picks_from)
+
+        # Get target positions from the montage
+        ch_pos = montage.get_positions()["ch_pos"]
+        target_ch_names = list(ch_pos.keys())
+        if len(target_ch_names) == 0:
+            raise ValueError(
+                "The provided montage does not contain any channel positions."
+            )
+
+        # Create a new info structure
+        sfreq = self.info["sfreq"]
+        ch_types = ["eeg"] * len(target_ch_names)
+        new_info = create_info(ch_names=target_ch_names, sfreq=sfreq, ch_types=ch_types)
+        new_info.set_montage(montage)
+
+        # Create a simple old_info
+        sfreq = self.info["sfreq"]
+        ch_names = self.info["ch_names"]
+        ch_types = ["eeg"] * len(ch_names)
+        old_info = create_info(ch_names=ch_names, sfreq=sfreq, ch_types=ch_types)
+        old_info.set_montage(self.info.get_montage())
+
+        # Compute mapping from current montage to target montage
+        mapping = _map_meg_or_eeg_channels(
+            old_info, new_info, mode="accurate", origin="auto"
+        )
+
+        # Apply the interpolation mapping
+        data_interp = mapping.dot(data_orig)
+
+        # Update bad channels
+        new_info["bads"] = [ch for ch in self.info["bads"] if ch in target_ch_names]
+
+        # Update the instance's info and data
+        self.info = new_info
+        self._data = data_interp
+
+        return self
+
 
 @verbose
 def rename_channels(info, mapping, allow_duplicates=False, *, verbose=None):

mne/channels/tests/test_interpolation.py

@@ -12,7 +12,7 @@
 from mne import Epochs, pick_channels, pick_types, read_events
 from mne._fiff.constants import FIFF
 from mne._fiff.proj import _has_eeg_average_ref_proj
-from mne.channels import make_dig_montage
+from mne.channels import make_dig_montage, make_standard_montage
 from mne.channels.interpolation import _make_interpolation_matrix
 from mne.datasets import testing
 from mne.io import RawArray, read_raw_ctf, read_raw_fif, read_raw_nirx
@@ -439,3 +439,39 @@ def test_method_str():
         raw.interpolate_bads(method="spline")
     raw.pick("eeg", exclude=())
     raw.interpolate_bads(method="spline")
+
+
+@pytest.mark.parametrize("montage_name", ["biosemi16", "standard_1020"])
+def test_interpolate_to_eeg(montage_name):
+    """Test the interpolate_to method for EEG."""
+    # Load EEG data
+    raw, _ = _load_data("eeg")
+
+    # Select only EEG channels
+    raw.pick("eeg")
+
+    # Load data
+    raw.load_data()
+
+    # Create a target montage
+    montage = make_standard_montage(montage_name)
+
+    # Copy the raw object and apply interpolation
+    raw_interpolated = raw.copy().interpolate_to(montage)
+
+    # Check if channel names match the target montage
+    assert set(raw_interpolated.info["ch_names"]) == set(montage.ch_names)
+
+    # Check if the data was interpolated correctly
+    assert raw_interpolated.get_data().shape == (len(montage.ch_names), raw.n_times)
+
+    # Ensure original data is not altered
+    assert raw.info["ch_names"] != raw_interpolated.info["ch_names"]
+    assert raw.get_data().shape == (len(raw.info["ch_names"]), raw.n_times)
+
+    # Validate that bad channels are carried over
+    raw.info["bads"] = [raw.info["ch_names"][0]]
+    raw_interpolated = raw.copy().interpolate_to(montage)
+    assert raw_interpolated.info["bads"] == [
+        ch for ch in raw.info["bads"] if ch in montage.ch_names
+    ]