GazeNamespace#

class pypillometry.eyedata.gaze.GazeNamespace(data=None)[source]#

Bases: Namespace

Methods for gaze data, accessed as d.gaze (e.g., d.gaze.mask_offscreen()).

The methods need gaze data (x and y) and raise a ValueError if there is none. The transforming methods return the data object (see Namespace).

Methods

mask_divergences

Calculate Euclidean distance between left and right eye coordinates and detect divergences.

mask_offscreen

Detect and mask gaze coordinates that fall outside the screen boundaries.

Details

mask_divergences(threshold=0.99, thr_type='percentile', store_as=None, ignore_existing_mask=True, inplace=None)[source]#

Calculate Euclidean distance between left and right eye coordinates and detect divergences.

This method computes the distance between corresponding (x,y) coordinates in the left and right eyes. Points where the distance exceeds a threshold are detected as divergences and masked: they replace the "divergence" layer of x and y of both eyes (so running the method again with another threshold gives the same result as running it once; clear_layer("divergence") removes them). Read the divergences with get_layer_intervals("divergence").

Parameters:

  • threshold (float) – If thr_type is “percentile”: percentile value (0-1) for threshold calculation. If thr_type is “pixel”: maximum allowed distance in pixels.

  • thr_type (str) –

    Type of threshold to apply:

    • ”percentile”: threshold is calculated as the given percentile of the distance distribution

    • ”pixel”: threshold is the maximum allowed distance in pixels

  • store_as (str | None) – Variable name to store the distance timeseries. If None, distance is not stored. The distance is stored once, under the eye "both" (both_<store_as>), masked where one of the coordinates is masked or the eyes diverge.

  • ignore_existing_mask (bool) – If True (default), check all data points including those already masked (e.g., from blinks). If False, only check the data points that are usable under the default mask policy for divergences (the divergence layer itself does not count).

  • inplace (bool or None) – If True, make change in-place and return the object. If False, make and return copy before making changes. If None, use the object-level setting.

Return type:

EyeData

Returns:

the object with the divergences masked (self or a copy, depending on inplace)

Raises:

ValueError – If both left and right eye data are not available. If thr_type is not “percentile” or “pixel”.

Examples

>>> import pypillometry as pp
>>> d = pp.get_example_data("rlmw_002_short")
>>> # Mask divergences at 99th percentile
>>> d = d.gaze.mask_divergences(threshold=0.99, thr_type="percentile")

>>> # The detected divergences (in ms)
>>> divergences = d.get_layer_intervals("divergence", "left", "x", units="ms")
>>> list(divergences)
['left_x']

>>> # Mask divergences beyond 100 pixels
>>> d = d.gaze.mask_divergences(threshold=100, thr_type="pixel")

>>> # Only check non-masked data points
>>> d = d.gaze.mask_divergences(ignore_existing_mask=False)
mask_offscreen(eyes=[], ignore_existing_mask=False, inplace=None)[source]#

Detect and mask gaze coordinates that fall outside the screen boundaries.

This method identifies points where the (x,y) coordinates fall outside the defined screen limits. These points are masked: they replace the "offscreen" layer of x and y of the checked eyes (so running the method again with other screen limits gives the same result as running it once; clear_layer("offscreen") removes them). Read the off-screen periods with get_layer_intervals("offscreen").

Parameters:

  • eyes (str | list) – Eye(s) to check for offscreen coordinates. If empty, checks all available eyes that have x and y data. Can be a single eye name (e.g., “left”) or a list (e.g., [“left”, “right”]).

  • ignore_existing_mask (bool) – If False (default), only check the data points that are usable under the default mask policy for offscreen coordinates (the offscreen layer itself does not count). If True, check all data points including those already masked (e.g., from blinks).

  • inplace (bool or None) – If True, make change in-place and return the object. If False, make and return copy before making changes. If None, use the object-level setting.

Return type:

EyeData

Returns:

the object with the off-screen samples masked (self or a copy, depending on inplace)

Examples

>>> import pypillometry as pp
>>> d = pp.get_example_data("rlmw_002_short")  # has a setup
>>> # Mask offscreen coordinates for all eyes
>>> d = d.gaze.mask_offscreen()

>>> # The detected off-screen periods (in ms)
>>> offscreen = d.get_layer_intervals("offscreen", variables="x", units="ms")
>>> list(offscreen)
['left_x', 'right_x']

>>> # Mask offscreen coordinates for left eye only
>>> d = d.gaze.mask_offscreen(eyes="left")

>>> # Check all data including already masked points (e.g., during blinks)
>>> d = d.gaze.mask_offscreen(ignore_existing_mask=True)