ENH: Add initial BCI2000 .dat reader (preload-only) by HansujaB · Pull Request #13699 · mne-tools/mne-python

HansujaB · 2026-02-26T20:56:18Z

Reference issue (if any)

What does this implement/fix?

This PR adds basic support for reading BCI2000 .dat files via:

mne.io.read_raw_bci2k()

The implementation:

Parses minimal required header fields
Decodes signal and state vector
Maps StimulusCode to STI 014 stim channel
Returns a Raw object using RawArray
Includes deterministic unit tests with a synthetic demo file

Tests

Synthetic .dat generator included in tests
Verifies:
- sampling rate
- number of samples
- stim channel creation
- correct StimulusCode decoding
- preload=False raises

Scope (Intentional Limitations)

preload=False is not supported (raises NotImplementedError)
Minimal header parsing (SamplingRate + State Vector Definition only)
Generic channel names (EEG1, EEG2, …)
No gain/scaling applied
Not added to _get_supported() (since .dat is already mapped to Curry)

The goal is to provide a correct, minimal reader that can be safely extended in follow-up PRs.

for more information, see https://pre-commit.ci

larsoner

I didn't look too deeply at the code, but looks like a reasonable start! With something like this we'd want to see it used somewhere, too -- is there a good file we could download using pooch in an example and use in an examples/io/something.py or similar? We could do something like what's done here

https://github.com/mne-tools/mne-bids/blob/15ee0e48179181c66705931683e16272dfd97a9a/examples/convert_fieldtrip_emg.py#L61

Also did you use AI tools in developing this code? If so please disclose the nature of AI tool usage

larsoner · 2026-03-02T16:30:04Z

mne/io/bci2k/tests/test_bci2k.py

+from mne.io.bci2k import RawBCI2k, read_raw_bci2k
+
+
+def _write_demo_bci2k(


A more modern way to do this would be to

Suggested change

def _write_demo_bci2k(

@pytest.fixture

def bci2k_path(tmp_path):

fname = tmp_path / "something"

...

return fname

and then you use this inside your test

@larsoner Thanks a lot for your review!
I searched for an example file but couldn't really find one, although I came across PhysioNet bigP3BCI dataset. The problem is , they converted .dat files to EDF + file header, so we can't use it !

What we can do is (use the same approach to generate a small example file) :
We can generate a small BCI2000 .dat file using a short P3Speller session with minimal channels and then host a trimmed version (a few seconds only) .
If this approach is acceptable I can work on it , Let me know!

Regarding AI usage , I looked upon the major stuff and algorithm development myself but for debugging and redundancy reduction, I took the help of AI tools to increase my efficiency!

We can generate a small BCI2000 .dat file using a short P3Speller session with minimal channels and then host a trimmed version (a few seconds only) .

This would be great, then we could add it to mne-testing-data and use it here

@larsoner Great! Should I open a separate PR to add the sample file to mne-testing-data, or can I include it in this PR?

@HansujaB you can make a PR to https://github.com/mne-tools/mne-testing-data

Please make sure the new testing file is super small! Like < 1mb if possible. You can crop the data in the file to be only 1-second long if needed.

@scott-huberty Thanks! I’ll generate a small trimmed .dat file and open a PR to mne-testing-data. It might take me a little while since I have exams this week, but I’ll try to get it up as soon as possible.

for more information, see https://pre-commit.ci

HansujaB · 2026-03-15T05:56:51Z

@larsoner @scott-huberty I have opened a PR for test file in mne-testing-data as discussed. While testing the dataset locally with the BCI2000 reader, I noticed a small parsing issue and have pushed a fix for that as well. Apologies for the delay!

…python into add-bci2000-reader

for more information, see https://pre-commit.ci

…python into add-bci2000-reader

for more information, see https://pre-commit.ci

HansujaB · 2026-03-17T21:47:24Z

@larsoner Since the mne-testing-data PR has been merged, I have updated the test to use the dataset from there. Please let me know if anything else needs to be changed.

larsoner · 2026-03-18T16:24:34Z

Looks like the style CI is unhappy, can you look? Once that's passing I can approve the other workflows

larsoner · 2026-03-18T16:25:28Z

Also looks like the main comment from #13699 (review) hasn't been addressed

HansujaB · 2026-03-18T20:25:50Z

Hi @larsoner, tests now use mne-testing-data , so the fixture suggestion no longer applies. Could you confirm if there's anything else from that thread that still needs addressing? Also pushed the style CI fixes. Thanks!

larsoner · 2026-03-18T21:13:33Z

Could you confirm if there's anything else from that thread that still needs addressing?

Yeah, the comment I linked to had this:

I didn't look too deeply at the code, but looks like a reasonable start! With something like this we'd want to see it used somewhere, too -- is there a good file we could download using pooch in an example and use in an examples/io/something.py or similar? We could do something like what's done here

https://github.com/mne-tools/mne-bids/blob/15ee0e48179181c66705931683e16272dfd97a9a/examples/convert_fieldtrip_emg.py#L61

I don't see any examples/io/* file modified usidng pooch or similar (or discussion about it above) ... ?

for more information, see https://pre-commit.ci

HansujaB · 2026-03-18T23:04:38Z

@larsoner I have added the example file!

HansujaB · 2026-03-19T10:17:43Z

@larsoner Right now , we are failing 2 tests

I checked , still version 0.172 of mne-testing-data is used so we are getting File not found error for test test_read_raw_bci2k
read_raw_bci2k is added to doc/api/reading_raw_data.rst but purposefully not added to _get_supported() so we are facing the following error
`FAILED mne/io/tests/test_read_raw.py::test_all_reader_documented - AssertionError: Functions missing from documentation:

Functions missing from read_raw:
read_raw_bci2k`

Should I remove it from doc/api/reading_raw_data.rst ?

larsoner · 2026-03-24T14:00:23Z

These errors are likely because it needs to be added to the API reference like other reading functions:

$ git grep "read_raw_edf" doc/api/
doc/api/reading_raw_data.rst:   read_raw_edf

HansujaB · 2026-03-24T14:17:36Z

@larsoner Actually it is added to the API reference as well !

larsoner · 2026-03-24T16:54:37Z

examples/io/read_bci2k.py

+
+fname = pooch.retrieve(
+    url="https://raw.githubusercontent.com/mne-tools/mne-testing-data/master/BCI2k/bci2k_test.dat",
+    known_hash="sha256:8efc7b5f700660a044086cb1449806ca408c2e6d32d9338c32e1bf31ce3ca9cb",


We should save to whatever this path is, plus maybe a new folder (if needed) bci_data or similar?

https://mne.tools/stable/generated/mne.datasets.default_path.html#mne.datasets.default_path

So something like

data_dir = mne.datasets.default_path() / "bci2k_data" data_dir.mkdir(exist_ok=True) ...

larsoner · 2026-03-24T16:55:20Z

mne/io/bci2k/bci2k.py

+    params = {}
+    state_defs = {}
+
+    def _parse_sampling_rate(val):


Can you move this outside the function? Nesting like this makes it hard to know which vars are from this function's scope and which are from the parent's

…le/io/read_bci2k.py file

HansujaB · 2026-03-24T21:07:02Z

@larsoner I have pushed the changes , let me know if something needs to be modified. Thanks!

HansujaB · 2026-03-24T21:43:11Z

@larsoner Right now , we are failing 2 tests

I checked , still version 0.172 of mne-testing-data is used so we are getting File not found error for test test_read_raw_bci2k

read_raw_bci2k is added to doc/api/reading_raw_data.rst but purposefully not added to _get_supported() so we are facing the following error
`FAILED mne/io/tests/test_read_raw.py::test_all_reader_documented - AssertionError: Functions missing from documentation:

Functions missing from read_raw: read_raw_bci2k`

Should I remove it from doc/api/reading_raw_data.rst ?

@larsoner We are still facing these 2 issues :(
I can't really understand how to fix them can you help me out?

larsoner · 2026-04-03T21:08:14Z

I'll push a commit to fix the doc linking error and finish the steps from https://github.com/mne-tools/mne-testing-data?tab=readme-ov-file#add-or-change-files-in-the-repo-for-use-with-mne to update the version

HansujaB · 2026-04-03T22:11:14Z

@larsoner Thanks a lot for the finishing touches!
Really sorry I missed the last step to change version here my bad.

larsoner · 2026-04-04T00:13:55Z

Thanks @HansujaB !

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

197649b

HansujaB requested review from agramfort, drammock and mscheltienne as code owners February 26, 2026 20:56

pre-commit-ci bot and others added 6 commits February 26, 2026 20:56

[pre-commit.ci] auto fixes from pre-commit.com hooks

2c83c2a

for more information, see https://pre-commit.ci

Merge branch 'main' into add-bci2000-reader

83d11de

MAINT: Address CI feedback (style and import fixes)

20a89f5

[pre-commit.ci] auto fixes from pre-commit.com hooks

31bb511

for more information, see https://pre-commit.ci

MAINT: Use explicit relative import for create_info

21d9519

DOC: Add read_raw_bci2k to reading_raw_data autosummary

fdca559

HansujaB requested a review from larsoner as a code owner February 27, 2026 16:36

DOC: Fix numpydoc format for read_raw_bci2k

77dc37f

larsoner reviewed Mar 2, 2026

View reviewed changes

DOC/MAINT: Document read_raw_bci2k and fix numpydoc/sphinx warnings

d871e26

HansujaB requested a review from larsoner March 2, 2026 22:58

DOC: Remove duplicate read_raw_bci2k from mne/io/tests/__init__.pyi

090d208

HansujaB force-pushed the add-bci2000-reader branch from d50fc36 to 090d208 Compare March 3, 2026 16:30

HansujaB mentioned this pull request Mar 15, 2026

ENH : Add BCI2k .dat test dataset mne-tools/mne-testing-data#133

Merged

HansujaB and others added 2 commits March 15, 2026 11:21

FIX: Improve BCI2000 header parsing for multi-field header line

142967e

[pre-commit.ci] auto fixes from pre-commit.com hooks

37f00ff

for more information, see https://pre-commit.ci

HansujaB and others added 6 commits March 18, 2026 02:55

TEST: use BCI2k test dataset from mne-testing-data in BCI2K reader tests

6f4033f

Merge branch 'add-bci2000-reader' of https://github.com/HansujaB/mne-…

bfc888d

…python into add-bci2000-reader

[pre-commit.ci] auto fixes from pre-commit.com hooks

4073dff

for more information, see https://pre-commit.ci

TEST : remove unused imports and variables in BCI2k reader test

dc50c11

Merge branch 'add-bci2000-reader' of https://github.com/HansujaB/mne-…

1e3b777

…python into add-bci2000-reader

[pre-commit.ci] auto fixes from pre-commit.com hooks

3c763ad

for more information, see https://pre-commit.ci

FIX: remove unused stim_data and _bci2k_states assignments

02c6d88

HansujaB and others added 2 commits March 19, 2026 04:33

ENH: add example for reading BCI2000 .dat files

346ae38

[pre-commit.ci] auto fixes from pre-commit.com hooks

8b1757e

for more information, see https://pre-commit.ci

larsoner reviewed Mar 24, 2026

View reviewed changes

HansujaB and others added 4 commits March 25, 2026 02:16

FIX: move nested function outside , add bci2k_data save path in examp…

3b16882

…le/io/read_bci2k.py file

Merge branch 'main' into add-bci2000-reader

5dff160

[autofix.ci] apply automated fixes

ab5c597

DOC : add changelog entry

c551e4d

FIX: Fixes

9c5dd22

larsoner enabled auto-merge (squash) April 3, 2026 21:21

larsoner added 2 commits April 3, 2026 17:29

FIX: Exception

b7465c8

FIX: More

63dfae1

larsoner added this to the 1.12 milestone Apr 3, 2026

FIX: Better

2da83bc

larsoner added 2 commits April 3, 2026 18:21

FIX: mark

52c16bb

Merge remote-tracking branch 'upstream/main' into add-bci2000-reader

8baf714

larsoner merged commit 9b14298 into mne-tools:main Apr 3, 2026
32 checks passed

		from mne.io.bci2k import RawBCI2k, read_raw_bci2k


		def _write_demo_bci2k(

-def _write_demo_bci2k(
+@pytest.fixture
+def bci2k_path(tmp_path):
+    fname = tmp_path / "something"
+    ...
+    return fname

Uh oh!

Conversation

HansujaB commented Feb 26, 2026

Reference issue (if any)

What does this implement/fix?

The implementation:

Tests

Scope (Intentional Limitations)

Uh oh!

larsoner left a comment

Choose a reason for hiding this comment

Uh oh!

larsoner Mar 2, 2026

Choose a reason for hiding this comment

Uh oh!

HansujaB Mar 2, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Choose a reason for hiding this comment

Uh oh!

larsoner Mar 4, 2026

Choose a reason for hiding this comment

Uh oh!

HansujaB Mar 4, 2026

Choose a reason for hiding this comment

Uh oh!

scott-huberty Mar 4, 2026

Choose a reason for hiding this comment

Uh oh!

HansujaB Mar 5, 2026

Choose a reason for hiding this comment

Uh oh!

HansujaB commented Mar 15, 2026

Uh oh!

HansujaB commented Mar 17, 2026

Uh oh!

larsoner commented Mar 18, 2026

Uh oh!

larsoner commented Mar 18, 2026

Uh oh!

HansujaB commented Mar 18, 2026

Uh oh!

larsoner commented Mar 18, 2026

Uh oh!

HansujaB commented Mar 18, 2026

Uh oh!

HansujaB commented Mar 19, 2026

Uh oh!

larsoner commented Mar 24, 2026

Uh oh!

HansujaB commented Mar 24, 2026

Uh oh!

larsoner Mar 24, 2026

Choose a reason for hiding this comment

Uh oh!

larsoner Mar 24, 2026

Choose a reason for hiding this comment

Uh oh!

HansujaB commented Mar 24, 2026

Uh oh!

HansujaB commented Mar 24, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Uh oh!

larsoner commented Apr 3, 2026

Uh oh!

HansujaB commented Apr 3, 2026

Uh oh!

Uh oh!

larsoner commented Apr 4, 2026

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

3 participants

HansujaB Mar 2, 2026 •

edited

Loading

HansujaB commented Mar 24, 2026 •

edited

Loading