pymovements.Gaze.map_to_aois#

Gaze.map_to_aois(aoi_dataframe: TextStimulus, *, eye: str = 'auto', gaze_type: str = 'pixel', preserve_structure: bool = True, verbose: bool = True) → None[source]#

Map gaze samples to AOIs.

This maps each gaze point to an AOI label based on the configured stimulus rectangles. The mapping uses half-open intervals [start, end) for spatial bounds.

Parameters:

  • aoi_dataframe (TextStimulus) – Area of interest dataframe.

  • eye (str) – String specifier for inferring eye components. Supported values are: auto, mono, left, right, cyclops. Default: auto.

  • gaze_type (str) – Whether to use position or pixel coordinates for mapping. Default: pixel.

  • preserve_structure (bool) –

    Controls how list component columns are handled before mapping.

    • If True (default), unnest() is attempted so that downstream logic can rely on flat component columns (e.g. pixel_xr/pixel_yr). A few common exceptions from unnesting are tolerated, and mapping continues without failing.

    • If False, no unnesting is attempted. Coordinates are extracted per-row from any list columns and passed to the AOI lookup without altering the samples’ schema.

  • verbose (bool) – If True, show a progress bar. (default: True)

On this page

This Page