ENH: Add initial BCI2000 .dat reader (preload-only) (#13699)

Co-authored-by: pre-commit-ci[bot] <66853113+pre-commit-ci[bot]@users.noreply.github.com>
Co-authored-by: autofix-ci[bot] <114827586+autofix-ci[bot]@users.noreply.github.com>
Co-authored-by: Eric Larson <larson.eric.d@gmail.com>

Author: 4 people

doc/api/reading_raw_data.rst

@@ -16,6 +16,7 @@ Reading raw data
    read_raw
    read_raw_ant
    read_raw_artemis123
+   read_raw_bci2k
    read_raw_bdf
    read_raw_boxy
    read_raw_brainvision

doc/changes/dev/13699.newfeature.rst

@@ -0,0 +1 @@
+Add support for reading BCI2000 ``.dat`` files via :func:`mne.io.read_raw_bci2k`, and an example :file:`examples/io/read_bci2k.py` for downloading and visualizing BCI2000 data, by :newcontrib:`Hansuja Budhiraja`.

doc/conf.py

@@ -291,6 +291,7 @@
     "EpochsEEGLAB": "mne.Epochs",
     "EpochsKIT": "mne.Epochs",
     "RawANT": "mne.io.Raw",
+    "RawBCI2k": "mne.io.Raw",
     "RawBOXY": "mne.io.Raw",
     "RawBrainVision": "mne.io.Raw",
     "RawBTi": "mne.io.Raw",

doc/sphinxext/related_software_nodeps.txt

@@ -3,3 +3,4 @@ cross-domain-saliency-maps
 fsleyes
 mne-kit-gui
 mne-videobrowser
+hedtools  # because it limits our Pandas version currently

examples/io/read_bci2k.py

@@ -0,0 +1,66 @@
+"""
+======================
+Reading BCI2000 files
+======================
+
+In this example, we use MNE-Python to read a BCI2000 ``.dat`` file.
+BCI2000 is a general-purpose brain-computer interface (BCI) system widely
+used in EEG research. The file is downloaded from the MNE testing data
+repository using ``pooch``.
+"""  # noqa: D205 D400
+
+# Authors: The MNE-Python contributors.
+# License: BSD-3-Clause
+# Copyright the MNE-Python contributors.
+
+import pooch
+
+import mne
+
+# %%
+# First, we download the sample BCI2000 ``.dat`` file using ``pooch``.
+
+data_dir = mne.datasets.default_path() / "bci2k_data"
+data_dir.mkdir(exist_ok=True)
+
+fname = pooch.retrieve(
+    url="https://raw.githubusercontent.com/mne-tools/mne-testing-data/master/BCI2k/bci2k_test.dat",
+    known_hash="sha256:8efc7b5f700660a044086cb1449806ca408c2e6d32d9338c32e1bf31ce3ca9cb",
+    path=data_dir,
+)
+
+# %%
+# Now we can read the file using :func:`mne.io.read_raw_bci2k`.
+# Note that ``preload=True`` is required for BCI2000 files.
+
+raw = mne.io.read_raw_bci2k(fname, preload=True)
+print(raw.info)
+
+# %%
+# We can inspect the object representation, channel names, types, sampling
+# frequency, and recording duration.
+
+print(raw)
+print(f"Channel names : {raw.ch_names}")
+print(f"Channel types : {raw.get_channel_types()}")
+print(f"Sampling freq : {raw.info['sfreq']} Hz")
+print(f"Duration      : {raw.times[-1]:.2f} s")
+print(f"n_channels    : {raw.info['nchan']}")
+print(f"Data shape    : {raw.get_data().shape}  (n_channels, n_samples)")
+
+# %%
+# If the BCI2000 file contains a ``StimulusCode`` state, it is automatically
+# mapped to a ``STI 014`` stim channel. We can extract events from it using
+# :func:`mne.find_events`.
+
+if "STI 014" in raw.ch_names:
+    events = mne.find_events(raw, shortest_event=1)
+    print(f"Found {len(events)} events")
+    print(mne.count_events(events))
+else:
+    print("No stim channel found in this file.")
+
+# %%
+# Finally, we can visualize the raw data.
+
+raw.plot(duration=5, n_channels=len(raw.ch_names), scalings="auto")

mne/datasets/config.py

@@ -87,7 +87,7 @@
 # update the checksum in the MNE_DATASETS dict below, and change version
 # here: ↓↓↓↓↓↓↓↓
 RELEASES = dict(
-    testing="0.172",
+    testing="0.173",
     misc="0.27",
     phantom_kit="0.2",
     ucl_opm_auditory="0.2",
@@ -115,7 +115,7 @@
 # Testing and misc are at the top as they're updated most often
 MNE_DATASETS["testing"] = dict(
     archive_name=f"{TESTING_VERSIONED}.tar.gz",
-    hash="md5:9d031f1a91d2bd903a9464ca2cd7dc09",
+    hash="md5:0973c25cd0e3ca43a75ea6953ace1daa",
     url=(
         "https://codeload.github.com/mne-tools/mne-testing-data/"
         f"tar.gz/{RELEASES['testing']}"

mne/io/__init__.pyi

@@ -19,6 +19,7 @@ __all__ = [
     "read_raw",
     "read_raw_ant",
     "read_raw_artemis123",
+    "read_raw_bci2k",
     "read_raw_bdf",
     "read_raw_boxy",
     "read_raw_brainvision",
@@ -65,6 +66,7 @@ from .ant import read_raw_ant
 from .array import RawArray
 from .artemis123 import read_raw_artemis123
 from .base import BaseRaw, concatenate_raws, match_channel_orders
+from .bci2k import read_raw_bci2k
 from .besa import read_evoked_besa
 from .boxy import read_raw_boxy
 from .brainvision import read_raw_brainvision

mne/io/_read_raw.py

@@ -26,6 +26,7 @@ def _get_supported():
     from . import (
         read_raw_ant,
         read_raw_artemis123,
+        read_raw_bci2k,
         read_raw_bdf,
         read_raw_boxy,
         read_raw_brainvision,
@@ -79,7 +80,10 @@ def _get_supported():
         ".ds": dict(CTF=read_raw_ctf),
         ".txt": dict(BOXY=read_raw_boxy),
         # Curry
-        ".dat": dict(CURRY=read_raw_curry),
+        ".dat": dict(
+            CURRY=read_raw_curry,
+            BCI2K=read_raw_bci2k,
+        ),
         ".dap": dict(CURRY=read_raw_curry),
         ".rs3": dict(CURRY=read_raw_curry),
         ".cdt": dict(CURRY=read_raw_curry),
@@ -130,6 +134,7 @@ def read_raw(fname, *, preload=False, verbose=None, **kwargs) -> BaseRaw:
 
     * `~mne.io.read_raw_ant`
     * `~mne.io.read_raw_artemis123`
+    * `~mne.io.read_raw_bci2k`
     * `~mne.io.read_raw_bdf`
     * `~mne.io.read_raw_boxy`
     * `~mne.io.read_raw_brainvision`

mne/io/bci2k/__init__.py

@@ -0,0 +1,5 @@
+# Authors: The MNE-Python contributors.
+# License: BSD-3-Clause
+# Copyright the MNE-Python contributors.
+
+from .bci2k import read_raw_bci2k, RawBCI2k