.. DO NOT EDIT.
.. THIS FILE WAS AUTOMATICALLY GENERATED BY SPHINX-GALLERY.
.. TO MAKE CHANGES, EDIT THE SOURCE PYTHON FILE:
.. "generated/tutorials/10_stream_recorder.py"
.. LINE NUMBERS ARE GIVEN BELOW.

.. only:: html

    .. note::
        :class: sphx-glr-download-link-note

        :ref:`Go to the end <sphx_glr_download_generated_tutorials_10_stream_recorder.py>`
        to download the full example code.

.. rst-class:: sphx-glr-example-title

.. _sphx_glr_generated_tutorials_10_stream_recorder.py:


StreamRecorder: resting-state recording
=======================================

A resting-state recording is a simple offline recording during which the brain
activity of a subject is measured in the absence of any stimulus or task. A
resting-state recording can be designed with a `~bsl.StreamRecorder`.

.. GENERATED FROM PYTHON SOURCE LINES 11-17

.. code-block:: Python


    # Authors: Mathieu Scheltienne <mathieu.scheltienne@fcbg.ch>
    #
    # License: LGPL-2.1









.. GENERATED FROM PYTHON SOURCE LINES 19-32

.. warning::

    Both `~bsl.StreamPlayer` and `~bsl.StreamRecorder` create a new process
    to stream or record data. On Windows, mutliprocessing suffers a couple of
    restrictions. The entry-point of a multiprocessing program should be
    protected with ``if __name__ == '__main__':`` to ensure it can safely
    import and run the module. More information on the
    `documentation for multiprocessing on Windows
    <https://docs.python.org/2/library/multiprocessing.html#windows>`_.

This example will use a sample EEG resting-state dataset that can be retrieve
with :ref:`bsl.datasets <api/utils:Datasets>`. The dataset is stored in the user home
directory in the folder ``bsl_data`` (e.g. ``C:\Users\User\bsl_data``).

.. GENERATED FROM PYTHON SOURCE LINES 34-44

.. code-block:: Python


    import os
    import time
    from pathlib import Path

    import mne

    from bsl import StreamPlayer, StreamRecorder, datasets
    from bsl.triggers import MockTrigger








.. GENERATED FROM PYTHON SOURCE LINES 45-47

To simulate an actual signal coming from an LSL stream, a `~bsl.StreamPlayer`
is used with a 40 seconds resting-state recording.

.. GENERATED FROM PYTHON SOURCE LINES 48-55

.. code-block:: Python


    stream_name = "StreamPlayer"
    fif_file = datasets.eeg_resting_state.data_path()
    player = StreamPlayer(stream_name, fif_file)
    player.start()
    print(player)





.. rst-class:: sphx-glr-script-out

 .. code-block:: none

    <Player: StreamPlayer | ON | /home/runner/bsl_data/eeg_sample/resting_state-raw.fif>




.. GENERATED FROM PYTHON SOURCE LINES 56-59

For this example, the folder ``bsl_data/examples`` located in the user home
directory will be used to stored recorded files. To ensure its existence,
`os.makedirs` is used.

.. GENERATED FROM PYTHON SOURCE LINES 60-65

.. code-block:: Python


    record_dir = Path("~/bsl_data/examples").expanduser()
    os.makedirs(record_dir, exist_ok=True)
    print(record_dir)





.. rst-class:: sphx-glr-script-out

 .. code-block:: none

    /home/runner/bsl_data/examples




.. GENERATED FROM PYTHON SOURCE LINES 66-89

For this simple offline recording, the goal is to start a
`~bsl.StreamRecorder`, send an event on a trigger to mark the beginning of
the resting-state recording, wait for a defined duration, and stop the
recording.

By default, a `~bsl.StreamRecorder` does not require any argument. The
current working directory is used to record data from all available streams
in files named based on the date/time timestamp at which the recorder is
started.

To record only a subset of the available streams with a specific file name
and in a specific directory, the arguments ``record_dir``, ``fname`` and
``stream_name`` must be provided.

For this example, the directory used to store recordings is
``bsl_data/examples`` and the file name will start with
``example-resting-state``.

.. note::

    By default, the `~bsl.StreamRecorder.start` method is blocking and will
    wait for the recording to start. This behavior can be changed with the
    ``blocking`` argument.

.. GENERATED FROM PYTHON SOURCE LINES 90-95

.. code-block:: Python


    recorder = StreamRecorder(record_dir, fname="example-resting-state")
    recorder.start()
    print(recorder)





.. rst-class:: sphx-glr-script-out

 .. code-block:: none

    <Recorder: All streams | ON | /home/runner/bsl_data/examples>




.. GENERATED FROM PYTHON SOURCE LINES 96-100

Now that a `~bsl.StreamRecorder` is started and is acquiring data, a trigger
to mark the beginning of the segment of interest is created. For this
example, a `~bsl.triggers.MockTrigger` is used, but this example
would be equally valid with a different type of trigger.

.. GENERATED FROM PYTHON SOURCE LINES 101-104

.. code-block:: Python


    trigger = MockTrigger()








.. GENERATED FROM PYTHON SOURCE LINES 105-107

To mark the beginning of the segment of interest in the recording, a signal
is sent on the trigger. For this example, the event value (1) is used.

.. GENERATED FROM PYTHON SOURCE LINES 108-111

.. code-block:: Python


    trigger.signal(1)








.. GENERATED FROM PYTHON SOURCE LINES 112-113

Finally, after the appropriate duration, the recording is interrupted.

.. GENERATED FROM PYTHON SOURCE LINES 114-120

.. code-block:: Python


    time.sleep(2)  # 2 seconds duration
    del trigger
    recorder.stop()
    print(recorder)





.. rst-class:: sphx-glr-script-out

 .. code-block:: none

    <Recorder: All streams | OFF | /home/runner/bsl_data/examples>




.. GENERATED FROM PYTHON SOURCE LINES 121-130

A `~bsl.StreamRecorder` records data in ``.pcl`` format. This file can be
open with `pickle.load`, and is automatically converted to a `~mne.io.Raw`
FIF file in a subdirectory ``fif``. The recorded files name syntax is:

- If ``fname`` is not provided: ``[date/time timestamp]-[stream]-raw.fif``
- If ``fname`` is provided: ``[fname]-[stream]-raw.fif``

Where ``stream`` is the name of the recorded LSL stream. Thus, one file is
created for each stream being recorded.

.. GENERATED FROM PYTHON SOURCE LINES 131-138

.. code-block:: Python


    fname = record_dir / "fif" / "example-resting-state-StreamPlayer-raw.fif"
    raw = mne.io.read_raw_fif(fname, preload=True)
    print(raw)
    events = mne.find_events(raw, stim_channel="TRIGGER")
    print(events)





.. rst-class:: sphx-glr-script-out

 .. code-block:: none

    <Raw | example-resting-state-StreamPlayer-raw.fif, 65 x 1424 (2.8 s), ~781 kB, data loaded>
    []




.. GENERATED FROM PYTHON SOURCE LINES 139-142

As for the `~bsl.StreamPlayer`, the `~bsl.StreamRecorder` can be used as a
context manager. The context manager takes care of starting and stopping the
recording.

.. GENERATED FROM PYTHON SOURCE LINES 143-147

.. code-block:: Python


    with StreamRecorder(record_dir):
        time.sleep(1)








.. GENERATED FROM PYTHON SOURCE LINES 148-165

As for the `~bsl.StreamPlayer`, the `~bsl.StreamRecorder` can be started via
command-line when a LSL stream is accessible on the network.

Example assuming:

- the current working directory is ``bsl_data`` in the user home directory
- the stream to connect to is named ``MyStream``
- the recorded file naming scheme is ``test-[stream]-raw.fif``, i.e.
  ``test-MyStream-raw.fif``

.. code-block:: console

    $ bsl_stream_recorder -d examples -f test -s MyStream

.. image:: ../../_static/stream_recorder/stream_recorder_cli.gif
   :alt: StreamRecorder
   :align: center

.. GENERATED FROM PYTHON SOURCE LINES 168-169

| Stop the mock LSL stream used in this example.

.. GENERATED FROM PYTHON SOURCE LINES 169-171

.. code-block:: Python


    player.stop()








.. rst-class:: sphx-glr-timing

   **Total running time of the script:** (0 minutes 8.327 seconds)

**Estimated memory usage:**  204 MB


.. _sphx_glr_download_generated_tutorials_10_stream_recorder.py:

.. only:: html

  .. container:: sphx-glr-footer sphx-glr-footer-example

    .. container:: sphx-glr-download sphx-glr-download-jupyter

      :download:`Download Jupyter notebook: 10_stream_recorder.ipynb <10_stream_recorder.ipynb>`

    .. container:: sphx-glr-download sphx-glr-download-python

      :download:`Download Python source code: 10_stream_recorder.py <10_stream_recorder.py>`

    .. container:: sphx-glr-download sphx-glr-download-zip

      :download:`Download zipped: 10_stream_recorder.zip <10_stream_recorder.zip>`


.. only:: html

 .. rst-class:: sphx-glr-signature

    `Gallery generated by Sphinx-Gallery <https://sphinx-gallery.github.io>`_