Fix for annotation with no duration (#399)

Co-authored-by: autofix-ci[bot] <114827586+autofix-ci[bot]@users.noreply.github.com>

Author: mscheltienne

doc/development/changes/authors.inc

@@ -4,4 +4,5 @@
 .. _Kyuhwa Lee: https://github.com/dbdq
 .. _Mathieu Scheltienne: https://mathieu.scheltienne.net
 .. _Thomas Binns: https://github.com/tsbinns
+.. _Tom Ma: https://github.com/myd7349
 .. _Toni M. Brotons: https://github.com/toni-neurosc

doc/development/changes/latest.rst

@@ -20,3 +20,5 @@ Version 1.9
 ===========
 
 - Fix sphinx formatting in tutorials (:pr:`388` and :pr:`389` by `Thomas Binns`_)
+- Fix source links in the documentation (:pr:`398` by `Tom Ma`_)
+- Fix stream of annotations by a :class:`~mne_lsl.player.PlayerLSL` when the annotation duration is 0 (:pr:`399` by `Mathieu Scheltienne`_)

src/mne_lsl/player/player_lsl.py

@@ -61,7 +61,7 @@ class PlayerLSL(BasePlayer):
     the chunk are pushed on the annotation :class:`~mne_lsl.lsl.StreamOutlet`. The
     :class:`~mne.Annotations` are pushed with a timestamp corrected for the annotation
     onset in regards to the chunk beginning. However, :class:`~mne.Annotations` push is
-    *not* delayed until the the annotation timestamp or until the end of the chunk.
+    *not* delayed until the annotation timestamp or until the end of the chunk.
     Thus, an :class:`~mne.Annotations` can arrived at the client
     :class:`~mne_lsl.lsl.StreamInlet` "ahead" of time, i.e. earlier than the current
     time (as returned by the function :func:`~mne_lsl.lsl.local_clock`). Thus, it is
@@ -90,6 +90,12 @@ class PlayerLSL(BasePlayer):
     streamed on a channel correspond to the duration of the :class:`~mne.Annotations`.
     Thus, a sample on this :class:`~mne_lsl.lsl.StreamOutlet` is a one-hot encoded
     vector of the :class:`~mne.Annotations` description/duration.
+
+    .. note::
+
+        If the duration of an annotatation is ``0``, then the one-hot encoded vector
+        becomes a null vector. In this special case, the value ``-1`` is encoded and
+        denotes an annotation with a duration of ``0``.
     """
 
     def __init__(
@@ -345,7 +351,9 @@ def _stream_annotations(
             ]
         )
         data = np.zeros((timestamps.size, len(self._annotations_names)))
-        data[np.arange(timestamps.size), idx_] = self.annotations.duration[idx]
+        durations = self.annotations.duration[idx]
+        durations[durations == 0] = -1
+        data[np.arange(timestamps.size), idx_] = durations
         # push as a chunk all annotations in the [start:stop] range
         with catch_warnings():
             filterwarnings(

src/mne_lsl/player/player_lsl.pyi

@@ -60,7 +60,7 @@ class PlayerLSL(BasePlayer):
     the chunk are pushed on the annotation :class:`~mne_lsl.lsl.StreamOutlet`. The
     :class:`~mne.Annotations` are pushed with a timestamp corrected for the annotation
     onset in regards to the chunk beginning. However, :class:`~mne.Annotations` push is
-    *not* delayed until the the annotation timestamp or until the end of the chunk.
+    *not* delayed until the annotation timestamp or until the end of the chunk.
     Thus, an :class:`~mne.Annotations` can arrived at the client
     :class:`~mne_lsl.lsl.StreamInlet` "ahead" of time, i.e. earlier than the current
     time (as returned by the function :func:`~mne_lsl.lsl.local_clock`). Thus, it is
@@ -89,6 +89,12 @@ class PlayerLSL(BasePlayer):
     streamed on a channel correspond to the duration of the :class:`~mne.Annotations`.
     Thus, a sample on this :class:`~mne_lsl.lsl.StreamOutlet` is a one-hot encoded
     vector of the :class:`~mne.Annotations` description/duration.
+
+    .. note::
+
+        If the duration of an annotatation is ``0``, then the one-hot encoded vector
+        becomes a null vector. In this special case, the value ``-1`` is encoded and
+        denotes an annotation with a duration of ``0``.
     """
 
     _name: Incomplete

tests/player/test_player_lsl.py

@@ -459,6 +459,47 @@ def test_player_annotations(raw_annotations, close_io, chunk_size, request):
     player.stop()
 
 
+@pytest.mark.slow
+def test_player_annotations_no_duration(raw_annotations, close_io, chunk_size, request):
+    """Test player with annotations."""
+    name = f"P_{request.node.name}"
+    source_id = uuid.uuid4().hex
+    annotations = sorted(set(raw_annotations.annotations.description))
+    raw_annotations.annotations.duration.fill(0)  # overwrite durations
+    player = Player(
+        raw_annotations, chunk_size=chunk_size, name=name, source_id=source_id
+    )
+    assert f"Player: {name}" in repr(player)
+    assert player.name == name
+    assert player.source_id == source_id
+    assert player.fname == Path(raw_annotations.filenames[0])
+    streams = resolve_streams(timeout=0.1)
+    assert (name, source_id) not in [
+        (stream.name, stream.source_id) for stream in streams
+    ]
+    player.start()
+    streams = resolve_streams(timeout=2)
+    assert (name, source_id) in [(stream.name, stream.source_id) for stream in streams]
+    assert (f"{name}-annotations", source_id) in [
+        (stream.name, stream.source_id) for stream in streams
+    ]
+    # compare with a Stream object for simplicity
+    stream = Stream(bufsize=40, stype="annotations", source_id=source_id)
+    stream.connect(processing_flags=["clocksync"])
+    assert stream.info["ch_names"] == annotations
+    time.sleep(3)  # acquire some annotations
+    for picks in ("bad_test", "test2", "test3"):
+        data, ts = stream.get_data(picks=picks)
+        data = data.squeeze()
+        assert ts.size == data.size
+        idx = np.where(data != 0.0)[0]
+        assert_allclose(data[idx], [-1] * idx.size)
+    # clean-up
+    stream.disconnect()
+    close_io()
+    player.stop()
+
+
 @pytest.fixture
 def raw_annotations_1000_samples() -> BaseRaw:
     """Return a 1000 sample raw object with annotations."""

tutorials/20_player_annotations.py

@@ -22,6 +22,11 @@
 channels, each corresponding to one of the 3 descriptions. When an annotation is
 streamed, it's duration is encoded as the value on its channel while the other channels
 remain to zero.
+
+.. note::
+
+    Annotation with a duration equal to zero are special cased and yield an encoded
+    value of ``-1``.
 """
 
 # sphinx_gallery_thumbnail_number = 2