ENH: Create a Calibrations class for eyetracking data

doc/file_io.rst

@@ -62,3 +62,4 @@ Base class:
    :template: autosummary/class_no_members.rst
 
    BaseEpochs
+

doc/preprocessing.rst

@@ -153,6 +153,7 @@ Projections:
 .. autosummary::
    :toctree: generated/
 
+   Calibration
    set_channel_types_eyetrack
 
 EEG referencing:

doc/reading_raw_data.rst

@@ -21,6 +21,7 @@ Reading raw data
    read_raw_curry
    read_raw_edf
    read_raw_eyelink
+   read_eyelink_calibration
    read_raw_bdf
    read_raw_gdf
    read_raw_kit

mne/io/__init__.py

@@ -68,7 +68,7 @@
 from .fieldtrip import read_raw_fieldtrip, read_epochs_fieldtrip, read_evoked_fieldtrip
 from .nihon import read_raw_nihon
 from ._read_raw import read_raw
-from .eyelink import read_raw_eyelink
+from .eyelink import read_raw_eyelink, read_eyelink_calibration
 
 
 # for backward compatibility

mne/io/eyelink/__init__.py

@@ -1,7 +1,8 @@
 """Module for loading Eye-Tracker data."""
 
-# Author: Dominik Welke <[email protected]>
+# Authors: Dominik Welke <[email protected]>
+#          Scott Huberty <[email protected]>
 #
 # License: BSD-3-Clause
 
-from .eyelink import read_raw_eyelink
+from .eyelink import read_raw_eyelink, read_eyelink_calibration

mne/io/eyelink/_utils.py

@@ -0,0 +1,107 @@
+"""Helper functions for reading eyelink ASCII files."""
+# Authors: Scott Huberty <[email protected]>
+# License: BSD-3-Clause
+
+import re
+
+from ...preprocessing.eyetracking.calibration import Calibration
+
+
+def _find_recording_start(lines):
+    """Return the first START line in an SR Research EyeLink ASCII file.
+
+    Parameters
+    ----------
+        lines: A list of strings, which are The lines in an eyelink ASCII file.
+
+    Returns
+    -------
+        The line that contains the info on the start of the recording.
+    """
+    for line in lines:
+        if line.startswith("START"):
+            return line
+    raise ValueError("Could not find the start of the recording.")
+
+
+def _parse_validation_line(line):
+    """Parse a single line of eyelink validation data.
+
+    Parameters
+    ----------
+        line: A string containing a line of validation data from an eyelink
+        ASCII file.
+
+    Returns
+    -------
+        A list of tuples containing the validation data.
+    """
+    tokens = line.split()
+    xy = tokens[-6].strip("[]").split(",")  # e.g. '960, 540'
+    xy_diff = tokens[-2].strip("[]").split(",")  # e.g. '-1.5, -2.8'
+    vals = tuple([float(v) for v in [*xy, tokens[-4], *xy_diff]])
+
+    return vals
+
+
+def _parse_calibration(
+    lines, screen_size=None, screen_distance=None, screen_resolution=None
+):
+    """Parse the lines in the given list and returns a list of Calibration instances.
+
+    Parameters
+    ----------
+        lines: A list of strings, which are The lines in an eyelink ASCII file.
+
+    Returns
+    -------
+        A list containing one or more Calibration instances,
+        one for each calibration that was recorded in the eyelink ASCII file
+        data.
+    """
+    regex = re.compile(r"\d+")  # for finding numeric characters
+    calibrations = list()
+    rec_start = float(_find_recording_start(lines).split()[1])
+
+    for line_number, line in enumerate(lines):
+        if (
+            "!CAL VALIDATION " in line and "ABORTED" not in line
+        ):  # Start of a calibration
+            calibration = Calibration(
+                screen_size=screen_size,
+                screen_distance=screen_distance,
+                screen_resolution=screen_resolution,
+            )
+            tokens = line.split()
+            this_eye = tokens[6].lower()
+            assert this_eye in ["left", "right"], this_eye
+            calibration["model"] = tokens[4]  # e.g. 'HV13'
+            assert calibration["model"].startswith("H")
+            calibration["eye"] = this_eye
+            timestamp = float(tokens[1])
+            onset = (timestamp - rec_start) / 1000.0  # in seconds
+            calibration["onset"] = 0 if onset < 0 else onset
+
+            avg_error = float(line.split("avg.")[0].split()[-1])  # e.g. 0.3
+            max_error = float(line.split("max")[0].split()[-1])  # e.g. 0.9
+            calibration["avg_error"] = avg_error
+            calibration["max_error"] = max_error
+
+            n_points = int(regex.search(calibration["model"]).group())  # e.g. 9
+            n_points *= 2 if "LR" in line else 1  # one point per eye if "LR"
+            # The next n_point lines contain the validation data
+            points = []
+            for validation_index in range(n_points):
+                subline = lines[line_number + validation_index + 1]
+                if "!CAL VALIDATION" in subline:
+                    continue  # for bino mode, skip the second eye's validation summary
+                subline_eye = subline.split("at")[0].split()[-1].lower()
+                assert subline_eye in ["left", "right"], subline_eye
+                if subline_eye != this_eye:
+                    continue  # skip the validation lines for the other eye
+                point_info = _parse_validation_line(subline)
+                points.append(point_info)
+            # Convert the list of validation data into a numpy array
+            calibration.set_calibration_array(points)
+            calibrations.append(calibration)
+    return calibrations

mne/io/eyelink/eyelink.py

@@ -1,3 +1,5 @@
+"""SR Research Eyelink Load Function."""
+
 # Authors: Dominik Welke <[email protected]>
 #          Scott Huberty <[email protected]>
 #          Christian O'Reilly <[email protected]>
@@ -8,6 +10,7 @@
 from pathlib import Path
 
 import numpy as np
+from ._utils import _parse_calibration
 from ..constants import FIFF
 from ..base import BaseRaw
 from ..meas_info import create_info
@@ -284,6 +287,45 @@ def _find_overlaps(df, max_time=0.05):
     return ovrlp.drop(columns=tmp_cols).reset_index(drop=True)
 
 
+@fill_doc
+def read_eyelink_calibration(
+    filename, screen_size=None, screen_distance=None, screen_resolution=None
+):
+    """Return info on calibrations collected in an eyelink file.
+
+    Parameters
+    ----------
+    filename : str
+        Path to the eyelink file (.asc).
+    screen_size : tuple
+        The width and height (in meters) of the screen that the eyetracking
+        data was collected with. For example (.531, .298) for a monitor with
+        a display area of 531 x 298 cm. Defaults to None.
+    screen_distance : float
+        The distance (in meters) from the participant's eyes to the screen.
+        Defaults to None.
+    screen_resolution : tuple
+        The resolution (in pixels) of the screen that the eyetracking data
+        was collected with. For example, (1920, 1080) for a 1920x1080
+        resolution display. Defaults to None.
+
+    Returns
+    -------
+    calibrations : list
+        A list of Calibration instances, one for each eye of every
+        calibration that was performed during the recording session.
+    """
+    fname = Path(filename)
+    if not fname.exists():
+        raise FileNotFoundError(f"Could not find file {filename}")
+    logger.info("Reading calibration data from {}".format(fname))
+    with fname.open() as file:
+        lines = file.readlines()
+        return _parse_calibration(
+            lines, screen_size, screen_distance, screen_resolution
+        )
+
+
 @fill_doc
 def read_raw_eyelink(
     fname,
@@ -294,6 +336,10 @@ def read_raw_eyelink(
     find_overlaps=False,
     overlap_threshold=0.05,
     gap_description="bad_rec_gap",
+    return_calibration=False,
+    screen_size=None,
+    screen_distance=None,
+    screen_resolution=None,
 ):
     """Reader for an Eyelink .asc file.
 
@@ -328,6 +374,24 @@ def read_raw_eyelink(
         the annotation that will span across the gap period between the
         blocks. Uses 'bad_rec_gap' by default so that these time periods will
         be considered bad by MNE and excluded from operations like epoching.
+    return_calibration : bool (default False)
+        If True, returns a tuple of (raw, calibrations) where calibrations is
+        a list of Calibration instances, each containing information about a
+        single calibration collected during the recording.
+    screen_size : tuple
+        Only set if 'return_calibration' is set to True.
+        The width and height (in meters) of the screen that the eyetracking
+        data was collected with. For example (.531, .298) for a monitor with
+        a display area of 531 x 298 cm. Defaults to None.
+    screen_distance : float
+        Only set if 'return_calibration' is set to True.
+        The distance from the participant's eyes to the screen in meters.
+        Defaults to None.
+    screen_resolution : tuple
+        Only set if 'return_calibration' is set to True.
+        The resolution (in pixels) of the screen that the eyetracking data
+        was collected with. For example, (1920, 1080) for a 1920x1080
+        resolution display. Defaults to None.
 
     Returns
     -------
@@ -347,7 +411,7 @@ def read_raw_eyelink(
             " files to .asc format."
         )
 
-    return RawEyelink(
+    raw_eyelink = RawEyelink(
         fname,
         preload=preload,
         verbose=verbose,
@@ -357,6 +421,13 @@ def read_raw_eyelink(
         overlap_threshold=overlap_threshold,
         gap_desc=gap_description,
     )
+    if return_calibration:
+        calibrations = read_eyelink_calibration(
+            fname, screen_size, screen_distance, screen_resolution
+        )
+        return raw_eyelink, calibrations
+    else:
+        return raw_eyelink
 
 
 @fill_doc