initial commit

mne/io/eyelink/eyelink.py

@@ -0,0 +1,133 @@
+"""SR Research Eyelink Load Function."""
+
+# Authors: The MNE-Python contributors.
+# License: BSD-3-Clause
+# Copyright the MNE-Python contributors.
+
+from pathlib import Path
+
+from ...utils import (
+    _check_fname,
+    fill_doc,
+    logger,
+    verbose,
+)
+from ..base import BaseRaw
+from ._utils import _make_eyelink_annots, _make_gap_annots, _parse_eyelink_ascii
+
+
+@fill_doc
+def read_raw_eyelink(
+    fname,
+    *,
+    create_annotations=True,
+    apply_offsets=False,
+    find_overlaps=False,
+    overlap_threshold=0.05,
+    verbose=None,
+) -> "RawEyelink":
+    """Reader for an Eyelink ``.asc`` file.
+
+    Parameters
+    ----------
+    %(eyelink_fname)s
+    %(eyelink_create_annotations)s
+    %(eyelink_apply_offsets)s
+    %(eyelink_find_overlaps)s
+    %(eyelink_overlap_threshold)s
+    %(verbose)s
+
+    Returns
+    -------
+    raw : instance of RawEyelink
+        A Raw object containing eyetracker data.
+
+    See Also
+    --------
+    mne.io.Raw : Documentation of attribute and methods.
+
+    Notes
+    -----
+    It is common for SR Research Eyelink eye trackers to only record data during trials.
+    To avoid frequent data discontinuities and to ensure that the data is continuous
+    so that it can be aligned with EEG and MEG data (if applicable), this reader will
+    preserve the times between recording trials and annotate them with
+    ``'BAD_ACQ_SKIP'``.
+    """
+    fname = _check_fname(fname, overwrite="read", must_exist=True, name="fname")
+
+    raw_eyelink = RawEyelink(
+        fname,
+        create_annotations=create_annotations,
+        apply_offsets=apply_offsets,
+        find_overlaps=find_overlaps,
+        overlap_threshold=overlap_threshold,
+        verbose=verbose,
+    )
+    return raw_eyelink
+
+
+@fill_doc
+class RawEyelink(BaseRaw):
+    """Raw object from an XXX file.
+
+    Parameters
+    ----------
+    %(eyelink_fname)s
+    %(eyelink_create_annotations)s
+    %(eyelink_apply_offsets)s
+    %(eyelink_find_overlaps)s
+    %(eyelink_overlap_threshold)s
+    %(verbose)s
+
+    See Also
+    --------
+    mne.io.Raw : Documentation of attribute and methods.
+    """
+
+    @verbose
+    def __init__(
+        self,
+        fname,
+        *,
+        create_annotations=True,
+        apply_offsets=False,
+        find_overlaps=False,
+        overlap_threshold=0.05,
+        verbose=None,
+    ):
+        logger.info(f"Loading {fname}")
+
+        fname = Path(fname)
+
+        # ======================== Parse ASCII file ==========================
+        eye_ch_data, info, raw_extras = _parse_eyelink_ascii(
+            fname, find_overlaps, overlap_threshold, apply_offsets
+        )
+        # ======================== Create Raw Object =========================
+        super().__init__(
+            info,
+            preload=eye_ch_data,
+            filenames=[fname],
+            verbose=verbose,
+            raw_extras=[raw_extras],
+        )
+        self.set_meas_date(self._raw_extras[0]["dt"])
+
+        # ======================== Make Annotations =========================
+        gap_annots = None
+        if self._raw_extras[0]["n_blocks"] > 1:
+            gap_annots = _make_gap_annots(self._raw_extras[0])
+        eye_annots = None
+        if create_annotations:
+            eye_annots = _make_eyelink_annots(
+                self._raw_extras[0]["dfs"], create_annotations, apply_offsets
+            )
+        if gap_annots and eye_annots:  # set both
+            self.set_annotations(gap_annots + eye_annots)
+        elif gap_annots:
+            self.set_annotations(gap_annots)
+        elif eye_annots:
+            self.set_annotations(eye_annots)
+        else:
+            logger.info("Not creating any annotations")