annotate_fixations#

pymovements.measure.reading.annotate_fixations(events: DataFrame, group_columns: list[str] | None = None) → DataFrame[source]#

Annotate fixations with run- and pass-level information.

Computes the following per-fixation annotations:

  • run_id: integer ID for each contiguous sequence of fixations on the same word.

  • prev_word_idx / next_word_idx: word indices of the immediately preceding and following fixations.

  • is_reg_in / is_reg_out: whether the fixation arrives from a higher-index word (regression in) or departs to a lower-index word (regression out).

  • is_first_fix: whether this is the first fixation ever on the word within the trial.

  • is_first_pass: whether the fixation belongs to the first-pass reading episode of the word (see annotate_is_first_pass()).

Parameters:

  • events (pl.DataFrame) – DataFrame containing pymovements fixation events mapped to AOIs. Must contain at least name, word_idx, and onset columns, plus whatever columns are listed in group_columns.

  • group_columns (list[str] | None) – Column names used to partition the data into independent reading sequences (e.g. one trial per page). If None, defaults to ['trial', 'stimulus', 'page'].

Returns:

Fixation-level DataFrame with the original columns plus fixation_id, run_id, prev_word_idx, next_word_idx, delta_in, delta_out, is_reg_in, is_reg_out, is_first_fix, and is_first_pass.

Return type:

pl.DataFrame