Support mixed hed annotations, concat and solve version registration (#13736)

Author: bruAristimunha

doc/changes/dev/13736.bugfix.rst

@@ -0,0 +1 @@
+Support mixed-type concatenation of :class:`mne.Annotations` and :class:`mne.HEDAnnotations`, preserving HED strings in ``extras["HED"]``, by `Bruno Aristimunha`_.

mne/annotations.py

@@ -489,12 +489,15 @@ def __iadd__(self, other):
                 "orig_time should be the same to add/concatenate 2 annotations (got "
                 f"{self.orig_time} != {other.orig_time})"
             )
+        extras = other.extras
+        if hasattr(other, "hed_string"):
+            extras = _hed_extras_from_hed_annotations(other)
         return self.append(
             other.onset,
             other.duration,
             other.description,
             other.ch_names,
-            extras=other.extras,
+            extras=extras,
         )
 
     def __iter__(self):
@@ -982,6 +985,11 @@ def append(self, item):
         self._objs.append(hs)
 
 
+def _hed_extras_from_hed_annotations(annot):
+    """Convert HEDAnnotations hed_string data into extras dicts with "HED" key."""
+    return [{**d, "HED": str(hs)} for d, hs in zip(annot.extras, annot.hed_string)]
+
+
 @fill_doc
 class HEDAnnotations(Annotations):
     """Annotations object for annotating segments of raw data with HED tags.
@@ -1024,6 +1032,16 @@ class HEDAnnotations(Annotations):
 
     Notes
     -----
+    When concatenating annotations using the ``+`` operator or ``+=``:
+
+    - ``HEDAnnotations + HEDAnnotations`` returns a
+      :class:`~mne.HEDAnnotations`.
+    - ``HEDAnnotations + Annotations`` returns a plain
+      :class:`~mne.Annotations`, with HED strings preserved in
+      ``extras["HED"]``.
+    - ``Annotations + HEDAnnotations`` returns a plain
+      :class:`~mne.Annotations`, with HED strings preserved in
+      ``extras["HED"]``.
 
     .. versionadded:: 1.12
     """
@@ -1211,9 +1229,18 @@ def append(
     def __iadd__(self, other):
         """Add (concatenate) two HEDAnnotations objects in-place."""
         if not isinstance(other, type(self)):
-            raise TypeError(
-                f"Cannot concatenate {type(self).__name__} and {type(other).__name__}."
+            # Convert self to plain Annotations, preserving HED in extras
+            extras = _hed_extras_from_hed_annotations(self)
+            result = Annotations(
+                onset=self.onset,
+                duration=self.duration,
+                description=self.description,
+                orig_time=self.orig_time,
+                ch_names=self.ch_names,
+                extras=extras,
             )
+            result += other
+            return result
         if len(self) == 0:
             self._orig_time = other.orig_time
         if self.orig_time != other.orig_time:

mne/tests/test_annotations.py

@@ -2130,6 +2130,103 @@ def test_hed_annotations():
     assert list(empty_ann.hed_string) == []
 
 
+def test_hed_annotations_mixed_concatenation():
+    """Test concatenation of HEDAnnotations with regular Annotations."""
+    pytest.importorskip("hed")
+    tone = (
+        "Sensory-event, Experimental-stimulus, Auditory-presentation, "
+        "(Tone, Frequency/550 Hz)"
+    )
+    press = "Agent-action, (Experiment-participant, (Press, Mouse-button))"
+
+    hed = HEDAnnotations(
+        onset=[0, 1],
+        duration=[0.1, 0.2],
+        description=["tone", "press"],
+        hed_string=[tone, press],
+        extras=[{"run": 1}, {"run": 2}],
+    )
+    reg = Annotations(
+        onset=[2, 3],
+        duration=[0.3, 0.4],
+        description=["plain1", "plain2"],
+        extras=[{"run": 3}, {}],
+    )
+
+    # --- Annotations += HEDAnnotations ---
+    combined = reg.copy()
+    combined += hed
+    assert isinstance(combined, Annotations)
+    assert not isinstance(combined, HEDAnnotations)
+    assert len(combined) == 4
+    # sorted by onset: hed(0,1) then reg(2,3)
+    assert combined.extras[0]["HED"] == tone
+    assert combined.extras[1]["HED"] == press
+    assert "HED" not in combined.extras[2]
+    assert "HED" not in combined.extras[3]
+    # pre-existing extras preserved
+    assert combined.extras[0]["run"] == 1
+    assert combined.extras[1]["run"] == 2
+    assert combined.extras[2]["run"] == 3
+
+    # --- HEDAnnotations += Annotations ---
+    combined2 = hed.copy()
+    combined2 += reg
+    # result is plain Annotations (rebinding semantics)
+    assert isinstance(combined2, Annotations)
+    assert not isinstance(combined2, HEDAnnotations)
+    assert len(combined2) == 4
+    # sorted by onset: hed(0,1) then reg(2,3)
+    assert combined2.extras[0]["HED"] == tone
+    assert combined2.extras[1]["HED"] == press
+    assert "HED" not in combined2.extras[2]
+    assert "HED" not in combined2.extras[3]
+    # pre-existing extras preserved
+    assert combined2.extras[0]["run"] == 1
+    assert combined2.extras[2]["run"] == 3
+
+    # --- non-mutating + operators ---
+    hed_orig = hed.copy()
+    reg_orig = reg.copy()
+
+    out1 = reg + hed
+    assert isinstance(out1, Annotations)
+    assert not isinstance(out1, HEDAnnotations)
+    assert len(out1) == 4
+    assert out1.extras[0]["HED"] == tone
+    assert out1.extras[1]["HED"] == press
+
+    out2 = hed + reg
+    assert isinstance(out2, Annotations)
+    assert not isinstance(out2, HEDAnnotations)
+    assert len(out2) == 4
+    assert out2.extras[0]["HED"] == tone
+    assert out2.extras[1]["HED"] == press
+
+    # originals are not mutated
+    assert hed == hed_orig
+    assert reg == reg_orig
+
+    # --- ch_names are preserved ---
+    hed_ch = HEDAnnotations(
+        onset=[0],
+        duration=[0.1],
+        description=["x"],
+        hed_string=[tone],
+        ch_names=[["EEG 001"]],
+    )
+    reg_ch = Annotations(
+        onset=[1],
+        duration=[0.1],
+        description=["y"],
+        ch_names=[["EEG 002"]],
+    )
+    out3 = reg_ch + hed_ch
+    # sorted by onset: hed_ch(0) then reg_ch(1)
+    assert out3[0]["ch_names"] == ("EEG 001",)
+    assert out3[1]["ch_names"] == ("EEG 002",)
+
+
 def test_hed_annotations_to_data_frame():
     """Test HEDAnnotations.to_data_frame()."""
     pytest.importorskip("hed")

mne/utils/check.py

@@ -407,6 +407,7 @@ def _soft_import(name, purpose, strict=True, *, min_version=None):
         mne_connectivity="mne-connectivity",
         mne_gui_addons="mne-gui-addons",
         pyvista="pyvistaqt",
+        hed="hedtools",
     ).get(name, name)
 
     got_version = None

mne/utils/config.py

@@ -848,6 +848,7 @@ def sys_info(
         use_mod_names += (
             "# Testing",
             "pytest",
+            "hedtools",
             "statsmodels",
             "numpydoc",
             "jupyter_client",
@@ -877,6 +878,7 @@ def sys_info(
     except Exception:  # in case someone overrides sys.stdout in an unsafe way
         unicode = False
     mne_version_good = True
+    import_names = dict(hedtools="hed")
     for mi, mod_name in enumerate(use_mod_names):
         # upcoming break
         if mod_name == "":  # break
@@ -897,7 +899,8 @@ def sys_info(
         if last:
             pre = "└"
         try:
-            mod = import_module(mod_name.replace("-", "_"))
+            import_name = import_names.get(mod_name, mod_name.replace("-", "_"))
+            mod = import_module(import_name)
         except Exception:
             unavailable.append(mod_name)
         else:

pyproject.toml

@@ -65,6 +65,7 @@ test = [
 test_extra = [
   "edfio >= 0.4.10",
   "eeglabio",
+  "hedtools",
   "imageio >= 2.6.1",
   "imageio-ffmpeg >= 0.4.1",
   "jupyter_client",