Data Loading (pyavs.dataloader)

The dataloader module provides functions for loading MEG, eye tracking, and auxiliary data from the AVS dataset.

Core Data Loaders

Data loading functions for pyAVS package.

This module provides functions for loading MEG, eye-tracking, and anatomical data from the Active Visual Semantics BIDS dataset.

pyavs.dataloader.loaders.load_eye_events(subject_id: int, session: int, data_path: str | None = None, preprocessed: bool = True, output_prefix: str = 'as') → Tuple[DataFrame, DataFrame][source]

Load eye tracking events and messages for a subject/session.

Parameters:

  • subject_id (int) – Subject ID

  • session (int) – Session number

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

  • preprocessed (bool, optional) – Whether to load preprocessed data (default: True)

  • output_prefix (str, optional) – Output file prefix (default: ‘as’)

Returns:

(events_df, messages_df) - Eye tracking events and messages dataframes

Return type:

tuple

pyavs.dataloader.loaders.load_eye_samples(subject_id: int, session: int, data_path: str | None = None, output_prefix: str = 'as') → DataFrame[source]

Load cleaned eye tracking samples (including pupil area) for a subject/session.

pyavs.dataloader.loaders.load_experiment_log(subject_id: int, session: int, data_path: str | None = None, output_prefix: str = 'as') → DataFrame[source]

Load experiment log for a subject/session.

Parameters:

  • subject_id (int) – Subject ID

  • session (int) – Session number

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

  • output_prefix (str, optional) – Output file prefix (default: ‘as’)

Returns:

Experiment log dataframe

Return type:

pd.DataFrame

pyavs.dataloader.loaders.load_anatomical(subject_id: int, data_path: str | None = None) → str[source]

Load anatomical data path for a subject.

Parameters:

  • subject_id (int) – Subject ID

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

Returns:

Path to the defaced T1 volume.

Return type:

str

Notes

The release ships the defaced T1 at sub-XX/anat/T1.mgz. A FreeSurfer copy under derivatives/freesurfer/sub-XX/mri/T1.mgz is used as a fallback where present; mri/ volumes beyond the defaced T1 are withheld from the release.

pyavs.dataloader.loaders.load_scenes(scene_ids: str | List[int] = 'all', data_path: str | None = None, download: bool = True) → Dict[int, str][source]

Load scene image paths, fetching from COCO on demand if not shipped locally.

Parameters:

  • scene_ids (str or list of int, optional) – Scene IDs to load. If ‘all’, loads every AVS scene: from the shipped stimuli/images/ directory if present, else — if download — by fetching all 4,080 from COCO (slow; a one-time cost, since each fetch is cached). (default: ‘all’)

  • data_path (str, optional) – Path to the avs-public root. If None, uses configured data path

  • download (bool, optional) – Fetch images missing locally from COCO’s own hosting and cache them under the layout’s derivatives_root (default: True). If False, only already-shipped/cached images are returned.

Returns:

Dictionary mapping COCO image IDs to image file paths.

Return type:

dict

Notes

The release does not ship per-image scene JPEGs (COCO/Flickr photos carry no redistribution license). Images are reconstructed on first use from coco_url in stimuli/avs_scenes_all_licenses.parquet and the same center-crop + resize used to build the original {coco_id:012d}_MEG_size.jpg stimuli, then cached locally so repeat calls skip the network.

pyavs.dataloader.loaders.load_calibration_files(subject_id: int, session: int, data_path: str | None = None) → Dict[str, str][source]

Load calibration file paths for a subject/session.

Parameters:

  • subject_id (int) – Subject ID

  • session (int) – Session number

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

Returns:

Dictionary with calibration file paths

Return type:

dict

pyavs.dataloader.loaders.load_empty_room(subject_id: int, session: int, before_after: str = 'both', data_path: str | None = None) → Dict[str, str][source]

Load empty room recording paths.

Parameters:

  • subject_id (int) – Subject ID

  • session (int) – Session number

  • before_after (str, optional) – Which recordings to load (‘before’, ‘after’, ‘both’, default: ‘both’)

  • data_path (str, optional) – Path to the avs-public root. If None, uses configured data path

Returns:

Dictionary mapping ‘before’/’after’ to existing empty-room file paths. Sessions record two empty rooms, as01ab.fif (‘b’ = bevor) and as01ad.fif (‘d’ = danach); as05a has no after recording.

Return type:

dict

Eye Tracking Data

Eye tracking data processing for pyAVS package.

This module provides functions for loading, enriching, and processing eye tracking events from the Active Visual Semantics dataset.

pyavs.dataloader.eye.load_and_enrich_eye_events(subjects: List[int], sessions: List[int], data_path: str | None = None, output_prefix: str = 'as', preprocessed: bool = True, fix_multi_saccades: bool = True, verbose: bool = True, include_fixation_zero: bool = False, offset_scene_triggers_ms: int = 20, add_event_sequence_positions: bool = True, add_pupil_dilation: bool = False, **kwargs) → Tuple[DataFrame, DataFrame][source]

Load and enrich eye tracking events for multiple subjects/sessions.

This function combines fixation events from all subjects into one dataframe and enriches it with: - Trial, block, and scene ID information - Scene vs caption task recording type - Timing information relative to trial onset - Fixation sequence positions

Parameters:

  • subjects (list of int) – List of subject IDs to include

  • sessions (list of int) – List of session numbers to include

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

  • output_prefix (str, optional) – Output file prefix (default: ‘as’)

  • preprocessed (bool, optional) – Whether to load preprocessed data (default: True)

  • fix_multi_saccades (bool, optional) – Whether to fix multi-saccade artifacts (default: True)

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

  • include_fixation_zero (bool, optional) – Whether to include fixations that partially overlap with fixation cross (default: False)

  • offset_scene_triggers_ms (int, optional) – Offset to fix scene trigger delay in milliseconds (default: 20)

  • add_pupil_dilation (bool, optional) – Whether to compute and add pa_mean and pa_sd per fixation from cleaned samples (default: False). Requires cleaned_samples file to be present.

Returns:

(experiment_log_df, events_df) - Combined experiment log and events dataframes

Return type:

tuple

pyavs.dataloader.eye.add_fixation_sequence_position(events: DataFrame, add_saccade_sequence: bool = True, verbose: bool = False) → DataFrame[source]

Add fixation sequence positions to events dataframe.

Parameters:

  • events (pd.DataFrame) – Events dataframe

  • add_saccade_sequence (bool, optional) – Whether to also add saccade sequence positions (default: True)

  • verbose (bool, optional) – Whether to print progress information (default: False)

Returns:

Events dataframe with sequence positions added

Return type:

pd.DataFrame

pyavs.dataloader.eye.add_pupil_dilation_to_events(events_df: DataFrame, samples_df: DataFrame) → DataFrame[source]

Add mean and SD of pupil area to fixation events.

For each fixation event, all cleaned samples whose smpl_time falls within [start_time, end_time] are aggregated. Adds columns pa_mean and pa_sd. Non-fixation events receive NaN.

Parameters:

  • events_df (pd.DataFrame) – Events dataframe (must have start_time, end_time, type columns).

  • samples_df (pd.DataFrame) – Cleaned samples dataframe with smpl_time and pa columns.

Returns:

events_df with pa_mean and pa_sd columns added.

Return type:

pd.DataFrame

pyavs.dataloader.eye.extract_pupil_epochs(events_df: DataFrame, samples_df: DataFrame, epoch_length_ms: int = 1000, pre_onset_ms: int = 200) → Tuple[ndarray, DataFrame, ndarray][source]

Extract per-fixation pupil area timecourses from cleaned samples.

The epoch window starts pre_onset_ms milliseconds before each fixation onset, so index 0 = pre_onset_ms before onset and index pre_onset_ms = onset.

Fixations shorter than epoch_length_ms - pre_onset_ms ms are right-padded with NaN. Fixations longer than that are truncated at epoch_length_ms.

Parameters:

  • events_df (pd.DataFrame) – Enriched events dataframe (must have start_time, end_time, type columns). Only fixation rows are processed.

  • samples_df (pd.DataFrame) – Cleaned samples dataframe for the same recording session, with smpl_time (seconds) and pa columns.

  • epoch_length_ms (int, optional) – Total epoch length in milliseconds (default 1000). Assumes 1000 Hz sampling.

  • pre_onset_ms (int, optional) – Number of milliseconds before fixation onset included at the start of the epoch (default 200). Must be < epoch_length_ms.

Returns:

  • epochs (np.ndarray, shape (n_fixations, epoch_length_ms)) – Pupil area timecourses; NaN where data is absent. Row index pre_onset_ms corresponds to fixation onset.

  • fix_events (pd.DataFrame) – Fixation rows from events_df (reset index), row-aligned with epochs.

  • times (np.ndarray, shape (epoch_length_ms,)) – Time axis in milliseconds relative to fixation onset. times[pre_onset_ms] == 0 by construction.

pyavs.dataloader.eye.add_cross_event_information(events_df: DataFrame, verbose: bool = False) → DataFrame[source]

Add cross-event information (saccade-fixation relationships).

This function adds information about: - Preceding/following saccade amplitudes for fixations - Preceding/following fixation durations for saccades - Object labels for cross-event relationships (if available)

Parameters:

  • events_df (pd.DataFrame) – Events dataframe

  • verbose (bool, optional) – Whether to print warnings (default: False)

Returns:

Events dataframe with cross-event information added

Return type:

pd.DataFrame

MEG Data

MEG data loading for pyAVS package.

This module provides functions for loading MEG data from the Active Visual Semantics BIDS dataset, including raw files, preprocessed data, and empty room recordings.

pyavs.dataloader.meg.load_meg_raw(subject_id: int, session: int, run: int, data_path: str | None = None, preload: bool = False, verbose: bool = True) → mne.io.Raw[source]

Load raw MEG data for a specific subject/session/run.

Parameters:

  • subject_id (int) – Subject ID

  • session (int) – Session number

  • run (int) – Run/block number

  • data_path (str, optional) – Path to the avs-public root. If None, uses configured data path

  • preload (bool, optional) – Whether to preload the data into memory (default: False)

  • verbose (bool, optional) – Whether to print loading information (default: True)

Returns:

Raw MEG data

Return type:

mne.io.Raw

pyavs.dataloader.meg.load_meg_preprocessed(subject_id: int, session: int, run: int, data_path: str | None = None, preload: bool = False, verbose: bool = True) → mne.io.Raw[source]

Load preprocessed MEG data for a specific subject/session/run.

Parameters:

  • subject_id (int) – Subject ID

  • session (int) – Session number

  • run (int) – Run/block number

  • data_path (str, optional) – Path to the avs-public root. If None, uses configured data path

  • preload (bool, optional) – Whether to preload the data into memory (default: False)

  • verbose (bool, optional) – Whether to print loading information (default: True)

Returns:

Preprocessed (Maxwell-filtered) raw MEG data

Return type:

mne.io.Raw

pyavs.dataloader.meg.load_meg_session(subject_id: int, session: int, runs: List[int] | None = None, data_path: str | None = None, preprocessed: bool = True, preload: bool = False, verbose: bool = True) → Dict[int, mne.io.Raw][source]

Load MEG data for all runs in a session.

Parameters:

  • subject_id (int) – Subject ID

  • session (int) – Session number

  • runs (list of int, optional) – List of run numbers to load. If None, loads all available runs

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

  • preprocessed (bool, optional) – Whether to load preprocessed data (default: True)

  • preload (bool, optional) – Whether to preload the data into memory (default: False)

  • verbose (bool, optional) – Whether to print loading information (default: True)

Returns:

Dictionary mapping run numbers to Raw objects

Return type:

dict

pyavs.dataloader.meg.load_empty_room_recording(subject_id: int, session: int, recording_type: str = 'before', data_path: str | None = None, preload: bool = False, verbose: bool = True) → mne.io.Raw | None[source]

Load empty room recording for a session.

Parameters:

  • subject_id (int) – Subject ID

  • session (int) – Session number

  • recording_type (str, optional) – Type of empty room recording (‘before’ or ‘after’) (default: ‘before’)

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

  • preload (bool, optional) – Whether to preload the data into memory (default: False)

  • verbose (bool, optional) – Whether to print loading information (default: True)

Returns:

Empty room recording, or None if not found

Return type:

mne.io.Raw or None

pyavs.dataloader.meg.load_and_preprocess_meg_run(subject_id: int, session: int, run: int, data_path: str | None = None, force_recompute: bool = False, save_preprocessed: bool = True, **preprocessing_kwargs) → mne.io.Raw[source]

Load and preprocess MEG data for a single run.

Parameters:

  • subject_id (int) – Subject ID

  • session (int) – Session number

  • run (int) – Run/block number

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

  • force_recompute (bool, optional) – Whether to force recomputation even if preprocessed data exists (default: False)

  • save_preprocessed (bool, optional) – Whether to save preprocessed data (default: True)

  • **preprocessing_kwargs – Additional arguments passed to preprocess_meg_block

Returns:

Preprocessed MEG data

Return type:

mne.io.Raw

pyavs.dataloader.meg.save_preprocessed_meg(raw: mne.io.Raw, subject_id: int, session: int, run: int, data_path: str | None = None, overwrite: bool = True) → str[source]

Save preprocessed MEG data.

Parameters:

  • raw (mne.io.Raw) – Preprocessed MEG data

  • subject_id (int) – Subject ID

  • session (int) – Session number

  • run (int) – Run/block number

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

  • overwrite (bool, optional) – Whether to overwrite existing files (default: True)

Returns:

Path to saved file

Return type:

str

pyavs.dataloader.meg.concatenate_meg_runs(raws_dict: Dict[int, mne.io.Raw], events_list: List[ndarray] | None = None, verbose: bool = True) → Tuple[mne.io.Raw, ndarray | None][source]

Concatenate MEG data from multiple runs.

Parameters:

  • raws_dict (dict) – Dictionary mapping run numbers to Raw objects

  • events_list (list of np.ndarray, optional) – List of events arrays for each run (default: None)

  • verbose (bool, optional) – Whether to print concatenation information (default: True)

Returns:

(concatenated_raw, concatenated_events)

Return type:

tuple

pyavs.dataloader.meg.load_meg_events(raw: mne.io.Raw, stim_channel: str = 'STI101', min_duration: float = 0.001, shortest_event: int = 1, mask: int | None = None, uint_cast: bool = False, mask_type: str = 'and', initial_event: bool = False, verbose: bool = True) → ndarray[source]

Extract events from MEG stimulus channel.

Parameters:

  • raw (mne.io.Raw) – MEG raw data

  • stim_channel (str, optional) – Stimulus channel name (default: ‘STI101’)

  • min_duration (float, optional) – Minimum event duration in seconds (default: 0.001)

  • shortest_event (int, optional) – Shortest event in samples (default: 1)

  • mask (int, optional) – Mask for trigger values (default: None)

  • uint_cast (bool, optional) – Whether to cast to unsigned int (default: False)

  • mask_type (str, optional) – Type of mask operation (default: ‘and’)

  • initial_event (bool, optional) – Whether to include initial event (default: False)

  • verbose (bool, optional) – Whether to print event information (default: True)

Returns:

Events array with shape (n_events, 3) containing [sample, prev_id, id]

Return type:

np.ndarray

pyavs.dataloader.meg.check_meg_data_integrity(subject_id: int, session: int, runs: List[int] | None = None, data_path: str | None = None) → Dict[str, Any][source]

Check integrity of MEG data files.

Parameters:

  • subject_id (int) – Subject ID

  • session (int) – Session number

  • runs (list of int, optional) – List of run numbers to check. If None, checks all available runs

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

Returns:

Dictionary with integrity check results

Return type:

dict