Pilot Data (pyavs.pilot)

Note

This module loads and enriches pilot-phase eye-tracking data – a distinct, earlier-stage dataset from the main AVS experiment (as01-as05) documented elsewhere in this site. Ported from the standalone pilot-data-manager/ package.

Loading, enrichment, and coordinate conversion for AVS pilot eye-tracking data.

Ported from pilot-data-manager/dataloader.py into the pyavs package. Author: P. Sulewski (phsulewski@gmail.com)

pyavs.pilot.dataloader.load_pilot_events(subjects, data_path, preprocessed=True)[source]

Combine fixation events from all pilot subjects into one enriched DataFrame.

Parameters:

  • subjects (list[int]) – Subject numbers to load (e.g. list(range(1, 23))).

  • data_path (str) – Root results directory (contains Sub1/, Sub2/, …).

  • preprocessed (bool) – If True use preprocessed/ subfolder and *_el_events / *_el_msgs files.

Returns:

  • explog_df (pd.DataFrame) – Concatenated experimental log across subjects.

  • events_df (pd.DataFrame) – Concatenated, trial-enriched fixation events across subjects. Added columns: subject, trial, recording, sceneID, time_in_trial, block, trial_per_block.

pyavs.pilot.dataloader.load_pilot_samples(subjects, data_path, preprocessed=True)[source]

Combine enriched gaze samples from all pilot subjects into one DataFrame.

Mirrors the interface of load_pilot_events() but operates on raw 1000 Hz sample data instead of aggregated fixation/saccade/blink events.

Parameters:

  • subjects (list[int]) – Subject numbers to load (e.g. list(range(1, 23))).

  • data_path (str) – Root results directory (contains Sub1/, Sub2/, …).

  • preprocessed (bool) – If True use preprocessed/ subfolder and *_el_samples / *_el_msgs files.

Returns:

  • explog_df (pd.DataFrame) – Concatenated experimental log across subjects.

  • samples_df (pd.DataFrame) – Concatenated, trial-enriched gaze samples across subjects. Added columns: subject, trial, recording, sceneID, time_in_trial, block, trial_per_block.

pyavs.pilot.dataloader.add_scene_coordinates(events)[source]

Add scene-centred and normalised gaze coordinates to fixation events.

Converts raw screen-pixel coordinates (origin top-left, y-down) to:

  • mean_gx_scene / mean_gy_scene : scene-centred pixels (+right / +up)

  • mean_gx_scene_norm / mean_gy_scene_norm : normalised so ±1 = scene edge

Parameters:

events (pd.DataFrame) – Fixation events DataFrame (must contain ‘mean_gx’ and ‘mean_gy’ columns).

Returns:

Same DataFrame with four additional columns.

Return type:

pd.DataFrame

pyavs.pilot.dataloader.add_sample_scene_coordinates(samples)[source]

Add scene-centred and normalised gaze coordinates to raw samples.

Converts raw screen-pixel coordinates (origin top-left, y-down) to:

  • gx_scene / gy_scene : scene-centred pixels (+right / +up)

  • gx_scene_norm / gy_scene_norm : normalised so ±1 = scene edge

Operates on sample-level columns ‘gx’ / ‘gy’ (cf. add_scene_coordinates() which uses ‘mean_gx’ / ‘mean_gy’ for fixation events).

Parameters:

samples (pd.DataFrame) – Gaze samples (must contain ‘gx’ and ‘gy’ columns).

Returns:

Same DataFrame with four additional columns.

Return type:

pd.DataFrame

pyavs.pilot.dataloader.add_fixation_sequence_position(events)[source]

Add fixation sequence position (from first and from last) per trial/recording.

Parameters:

events (pd.DataFrame) – Fixation events DataFrame enriched by load_pilot_events().

Returns:

Same DataFrame with ‘fix_sequence’ and ‘fix_sequence_from_last’ columns added.

Return type:

pd.DataFrame