Add support for dictionary-type ref_channels in set_eeg_reference()

doc/changes/devel/12366.newfeature.rst

@@ -0,0 +1 @@
+Add support for `dict` type argument ``ref_channels`` to :func:`mne._fiff.reference.set_eeg_reference`, by `Qian Chu`_.

mne/_fiff/reference.py

@@ -155,6 +155,31 @@ def _apply_reference(inst, ref_from, ref_to=None, forward=None, ch_type="auto"):
     return inst, ref_data
 
 
+def _apply_dict_reference(inst, ref_dict, ch_type="auto"):
+    """Apply a dict-based custom EEG referencing scheme."""
+    # ref_to = _check_before_reference(inst, ref_from, ref_to, ch_type)
+
+    # # Compute reference
+    # if len(ref_from) > 0:
+    #     # this is guaranteed below, but we should avoid the crazy pick_channels
+    #     # behavior that [] gives all. Also use ordered=True just to make sure
+    #     # that all supplied channels actually exist.
+    #     assert len(ref_to) > 0
+    #     ref_names = ref_from
+    #     ref_from = pick_channels(inst.ch_names, ref_from, ordered=True)
+    #     ref_to = pick_channels(inst.ch_names, ref_to, ordered=True)
+
+    #     data = inst._data
+    #     ref_data = data[..., ref_from, :].mean(-2, keepdims=True)
+    #     data[..., ref_to, :] -= ref_data
+    #     ref_data = ref_data[..., 0, :]
+
+    # else:
+    #     ref_data = None
+
+    # return inst, ref_data
+
+
 @fill_doc
 def add_reference_channels(inst, ref_channels, copy=True):
     """Add reference channels to data that consists of all zeros.
@@ -430,7 +455,10 @@ def set_eeg_reference(
             "reference."
         )
 
-    return _apply_reference(inst, ref_channels, ch_sel, forward, ch_type=ch_type)
+    if ref_channels is dict:
+        return _apply_dict_reference(inst, ref_channels, ch_type=ch_type)
+    else:
+        return _apply_reference(inst, ref_channels, ch_sel, forward, ch_type=ch_type)
 
 
 def _get_ch_type(inst, ch_type):

mne/utils/docs.py

@@ -3213,13 +3213,20 @@ def _reflow_param_docstring(docstring, has_first_line=True, width=75):
 """
 
 docdict["ref_channels_set_eeg_reference"] = """
-ref_channels : list of str | str
+ref_channels : list of str | str | dict
     Can be:
 
-    - The name(s) of the channel(s) used to construct the reference.
+    - The name(s) of the channel(s) used to construct the reference for
+      every channel of ``ch_type``.
     - ``'average'`` to apply an average reference (default)
     - ``'REST'`` to use the Reference Electrode Standardization Technique
       infinity reference :footcite:`Yao2001`.
+    - A dictionary mapping names of channels to be referenced to (a list of)
+      names of channels to use as reference. This is the most flexible
+      re-referencing approaching. For example, {'A1': 'A3'} would replace the
+      data in channel 'A1' with the difference between 'A1' and 'A3'. To take
+      the average of multiple channels as reference, supply a list of channel
+      names as the dictionary value, e.g. {'A1': ['A2', 'A3']}.
     - An empty list, in which case MNE will not attempt any re-referencing of
       the data
 """