`read_raw_eyelink()` fails to find and drop status column

[qian-chu]

Description of the problem

mne.io.read_raw_eyelink() returns error when reading .asc format eye-tracking data (see below). Error message points to a potential column parsing error.

From what I notice, the data is a bit special in two ways:

• It has two recording segments, the first one only spanning 12 samples
• The second segment starts with a bunch of null data

Steps to reproduce

from mne.io import read_raw_eyelink
raw = read_raw_eyelink("my_data.asc")

Link to data

https://drive.google.com/file/d/1Opc_EDcaOgsx11VsDW4Ul-kP4548tRXq/view?usp=sharing

or to view the starting segment:

** CONVERTED FROM fname.edf using edfapi 4.2.762.0 Windows   standalone Jul 20 2023 on Sat Dec 27 13:33:11 2025
** DATE: Fri Nov 28 14:28:25 2025
** TYPE: EDF_FILE BINARY EVENT SAMPLE TAGGED
** VERSION: EYELINK II 1
** SOURCE: EYELINK CL
** EYELINK II CL v6.10.01 Apr 13 2017 (EyeLink Portable Duo)
** CAMERA: EyeLink USBCAM Version 1.01
** SERIAL NUMBER: CLU-DAB12
** CAMERA_CONFIG: DAB12200.SCD
** REPARSED BY EDF Reparser using XXXX\edf_reparser_1.ini on Sat Dec 27 13:32:32 2025
**

MSG	814482 DISPLAY_COORDS 0 0 1919 1079
MSG	854216 !CAL 
>>>>>>> CALIBRATION (HV13,P-CR) FOR RIGHT: <<<<<<<<<
MSG	854216 !CAL Calibration points:  
MSG	854216 !CAL  6.3, -20.8      1902,   5137   
MSG	854216 !CAL  5.4, -30.6      2090,   8027   
MSG	854216 !CAL  7.3, -10.0      1736,   2608   
MSG	854216 !CAL -14.7, -20.1     -1653,   5232   
MSG	854216 !CAL  26.9, -19.8      5627,   5033   
MSG	854217 !CAL -15.4, -30.0     -1717,   8061   
MSG	854217 !CAL  26.0, -29.4      6100,   7998   
MSG	854217 !CAL -14.3, -10.5     -1599,   2756   
MSG	854217 !CAL  26.6, -9.7      5225,   2457   
MSG	854217 !CAL -5.4, -25.7       132,   6565   
MSG	854217 !CAL  15.7, -25.3      3896,   6493   
MSG	854217 !CAL -3.3, -15.0        76,   3896   
MSG	854217 !CAL  16.9, -14.7      3597,   3768   
MSG	854217 !CAL  0.0,  0.0         0,      0   
MSG	854217 !CAL eye check box: (L,R,T,B)
	  -20    31   -34     3
MSG	854217 !CAL href cal range: (L,R,T,B)
	-3672  8054 -2015  10076
MSG	854217 !CAL Cal coeff:(X=a+bx+cy+dxx+eyy,Y=f+gx+goaly+ixx+jyy)
   1390.2  161.17  166.04  0.80193  9.8325 
  -309.93  11.066 -368.28 -0.37089 -9.0911
MSG	854217 !CAL Gains: cx:173.631 lx:142.706 rx:195.646
MSG	854217 !CAL Gains: cy:228.075 ty:418.147 by:494.680
MSG	854217 !CAL Resolution (upd) at screen center: X=1.5, Y=1.2
MSG	854217 !CAL Gain Change Proportion: X: 0.371 Y: 0.183
MSG	854217 !CAL Gain Ratio (Gy/Gx) = 1.314
MSG	854217 !CAL Cross-Gain Ratios: X=0.555, Y=0.033 
MSG	854217 !CAL PCR gain ratio(x,y) = 2.500, 2.500
MSG	854217 !CAL CR gain match(x,y) = 1.000, 1.000
MSG	854217 !CAL Slip rotation correction OFF
MSG	854217 !CAL CALIBRATION HV13 R RIGHT   GOOD 
MSG	883460 !CAL VALIDATION HV13 R RIGHT GOOD ERROR 0.41 avg. 0.92 max  OFFSET 0.15 deg. 5.5,-4.9 pix.
MSG	883460 VALIDATE R 4POINT 0 RIGHT  at 960,540  OFFSET 0.23 deg.  -0.9,-9.5 pix.
MSG	883460 VALIDATE R 4POINT 1 RIGHT  at 960,168  OFFSET 0.46 deg.  18.4,13.2 pix.
MSG	883460 VALIDATE R 4POINT 2 RIGHT  at 960,911  OFFSET 0.47 deg.  -23.0,8.5 pix.
MSG	883460 VALIDATE R 4POINT 3 RIGHT  at 259,540  OFFSET 0.88 deg.  40.4,-20.4 pix.
MSG	883460 VALIDATE R 4POINT 4 RIGHT  at 1660,540  OFFSET 0.22 deg.  4.4,8.4 pix.
MSG	883460 VALIDATE R 4POINT 5 RIGHT  at 343,212  OFFSET 0.79 deg.  39.1,14.0 pix.
MSG	883460 VALIDATE R 4POINT 6 RIGHT  at 1576,212  OFFSET 0.20 deg.  -5.2,-7.4 pix.
MSG	883460 VALIDATE R 4POINT 7 RIGHT  at 343,867  OFFSET 0.88 deg.  -48.2,-4.4 pix.
MSG	883460 VALIDATE R 4POINT 8 RIGHT  at 1576,867  OFFSET 0.21 deg.  6.4,7.1 pix.
MSG	883460 VALIDATE R 4POINT 9 RIGHT  at 609,354  OFFSET 0.55 deg.  22.7,14.8 pix.
MSG	883460 VALIDATE R 4POINT 10 RIGHT  at 1310,354  OFFSET 0.30 deg.  16.7,-0.4 pix.
MSG	883460 VALIDATE R 4POINT 11 RIGHT  at 609,725  OFFSET 0.92 deg.  -50.6,-4.2 pix.
MSG	883460 VALIDATE R 4POINT 12 RIGHT  at 1310,725  OFFSET 0.20 deg.  -10.2,3.4 pix.
MSG	888976 RECCFG CR 1000 2 1 R
MSG	888976 ELCLCFG RBTABLER
MSG	888976 GAZE_COORDS 0.00 0.00 1919.00 1079.00
MSG	888976 THRESHOLDS R 77 210
MSG	888976 ELCL_WINDOW_SIZES 176 176 208 208
MSG	888976 CAMERA_LENS_FOCAL_LENGTH 27.00 
MSG	888976 PUPIL_DATA_TYPE RAW_AUTOSLIP
MSG	888976 ELCL_PROC ELLIPSE  (5)
MSG	888976 ELCL_EFIT_PARAMS 1.01 4.00  0.15 0.05  0.65 0.65  0.00 0.00 0.30
START	888977 	RIGHT	SAMPLES	EVENTS
PRESCALER	1
VPRESCALER	1
PUPIL	AREA
EVENTS	GAZE	RIGHT	RATE	1000.00	TRACKING	CR	FILTER	2
SAMPLES	GAZE	RIGHT	RATE	1000.00	TRACKING	CR	FILTER	2
MSG	888977 !MODE RECORD CR 1000 2 1 R
888977	  961.0	  600.1	  757.0	...
888978	  960.8	  600.3	  758.0	...
888979	  960.8	  600.6	  759.0	...
888980	  960.8	  601.0	  760.0	...
888981	  960.8	  601.4	  762.0	...
888982	  960.9	  601.8	  763.0	...
888983	  960.9	  602.1	  763.0	...
888984	  961.0	  602.3	  764.0	...
888985	  961.1	  602.5	  764.0	...
888986	  961.2	  602.6	  764.0	...
888987	  961.2	  602.7	  765.0	...
888988	  961.3	  602.8	  764.0	...
MSG	888989 RECCFG CR 1000 2 1 R
MSG	888989 ELCLCFG RBTABLER
MSG	888989 GAZE_COORDS 0.00 0.00 1919.00 1079.00
MSG	888989 THRESHOLDS R 76 210
MSG	888989 ELCL_WINDOW_SIZES 176 176 208 208
MSG	888989 CAMERA_LENS_FOCAL_LENGTH 27.00 
MSG	888989 PUPIL_DATA_TYPE RAW_AUTOSLIP
MSG	888989 ELCL_PROC ELLIPSE  (5)
MSG	888989 ELCL_EFIT_PARAMS 1.01 4.00  0.15 0.05  0.65 0.65  0.00 0.00 0.30
888989	  961.5	  602.8	  764.0	...
MSG	888990 !MODE RECORD CR 1000 2 1 R
888990	  961.8	  602.9	  764.0	...
888991	  962.2	  602.9	  764.0	...
END	888991 	SAMPLES	EVENTS	RES	  54.10	  40.70
START	888991 	RIGHT	SAMPLES	EVENTS
PRESCALER	1
VPRESCALER	1
PUPIL	AREA
EVENTS	GAZE	RIGHT	RATE	1000.00	TRACKING	CR	FILTER	2
SAMPLES	GAZE	RIGHT	RATE	1000.00	TRACKING	CR	FILTER	2
888993	   .	   .	    0.0
888994	   .	   .	    0.0
888995	   .	   .	    0.0
888996	   .	   .	    0.0
888997	   .	   .	    0.0
SFIX R   888998
888998	   .	   .	    0.0
<same null data, dropped for display on GitHub>
889500	   .	   .	    0.0
889501	   .	   .	    0.0
889502	   .	   .	    0.0
889503	   .	   .	    0.0
889504	  916.5	  575.5	  655.0	...
889505	  916.3	  575.2	  655.0	...
889506	  916.0	  574.7	  655.0	...
889507	  916.0	  574.1	  655.0	...
889508	  915.9	  573.6	  655.0	...
889509	  915.9	  573.0	  655.0	...

Expected results

Data successfully read into as a Raw instance.

Actual results

Loading C:\Users\qian.chu\Downloads\my_data.asc
Pixel coordinate data detected.Pass `scalings=dict(eyegaze=1e3)` when using plot method to make traces more legible.
Pupil-size area detected.
No button events found in this file.
Traceback (most recent call last):
  File "c:\Users\qian.chu\Downloads\read.py", line 2, in <module>
    raw = read_raw_eyelink("my_data.asc")
  File "C:\Users\qian.chu\Documents\GitHub\mne-python\mne\io\eyelink\eyelink.py", line 59, in read_raw_eyelink
    raw_eyelink = RawEyelink(
        fname,
    ...<4 lines>...
        verbose=verbose,
    )
  File "<decorator-gen-206>", line 12, in __init__
  File "C:\Users\qian.chu\Documents\GitHub\mne-python\mne\io\eyelink\eyelink.py", line 104, in __init__
    eye_ch_data, info, raw_extras = _parse_eyelink_ascii(
                                    ~~~~~~~~~~~~~~~~~~~~^
        fname, find_overlaps, overlap_threshold, apply_offsets
        ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
    )
    ^
  File "C:\Users\qian.chu\Documents\GitHub\mne-python\mne\io\eyelink\_utils.py", line 56, in _parse_eyelink_ascii
    processed_blocks = _create_dataframes(data_blocks, apply_offsets)
  File "C:\Users\qian.chu\Documents\GitHub\mne-python\mne\io\eyelink\_utils.py", line 336, in _create_dataframes
    block_dfs = _create_dataframes_for_block(block, apply_offsets)
  File "C:\Users\qian.chu\Documents\GitHub\mne-python\mne\io\eyelink\_utils.py", line 370, in _create_dataframes_for_block
    df_dict["samples"] = _drop_status_col(df_dict["samples"])  # drop STATUS col
                         ~~~~~~~~~~~~~~~~^^^^^^^^^^^^^^^^^^^^
  File "C:\Users\qian.chu\Documents\GitHub\mne-python\mne\io\eyelink\_utils.py", line 562, in _drop_status_col
    if samples_df[col][0][0].isnumeric():
       ~~~~~~~~~~~~~~~~~~^^^
TypeError: 'NoneType' object is not subscriptable

Additional information

Platform             Windows-11-10.0.26100-SP0
Python               3.13.7 | packaged by conda-forge | (main, Sep  3 2025, 14:18:04) [MSC v.1944 64 bit (AMD64)]
Executable           <directory omitted>l\miniforge3\envs\ieeg\python.exe
CPU                  Intel(R) Core(TM) i7-8550U CPU @ 1.80GHz (8 cores)
Memory               15.9 GiB

Core
 X mne               1.11.0.dev64+g3e29187ce (outdated, release 1.11.0 is available!)
 + numpy             2.3.3 (OpenBLAS 0.3.30 with 8 threads)
 + scipy             1.16.2
 + matplotlib        3.10.6 (backend=qtagg)

Numerical (optional)
 + sklearn           1.7.2
 + numba             0.62.0
 + nibabel           5.3.2
 + nilearn           0.12.1
 + dipy              1.11.0
 + openmeeg          2.5.15
 + pandas            2.3.2
 + h5io              0.2.5
 + h5py              3.14.0
 - unavailable       cupy

Visualization (optional)
 + pyvista           0.46.3 (OpenGL 4.5.0 - Build 31.0.101.2135 via Intel(R) UHD Graphics 620)
 + pyvistaqt         0.11.3
 + vtk               9.5.2
 + qtpy              2.4.3 (PyQt6=6.9.0)
 + ipympl            0.9.7
 + pyqtgraph         0.13.7
 + mne-qt-browser    0.7.2
 + ipywidgets        8.1.7
 + trame_client      3.10.4
 + trame_server      3.6.1
 + trame_vtk         2.9.1
 + trame_vuetify     3.1.0

Ecosystem (optional)
 + mne-bids          0.17.0
 + neo               0.14.2
 + eeglabio          0.1.2
 + edfio             0.4.9
 + mffpy             0.10.0
 + pybv              0.7.6
 + antio             0.6.1
 + defusedxml        0.7.1
 - unavailable       mne-nirs, mne-features, mne-connectivity, mne-icalabel, mne-bids-pipeline, curryreader

[qian-chu]

Update: I added a little debug print function in mne/io/eyelink/_utils.py

mne-python/mne/io/eyelink/_utils.py

Lines 552 to 567 in 3868eff

	def _drop_status_col(samples_df):
	"""Drop STATUS column from samples dataframe.
	see https://github.com/mne-tools/mne-python/issues/11809, and section 4.9.2.1 of
	the Eyelink 1000 Plus User Manual, version 1.0.19. We know that the STATUS
	column is either 3, 5, 13, or 17 characters long, i.e. "...", ".....", ".C."
	"""
	status_cols = []
	# we know the first 3 columns will be the time, xpos, ypos
	for col in samples_df.columns[3:]:
	if samples_df[col][0][0].isnumeric():
	# if the value is numeric, it's not a status column
	continue
	if len(samples_df[col][0]) in [3, 5, 13, 17]:
	status_cols.append(col)
	return samples_df.drop(columns=status_cols)

def _drop_status_col(samples_df):
    """Drop STATUS column from samples dataframe.

    see https://github.com/mne-tools/mne-python/issues/11809, and section 4.9.2.1 of
    the Eyelink 1000 Plus User Manual, version 1.0.19. We know that the STATUS
    column is either 3, 5, 13, or 17 characters long, i.e. "...", ".....", ".C."
    """
    status_cols = []
    # we know the first 3 columns will be the time, xpos, ypos
    print(f"DataFrame head:\n{samples_df.head()}") # Debug print
    for col in samples_df.columns[3:]:
        if samples_df[col][0][0].isnumeric():
            # if the value is numeric, it's not a status column
            continue
        if len(samples_df[col][0]) in [3, 5, 13, 17]:
            status_cols.append(col)
    return samples_df.drop(columns=status_cols)

And I got the following output:

Loading C:\Users\qian.chu\Downloads\my_data.asc
Pixel coordinate data detected.Pass `scalings=dict(eyegaze=1e3)` when using plot method to make traces more legible.
Pupil-size area detected.
DataFrame head:
        0      1      2      3    4
0  888977  961.0  600.1  757.0  ...
1  888978  960.8  600.3  758.0  ...
2  888979  960.8  600.6  759.0  ...
3  888980  960.8  601.0  760.0  ...
4  888981  960.8  601.4  762.0  ...
No button events found in this file.
DataFrame head:
        0  1  2    3     4
0  888993  .  .  0.0  None
1  888994  .  .  0.0  None
2  888995  .  .  0.0  None
3  888996  .  .  0.0  None
4  888997  .  .  0.0  None
Traceback (most recent call last):
  File "c:\Users\qian.chu\Downloads\read.py", line 2, in <module>
    raw = read_raw_eyelink("my_data.asc")
  File "C:\Users\qian.chu\Documents\GitHub\mne-python\mne\io\eyelink\eyelink.py", line 59, in read_raw_eyelink
    raw_eyelink = RawEyelink(
        fname,
    ...<4 lines>...
        verbose=verbose,
    )
  File "<decorator-gen-206>", line 12, in __init__
  File "C:\Users\qian.chu\Documents\GitHub\mne-python\mne\io\eyelink\eyelink.py", line 104, in __init__
    eye_ch_data, info, raw_extras = _parse_eyelink_ascii(
                                    ~~~~~~~~~~~~~~~~~~~~^
        fname, find_overlaps, overlap_threshold, apply_offsets
        ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
    )
    ^
  File "C:\Users\qian.chu\Documents\GitHub\mne-python\mne\io\eyelink\_utils.py", line 56, in _parse_eyelink_ascii
    processed_blocks = _create_dataframes(data_blocks, apply_offsets)
  File "C:\Users\qian.chu\Documents\GitHub\mne-python\mne\io\eyelink\_utils.py", line 336, in _create_dataframes
    block_dfs = _create_dataframes_for_block(block, apply_offsets)
  File "C:\Users\qian.chu\Documents\GitHub\mne-python\mne\io\eyelink\_utils.py", line 370, in _create_dataframes_for_block
    df_dict["samples"] = _drop_status_col(df_dict["samples"])  # drop STATUS col
                         ~~~~~~~~~~~~~~~~^^^^^^^^^^^^^^^^^^^^
  File "C:\Users\qian.chu\Documents\GitHub\mne-python\mne\io\eyelink\_utils.py", line 563, in _drop_status_col
    if samples_df[col][0][0].isnumeric():
       ~~~~~~~~~~~~~~~~~~^^^
TypeError: 'NoneType' object is not subscriptable

So it seems like the code always assumed DataFrame elements to be string. However, the second segment in my data has its 4th column starting with None, which is not subscriptable. A safer version could use a type check first. Is it safe to assume columns with None are also status columns?

[qian-chu]

The following modification should fix the bug and make the code more robust by:

• Getting the first valid data instead of the first position. (might be slightly slower but prevents the first position being empty)
• Using a float conversion attempt to test if value is numerical. This should handle more edge cases than str[0].isnumeric() (consider, for example, ".5").

def _drop_status_col(samples_df):
    """Drop STATUS column from samples dataframe.

    see https://github.com/mne-tools/mne-python/issues/11809, and section 4.9.2.1 of
    the Eyelink 1000 Plus User Manual, version 1.0.19. We know that the STATUS
    column is either 3, 5, 13, or 17 characters long, i.e. "...", ".....", ".C."
    """
    status_cols = []
    # we know the first 3 columns will be the time, xpos, ypos
    for col in samples_df.columns[3:]:
        first_valid_index = samples_df[col].first_valid_index()
        if first_valid_index is None:
            # the entire column is NaN, so we can drop it
            status_cols.append(col)
            continue
        value = samples_df.loc[first_valid_index, col]
        try:
            float(value)
            continue  # if the value is numeric, it's not a status column
        except (ValueError, TypeError):
            # cannot convert to float, so it might be a status column
            pass
        # further check the length of the string value
        if len(value) in [3, 5, 13, 17]:
            status_cols.append(col)
    return samples_df.drop(columns=status_cols)

Happy to init a PR if this seems sensible.

[scott-huberty]

Hey @qian-chu thanks for reporting and investigating!

identifying the STATUS column of an EyeLink has been a pain point for us, as it is a bit of a guessing game (the EyeLink file metadata doesn't give us any hints as to whether it is present, and what it looks like if it is).

I agree with your diagnosis here, it seems that if the recording block starts with missing data, the STATUS column will not be present until actual data starts being recorded (?)

Can you open a PR with your fix and we can iterate from there?