pyavs.create_et_event_epochs

pyavs.create_et_event_epochs(raw: mne.io.Raw, eye_events_df: DataFrame, event_type: str = 'saccade', recording: str = 'scene', tmin: float = -0.2, tmax: float = 0.8, baseline: Tuple[float, float] | None = None, picks: str | list | None = 'meg', reject: dict | None = None, reject_by_annotation: bool = True, preload: bool = True, offset_scene_triggers_ms: float = 20.0, verbose: bool = True, **kwargs) → Tuple[mne.Epochs, DataFrame][source]

Create MEG epochs based on eye tracking events using the AVS composer approach.

This function aligns MEG and ET data by using scene onset triggers (code 100) as temporal anchors and then adding the eye tracking event’s time_in_trial relative timing. This follows the methodology from the original AVS-machine-room codebase.

Parameters:

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

  • eye_events_df (pd.DataFrame) – Eye tracking events dataframe with ‘time_in_trial’, ‘block’, ‘trial_per_block’ columns

  • event_type (str, optional) – Type of eye tracking event to use (‘scene’, ‘fixation’, ‘saccade’, ‘blink’) (default: ‘saccade’)

  • recording (str, optional) – Recording context (‘scene’, ‘caption’, ‘microphone’) (default: ‘scene’)

  • tmin (float, optional) – Start time before event in seconds (default: -0.2)

  • tmax (float, optional) – End time after event in seconds (default: 0.8)

  • baseline (tuple or None, optional) – Baseline time window (default: None)

  • picks (str or list, optional) – Channels to include (default: ‘meg’)

  • reject (dict, optional) – Rejection criteria (default: None)

  • reject_by_annotation (bool, optional) – Whether to reject by annotations (default: True)

  • preload (bool, optional) – Whether to preload epoch data (default: True)

  • offset_scene_triggers_ms (float, optional) – Systematic offset correction in milliseconds (default: 20.0) This compensates for hardware delays between MEG and ET systems

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

Returns:

(epochs, events_metadata) - MEG epochs and corresponding event metadata

Return type:

tuple

Notes

This implementation follows the AVS composer methodology: 1. Find MEG scene onset triggers (code 100) for each trial 2. Calculate MEG event times as: scene_onset_time + time_in_trial + offset 3. Apply systematic 20ms offset correction for hardware delays 4. Create epochs using the calculated MEG sample times

Required columns in eye_events_df: - ‘time_in_trial’: Relative time from scene onset in seconds - ‘block’: Block number - ‘trial_per_block’: Trial number within block - ‘type’: Event type (‘fixation’, ‘saccade’, ‘blink’) - ‘recording’: Recording context (‘scene’, ‘caption’, etc.)