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

.. only:: html

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

        Click :ref:`here <sphx_glr_download_auto_examples_plot_dataset_example.py>`
        to download the full example code

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

.. _sphx_glr_auto_examples_plot_dataset_example.py:

MOABB Dataset Example
========================

In this example, we show how to fetch and prepare a MOABB dataset for usage
with Braindecode.

.. GENERATED FROM PYTHON SOURCE LINES 7-22

.. code-block:: default


    # Authors: Lukas Gemein <l.gemein@gmail.com>
    #          Hubert Banville <hubert.jbanville@gmail.com>
    #          Simon Brandt <simonbrandt@protonmail.com>
    #
    # License: BSD (3-clause)

    import matplotlib.pyplot as plt
    from IPython.display import display

    from braindecode.datasets import MOABBDataset
    from braindecode.datautil.windowers import \
        create_windows_from_events, create_fixed_length_windows
    from braindecode.datautil.preprocess import preprocess, Preprocessor








.. GENERATED FROM PYTHON SOURCE LINES 23-24

First, we create a dataset based on BCIC IV 2a fetched with MOABB,

.. GENERATED FROM PYTHON SOURCE LINES 24-26

.. code-block:: default

    ds = MOABBDataset(dataset_name="BNCI2014001", subject_ids=[1])





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

 Out:

 .. code-block:: none

    48 events found
    Event IDs: [1 2 3 4]
    48 events found
    Event IDs: [1 2 3 4]
    48 events found
    Event IDs: [1 2 3 4]
    48 events found
    Event IDs: [1 2 3 4]
    48 events found
    Event IDs: [1 2 3 4]
    48 events found
    Event IDs: [1 2 3 4]
    48 events found
    Event IDs: [1 2 3 4]
    48 events found
    Event IDs: [1 2 3 4]
    48 events found
    Event IDs: [1 2 3 4]
    48 events found
    Event IDs: [1 2 3 4]
    48 events found
    Event IDs: [1 2 3 4]
    48 events found
    Event IDs: [1 2 3 4]




.. GENERATED FROM PYTHON SOURCE LINES 27-28

ds has a pandas DataFrame with additional description of its internal datasets

.. GENERATED FROM PYTHON SOURCE LINES 28-30

.. code-block:: default

    display(ds.description)





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

 Out:

 .. code-block:: none

        subject    session    run
    0         1  session_T  run_0
    1         1  session_T  run_1
    2         1  session_T  run_2
    3         1  session_T  run_3
    4         1  session_T  run_4
    5         1  session_T  run_5
    6         1  session_E  run_0
    7         1  session_E  run_1
    8         1  session_E  run_2
    9         1  session_E  run_3
    10        1  session_E  run_4
    11        1  session_E  run_5




.. GENERATED FROM PYTHON SOURCE LINES 31-34

We can iterate through ds which yields one time point of a continuous signal x,
and a target y (which can be None if targets are not defined for the entire
continuous signal).

.. GENERATED FROM PYTHON SOURCE LINES 34-38

.. code-block:: default

    for x, y in ds:
        print(x.shape, y)
        break





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

 Out:

 .. code-block:: none

    (26, 1) None




.. GENERATED FROM PYTHON SOURCE LINES 39-41

We can apply preprocessing transforms that are defined in mne and work
in-place, such as resampling, bandpass filtering, or electrode selection.

.. GENERATED FROM PYTHON SOURCE LINES 41-49

.. code-block:: default

    preprocessors = [
        Preprocessor('pick_types', eeg=True, meg=False, stim=True),
        Preprocessor('resample', sfreq=100)
    ]
    print(ds.datasets[0].raw.info["sfreq"])
    preprocess(ds, preprocessors)
    print(ds.datasets[0].raw.info["sfreq"])





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

 Out:

 .. code-block:: none

    250.0
    48 events found
    Event IDs: [1 2 3 4]
    48 events found
    Event IDs: [1 2 3 4]
    48 events found
    Event IDs: [1 2 3 4]
    48 events found
    Event IDs: [1 2 3 4]
    48 events found
    Event IDs: [1 2 3 4]
    48 events found
    Event IDs: [1 2 3 4]
    48 events found
    Event IDs: [1 2 3 4]
    48 events found
    Event IDs: [1 2 3 4]
    48 events found
    Event IDs: [1 2 3 4]
    48 events found
    Event IDs: [1 2 3 4]
    48 events found
    Event IDs: [1 2 3 4]
    48 events found
    Event IDs: [1 2 3 4]
    48 events found
    Event IDs: [1 2 3 4]
    48 events found
    Event IDs: [1 2 3 4]
    48 events found
    Event IDs: [1 2 3 4]
    48 events found
    Event IDs: [1 2 3 4]
    48 events found
    Event IDs: [1 2 3 4]
    48 events found
    Event IDs: [1 2 3 4]
    48 events found
    Event IDs: [1 2 3 4]
    48 events found
    Event IDs: [1 2 3 4]
    48 events found
    Event IDs: [1 2 3 4]
    48 events found
    Event IDs: [1 2 3 4]
    48 events found
    Event IDs: [1 2 3 4]
    48 events found
    Event IDs: [1 2 3 4]
    100.0




.. GENERATED FROM PYTHON SOURCE LINES 50-52

We can easily split ds based on a criteria applied to the description
DataFrame:

.. GENERATED FROM PYTHON SOURCE LINES 52-55

.. code-block:: default

    subsets = ds.split("session")
    print({subset_name: len(subset) for subset_name, subset in subsets.items()})





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

 Out:

 .. code-block:: none

    {'session_E': 232164, 'session_T': 232164}




.. GENERATED FROM PYTHON SOURCE LINES 56-57

Next, we use a windower to extract events from the dataset based on events:

.. GENERATED FROM PYTHON SOURCE LINES 57-62

.. code-block:: default

    windows_ds = create_windows_from_events(
        ds, trial_start_offset_samples=0, trial_stop_offset_samples=100,
        window_size_samples=400, window_stride_samples=100,
        drop_last_window=False)





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

 Out:

 .. code-block:: none

    Used Annotations descriptions: ['feet', 'left_hand', 'right_hand', 'tongue']
    Adding metadata with 4 columns
    Replacing existing metadata with 4 columns
    96 matching events found
    No baseline correction applied
    0 projection items activated
    Loading data for 96 events and 400 original time points ...
    0 bad epochs dropped
    Used Annotations descriptions: ['feet', 'left_hand', 'right_hand', 'tongue']
    Adding metadata with 4 columns
    Replacing existing metadata with 4 columns
    96 matching events found
    No baseline correction applied
    0 projection items activated
    Loading data for 96 events and 400 original time points ...
    0 bad epochs dropped
    Used Annotations descriptions: ['feet', 'left_hand', 'right_hand', 'tongue']
    Adding metadata with 4 columns
    Replacing existing metadata with 4 columns
    96 matching events found
    No baseline correction applied
    0 projection items activated
    Loading data for 96 events and 400 original time points ...
    0 bad epochs dropped
    Used Annotations descriptions: ['feet', 'left_hand', 'right_hand', 'tongue']
    Adding metadata with 4 columns
    Replacing existing metadata with 4 columns
    96 matching events found
    No baseline correction applied
    0 projection items activated
    Loading data for 96 events and 400 original time points ...
    0 bad epochs dropped
    Used Annotations descriptions: ['feet', 'left_hand', 'right_hand', 'tongue']
    Adding metadata with 4 columns
    Replacing existing metadata with 4 columns
    96 matching events found
    No baseline correction applied
    0 projection items activated
    Loading data for 96 events and 400 original time points ...
    0 bad epochs dropped
    Used Annotations descriptions: ['feet', 'left_hand', 'right_hand', 'tongue']
    Adding metadata with 4 columns
    Replacing existing metadata with 4 columns
    96 matching events found
    No baseline correction applied
    0 projection items activated
    Loading data for 96 events and 400 original time points ...
    0 bad epochs dropped
    Used Annotations descriptions: ['feet', 'left_hand', 'right_hand', 'tongue']
    Adding metadata with 4 columns
    Replacing existing metadata with 4 columns
    96 matching events found
    No baseline correction applied
    0 projection items activated
    Loading data for 96 events and 400 original time points ...
    0 bad epochs dropped
    Used Annotations descriptions: ['feet', 'left_hand', 'right_hand', 'tongue']
    Adding metadata with 4 columns
    Replacing existing metadata with 4 columns
    96 matching events found
    No baseline correction applied
    0 projection items activated
    Loading data for 96 events and 400 original time points ...
    0 bad epochs dropped
    Used Annotations descriptions: ['feet', 'left_hand', 'right_hand', 'tongue']
    Adding metadata with 4 columns
    Replacing existing metadata with 4 columns
    96 matching events found
    No baseline correction applied
    0 projection items activated
    Loading data for 96 events and 400 original time points ...
    0 bad epochs dropped
    Used Annotations descriptions: ['feet', 'left_hand', 'right_hand', 'tongue']
    Adding metadata with 4 columns
    Replacing existing metadata with 4 columns
    96 matching events found
    No baseline correction applied
    0 projection items activated
    Loading data for 96 events and 400 original time points ...
    0 bad epochs dropped
    Used Annotations descriptions: ['feet', 'left_hand', 'right_hand', 'tongue']
    Adding metadata with 4 columns
    Replacing existing metadata with 4 columns
    96 matching events found
    No baseline correction applied
    0 projection items activated
    Loading data for 96 events and 400 original time points ...
    0 bad epochs dropped
    Used Annotations descriptions: ['feet', 'left_hand', 'right_hand', 'tongue']
    Adding metadata with 4 columns
    Replacing existing metadata with 4 columns
    96 matching events found
    No baseline correction applied
    0 projection items activated
    Loading data for 96 events and 400 original time points ...
    0 bad epochs dropped




.. GENERATED FROM PYTHON SOURCE LINES 63-67

We can iterate through the windows_ds which yields a window x,
a target y, and window_ind (which itself contains `i_window_in_trial`,
`i_start_in_trial`, and `i_stop_in_trial`, which are required for combining
window predictions in the scorer).

.. GENERATED FROM PYTHON SOURCE LINES 67-71

.. code-block:: default

    for x, y, window_ind in windows_ds:
        print(x.shape, y, window_ind)
        break





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

 Out:

 .. code-block:: none

    Loading data for 1 events and 400 original time points ...
    (23, 400) 3 [0, 300, 700]




.. GENERATED FROM PYTHON SOURCE LINES 72-73

We visually inspect the windows:

.. GENERATED FROM PYTHON SOURCE LINES 73-83

.. code-block:: default

    max_i = 2
    fig, ax_arr = plt.subplots(1, max_i + 1, figsize=((max_i + 1) * 7, 5),
                               sharex=True, sharey=True)
    for i, (x, y, window_ind) in enumerate(windows_ds):
        ax_arr[i].plot(x.T)
        ax_arr[i].set_ylim(-0.0002, 0.0002)
        ax_arr[i].set_title(f"label={y}")
        if i == max_i:
            break




.. image:: /auto_examples/images/sphx_glr_plot_dataset_example_001.png
    :alt: label=3, label=3, label=0
    :class: sphx-glr-single-img


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

 Out:

 .. code-block:: none

    Loading data for 1 events and 400 original time points ...
    Loading data for 1 events and 400 original time points ...
    Loading data for 1 events and 400 original time points ...




.. GENERATED FROM PYTHON SOURCE LINES 84-86

Alternatively, we can create evenly spaced ("sliding") windows using a
different windower.

.. GENERATED FROM PYTHON SOURCE LINES 86-96

.. code-block:: default

    sliding_windows_ds = create_fixed_length_windows(
        ds, start_offset_samples=0, stop_offset_samples=0,
        window_size_samples=1200, window_stride_samples=1000,
        drop_last_window=False)

    print(len(sliding_windows_ds))
    for x, y, window_ind in sliding_windows_ds:
        print(x.shape, y, window_ind)
        break





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

 Out:

 .. code-block:: none

    /home/robintibor/work/braindecode-test/braindecode/braindecode/braindecode/datautil/windowers.py:174: UserWarning: Meaning of `trial_stop_offset_samples`=0 has changed, use `None` to indicate end of trial/recording. Using `None`.
      warnings.warn(
    Adding metadata with 4 columns
    Replacing existing metadata with 4 columns
    39 matching events found
    No baseline correction applied
    0 projection items activated
    Loading data for 39 events and 1200 original time points ...
    0 bad epochs dropped
    Adding metadata with 4 columns
    Replacing existing metadata with 4 columns
    39 matching events found
    No baseline correction applied
    0 projection items activated
    Loading data for 39 events and 1200 original time points ...
    0 bad epochs dropped
    Adding metadata with 4 columns
    Replacing existing metadata with 4 columns
    39 matching events found
    No baseline correction applied
    0 projection items activated
    Loading data for 39 events and 1200 original time points ...
    0 bad epochs dropped
    Adding metadata with 4 columns
    Replacing existing metadata with 4 columns
    39 matching events found
    No baseline correction applied
    0 projection items activated
    Loading data for 39 events and 1200 original time points ...
    0 bad epochs dropped
    Adding metadata with 4 columns
    Replacing existing metadata with 4 columns
    39 matching events found
    No baseline correction applied
    0 projection items activated
    Loading data for 39 events and 1200 original time points ...
    0 bad epochs dropped
    Adding metadata with 4 columns
    Replacing existing metadata with 4 columns
    39 matching events found
    No baseline correction applied
    0 projection items activated
    Loading data for 39 events and 1200 original time points ...
    0 bad epochs dropped
    Adding metadata with 4 columns
    Replacing existing metadata with 4 columns
    39 matching events found
    No baseline correction applied
    0 projection items activated
    Loading data for 39 events and 1200 original time points ...
    0 bad epochs dropped
    Adding metadata with 4 columns
    Replacing existing metadata with 4 columns
    39 matching events found
    No baseline correction applied
    0 projection items activated
    Loading data for 39 events and 1200 original time points ...
    0 bad epochs dropped
    Adding metadata with 4 columns
    Replacing existing metadata with 4 columns
    39 matching events found
    No baseline correction applied
    0 projection items activated
    Loading data for 39 events and 1200 original time points ...
    0 bad epochs dropped
    Adding metadata with 4 columns
    Replacing existing metadata with 4 columns
    39 matching events found
    No baseline correction applied
    0 projection items activated
    Loading data for 39 events and 1200 original time points ...
    0 bad epochs dropped
    Adding metadata with 4 columns
    Replacing existing metadata with 4 columns
    39 matching events found
    No baseline correction applied
    0 projection items activated
    Loading data for 39 events and 1200 original time points ...
    0 bad epochs dropped
    Adding metadata with 4 columns
    Replacing existing metadata with 4 columns
    39 matching events found
    No baseline correction applied
    0 projection items activated
    Loading data for 39 events and 1200 original time points ...
    0 bad epochs dropped
    468
    Loading data for 1 events and 1200 original time points ...
    (23, 1200) -1 [0, 0, 1200]




.. GENERATED FROM PYTHON SOURCE LINES 97-99

Transforms can also be applied on windows in the same way as shown
above on continuous data:

.. GENERATED FROM PYTHON SOURCE LINES 99-129

.. code-block:: default



    def crop_windows(windows, start_offset_samples, stop_offset_samples):
        fs = windows.info["sfreq"]
        windows.crop(tmin=start_offset_samples / fs, tmax=stop_offset_samples / fs,
                     include_tmax=False)


    epochs_preprocessors = [
        Preprocessor('pick_types', eeg=True, meg=False, stim=False),
        Preprocessor(crop_windows, apply_on_array=False, start_offset_samples=100,
                     stop_offset_samples=900)
    ]

    print(windows_ds.datasets[0].windows.info["ch_names"],
          len(windows_ds.datasets[0].windows.times))
    preprocess(windows_ds, epochs_preprocessors)
    print(windows_ds.datasets[0].windows.info["ch_names"],
          len(windows_ds.datasets[0].windows.times))

    max_i = 2
    fig, ax_arr = plt.subplots(1, max_i + 1, figsize=((max_i + 1) * 7, 5),
                               sharex=True, sharey=True)
    for i, (x, y, window_ind) in enumerate(windows_ds):
        ax_arr[i].plot(x.T)
        ax_arr[i].set_ylim(-0.0002, 0.0002)
        ax_arr[i].set_title(f"label={y}")
        if i == max_i:
            break




.. image:: /auto_examples/images/sphx_glr_plot_dataset_example_002.png
    :alt: label=3, label=3, label=0
    :class: sphx-glr-single-img


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

 Out:

 .. code-block:: none

    ['Fz', 'FC3', 'FC1', 'FCz', 'FC2', 'FC4', 'C5', 'C3', 'C1', 'Cz', 'C2', 'C4', 'C6', 'CP3', 'CP1', 'CPz', 'CP2', 'CP4', 'P1', 'Pz', 'P2', 'POz', 'stim'] 400
    Loading data for 96 events and 400 original time points ...
    /home/robintibor/work/braindecode-test/braindecode/braindecode/examples/plot_dataset_example.py:103: RuntimeWarning: tmax is not in epochs time interval. tmax is set to epochs.tmax
      windows.crop(tmin=start_offset_samples / fs, tmax=stop_offset_samples / fs,
    Loading data for 96 events and 400 original time points ...
    /home/robintibor/work/braindecode-test/braindecode/braindecode/examples/plot_dataset_example.py:103: RuntimeWarning: tmax is not in epochs time interval. tmax is set to epochs.tmax
      windows.crop(tmin=start_offset_samples / fs, tmax=stop_offset_samples / fs,
    Loading data for 96 events and 400 original time points ...
    /home/robintibor/work/braindecode-test/braindecode/braindecode/examples/plot_dataset_example.py:103: RuntimeWarning: tmax is not in epochs time interval. tmax is set to epochs.tmax
      windows.crop(tmin=start_offset_samples / fs, tmax=stop_offset_samples / fs,
    Loading data for 96 events and 400 original time points ...
    /home/robintibor/work/braindecode-test/braindecode/braindecode/examples/plot_dataset_example.py:103: RuntimeWarning: tmax is not in epochs time interval. tmax is set to epochs.tmax
      windows.crop(tmin=start_offset_samples / fs, tmax=stop_offset_samples / fs,
    Loading data for 96 events and 400 original time points ...
    /home/robintibor/work/braindecode-test/braindecode/braindecode/examples/plot_dataset_example.py:103: RuntimeWarning: tmax is not in epochs time interval. tmax is set to epochs.tmax
      windows.crop(tmin=start_offset_samples / fs, tmax=stop_offset_samples / fs,
    Loading data for 96 events and 400 original time points ...
    /home/robintibor/work/braindecode-test/braindecode/braindecode/examples/plot_dataset_example.py:103: RuntimeWarning: tmax is not in epochs time interval. tmax is set to epochs.tmax
      windows.crop(tmin=start_offset_samples / fs, tmax=stop_offset_samples / fs,
    Loading data for 96 events and 400 original time points ...
    /home/robintibor/work/braindecode-test/braindecode/braindecode/examples/plot_dataset_example.py:103: RuntimeWarning: tmax is not in epochs time interval. tmax is set to epochs.tmax
      windows.crop(tmin=start_offset_samples / fs, tmax=stop_offset_samples / fs,
    Loading data for 96 events and 400 original time points ...
    /home/robintibor/work/braindecode-test/braindecode/braindecode/examples/plot_dataset_example.py:103: RuntimeWarning: tmax is not in epochs time interval. tmax is set to epochs.tmax
      windows.crop(tmin=start_offset_samples / fs, tmax=stop_offset_samples / fs,
    Loading data for 96 events and 400 original time points ...
    /home/robintibor/work/braindecode-test/braindecode/braindecode/examples/plot_dataset_example.py:103: RuntimeWarning: tmax is not in epochs time interval. tmax is set to epochs.tmax
      windows.crop(tmin=start_offset_samples / fs, tmax=stop_offset_samples / fs,
    Loading data for 96 events and 400 original time points ...
    /home/robintibor/work/braindecode-test/braindecode/braindecode/examples/plot_dataset_example.py:103: RuntimeWarning: tmax is not in epochs time interval. tmax is set to epochs.tmax
      windows.crop(tmin=start_offset_samples / fs, tmax=stop_offset_samples / fs,
    Loading data for 96 events and 400 original time points ...
    /home/robintibor/work/braindecode-test/braindecode/braindecode/examples/plot_dataset_example.py:103: RuntimeWarning: tmax is not in epochs time interval. tmax is set to epochs.tmax
      windows.crop(tmin=start_offset_samples / fs, tmax=stop_offset_samples / fs,
    Loading data for 96 events and 400 original time points ...
    /home/robintibor/work/braindecode-test/braindecode/braindecode/examples/plot_dataset_example.py:103: RuntimeWarning: tmax is not in epochs time interval. tmax is set to epochs.tmax
      windows.crop(tmin=start_offset_samples / fs, tmax=stop_offset_samples / fs,
    ['Fz', 'FC3', 'FC1', 'FCz', 'FC2', 'FC4', 'C5', 'C3', 'C1', 'Cz', 'C2', 'C4', 'C6', 'CP3', 'CP1', 'CPz', 'CP2', 'CP4', 'P1', 'Pz', 'P2', 'POz'] 299




.. GENERATED FROM PYTHON SOURCE LINES 130-132

Again, we can easily split windows_ds based on some criteria in the
description DataFrame:

.. GENERATED FROM PYTHON SOURCE LINES 132-134

.. code-block:: default

    subsets = windows_ds.split("session")
    print({subset_name: len(subset) for subset_name, subset in subsets.items()})




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

 Out:

 .. code-block:: none

    {'session_E': 576, 'session_T': 576}





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

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


.. _sphx_glr_download_auto_examples_plot_dataset_example.py:


.. only :: html

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



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

     :download:`Download Python source code: plot_dataset_example.py <plot_dataset_example.py>`



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

     :download:`Download Jupyter notebook: plot_dataset_example.ipynb <plot_dataset_example.ipynb>`


.. only:: html

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

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