pyavs.load_samples_with_scenes

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

Convenience function to load samples file and attach scene information.

This function loads eye tracking samples from a file and attaches scene information in a single step, following pyAVS conventions.

Parameters:

  • subject_id (int) – Subject identifier

  • session (int) – Session number

  • samples_file (str, optional) – Path to samples CSV file. If None, attempts to find standard location.

  • data_path (str, optional) – Path to 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

  • validate_results (bool, default True) – Whether to validate and report assignment results

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

Returns:

Samples dataframe with attached scene information

Return type:

pd.DataFrame

Examples

>>> # Load samples with scene information
>>> samples = load_samples_with_scenes(
...     subject_id=1, session=1,
...     data_path="/path/to/avs/data"
... )
>>>
>>> # Check coverage
>>> coverage = (samples['sceneID'].notna().sum() / len(samples)) * 100
>>> print(f"Scene coverage: {coverage:.1f}%")