diff --git a/mne/preprocessing/eyetracking/__init__.py b/mne/preprocessing/eyetracking/__init__.py index fb0792a696b..05160dedfe1 100644 --- a/mne/preprocessing/eyetracking/__init__.py +++ b/mne/preprocessing/eyetracking/__init__.py @@ -4,7 +4,7 @@ # License: BSD-3-Clause # Copyright the MNE-Python contributors. -from .eyetracking import set_channel_types_eyetrack, convert_units +from .eyetracking import set_channel_types_eyetrack, convert_units, find_blinks from .calibration import Calibration, read_eyelink_calibration from ._pupillometry import interpolate_blinks from .utils import get_screen_visual_angle diff --git a/mne/preprocessing/eyetracking/eyetracking.py b/mne/preprocessing/eyetracking/eyetracking.py index 5bf82068b52..b3f93dfbb4b 100644 --- a/mne/preprocessing/eyetracking/eyetracking.py +++ b/mne/preprocessing/eyetracking/eyetracking.py @@ -9,11 +9,68 @@ from ...epochs import BaseEpochs from ...evoked import Evoked from ...io import BaseRaw -from ...utils import _check_option, _validate_type, logger, warn +from ...utils import _check_option, _validate_type, logger, verbose, warn from .calibration import Calibration from .utils import _check_calibration +@verbose +def find_blinks( + inst, + *, + chs_src=None, + method="by_dropout", + dropout_value=None, + description="BAD_blink", + chs_dest=None, + verbose=None, +): + """Find blinks in eye-tracking data and create corresponding annotations. + + Parameters + ---------- + inst : instance of Raw + The data instance to use for finding blinks. Must contain pupil channels. + chs_src : list | None + A list of channel names that will be used to find blinks. None (default) will + result in selecting all channels of type ``pupil``. See Notes for more + information. + method : str + Which method to use to find blinks in ``inst``. Currently the only supported + method is ``'by_dropout'`` (default), which uses the value specified via + ``dropout_value`` to identify blinks. + dropout_value : float | None + Which value in the data denotes a dropout. In Eyelink data, this is ``0``, + whereas for other eye-tracking data this may be ``np.nan``, or something else. + Defaults to None, which sets the ``dropout_value`` to ``np.nan``. + description : str + Which description to use for the blink annotations. Defaults to ``'BAD_blink'``. + chs_dest : list | None + A list of channel names that will be associated with the blink annotations. + None (default) and passing an empty lists will associate each blink annotation + with all channels in ``inst``. + %(verbose)s + + Returns + ------- + annots : mne.Annotations + The annotations objects containing blink annotations. + + Notes + ----- + If multiple channels are used to find blinks in ``inst``, resulting overlapping + blink annotations are always merged over all channels. That is, if a left and a + right pupil channel would be used for blink detection, and each on their own would + produce overlapping blink annotations with onsets ``[1.5, 1.6]`` and durations + ``[0.2, 0.3]``, respectively, then passing both channels into this function will + result in a single blink annotation with onset ``1.5`` and duration ``0.4``. + Note that this corresponds to the minimum onset and the maximum offset between + the two annotations. + """ + logger.info("Found blinks") + return + + # specific function to set eyetrack channels def set_channel_types_eyetrack(inst, mapping): """Define sensor type for eyetrack channels. @@ -168,7 +225,8 @@ def _convert_deg_to_rad(array): return array * np.pi / 180.0 -def convert_units(inst, calibration, to="radians"): +@verbose +def convert_units(inst, calibration, to="radians", verbose=None): """Convert Eyegaze data from pixels to radians of visual angle or vice versa. .. warning:: @@ -191,6 +249,7 @@ def convert_units(inst, calibration, to="radians"): (in pixels). to : str Must be either ``"radians"`` or ``"pixels"``, indicating the desired unit. + %(verbose)s Returns ------- diff --git a/mne/preprocessing/eyetracking/tests/test_eyetracking.py b/mne/preprocessing/eyetracking/tests/test_eyetracking.py index a4a0404fcb1..3d372cb04a3 100644 --- a/mne/preprocessing/eyetracking/tests/test_eyetracking.py +++ b/mne/preprocessing/eyetracking/tests/test_eyetracking.py @@ -8,9 +8,15 @@ import mne from mne._fiff.constants import FIFF +from mne.preprocessing.eyetracking import find_blinks from mne.utils import _record_warnings +def test_find_blinks(): + """Test creating blink annotations.""" + find_blinks + + def test_set_channel_types_eyetrack(eyetrack_raw): """Test that set_channel_types_eyetrack worked on the fixture.""" assert eyetrack_raw.info["chs"][0]["kind"] == FIFF.FIFFV_EYETRACK_CH