pyavs.attach_scene_ids_to_samples

pyavs.attach_scene_ids_to_samples(samples: DataFrame, subject_id: int, session: int, data_path: str | None = None, offset_scene_triggers_ms: int = 20, verbose: bool = True) → DataFrame[source]

Attach scene IDs and trial information to eye tracking samples using pyAVS conventions.

This function assigns stimulus scene information to individual eye tracking samples, enabling sample-level analysis of gaze behavior during scene viewing.

Parameters:

  • samples (pd.DataFrame) – Eye tracking samples dataframe with ‘smpl_time’ column (in seconds)

  • subject_id (int) – Subject identifier

  • session (int) – Session number

  • data_path (str, optional) – Path to the data directory. If None, uses configured data path.

  • offset_scene_triggers_ms (int, default 20) – Offset to correct for systematic delay between MEG and eyetracker scene onset

  • verbose (bool, default True) – Whether to print detailed progress information

Returns:

Samples dataframe with added columns: subject, session, trial, recording, sceneID, time_in_trial, block, trial_per_block, caption_task

Return type:

pd.DataFrame

Raises:

  • KeyError – If required columns are missing from samples dataframe

  • FileNotFoundError – If required data files cannot be found