pymovements.stimulus.TextStimulus.get_aoi#

TextStimulus.get_aoi(*, row: row, x_eye: str, y_eye: str, max_matches: int | None = None) → DataFrame[source]#

Return the AOI that contains the given gaze row.

This function checks spatial bounds using the interval start <= coord < start + size if width/height is provided, or start <= coord < end if end_x_column/end_y_column is provided. In both cases, the end boundary is exclusive (half-open interval [start, end)). When trial_column and/or page_column are configured, AOIs are first filtered to match the current row’s values for these columns, which are then dropped to avoid duplicate columns during concatenation.

Parameters:

  • row (pl.DataFrame.row) – Eye movement row with fields for the eye coordinates and any trial/page identifiers.

  • x_eye (str) – Name of the x eye coordinate field in row.

  • y_eye (str) – Name of the y eye coordinate field in row.

  • max_matches (int | None) – If not None, reduce the number of matches to this amount. This may happen in case of overlapping AOIs. (default: None)

Returns:

A one-row DataFrame representing the matched AOI. If no AOI matches, the result is a single row with None values in the AOI columns.

Return type:

pl.DataFrame

Raises:

ValueError – If neither width/height nor end_x/end_y columns are defined to specify AOI bounds.

Notes

If multiple AOIs overlap and match the same point, a UserWarning is emitted. For invalid or missing coordinates (e.g. None or strings), a UserWarning is emitted, and the lookup returns a single row of None values.