FIX: Handle EyeLink Files with Eye Event Data set to "HREF" #13357
Conversation
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
1. If len(df.columns) > expected_col_names, and the df is for Sacccade or Fixation data, then just rename the first 4 columns of the df to the first 4 elements of expected_col_names, which should always be ('eye', 'start_time', 'end_time', 'duration')
2. Otherwise, if len(df.columns) != expected_col_names, then raise an error before doing df.rename(...), that is more informative than the error that Pandas would raise. I added this because the majority of bugs users are reporting come back to that column assignment line.
3. Move "messages" cols to the EYELINK_COLS constant, where the rest of the column names are..
scott-huberty
requested review from
larsoner,
drammock,
agramfort and
dengemann
as code owners
scott-huberty
changed the title
larsoner
reviewed
Aug 1, 2025
larsoner
reviewed
Aug 1, 2025
mne/io/eyelink/_utils.py
Outdated
| if key in ("samples", "blinks", "fixations", "saccades", "messages"): | ||
| cols = col_names[key] | ||
| else: | ||
| logger.debug(f"Skipping unsupported EyeLink Event type: {key}") |
There was a problem hiding this comment.
Maybe better to make a list of these and at the end of the loop if the list is non-empty logger.info it? Depends on how many messages we're skipping and how often I guess...
There was a problem hiding this comment.
Done in ace2530. The number of event types being skipped depends on the file, but typically it might be for example 'BUTTONS' (at least until #13287 is merged).
I kept the log level at DEBUG for now, I personally don't think the user needs to see this info every time, but if you feel strongly about it I can certainly bump it to INFO.
Co-authored-by: Eric Larson <[email protected]>
Co-authored-by: Eric Larson <[email protected]> Kept it at the debug level for now
larsoner
reviewed
Aug 1, 2025
larsoner
approved these changes
Aug 1, 2025
WouterKroot
pushed a commit
to WouterKroot/mne-python
that referenced
this pull request
Aug 13, 2025
…s#13357) Co-authored-by: Eric Larson <[email protected]>
zEdS15B3GCwq
pushed a commit
to zEdS15B3GCwq/mne-python
that referenced
this pull request
Aug 25, 2025
…s#13357) Co-authored-by: Eric Larson <[email protected]>
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
Add this suggestion to a batch that can be applied as a single commit.
This suggestion is invalid because no changes were made to the code.
Suggestions cannot be applied while the pull request is closed.
Suggestions cannot be applied while viewing a subset of changes.
Only one suggestion per line can be applied in a batch.
Add this suggestion to a batch that can be applied as a single commit.
Applying suggestions on deleted lines is not supported.
You must change the existing code in this line in order to create a valid suggestion.
Outdated suggestions cannot be applied.
This suggestion has been applied or marked resolved.
Suggestions cannot be applied from pending reviews.
Suggestions cannot be applied on multi-line comments.
Suggestions cannot be applied while the pull request is queued to merge.
Suggestion cannot be applied right now. Please check back later.
@anomalosepia and I discovered another edge case that breaks our eyelink reader. I've added a test that demonstrates this failure and will add a fix soon.
I know not everyone will follow this, but posting in detail for posterity 🙂 No obligation to read further
As discussed with Sam Hutton from SR Research:
On an EyeLink acquisition computer (referred to as the "Host PC"), the data acquisition GUI exposes a parameter "Eye Event Data", that defaults to "GAZE" but can be manually set to "HREF":
When "Eye Event Data" is set to "HREF" (Head-Referenced-Eye-Angle), then extra fields are written to the EDF (EyeLink-Data-Format) file for Saccade and Fixation events. These extra fields also show up in the ASCII file (after EDF -> ASCII file conversion).
For example in a typical file with "GAZE" Eye Event Data, a Saccade event would look like this:
Which translates to...
But in a file with "HREF" Eye Event Data, a Saccade event has 4 extra columns of info:
Basically, in this case the start x/y, end x/y amplitude, pupil-size columns are reported for both HREF and then GAZE datatypes.
Likewise for Fixation data, the avg-fixation x/y and avg-pupil-size columns are duplicated in the HREF case:
Fixation: GAZE Eye Event Data
Fixation: HREF Eye Event Data
The fix I'm about to implement will use defensive-programming extract the start/end time from saccade events even if they unexpectedly contain this extra information, which we don't need anyways.