pymovements.Events.map_to_aois

Events.map_to_aois(aoi_dataframe: TextStimulus, *, preserve_structure: bool = True, verbose: bool = True) → None

Map events to AOIs, ignoring non-fixations.

This function computes AOI membership only for rows whose name starts with "fixation" (e.g., "fixation", "fixation_ivt"). Rows that are not fixations are left unchanged and receive None values for all AOI columns. The original order and number of rows are preserved.

Schema handling:

• If preserve_structure=True (default), we mirror legacy behavior when a list location column exists: derive location_x/location_y and drop location. This keeps downstream expectations about flat component columns.

• If preserve_structure=False, no unnesting/derivation occurs and the original location list column is preserved. Coordinates are extracted per-row without altering the frame.

AOI columns used for trial/page keys in the stimulus (trial_column/page_column) are not appended to the events, as they are dropped by TextStimulus.get_aoi to avoid duplicate columns during concatenation.

Parameters:

• aoi_dataframe (TextStimulus) – Text stimulus defining AOI rectangles.

• preserve_structure (bool) – Control whether to derive component columns and drop the list column as described above. Default: True.

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

Raises:

• ValueError – If aoi_dataframe does not have either width_column or end_x_column defined.

• ValueError – If the events frame is empty.