MAINT: add OPM overlap grouping helper

doc/changes/dev/13847.other.rst

@@ -0,0 +1 @@
+Added a helper to split colocated OPM overlap sets into radial and tangential channel groups, and updated topomap regression coverage to use shared triaxial OPM fixtures, by `Pragnya Khandelwal`_.

mne/viz/tests/test_topomap.py

@@ -840,6 +840,17 @@ def test_prepare_topomap_plot_opm_non_quspin_coils():
     assert sum(name.endswith("MERGE-REMOVE") for name in merged_names) == 4
 
 
+def test_split_opm_overlaps(triaxial_evoked):
+    """Test splitting colocated OPM overlap sets into orientation groups."""
+    _picks, _pos, merge_channels, _merged_names, *_ = topomap._prepare_topomap_plot(
+        triaxial_evoked, "mag"
+    )
+
+    radial, tangential = topomap._split_opm_overlaps(merge_channels)
+    assert radial == ["OPM001", "OPM004"]
+    assert tangential == ["OPM002", "OPM003", "OPM005", "OPM006"]
+
+
 def test_plot_topomap_nirs_overlap(fnirs_epochs):
     """Test plotting nirs topomap with overlapping channels (gh-7414)."""
     fig = fnirs_epochs["A"].average(picks="hbo").plot_topomap()

mne/viz/topomap.py

@@ -312,6 +312,23 @@ def _find_radial_channel(info, overlapping_set):
     return radial_sensor
 
 
+def _split_opm_overlaps(overlapping_channels):
+    """Split OPM overlap sets into radial and tangential channel groups.
+
+    This keeps the first channel from each overlap set, which is the radial
+    channel as determined by :func:`_find_overlaps`, separate from the
+    remaining tangential channels. The result can be used by later plotting
+    code to render separate topomaps per orientation family.
+    """
+    radial = [overlap_set[0] for overlap_set in overlapping_channels]
+    tangential = list(
+        itertools.chain.from_iterable(
+            overlap_set[1:] for overlap_set in overlapping_channels
+        )
+    )
+    return radial, tangential
+
+
 def _plot_update_evoked_topomap(params, bools):
     """Update topomaps."""
     from ..channels.layout import _merge_ch_data