Fix `read_raw_eyelink()` failure when recording blocks are empty or starting with empty values #13571

qian-chu · 2025-12-30T14:34:59Z

Reference issue (if any)

Fixes #13567 and extend testing to the case mentioned in #13550.

What does this implement/fix?

As described in #13567, when a recording block starts with missing data, the status column sometimes is not present until actual data is present:

889502	   .	   .	    0.0
889503	   .	   .	    0.0
889504	  916.5	  575.5	  655.0	...
889505	  916.3	  575.2	  655.0	...

While it does not prevent the block to be read into a DataFrame (with four columns, in this case), the status column would start with None instead of any subscriptable string, causing a TypeError.

The fix instead gets the first valid value to infer if the column is status or not. Further, it updates the method to infer if the first value is numeric by trying to convert it to float.

Question: If not len(first_value) in [3, 5, 13, 17], should the code emit a warning/error to contact MNE developers?

Moreover, #13550 mentioned a scenerio that a recording block could be completely empty. While it doesn't seem to trigger any error anymore, this is not explicitly tested in the current tests. So we will also add this to the test coverage.

Minor fixes

Correct typo ("occular" -> "ocular")
if "PUPIL" in units, warn "Raw pupil position data detected" instead of "Raw eyegaze coordinates detected".

Additional information

The main focus of the PR is expanding _simulate_eye_tracking_data (which is already simulating multi-block data) to simulate more edge cases.

qian-chu · 2025-12-31T17:59:59Z

Just noticed that #13550 and #13555 are also related. It seems the two problems are complementary - users will want to discard any empty recording block AND read blocks with an empty start

Co-authored-by: Mathieu Scheltienne <[email protected]>

Co-authored-by: Daniel McCloy <[email protected]>

scott-huberty · 2026-01-05T19:47:53Z

thanks @qian-chu ! And thanks in advance for your patience, just getting back to the office after the holiday break. I will take a closer look this week.

qian-chu · 2026-01-05T19:51:08Z

thanks @qian-chu ! And thanks in advance for your patience, just getting back to the office after the holiday break. I will take a closer look this week.

No worries! Not expecting people to be back from holidays this soon. This PR is also still in progress anyways (I have yet to add new tests)

…column

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

Cathaway · 2026-01-19T17:12:43Z

Minor fixes

Correct typo ("occular" -> "ocular")

if "PUPIL" in units, warn "Raw pupil position data detected" instead of "Raw eyegaze coordinates detected".

just a note 'pupil' channels in Eyelink measure pupil size (or diameter), not positions, so the warning message should be 'pupil size data detected', if a warning is needed

qian-chu · 2026-01-19T17:24:48Z

Minor fixes

Correct typo ("occular" -> "ocular")

if "PUPIL" in units, warn "Raw pupil position data detected" instead of "Raw eyegaze coordinates detected".

just a note 'pupil' channels in Eyelink measure pupil size (or diameter), not positions, so the warning message should be 'pupil size data detected', if a warning is needed

This PUPIL unit, if I'm not mistaken, indicates the user used edf2asc -sp. According to edf2asc: "-sp outputs sample raw pupil position if present". This is not about pupil size, but what measurement the x and y are (default is gaze, could also be href and pupil).

scott-huberty · 2026-01-19T19:38:20Z

Minor fixes

Correct typo ("occular" -> "ocular")

if "PUPIL" in units, warn "Raw pupil position data detected" instead of "Raw eyegaze coordinates detected".

just a note 'pupil' channels in Eyelink measure pupil size (or diameter), not positions, so the warning message should be 'pupil size data detected', if a warning is needed

This PUPIL unit, if I'm not mistaken, indicates the user used edf2asc -sp. According to edf2asc: "-sp outputs sample raw pupil position if present". This is not about pupil size, but what measurement the x and y are (default is gaze, could also be href and pupil).

Agreed. It is easy to mix up, but, In EyeLink systems there is a distinction between Pupil Size data and eyegaze pupil position data.

Per the EDF2ASC Manual:

SAMPLES < data type > < eyes > < data options >
This specifies what types of data is present in sample lines, as a sequence of keywords. The < data type > is one of "GAZE", "HREF" or "PUPIL".

And per section 4.4.2.1 PUPIL of the Eyelink 1000 Plus User manual (v1.0.19):

Pupil position data is raw (x, y) coordinate pairs from the camera. It has not been converted to eye angles or to gaze position.

@qian-chu I'm only loosely following this so feel free to ping me when you are ready for review or need my input!

qian-chu · 2026-01-19T19:44:26Z

@scott-huberty Absolutely! I think it will be helpful if you could look at the evolution of conversation in #13550. It seems to have been solved by one of your previous PR but would love to hear your opinion. This will help determine the scope of this PR.

qian-chu · 2026-01-28T17:06:06Z

mne/io/eyelink/tests/test_eyelink.py

-        fp.write("END\t7453390\tRIGHT\tSAMPLES\tEVENTS\n")
+        fp.write("END\t7453490\tRIGHT\tSAMPLES\tEVENTS\n")


This seems to be a small typo, because the timestamps are from 7453390 to 7453490, therefore block end message should be 7453490

qian-chu · 2026-01-28T17:08:00Z

mne/io/eyelink/tests/test_eyelink.py

-    assert raw.annotations.description[-7] == "BAD_ACQ_SKIP"
-    assert np.isclose(raw.annotations.onset[-7], 1.001)
-    assert np.isclose(raw.annotations.duration[-7], 0.1)
+    assert raw.annotations.description[-8] == "BAD_ACQ_SKIP"
+    assert np.isclose(raw.annotations.onset[-8], 1.001)
+    assert np.isclose(raw.annotations.duration[-8], 0.1)


Event indices all move "up" by one becase a new "BAD_ACQ_SKIP" is introduced between block 2 and 3.

qian-chu · 2026-01-28T17:32:04Z

This PR is ready for review! While I believe this should resolve the bug already, it also opens a new question: what should MNE do with empty recordings? The behavior currently seems to be still read the empty data in, but maybe it makes more sense to also denote the period as "BAD_ACQ_SKIP"? (which is currently only done to between-block gaps.) Open to ideas and implementations.

FIX: handle empty first Eyelink recording block

cb45659

qian-chu requested review from agramfort, dengemann, drammock and larsoner as code owners December 30, 2025 21:58

qian-chu and others added 6 commits January 1, 2026 22:17

fix bug where empty first element leads to error

c6a624f

FIX: Corrected typos across codebase (mne-tools#13563)

90e172d

Co-authored-by: Mathieu Scheltienne <[email protected]>

FIX: Fixed incorrect module stripping in logging (mne-tools#13561)

bfd14ae

Co-authored-by: Daniel McCloy <[email protected]>

Update _utils.py

a44267a

Update _utils.py

fecb178

Create 13571.bugfix.rst

911310e

qian-chu force-pushed the fix-read-eyelink branch from 9f2d92c to 911310e Compare January 1, 2026 21:17

qian-chu requested review from jasmainak and mscheltienne as code owners January 1, 2026 21:17

qian-chu and others added 2 commits January 1, 2026 22:23

Merge branch 'mne-tools:main' into fix-read-eyelink

e289a1a

merge two PR contents

0510acc

qian-chu changed the title ~~Fix read_raw_eyelink() failure when status column starts with empty values~~ Fix read_raw_eyelink() failure when recording blocks are empty or starting with empty values Jan 2, 2026

qian-chu marked this pull request as draft January 2, 2026 13:24

fix typos

629c900

qian-chu and others added 3 commits January 7, 2026 17:29

two more typos

e22ebb9

add simulation of block starting with empty samples without a status …

f9af109

…column

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

bb406ae

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

qian-chu mentioned this pull request Jan 28, 2026

read_raw_eyelink() cannot handle empty first trial #13550

Open

add third block that is completely empty

cc6a93c

qian-chu marked this pull request as ready for review January 28, 2026 16:35

Update test_eyelink.py

b2c7e0c

qian-chu commented Jan 28, 2026

View reviewed changes

Merge branch 'main' into fix-read-eyelink

a16a950

		fp.write("END\t7453390\tRIGHT\tSAMPLES\tEVENTS\n")
		fp.write("END\t7453490\tRIGHT\tSAMPLES\tEVENTS\n")

Uh oh!

Fix read_raw_eyelink() failure when recording blocks are empty or starting with empty values #13571

Are you sure you want to change the base?

Fix read_raw_eyelink() failure when recording blocks are empty or starting with empty values #13571

Uh oh!

Conversation

qian-chu commented Dec 30, 2025 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Reference issue (if any)

What does this implement/fix?

Minor fixes

Additional information

Uh oh!

qian-chu commented Dec 31, 2025

Uh oh!

scott-huberty commented Jan 5, 2026

Uh oh!

qian-chu commented Jan 5, 2026

Uh oh!

Cathaway commented Jan 19, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Minor fixes

Uh oh!

qian-chu commented Jan 19, 2026

Minor fixes

Uh oh!

scott-huberty commented Jan 19, 2026

Minor fixes

Uh oh!

qian-chu commented Jan 19, 2026

Uh oh!

qian-chu Jan 28, 2026

Choose a reason for hiding this comment

Uh oh!

scott-huberty Jan 28, 2026

Choose a reason for hiding this comment

Uh oh!

qian-chu Jan 28, 2026

Choose a reason for hiding this comment

Uh oh!

qian-chu commented Jan 28, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

4 participants

Fix `read_raw_eyelink()` failure when recording blocks are empty or starting with empty values #13571

Fix `read_raw_eyelink()` failure when recording blocks are empty or starting with empty values #13571

qian-chu commented Dec 30, 2025 •

edited

Loading

Cathaway commented Jan 19, 2026 •

edited

Loading

qian-chu commented Jan 28, 2026 •

edited

Loading