repair_word_labels

pymovements.measure.reading.repair_word_labels(df: DataFrame) → DataFrame

Ensure consistent word string labels within each word index group.

Normalizes the word column so that all characters belonging to the same (trial, page, line_idx, word_idx) group share an identical word label.

Whitespace-only or empty word entries are treated as missing and are forward- and backward-filled within each word group. The word_idx column is not modified.

This is primarily used to assign a proper word label to characters such as inter-word spaces that already have a valid word_idx, ensuring downstream processing operates on consistent word-level labels.

Parameters:

df (pl.DataFrame) – Character-level AOI table containing at least the columns word_idx, word, and char_idx_in_line. Optionally grouped by trial, page, and line_idx.

Returns:

A copy of the input DataFrame with normalized word labels. No rows are added or removed, and word_idx assignments remain unchanged.

Return type:

pl.DataFrame