From 65e1aa6716b9a0615487ae12e4c468a6f71a8c5f Mon Sep 17 00:00:00 2001
From: =?UTF-8?q?Richard=20H=C3=B6chenberger?=
 <richard.hoechenberger@gmail.com>
Date: Fri, 21 Jun 2024 20:51:02 +0200
Subject: [PATCH] Rework how we apply EEG montages (#960)

---
 docs/source/v1.9.md.inc           |  5 +++++
 mne_bids_pipeline/_config.py      | 10 +++++++++-
 mne_bids_pipeline/_import_data.py |  6 +-----
 3 files changed, 15 insertions(+), 6 deletions(-)

diff --git a/docs/source/v1.9.md.inc b/docs/source/v1.9.md.inc
index 50f6986a6..55e9f5ac8 100644
--- a/docs/source/v1.9.md.inc
+++ b/docs/source/v1.9.md.inc
@@ -25,6 +25,11 @@
   had previously already been marked as bad in the dataset. Resulting entries in the TSV file may now look like:
   `"pre-existing (before MNE-BIDS-pipeline was run) & auto-noisy"` (previously: only `"auto-noisy"`). (#930 by @hoechenberger)
 - The `ica_ctps_ecg_threshold` has been renamed to [`ica_ecg_threshold`][mne_bids_pipeline._config.ica_ecg_threshold]. (#935 by @hoechenberger)
+- We changed the behavior when setting an EEG montage:
+  - When applying the montage, we now also check for channel aliases (e.g. `M1 -> TP9`).
+  - If the data contains a channel that is not present in the montage, we now abort with an exception (previously, we emitted a warning).
+    This is to prevent silent errors. To proceed in this situation, select a different montage, or drop the respective channels via
+    the [`drop_channels`][mne_bids_pipeline._config.drop_channels] configuration option. (#960 by @hoechenberger)
 
 ### :package: Requirements
 
diff --git a/mne_bids_pipeline/_config.py b/mne_bids_pipeline/_config.py
index 850599e36..5a66cd2c5 100644
--- a/mne_bids_pipeline/_config.py
+++ b/mne_bids_pipeline/_config.py
@@ -346,6 +346,13 @@
 You can find an overview of supported template montages at
 https://mne.tools/stable/generated/mne.channels.make_standard_montage.html
 
+!!! warning
+    If the data contains channel names that are not part of the template montage, the
+    pipeline run will fail with an error message. You must either pick a different
+    montage or remove those channels via
+    [`drop_channels`][mne_bids_pipeline._config.drop_channels] to continue.
+
+
 ???+ example "Example"
     Do not apply template montage:
     ```python
@@ -362,7 +369,8 @@
 """
 Names of channels to remove from the data. This can be useful, for example,
 if you have added a new bipolar channel via `eeg_bipolar_channels` and now wish
-to remove the anode, cathode, or both.
+to remove the anode, cathode, or both; or if your selected EEG template montage
+doesn't contain coordinates for some channels.
 
 ???+ example "Example"
     Exclude channels `Fp1` and `Cz` from processing:
diff --git a/mne_bids_pipeline/_import_data.py b/mne_bids_pipeline/_import_data.py
index e001406f1..494101055 100644
--- a/mne_bids_pipeline/_import_data.py
+++ b/mne_bids_pipeline/_import_data.py
@@ -326,14 +326,10 @@ def _set_eeg_montage(
     Modifies ``raw`` in-place.
     """
     montage = cfg.eeg_template_montage
-    is_mne_montage = isinstance(montage, mne.channels.montage.DigMontage)
-    montage_name = "custom_montage" if is_mne_montage else montage
     if cfg.datatype == "eeg" and montage:
         msg = f"Setting EEG channel locations to template montage: " f"{montage}."
         logger.info(**gen_log_kwargs(message=msg))
-        if not is_mne_montage:
-            montage = mne.channels.make_standard_montage(montage_name)
-        raw.set_montage(montage, match_case=False, on_missing="warn")
+        raw.set_montage(montage, match_case=False, match_alias=True)
 
 
 def _fix_stim_artifact_func(cfg: SimpleNamespace, raw: mne.io.BaseRaw) -> None: