Add tutorial about epochs and expose base stream class

.github/actions/get-testing-dataset/action.yaml

@@ -48,6 +48,7 @@ runs:
       run: rm mne_lsl_dataset_version.txt
 
     - name: Cache MNE sample dataset
+      if: ${{ inputs.mne-sample == 'true' }}
       id: cache_mne_sample
       uses: actions/cache@v4
       with:

.github/actions/retry-step/action.yaml

@@ -54,6 +54,7 @@ runs:
             eval $command_between_retries
           fi
 
+          echo "Retrying command after $exit_code error in attempt $attempt."
           attempt=$((attempt + 1))
           sleep 1
         done

.github/workflows/doc.yaml

@@ -37,7 +37,6 @@ jobs:
         with:
           sample: "true"
           testing: "false"
-          mne-sample: "true"
       - name: Build doc
         uses: ./.github/actions/retry-step
         with:

doc/api/abstract.rst

@@ -0,0 +1,16 @@
+Abstraction layer
+-----------------
+
+.. currentmodule:: mne_lsl.stream
+
+An abstraction layer is provided to create a ``Stream`` object that uses a different
+communication protocol than LSL. An object inheriting from
+:class:`~mne_lsl.stream.BaseStream` will be compatible with other objects from
+``mne-lsl``. For instance, it will be possible to epoch the stream with
+:class:`~mne_lsl.stream.EpochsStream`.
+
+.. autosummary::
+    :toctree: ../generated/api
+    :nosignatures:
+
+    BaseStream

doc/api/index.rst

@@ -17,6 +17,8 @@ This is the reference for classes (``CamelCase`` names) and functions
 
 .. include:: lsl (low-level).rst
 
+.. include:: abstract.rst
+
 .. include:: utilities.rst
 
 .. include:: legacy.rst

doc/api/most-used classes.rst

@@ -9,7 +9,8 @@ Stream
 ~~~~~~
 
 A ``Stream`` uses an `MNE <mne stable_>`_-like API to efficiently interacts with a
-numerical stream.
+numerical stream. ``Stream`` objects inherit from the abstract object
+:class:`~mne_lsl.stream.BaseStream`.
 
 .. currentmodule:: mne_lsl.stream
 
@@ -22,7 +23,7 @@ numerical stream.
 EpochsStream
 ~~~~~~~~~~~~
 
-An ``EpochsStream`` can be used to create epochs from a stream.
+An ``EpochsStream`` can be used to create epochs from a ``Stream``.
 
 .. currentmodule:: mne_lsl.stream
 

doc/changes/latest.rst

@@ -21,6 +21,8 @@ Version 1.5
 
 - Add ``exclude='bads'`` argument to :meth:`~mne_lsl.stream.StreamLSL.get_data` to control exclusion from ``picks`` (:pr:`258` by `Mathieu Scheltienne`_)
 - Add :class:`~mne_lsl.stream.EpochsStream` to epoch a Stream object object on the fly (:pr:`258` by `Mathieu Scheltienne`_)
+- Add tutorial about :class:`~mne_lsl.stream.EpochsStream` (:pr:`302` by `Mathieu Scheltienne`_)
+- Expose the abstract :class:`~mne_lsl.stream.BaseStream` object to create custom stream objects relying on different communication protocols (:pr:`302` by `Mathieu Scheltienne`_)
 
 Infrastructure
 --------------

examples/30_real_time_evoked_responses.py

@@ -9,23 +9,28 @@
 import numpy as np
 from matplotlib import pyplot as plt
 from mne import EvokedArray, combine_evoked
-from mne.datasets import sample
 from mne.io import read_raw_fif
 
+from mne_lsl.datasets import sample
 from mne_lsl.player import PlayerLSL
 from mne_lsl.stream import EpochsStream, StreamLSL
 from mne_lsl.utils.logs import logger
 
 # dataset used in the example
-data_path = sample.data_path()
-fname = data_path / "MEG" / "sample" / "sample_audvis_raw.fif"
-raw = read_raw_fif(fname, preload=False).pick(("meg", "stim")).crop(3, 212).load_data()
+fname = sample.data_path() / "mne-sample" / "sample_audvis_raw.fif"
+raw = read_raw_fif(fname, preload=False).pick(("meg", "stim")).load_data()
 
 # %%
 # First, we create a mock stream with :class:`mne_lsl.player.PlayerLSL` from the sample
 # dataset and connect a :class:`~mne_lsl.stream.StreamLSL` to it. Then, we attach a
 # :class:`~mne_lsl.stream.EpochsStream` object to create epochs from the LSL stream.
 # The epochs will be created around the event ID ``1`` from the ``'STI 014'`` channel.
+#
+# .. note::
+#
+#     A ``chunk_size`` of 200 samples is used here to ensure stability and reliability
+#     while building the documentation on the CI. In practice, a ``chunk_size`` of 200
+#     samples is too large to represent a real-time application.
 
 with PlayerLSL(raw, chunk_size=200, name="real-time-evoked-example"):
     stream = StreamLSL(bufsize=4, name="real-time-evoked-example")

mne_lsl/lsl/tests/test_stream_info.py

@@ -232,7 +232,7 @@ def test_stream_info_desc_from_info(close_io):
     compare_infos(info, info_retrieved)
 
     # test with FIFF file from the MNE sample dataset
-    fname = testing.data_path() / "sample_audvis_raw.fif"
+    fname = testing.data_path() / "mne-sample" / "sample_audvis_raw.fif"
     raw = read_raw_fif(fname, preload=False)
     sinfo = StreamInfo(
         "test", "", len(raw.ch_names), raw.info["sfreq"], np.float32, uuid.uuid4().hex

mne_lsl/player/player_lsl.py

@@ -141,6 +141,7 @@ def __init__(
             self._sinfo_annotations.set_channel_types("annotations")
             self._sinfo_annotations.set_channel_units("none")
             self._annotations_idx = self._raw.time_as_index(self._raw.annotations.onset)
+            self._annotations_idx -= self._raw.first_samp
         else:
             self._sinfo_annotations = None
             self._annotations_idx = None
@@ -319,7 +320,12 @@ def _stream_annotations(
             return None
         # estimate LSL timestamp of each annotation
         timestamps = (
-            start_timestamp + self.annotations.onset[idx] - self._raw.times[start]
+            start_timestamp
+            + (
+                self.annotations.onset[idx]
+                - self._raw.first_samp / self._raw.info["sfreq"]
+            )
+            - self._raw.times[start]
         )
         # one-hot encode the description and duration in the channels
         idx_ = np.array(

mne_lsl/stream/__init__.py

@@ -1,3 +1,4 @@
-from . import epochs, stream_lsl
+from . import base, epochs, stream_lsl
+from .base import BaseStream
 from .epochs import EpochsStream
 from .stream_lsl import StreamLSL