ENH: Add on_missing for combine_channels (mne-tools#13463)

Co-authored-by: Eric Larson <[email protected]>

Author: mistraube

doc/changes/dev/13463.newfeature.rst

@@ -0,0 +1 @@
+The ``combine_channels`` method now has an ``on_missing`` parameter to control behavior on missing event ids, by :newcontrib:`Michael Straube`.

doc/changes/names.inc

@@ -207,6 +207,7 @@
 .. _Matti Hämäläinen: https://research.aalto.fi/en/persons/matti-h%C3%A4m%C3%A4l%C3%A4inen/
 .. _Matti Toivonen: https://github.com/mattitoi
 .. _Mauricio Cespedes Tenorio: https://github.com/mcespedes99
+.. _Michael Straube: https://github.com/mistraube
 .. _Michal Žák: https://github.com/michalrzak
 .. _Michiru Kaneda: https://github.com/rcmdnk
 .. _Mikołaj Magnuski: https://github.com/mmagnuski

mne/channels/channels.py

@@ -2020,7 +2020,14 @@ def make_1020_channel_selections(info, midline="z", *, return_ch_names=False):
 
 @verbose
 def combine_channels(
-    inst, groups, method="mean", keep_stim=False, drop_bad=False, verbose=None
+    inst,
+    groups,
+    method="mean",
+    keep_stim=False,
+    drop_bad=False,
+    *,
+    on_missing="raise",
+    verbose=None,
 ):
     """Combine channels based on specified channel grouping.
 
@@ -2059,6 +2066,8 @@ def combine_channels(
     drop_bad : bool
         If ``True``, drop channels marked as bad before combining. Defaults to
         ``False``.
+    %(on_missing_epochs)s
+        .. versionadded:: 1.11.0
     %(verbose)s
 
     Returns
@@ -2174,6 +2183,7 @@ def combine_channels(
             event_id=inst.event_id,
             tmin=inst.times[0],
             baseline=inst.baseline,
+            on_missing=on_missing,
         )
         if inst.metadata is not None:
             combined_inst.metadata = inst.metadata.copy()

mne/channels/tests/test_channels.py

@@ -3,6 +3,7 @@
 # Copyright the MNE-Python contributors.
 
 import hashlib
+from contextlib import nullcontext
 from copy import deepcopy
 from functools import partial
 from pathlib import Path
@@ -673,6 +674,16 @@ def test_combine_channels():
         combine_channels(raw_ch_bad, warn3, drop_bad=True)
     assert len(record) == 3
 
+    # Test on_missing
+    event_id = [1, 100]  # 100 does not exist
+    epochs1 = Epochs(raw, read_events(eve_fname), event_id, on_missing="ignore")
+    with pytest.raises(ValueError, match="No matching events found"):
+        combine_channels(epochs1, groups={"foo": [0, 1]})
+    with pytest.warns(RuntimeWarning, match="No matching events found"):
+        combine_channels(epochs1, groups={"foo": [0, 1]}, on_missing="warn")
+    with nullcontext():
+        combine_channels(epochs1, groups={"foo": [0, 1]}, on_missing="ignore")
+
 
 def test_combine_channels_metadata():
     """Test if metadata is correctly retained in combined object."""