Handling Gaze Events#

What you will learn in this tutorial:#

  • how to detect different events using different algorithms like IDT, IVT and microsaccades

  • how to compute event properties like peak velocity and amplitude

  • how to save and load your event data

Preparations#

At first, we import pymovements as the alias pm for convenience.

import pymovements as pm

Then we download a dataset ToyDataset and load its data:

dataset = pm.Dataset('ToyDataset', path='data/ToyDataset')
dataset.download()
dataset.load()

INFO:pymovements.dataset.dataset:
        You are downloading the pymovements Toy Dataset. Please be aware that pymovements does not
        host or distribute any dataset resources and only provides a convenient interface to
        download the public dataset resources that were published by their respective authors.

        Please cite the referenced publication if you intend to use the dataset in your research.
        

Downloading https://github.com/pymovements/pymovements-toy-dataset/archive/refs/heads/main.zip to data/ToyDataset/downloads/pymovements-toy-dataset.zip

Checking integrity of pymovements-toy-dataset.zip
Extracting pymovements-toy-dataset.zip to data/ToyDataset/raw

Extracting archive:   0%|          | 0/23 [00:00<?, ?file/s]

Extracting archive: 100%|██████████| 23/23 [00:00<00:00, 284.15file/s]
Dataset
  • DatasetDefinition
    DatasetDefinition
    • name:
      'ToyDataset'
    • long_name:
      'pymovements Toy Dataset'
    • 'Example toy dataset. This dataset includes monocu...'
      'Example toy dataset.\n\nThis dataset includes monocular eye tracking data from a single participant in a single\nsession. Eye movements are recorded at a sampling frequency of 1000 Hz using an EyeLink Portable\nDuo video-based eye tracker and are provided as pixel coordinates.\n\nThe participant is instructed to read 4 texts with 5 screens each.\n'
    • Experiment
      Experiment
      • EyeTracker
        EyeTracker
        • left:
          None
        • model:
          None
        • mount:
          None
        • right:
          None
        • sampling_rate:
          1000
        • vendor:
          None
        • version:
          None
      • Screen
        Screen
        • distance_cm:
          68
        • height_cm:
          30.2
        • height_px:
          1024
        • origin:
          'upper left'
        • width_cm:
          38
        • width_px:
          1280
        • x_max_dva:
          15.599386487782953
        • x_min_dva:
          -15.599386487782953
        • y_max_dva:
          12.508044410882546
        • y_min_dva:
          -12.508044410882546
    • list (1 items)
      • ResourceDefinition
        • content:
          'gaze'
        • filename:
          'pymovements-toy-dataset.zip'
        • filename_pattern:
          'trial_{text_id:d}_{page_id:d}.csv'
        • dict (2 items)
          • text_id:
            <class 'int'>
          • page_id:
            <class 'int'>
        • load_function:
          None
        • dict (4 items)
          • time_column:
            'timestamp'
          • time_unit:
            'ms'
          • (2 more)
        • md5:
          '256901852c1c07581d375eef705855d6'
        • mirrors:
          None
        • WebSource
          WebSource(url='https://github.com/pymovements/pymovements-toy-dataset/archive/refs/heads/main.zip', filename='pymovements-toy-dataset.zip', md5='256901852c1c07581d375eef705855d6', mirrors=None)
        • 'https://github.com/pymovements/pymovements-toy-dat...'
          'https://github.com/pymovements/pymovements-toy-dataset/archive/refs/heads/main.zip'
  • tuple (20 items)
    • Events
      • DataFrame (4 columns, 0 rows)
        shape: (0, 4)
        nameonsetoffsetduration
        stri64i64i64
      • trial_columns:
        None
    • Events
      • DataFrame (4 columns, 0 rows)
        shape: (0, 4)
        nameonsetoffsetduration
        stri64i64i64
      • trial_columns:
        None
    • (18 more)
  • dict (1 items)
    • DataFrame (3 columns, 20 rows)
      shape: (20, 3)
      text_idpage_idfilepath
      i64i64str
      01"pymovements-toy-dataset-main/d…
      02"pymovements-toy-dataset-main/d…
      03"pymovements-toy-dataset-main/d…
      04"pymovements-toy-dataset-main/d…
      05"pymovements-toy-dataset-main/d…
      ………
      31"pymovements-toy-dataset-main/d…
      32"pymovements-toy-dataset-main/d…
      33"pymovements-toy-dataset-main/d…
      34"pymovements-toy-dataset-main/d…
      35"pymovements-toy-dataset-main/d…
  • list (20 items)
    • Gaze
      • DataFrame (4 columns, 17223 rows)
        shape: (17_223, 4)
        timestimuli_xstimuli_ypixel
        i64f64f64list[f64]
        1988145-1.0-1.0[206.8, 152.4]
        1988146-1.0-1.0[206.9, 152.1]
        1988147-1.0-1.0[207.0, 151.8]
        1988148-1.0-1.0[207.1, 151.7]
        1988149-1.0-1.0[207.0, 151.5]
        …………
        2005363-1.0-1.0[361.0, 415.4]
        2005364-1.0-1.0[358.0, 414.5]
        2005365-1.0-1.0[355.8, 413.8]
        2005366-1.0-1.0[353.1, 413.2]
        2005367-1.0-1.0[351.2, 412.9]
      • Events
        Events
        • DataFrame (4 columns, 0 rows)
          shape: (0, 4)
          nameonsetoffsetduration
          stri64i64i64
        • trial_columns:
          None
      • trial_columns:
        None
      • Experiment
        Experiment
        • EyeTracker
          EyeTracker
          • left:
            None
          • model:
            None
          • mount:
            None
          • right:
            None
          • sampling_rate:
            1000
          • vendor:
            None
          • version:
            None
        • Screen
          Screen
          • distance_cm:
            68
          • height_cm:
            30.2
          • height_px:
            1024
          • origin:
            'upper left'
          • width_cm:
            38
          • width_px:
            1280
          • x_max_dva:
            15.599386487782953
          • x_min_dva:
            -15.599386487782953
          • y_max_dva:
            12.508044410882546
          • y_min_dva:
            -12.508044410882546
    • Gaze
      • DataFrame (4 columns, 29799 rows)
        shape: (29_799, 4)
        timestimuli_xstimuli_ypixel
        i64f64f64list[f64]
        2008305-1.0-1.0[141.4, 153.6]
        2008306-1.0-1.0[141.1, 153.2]
        2008307-1.0-1.0[140.7, 152.8]
        2008308-1.0-1.0[140.6, 152.7]
        2008309-1.0-1.0[140.5, 152.6]
        …………
        2038099-1.0-1.0[273.8, 773.8]
        2038100-1.0-1.0[273.8, 774.1]
        2038101-1.0-1.0[273.9, 774.5]
        2038102-1.0-1.0[274.0, 774.4]
        2038103-1.0-1.0[274.0, 773.9]
      • Events
        Events
        • DataFrame (4 columns, 0 rows)
          shape: (0, 4)
          nameonsetoffsetduration
          stri64i64i64
        • trial_columns:
          None
      • trial_columns:
        None
      • Experiment
        Experiment
        • EyeTracker
          EyeTracker
          • left:
            None
          • model:
            None
          • mount:
            None
          • right:
            None
          • sampling_rate:
            1000
          • vendor:
            None
          • version:
            None
        • Screen
          Screen
          • distance_cm:
            68
          • height_cm:
            30.2
          • height_px:
            1024
          • origin:
            'upper left'
          • width_cm:
            38
          • width_px:
            1280
          • x_max_dva:
            15.599386487782953
          • x_min_dva:
            -15.599386487782953
          • y_max_dva:
            12.508044410882546
          • y_min_dva:
            -12.508044410882546
    • (18 more)
  • path:
    PosixPath('data/ToyDataset')
  • DatasetPaths
    DatasetPaths
    • dataset:
      PosixPath('data/ToyDataset')
    • downloads:
      PosixPath('data/ToyDataset/downloads')
    • events:
      PosixPath('data/ToyDataset/events')
    • precomputed_events:
      PosixPath('data/ToyDataset/precomputed_events')
    • precomputed_reading_measures:
      PosixPath('data/ToyDataset/precomputed_reading_measures')
    • preprocessed:
      PosixPath('data/ToyDataset/preprocessed')
    • raw:
      PosixPath('data/ToyDataset/raw')
    • root:
      PosixPath('data/ToyDataset')
    • stimuli:
      PosixPath('data/ToyDataset/stimuli')
  • precomputed_events:
    list (0 items)
  • precomputed_reading_measures:
    list (0 items)
  • stimuli:
    list (0 items)

The dataset consists of gaze data in 20 files (check Dataset/gaze above). Every Gaze has some samples with six columns (check Gaze/samples): [time, stimuli_x, stimuli_y, text_id, page_id, pixel]. The Gaze/events DataFrame is empty so far. To be able to calculate events, we need to do some basic preprocessing, which will add new columns to the dataset samples DataFrame:

  • Dataset.pix2deg(): adds position column with degrees from the screen center needed by the idt algorithm

  • Dataset.pos2vel(): adds velocity column with gaze velocities needed by microsaccades and ivt algorithms

dataset.pix2deg()
dataset.pos2vel('smooth')
dataset.gaze[0]
Gaze
  • DataFrame (6 columns, 17223 rows)
    shape: (17_223, 6)
    timestimuli_xstimuli_ypixelpositionvelocity
    i64f64f64list[f64]list[f64]list[f64]
    1988145-1.0-1.0[206.8, 152.4][-10.697598, -8.852399][null, null]
    1988146-1.0-1.0[206.9, 152.1][-10.695183, -8.859678][null, null]
    1988147-1.0-1.0[207.0, 151.8][-10.692768, -8.866956][1.610194, -5.256267]
    1988148-1.0-1.0[207.1, 151.7][-10.690352, -8.869381][0.402548, -4.447465]
    1988149-1.0-1.0[207.0, 151.5][-10.692768, -8.874233][0.402561, -3.234462]
    ………………
    2005363-1.0-1.0[361.0, 415.4][-6.932438, -2.386672][-63.266374, -21.085616]
    2005364-1.0-1.0[358.0, 414.5][-7.006376, -2.408998][-63.249652, -19.431326]
    2005365-1.0-1.0[355.8, 413.8][-7.060582, -2.426362][-60.359624, -15.710061]
    2005366-1.0-1.0[353.1, 413.2][-7.12709, -2.441245][null, null]
    2005367-1.0-1.0[351.2, 412.9][-7.173881, -2.448686][null, null]
  • Events
    Events
    • DataFrame (4 columns, 0 rows)
      shape: (0, 4)
      nameonsetoffsetduration
      stri64i64i64
    • trial_columns:
      None
  • trial_columns:
    None
  • Experiment
    Experiment
    • EyeTracker
      EyeTracker
      • left:
        None
      • model:
        None
      • mount:
        None
      • right:
        None
      • sampling_rate:
        1000
      • vendor:
        None
      • version:
        None
    • Screen
      Screen
      • distance_cm:
        68
      • height_cm:
        30.2
      • height_px:
        1024
      • origin:
        'upper left'
      • width_cm:
        38
      • width_px:
        1280
      • x_max_dva:
        15.599386487782953
      • x_min_dva:
        -15.599386487782953
      • y_max_dva:
        12.508044410882546
      • y_min_dva:
        -12.508044410882546

Now every Gaze/samples DataFrame has two more columns: position and velocity which will be used by the event detection algorithms.

Detecting Events#

pymovements provides a range of event detection methods for several types of gaze events.

See the reference for Events to get an overview of all the supported methods.

For this tutorial we will use the I-DT and I-VT (idt and ivt) algorithms for detecting fixations and the microsaccades algorithm for detecting saccades.

Let’s start with fixations detection using the idt algorithm with the dispersion_threshold equal to 2.7:

dataset.detect_events('idt', dispersion_threshold=2.7)
Dataset
  • DatasetDefinition
    DatasetDefinition
    • name:
      'ToyDataset'
    • long_name:
      'pymovements Toy Dataset'
    • 'Example toy dataset. This dataset includes monocu...'
      'Example toy dataset.\n\nThis dataset includes monocular eye tracking data from a single participant in a single\nsession. Eye movements are recorded at a sampling frequency of 1000 Hz using an EyeLink Portable\nDuo video-based eye tracker and are provided as pixel coordinates.\n\nThe participant is instructed to read 4 texts with 5 screens each.\n'
    • Experiment
      Experiment
      • EyeTracker
        EyeTracker
        • left:
          None
        • model:
          None
        • mount:
          None
        • right:
          None
        • sampling_rate:
          1000
        • vendor:
          None
        • version:
          None
      • Screen
        Screen
        • distance_cm:
          68
        • height_cm:
          30.2
        • height_px:
          1024
        • origin:
          'upper left'
        • width_cm:
          38
        • width_px:
          1280
        • x_max_dva:
          15.599386487782953
        • x_min_dva:
          -15.599386487782953
        • y_max_dva:
          12.508044410882546
        • y_min_dva:
          -12.508044410882546
    • list (1 items)
      • ResourceDefinition
        • content:
          'gaze'
        • filename:
          'pymovements-toy-dataset.zip'
        • filename_pattern:
          'trial_{text_id:d}_{page_id:d}.csv'
        • dict (2 items)
          • text_id:
            <class 'int'>
          • page_id:
            <class 'int'>
        • load_function:
          None
        • dict (4 items)
          • time_column:
            'timestamp'
          • time_unit:
            'ms'
          • (2 more)
        • md5:
          '256901852c1c07581d375eef705855d6'
        • mirrors:
          None
        • WebSource
          WebSource(url='https://github.com/pymovements/pymovements-toy-dataset/archive/refs/heads/main.zip', filename='pymovements-toy-dataset.zip', md5='256901852c1c07581d375eef705855d6', mirrors=None)
        • 'https://github.com/pymovements/pymovements-toy-dat...'
          'https://github.com/pymovements/pymovements-toy-dataset/archive/refs/heads/main.zip'
  • tuple (20 items)
    • Events
      • DataFrame (4 columns, 56 rows)
        shape: (56, 4)
        nameonsetoffsetduration
        stri64i64i64
        "fixation"19881451988563418
        "fixation"19885641988750186
        "fixation"19887511989178427
        "fixation"19891791989436257
        "fixation"19894371989600163
        …………
        "fixation"20039292004090161
        "fixation"20040912004363272
        "fixation"20043642004883519
        "fixation"20048852005116231
        "fixation"20051172005298181
      • trial_columns:
        None
    • Events
      • DataFrame (4 columns, 94 rows)
        shape: (94, 4)
        nameonsetoffsetduration
        stri64i64i64
        "fixation"20083052008621316
        "fixation"20086222008821199
        "fixation"20088222009214392
        "fixation"20092152009433218
        "fixation"20094342009704270
        …………
        "fixation"20368402037175335
        "fixation"20371762037424248
        "fixation"20374622037644182
        "fixation"20376452037824179
        "fixation"20378252038103278
      • trial_columns:
        None
    • (18 more)
  • dict (1 items)
    • DataFrame (3 columns, 20 rows)
      shape: (20, 3)
      text_idpage_idfilepath
      i64i64str
      01"pymovements-toy-dataset-main/d…
      02"pymovements-toy-dataset-main/d…
      03"pymovements-toy-dataset-main/d…
      04"pymovements-toy-dataset-main/d…
      05"pymovements-toy-dataset-main/d…
      ………
      31"pymovements-toy-dataset-main/d…
      32"pymovements-toy-dataset-main/d…
      33"pymovements-toy-dataset-main/d…
      34"pymovements-toy-dataset-main/d…
      35"pymovements-toy-dataset-main/d…
  • list (20 items)
    • Gaze
      • DataFrame (6 columns, 17223 rows)
        shape: (17_223, 6)
        timestimuli_xstimuli_ypixelpositionvelocity
        i64f64f64list[f64]list[f64]list[f64]
        1988145-1.0-1.0[206.8, 152.4][-10.697598, -8.852399][null, null]
        1988146-1.0-1.0[206.9, 152.1][-10.695183, -8.859678][null, null]
        1988147-1.0-1.0[207.0, 151.8][-10.692768, -8.866956][1.610194, -5.256267]
        1988148-1.0-1.0[207.1, 151.7][-10.690352, -8.869381][0.402548, -4.447465]
        1988149-1.0-1.0[207.0, 151.5][-10.692768, -8.874233][0.402561, -3.234462]
        ………………
        2005363-1.0-1.0[361.0, 415.4][-6.932438, -2.386672][-63.266374, -21.085616]
        2005364-1.0-1.0[358.0, 414.5][-7.006376, -2.408998][-63.249652, -19.431326]
        2005365-1.0-1.0[355.8, 413.8][-7.060582, -2.426362][-60.359624, -15.710061]
        2005366-1.0-1.0[353.1, 413.2][-7.12709, -2.441245][null, null]
        2005367-1.0-1.0[351.2, 412.9][-7.173881, -2.448686][null, null]
      • Events
        Events
        • DataFrame (4 columns, 56 rows)
          shape: (56, 4)
          nameonsetoffsetduration
          stri64i64i64
          "fixation"19881451988563418
          "fixation"19885641988750186
          "fixation"19887511989178427
          "fixation"19891791989436257
          "fixation"19894371989600163
          …………
          "fixation"20039292004090161
          "fixation"20040912004363272
          "fixation"20043642004883519
          "fixation"20048852005116231
          "fixation"20051172005298181
        • trial_columns:
          None
      • trial_columns:
        None
      • Experiment
        Experiment
        • EyeTracker
          EyeTracker
          • left:
            None
          • model:
            None
          • mount:
            None
          • right:
            None
          • sampling_rate:
            1000
          • vendor:
            None
          • version:
            None
        • Screen
          Screen
          • distance_cm:
            68
          • height_cm:
            30.2
          • height_px:
            1024
          • origin:
            'upper left'
          • width_cm:
            38
          • width_px:
            1280
          • x_max_dva:
            15.599386487782953
          • x_min_dva:
            -15.599386487782953
          • y_max_dva:
            12.508044410882546
          • y_min_dva:
            -12.508044410882546
    • Gaze
      • DataFrame (6 columns, 29799 rows)
        shape: (29_799, 6)
        timestimuli_xstimuli_ypixelpositionvelocity
        i64f64f64list[f64]list[f64]list[f64]
        2008305-1.0-1.0[141.4, 153.6][-12.268583, -8.823284][null, null]
        2008306-1.0-1.0[141.1, 153.2][-12.275749, -8.832989][null, null]
        2008307-1.0-1.0[140.7, 152.8][-12.285302, -8.842695][-5.572617, -6.065816]
        2008308-1.0-1.0[140.6, 152.7][-12.28769, -8.845121][-3.582268, -4.043733]
        2008309-1.0-1.0[140.5, 152.6][-12.290078, -8.847547][-2.388085, -2.021821]
        ………………
        2038099-1.0-1.0[273.8, 773.8][-9.071149, 6.490168][1.21962, 1.635403]
        2038100-1.0-1.0[273.8, 774.1][-9.071149, 6.497527][1.626175, 4.497406]
        2038101-1.0-1.0[273.9, 774.5][-9.06871, 6.50734][1.626186, 1.635423]
        2038102-1.0-1.0[274.0, 774.4][-9.066271, 6.504886][null, null]
        2038103-1.0-1.0[274.0, 773.9][-9.066271, 6.492621][null, null]
      • Events
        Events
        • DataFrame (4 columns, 94 rows)
          shape: (94, 4)
          nameonsetoffsetduration
          stri64i64i64
          "fixation"20083052008621316
          "fixation"20086222008821199
          "fixation"20088222009214392
          "fixation"20092152009433218
          "fixation"20094342009704270
          …………
          "fixation"20368402037175335
          "fixation"20371762037424248
          "fixation"20374622037644182
          "fixation"20376452037824179
          "fixation"20378252038103278
        • trial_columns:
          None
      • trial_columns:
        None
      • Experiment
        Experiment
        • EyeTracker
          EyeTracker
          • left:
            None
          • model:
            None
          • mount:
            None
          • right:
            None
          • sampling_rate:
            1000
          • vendor:
            None
          • version:
            None
        • Screen
          Screen
          • distance_cm:
            68
          • height_cm:
            30.2
          • height_px:
            1024
          • origin:
            'upper left'
          • width_cm:
            38
          • width_px:
            1280
          • x_max_dva:
            15.599386487782953
          • x_min_dva:
            -15.599386487782953
          • y_max_dva:
            12.508044410882546
          • y_min_dva:
            -12.508044410882546
    • (18 more)
  • path:
    PosixPath('data/ToyDataset')
  • DatasetPaths
    DatasetPaths
    • dataset:
      PosixPath('data/ToyDataset')
    • downloads:
      PosixPath('data/ToyDataset/downloads')
    • events:
      PosixPath('data/ToyDataset/events')
    • precomputed_events:
      PosixPath('data/ToyDataset/precomputed_events')
    • precomputed_reading_measures:
      PosixPath('data/ToyDataset/precomputed_reading_measures')
    • preprocessed:
      PosixPath('data/ToyDataset/preprocessed')
    • raw:
      PosixPath('data/ToyDataset/raw')
    • root:
      PosixPath('data/ToyDataset')
    • stimuli:
      PosixPath('data/ToyDataset/stimuli')
  • precomputed_events:
    list (0 items)
  • precomputed_reading_measures:
    list (0 items)
  • stimuli:
    list (0 items)

The detected events are added as rows with the name fixation to the event dataframe:

dataset.events[0]
Events
  • DataFrame (4 columns, 56 rows)
    shape: (56, 4)
    nameonsetoffsetduration
    stri64i64i64
    "fixation"19881451988563418
    "fixation"19885641988750186
    "fixation"19887511989178427
    "fixation"19891791989436257
    "fixation"19894371989600163
    …………
    "fixation"20039292004090161
    "fixation"20040912004363272
    "fixation"20043642004883519
    "fixation"20048852005116231
    "fixation"20051172005298181
  • trial_columns:
    None

As you can see, 56 fixations were found for the first file.

Now let’s try another algorithm ivt with velocity_threshold=20. Because we don’t want to mix fixations found by different algorithms we add name parameter with ‘fixation.ivt’

dataset.detect_events('ivt', velocity_threshold=20, name='fixation.ivt')
dataset.events[0]
Events
  • DataFrame (4 columns, 129 rows)
    shape: (129, 4)
    nameonsetoffsetduration
    stri64i64i64
    "fixation"19881451988563418
    "fixation"19885641988750186
    "fixation"19887511989178427
    "fixation"19891791989436257
    "fixation"19894371989600163
    …………
    "fixation.ivt"20041322004331199
    "fixation.ivt"20043992004687288
    "fixation.ivt"20047142004878164
    "fixation.ivt"20049312005109178
    "fixation.ivt"20051382005287149
  • trial_columns:
    None

Now we have additional rows with name=’fixations.ivt’.

Let’s try to use the microsaccades algorithm to detect fixations.

dataset.detect_events('microsaccades', minimum_duration=12)
Dataset
  • DatasetDefinition
    DatasetDefinition
    • name:
      'ToyDataset'
    • long_name:
      'pymovements Toy Dataset'
    • 'Example toy dataset. This dataset includes monocu...'
      'Example toy dataset.\n\nThis dataset includes monocular eye tracking data from a single participant in a single\nsession. Eye movements are recorded at a sampling frequency of 1000 Hz using an EyeLink Portable\nDuo video-based eye tracker and are provided as pixel coordinates.\n\nThe participant is instructed to read 4 texts with 5 screens each.\n'
    • Experiment
      Experiment
      • EyeTracker
        EyeTracker
        • left:
          None
        • model:
          None
        • mount:
          None
        • right:
          None
        • sampling_rate:
          1000
        • vendor:
          None
        • version:
          None
      • Screen
        Screen
        • distance_cm:
          68
        • height_cm:
          30.2
        • height_px:
          1024
        • origin:
          'upper left'
        • width_cm:
          38
        • width_px:
          1280
        • x_max_dva:
          15.599386487782953
        • x_min_dva:
          -15.599386487782953
        • y_max_dva:
          12.508044410882546
        • y_min_dva:
          -12.508044410882546
    • list (1 items)
      • ResourceDefinition
        • content:
          'gaze'
        • filename:
          'pymovements-toy-dataset.zip'
        • filename_pattern:
          'trial_{text_id:d}_{page_id:d}.csv'
        • dict (2 items)
          • text_id:
            <class 'int'>
          • page_id:
            <class 'int'>
        • load_function:
          None
        • dict (4 items)
          • time_column:
            'timestamp'
          • time_unit:
            'ms'
          • (2 more)
        • md5:
          '256901852c1c07581d375eef705855d6'
        • mirrors:
          None
        • WebSource
          WebSource(url='https://github.com/pymovements/pymovements-toy-dataset/archive/refs/heads/main.zip', filename='pymovements-toy-dataset.zip', md5='256901852c1c07581d375eef705855d6', mirrors=None)
        • 'https://github.com/pymovements/pymovements-toy-dat...'
          'https://github.com/pymovements/pymovements-toy-dataset/archive/refs/heads/main.zip'
  • tuple (20 items)
    • Events
      • DataFrame (4 columns, 222 rows)
        shape: (222, 4)
        nameonsetoffsetduration
        stri64i64i64
        "fixation"19881451988563418
        "fixation"19885641988750186
        "fixation"19887511989178427
        "fixation"19891791989436257
        "fixation"19894371989600163
        …………
        "saccade"2004373200438512
        "saccade"2004688200470416
        "saccade"2004879200490122
        "saccade"2005110200512616
        "saccade"2005288200534557
      • trial_columns:
        None
    • Events
      • DataFrame (4 columns, 366 rows)
        shape: (366, 4)
        nameonsetoffsetduration
        stri64i64i64
        "fixation"20083052008621316
        "fixation"20086222008821199
        "fixation"20088222009214392
        "fixation"20092152009433218
        "fixation"20094342009704270
        …………
        "saccade"2036849203686112
        "saccade"2037161203718827
        "saccade"2037412203750391
        "saccade"2037638203765416
        "saccade"2037812203783018
      • trial_columns:
        None
    • (18 more)
  • dict (1 items)
    • DataFrame (3 columns, 20 rows)
      shape: (20, 3)
      text_idpage_idfilepath
      i64i64str
      01"pymovements-toy-dataset-main/d…
      02"pymovements-toy-dataset-main/d…
      03"pymovements-toy-dataset-main/d…
      04"pymovements-toy-dataset-main/d…
      05"pymovements-toy-dataset-main/d…
      ………
      31"pymovements-toy-dataset-main/d…
      32"pymovements-toy-dataset-main/d…
      33"pymovements-toy-dataset-main/d…
      34"pymovements-toy-dataset-main/d…
      35"pymovements-toy-dataset-main/d…
  • list (20 items)
    • Gaze
      • DataFrame (6 columns, 17223 rows)
        shape: (17_223, 6)
        timestimuli_xstimuli_ypixelpositionvelocity
        i64f64f64list[f64]list[f64]list[f64]
        1988145-1.0-1.0[206.8, 152.4][-10.697598, -8.852399][null, null]
        1988146-1.0-1.0[206.9, 152.1][-10.695183, -8.859678][null, null]
        1988147-1.0-1.0[207.0, 151.8][-10.692768, -8.866956][1.610194, -5.256267]
        1988148-1.0-1.0[207.1, 151.7][-10.690352, -8.869381][0.402548, -4.447465]
        1988149-1.0-1.0[207.0, 151.5][-10.692768, -8.874233][0.402561, -3.234462]
        ………………
        2005363-1.0-1.0[361.0, 415.4][-6.932438, -2.386672][-63.266374, -21.085616]
        2005364-1.0-1.0[358.0, 414.5][-7.006376, -2.408998][-63.249652, -19.431326]
        2005365-1.0-1.0[355.8, 413.8][-7.060582, -2.426362][-60.359624, -15.710061]
        2005366-1.0-1.0[353.1, 413.2][-7.12709, -2.441245][null, null]
        2005367-1.0-1.0[351.2, 412.9][-7.173881, -2.448686][null, null]
      • Events
        Events
        • DataFrame (4 columns, 222 rows)
          shape: (222, 4)
          nameonsetoffsetduration
          stri64i64i64
          "fixation"19881451988563418
          "fixation"19885641988750186
          "fixation"19887511989178427
          "fixation"19891791989436257
          "fixation"19894371989600163
          …………
          "saccade"2004373200438512
          "saccade"2004688200470416
          "saccade"2004879200490122
          "saccade"2005110200512616
          "saccade"2005288200534557
        • trial_columns:
          None
      • trial_columns:
        None
      • Experiment
        Experiment
        • EyeTracker
          EyeTracker
          • left:
            None
          • model:
            None
          • mount:
            None
          • right:
            None
          • sampling_rate:
            1000
          • vendor:
            None
          • version:
            None
        • Screen
          Screen
          • distance_cm:
            68
          • height_cm:
            30.2
          • height_px:
            1024
          • origin:
            'upper left'
          • width_cm:
            38
          • width_px:
            1280
          • x_max_dva:
            15.599386487782953
          • x_min_dva:
            -15.599386487782953
          • y_max_dva:
            12.508044410882546
          • y_min_dva:
            -12.508044410882546
    • Gaze
      • DataFrame (6 columns, 29799 rows)
        shape: (29_799, 6)
        timestimuli_xstimuli_ypixelpositionvelocity
        i64f64f64list[f64]list[f64]list[f64]
        2008305-1.0-1.0[141.4, 153.6][-12.268583, -8.823284][null, null]
        2008306-1.0-1.0[141.1, 153.2][-12.275749, -8.832989][null, null]
        2008307-1.0-1.0[140.7, 152.8][-12.285302, -8.842695][-5.572617, -6.065816]
        2008308-1.0-1.0[140.6, 152.7][-12.28769, -8.845121][-3.582268, -4.043733]
        2008309-1.0-1.0[140.5, 152.6][-12.290078, -8.847547][-2.388085, -2.021821]
        ………………
        2038099-1.0-1.0[273.8, 773.8][-9.071149, 6.490168][1.21962, 1.635403]
        2038100-1.0-1.0[273.8, 774.1][-9.071149, 6.497527][1.626175, 4.497406]
        2038101-1.0-1.0[273.9, 774.5][-9.06871, 6.50734][1.626186, 1.635423]
        2038102-1.0-1.0[274.0, 774.4][-9.066271, 6.504886][null, null]
        2038103-1.0-1.0[274.0, 773.9][-9.066271, 6.492621][null, null]
      • Events
        Events
        • DataFrame (4 columns, 366 rows)
          shape: (366, 4)
          nameonsetoffsetduration
          stri64i64i64
          "fixation"20083052008621316
          "fixation"20086222008821199
          "fixation"20088222009214392
          "fixation"20092152009433218
          "fixation"20094342009704270
          …………
          "saccade"2036849203686112
          "saccade"2037161203718827
          "saccade"2037412203750391
          "saccade"2037638203765416
          "saccade"2037812203783018
        • trial_columns:
          None
      • trial_columns:
        None
      • Experiment
        Experiment
        • EyeTracker
          EyeTracker
          • left:
            None
          • model:
            None
          • mount:
            None
          • right:
            None
          • sampling_rate:
            1000
          • vendor:
            None
          • version:
            None
        • Screen
          Screen
          • distance_cm:
            68
          • height_cm:
            30.2
          • height_px:
            1024
          • origin:
            'upper left'
          • width_cm:
            38
          • width_px:
            1280
          • x_max_dva:
            15.599386487782953
          • x_min_dva:
            -15.599386487782953
          • y_max_dva:
            12.508044410882546
          • y_min_dva:
            -12.508044410882546
    • (18 more)
  • path:
    PosixPath('data/ToyDataset')
  • DatasetPaths
    DatasetPaths
    • dataset:
      PosixPath('data/ToyDataset')
    • downloads:
      PosixPath('data/ToyDataset/downloads')
    • events:
      PosixPath('data/ToyDataset/events')
    • precomputed_events:
      PosixPath('data/ToyDataset/precomputed_events')
    • precomputed_reading_measures:
      PosixPath('data/ToyDataset/precomputed_reading_measures')
    • preprocessed:
      PosixPath('data/ToyDataset/preprocessed')
    • raw:
      PosixPath('data/ToyDataset/raw')
    • root:
      PosixPath('data/ToyDataset')
    • stimuli:
      PosixPath('data/ToyDataset/stimuli')
  • precomputed_events:
    list (0 items)
  • precomputed_reading_measures:
    list (0 items)
  • stimuli:
    list (0 items)

The detected events are added as rows with the name saccade to the event dataframe:

dataset.events[0]
Events
  • DataFrame (4 columns, 222 rows)
    shape: (222, 4)
    nameonsetoffsetduration
    stri64i64i64
    "fixation"19881451988563418
    "fixation"19885641988750186
    "fixation"19887511989178427
    "fixation"19891791989436257
    "fixation"19894371989600163
    …………
    "saccade"2004373200438512
    "saccade"2004688200470416
    "saccade"2004879200490122
    "saccade"2005110200512616
    "saccade"2005288200534557
  • trial_columns:
    None

Now there are three sets of events in the dataset.events DataFrame with different values in the ‘name’ column:

set(dataset.events[0].frame['name'])

{'fixation', 'fixation.ivt', 'saccade'}

Computing Event Properties#

pymovements provides a range of event properties.

See the reference for Events to get an overview of all the supported properties.

For this tutorial we will compute several properties of saccades.

We start out with the peak velocity:

dataset.compute_event_properties("peak_velocity")

dataset.events[0]
Events
  • DataFrame (5 columns, 222 rows)
    shape: (222, 5)
    nameonsetoffsetdurationpeak_velocity
    stri64i64i64f64
    "fixation"19881451988563418200.144558
    "fixation"19885641988750186249.67823
    "fixation"19887511989178427211.598748
    "fixation"19891791989436257189.183243
    "fixation"19894371989600163255.077509
    ……………
    "saccade"200437320043851270.374183
    "saccade"2004688200470416175.646379
    "saccade"2004879200490122209.46361
    "saccade"2005110200512616137.917594
    "saccade"2005288200534557352.550667
  • trial_columns:
    None

Check above that a new column with the name peak_velocity has appeared in the event DataFrame.

We can also pass a list of properties. Let’s add the amplitude and dispersion:

dataset.compute_event_properties(["amplitude", "dispersion"])

dataset.events[0]
Events
  • DataFrame (7 columns, 222 rows)
    shape: (222, 7)
    nameonsetoffsetdurationpeak_velocityamplitudedispersion
    stri64i64i64f64f64f64
    "fixation"19881451988563418200.1445582.4928642.712569
    "fixation"19885641988750186249.678232.6511982.865026
    "fixation"19887511989178427211.5987482.5859062.779518
    "fixation"19891791989436257189.1832432.6143472.77424
    "fixation"19894371989600163255.0775092.5946512.729391
    …………………
    "saccade"200437320043851270.3741830.70730.766684
    "saccade"2004688200470416175.6463791.8074851.875716
    "saccade"2004879200490122209.463612.9338183.086169
    "saccade"2005110200512616137.9175941.4053541.501217
    "saccade"2005288200534557352.55066714.68254116.101153
  • trial_columns:
    None

This way we can compute all of our desired properties in a single run.

Saving Event Data#

Saving your event data is as simple as:

dataset.save_events()
Dataset
  • DatasetDefinition
    DatasetDefinition
    • name:
      'ToyDataset'
    • long_name:
      'pymovements Toy Dataset'
    • 'Example toy dataset. This dataset includes monocu...'
      'Example toy dataset.\n\nThis dataset includes monocular eye tracking data from a single participant in a single\nsession. Eye movements are recorded at a sampling frequency of 1000 Hz using an EyeLink Portable\nDuo video-based eye tracker and are provided as pixel coordinates.\n\nThe participant is instructed to read 4 texts with 5 screens each.\n'
    • Experiment
      Experiment
      • EyeTracker
        EyeTracker
        • left:
          None
        • model:
          None
        • mount:
          None
        • right:
          None
        • sampling_rate:
          1000
        • vendor:
          None
        • version:
          None
      • Screen
        Screen
        • distance_cm:
          68
        • height_cm:
          30.2
        • height_px:
          1024
        • origin:
          'upper left'
        • width_cm:
          38
        • width_px:
          1280
        • x_max_dva:
          15.599386487782953
        • x_min_dva:
          -15.599386487782953
        • y_max_dva:
          12.508044410882546
        • y_min_dva:
          -12.508044410882546
    • list (1 items)
      • ResourceDefinition
        • content:
          'gaze'
        • filename:
          'pymovements-toy-dataset.zip'
        • filename_pattern:
          'trial_{text_id:d}_{page_id:d}.csv'
        • dict (2 items)
          • text_id:
            <class 'int'>
          • page_id:
            <class 'int'>
        • load_function:
          None
        • dict (4 items)
          • time_column:
            'timestamp'
          • time_unit:
            'ms'
          • (2 more)
        • md5:
          '256901852c1c07581d375eef705855d6'
        • mirrors:
          None
        • WebSource
          WebSource(url='https://github.com/pymovements/pymovements-toy-dataset/archive/refs/heads/main.zip', filename='pymovements-toy-dataset.zip', md5='256901852c1c07581d375eef705855d6', mirrors=None)
        • 'https://github.com/pymovements/pymovements-toy-dat...'
          'https://github.com/pymovements/pymovements-toy-dataset/archive/refs/heads/main.zip'
  • tuple (20 items)
    • Events
      • DataFrame (7 columns, 222 rows)
        shape: (222, 7)
        nameonsetoffsetdurationpeak_velocityamplitudedispersion
        stri64i64i64f64f64f64
        "fixation"19881451988563418200.1445582.4928642.712569
        "fixation"19885641988750186249.678232.6511982.865026
        "fixation"19887511989178427211.5987482.5859062.779518
        "fixation"19891791989436257189.1832432.6143472.77424
        "fixation"19894371989600163255.0775092.5946512.729391
        …………………
        "saccade"200437320043851270.3741830.70730.766684
        "saccade"2004688200470416175.6463791.8074851.875716
        "saccade"2004879200490122209.463612.9338183.086169
        "saccade"2005110200512616137.9175941.4053541.501217
        "saccade"2005288200534557352.55066714.68254116.101153
      • trial_columns:
        None
    • Events
      • DataFrame (7 columns, 366 rows)
        shape: (366, 7)
        nameonsetoffsetdurationpeak_velocityamplitudedispersion
        stri64i64i64f64f64f64
        "fixation"20083052008621316167.3438772.2830242.706135
        "fixation"20086222008821199314.3969042.5788542.79657
        "fixation"20088222009214392305.5259172.6128952.908934
        "fixation"20092152009433218216.1952012.6122082.765062
        "fixation"20094342009704270208.051322.5663052.70311
        …………………
        "saccade"203684920368611254.7431370.4721410.529715
        "saccade"2037161203718827223.0561032.3586042.587752
        "saccade"2037412203750391406.70144416.9486318.346458
        "saccade"2037638203765416138.3827671.4116211.827761
        "saccade"2037812203783018240.1932362.7393123.024326
      • trial_columns:
        None
    • (18 more)
  • dict (1 items)
    • DataFrame (3 columns, 20 rows)
      shape: (20, 3)
      text_idpage_idfilepath
      i64i64str
      01"pymovements-toy-dataset-main/d…
      02"pymovements-toy-dataset-main/d…
      03"pymovements-toy-dataset-main/d…
      04"pymovements-toy-dataset-main/d…
      05"pymovements-toy-dataset-main/d…
      ………
      31"pymovements-toy-dataset-main/d…
      32"pymovements-toy-dataset-main/d…
      33"pymovements-toy-dataset-main/d…
      34"pymovements-toy-dataset-main/d…
      35"pymovements-toy-dataset-main/d…
  • list (20 items)
    • Gaze
      • DataFrame (6 columns, 17223 rows)
        shape: (17_223, 6)
        timestimuli_xstimuli_ypixelpositionvelocity
        i64f64f64list[f64]list[f64]list[f64]
        1988145-1.0-1.0[206.8, 152.4][-10.697598, -8.852399][null, null]
        1988146-1.0-1.0[206.9, 152.1][-10.695183, -8.859678][null, null]
        1988147-1.0-1.0[207.0, 151.8][-10.692768, -8.866956][1.610194, -5.256267]
        1988148-1.0-1.0[207.1, 151.7][-10.690352, -8.869381][0.402548, -4.447465]
        1988149-1.0-1.0[207.0, 151.5][-10.692768, -8.874233][0.402561, -3.234462]
        ………………
        2005363-1.0-1.0[361.0, 415.4][-6.932438, -2.386672][-63.266374, -21.085616]
        2005364-1.0-1.0[358.0, 414.5][-7.006376, -2.408998][-63.249652, -19.431326]
        2005365-1.0-1.0[355.8, 413.8][-7.060582, -2.426362][-60.359624, -15.710061]
        2005366-1.0-1.0[353.1, 413.2][-7.12709, -2.441245][null, null]
        2005367-1.0-1.0[351.2, 412.9][-7.173881, -2.448686][null, null]
      • Events
        Events
        • DataFrame (7 columns, 222 rows)
          shape: (222, 7)
          nameonsetoffsetdurationpeak_velocityamplitudedispersion
          stri64i64i64f64f64f64
          "fixation"19881451988563418200.1445582.4928642.712569
          "fixation"19885641988750186249.678232.6511982.865026
          "fixation"19887511989178427211.5987482.5859062.779518
          "fixation"19891791989436257189.1832432.6143472.77424
          "fixation"19894371989600163255.0775092.5946512.729391
          …………………
          "saccade"200437320043851270.3741830.70730.766684
          "saccade"2004688200470416175.6463791.8074851.875716
          "saccade"2004879200490122209.463612.9338183.086169
          "saccade"2005110200512616137.9175941.4053541.501217
          "saccade"2005288200534557352.55066714.68254116.101153
        • trial_columns:
          None
      • trial_columns:
        None
      • Experiment
        Experiment
        • EyeTracker
          EyeTracker
          • left:
            None
          • model:
            None
          • mount:
            None
          • right:
            None
          • sampling_rate:
            1000
          • vendor:
            None
          • version:
            None
        • Screen
          Screen
          • distance_cm:
            68
          • height_cm:
            30.2
          • height_px:
            1024
          • origin:
            'upper left'
          • width_cm:
            38
          • width_px:
            1280
          • x_max_dva:
            15.599386487782953
          • x_min_dva:
            -15.599386487782953
          • y_max_dva:
            12.508044410882546
          • y_min_dva:
            -12.508044410882546
    • Gaze
      • DataFrame (6 columns, 29799 rows)
        shape: (29_799, 6)
        timestimuli_xstimuli_ypixelpositionvelocity
        i64f64f64list[f64]list[f64]list[f64]
        2008305-1.0-1.0[141.4, 153.6][-12.268583, -8.823284][null, null]
        2008306-1.0-1.0[141.1, 153.2][-12.275749, -8.832989][null, null]
        2008307-1.0-1.0[140.7, 152.8][-12.285302, -8.842695][-5.572617, -6.065816]
        2008308-1.0-1.0[140.6, 152.7][-12.28769, -8.845121][-3.582268, -4.043733]
        2008309-1.0-1.0[140.5, 152.6][-12.290078, -8.847547][-2.388085, -2.021821]
        ………………
        2038099-1.0-1.0[273.8, 773.8][-9.071149, 6.490168][1.21962, 1.635403]
        2038100-1.0-1.0[273.8, 774.1][-9.071149, 6.497527][1.626175, 4.497406]
        2038101-1.0-1.0[273.9, 774.5][-9.06871, 6.50734][1.626186, 1.635423]
        2038102-1.0-1.0[274.0, 774.4][-9.066271, 6.504886][null, null]
        2038103-1.0-1.0[274.0, 773.9][-9.066271, 6.492621][null, null]
      • Events
        Events
        • DataFrame (7 columns, 366 rows)
          shape: (366, 7)
          nameonsetoffsetdurationpeak_velocityamplitudedispersion
          stri64i64i64f64f64f64
          "fixation"20083052008621316167.3438772.2830242.706135
          "fixation"20086222008821199314.3969042.5788542.79657
          "fixation"20088222009214392305.5259172.6128952.908934
          "fixation"20092152009433218216.1952012.6122082.765062
          "fixation"20094342009704270208.051322.5663052.70311
          …………………
          "saccade"203684920368611254.7431370.4721410.529715
          "saccade"2037161203718827223.0561032.3586042.587752
          "saccade"2037412203750391406.70144416.9486318.346458
          "saccade"2037638203765416138.3827671.4116211.827761
          "saccade"2037812203783018240.1932362.7393123.024326
        • trial_columns:
          None
      • trial_columns:
        None
      • Experiment
        Experiment
        • EyeTracker
          EyeTracker
          • left:
            None
          • model:
            None
          • mount:
            None
          • right:
            None
          • sampling_rate:
            1000
          • vendor:
            None
          • version:
            None
        • Screen
          Screen
          • distance_cm:
            68
          • height_cm:
            30.2
          • height_px:
            1024
          • origin:
            'upper left'
          • width_cm:
            38
          • width_px:
            1280
          • x_max_dva:
            15.599386487782953
          • x_min_dva:
            -15.599386487782953
          • y_max_dva:
            12.508044410882546
          • y_min_dva:
            -12.508044410882546
    • (18 more)
  • path:
    PosixPath('data/ToyDataset')
  • DatasetPaths
    DatasetPaths
    • dataset:
      PosixPath('data/ToyDataset')
    • downloads:
      PosixPath('data/ToyDataset/downloads')
    • events:
      PosixPath('data/ToyDataset/events')
    • precomputed_events:
      PosixPath('data/ToyDataset/precomputed_events')
    • precomputed_reading_measures:
      PosixPath('data/ToyDataset/precomputed_reading_measures')
    • preprocessed:
      PosixPath('data/ToyDataset/preprocessed')
    • raw:
      PosixPath('data/ToyDataset/raw')
    • root:
      PosixPath('data/ToyDataset')
    • stimuli:
      PosixPath('data/ToyDataset/stimuli')
  • precomputed_events:
    list (0 items)
  • precomputed_reading_measures:
    list (0 items)
  • stimuli:
    list (0 items)

All the event data is saved into this directory:

dataset.paths.events

PosixPath('data/ToyDataset/events')

Let’s confirm it by printing all files in this directory:

print(list(dataset.paths.events.glob('*/*/*')))

[PosixPath('data/ToyDataset/events/pymovements-toy-dataset-main/data/trial_3_5.feather'), PosixPath('data/ToyDataset/events/pymovements-toy-dataset-main/data/trial_3_4.feather'), PosixPath('data/ToyDataset/events/pymovements-toy-dataset-main/data/trial_0_1.feather'), PosixPath('data/ToyDataset/events/pymovements-toy-dataset-main/data/trial_2_3.feather'), PosixPath('data/ToyDataset/events/pymovements-toy-dataset-main/data/trial_2_4.feather'), PosixPath('data/ToyDataset/events/pymovements-toy-dataset-main/data/trial_1_2.feather'), PosixPath('data/ToyDataset/events/pymovements-toy-dataset-main/data/trial_0_4.feather'), PosixPath('data/ToyDataset/events/pymovements-toy-dataset-main/data/trial_0_3.feather'), PosixPath('data/ToyDataset/events/pymovements-toy-dataset-main/data/trial_0_5.feather'), PosixPath('data/ToyDataset/events/pymovements-toy-dataset-main/data/trial_1_4.feather'), PosixPath('data/ToyDataset/events/pymovements-toy-dataset-main/data/trial_2_1.feather'), PosixPath('data/ToyDataset/events/pymovements-toy-dataset-main/data/trial_3_1.feather'), PosixPath('data/ToyDataset/events/pymovements-toy-dataset-main/data/trial_3_2.feather'), PosixPath('data/ToyDataset/events/pymovements-toy-dataset-main/data/trial_2_2.feather'), PosixPath('data/ToyDataset/events/pymovements-toy-dataset-main/data/trial_1_3.feather'), PosixPath('data/ToyDataset/events/pymovements-toy-dataset-main/data/trial_0_2.feather'), PosixPath('data/ToyDataset/events/pymovements-toy-dataset-main/data/trial_2_5.feather'), PosixPath('data/ToyDataset/events/pymovements-toy-dataset-main/data/trial_1_5.feather'), PosixPath('data/ToyDataset/events/pymovements-toy-dataset-main/data/trial_3_3.feather'), PosixPath('data/ToyDataset/events/pymovements-toy-dataset-main/data/trial_1_1.feather')]

All files have been saved into the Dataset.paths.events as files in Feather format.

If we want to save the data into an alternative directory and also use a different file format like csv we can use the following:

dataset.save_events(events_dirname='events_csv', extension='csv')
Dataset
  • DatasetDefinition
    DatasetDefinition
    • name:
      'ToyDataset'
    • long_name:
      'pymovements Toy Dataset'
    • 'Example toy dataset. This dataset includes monocu...'
      'Example toy dataset.\n\nThis dataset includes monocular eye tracking data from a single participant in a single\nsession. Eye movements are recorded at a sampling frequency of 1000 Hz using an EyeLink Portable\nDuo video-based eye tracker and are provided as pixel coordinates.\n\nThe participant is instructed to read 4 texts with 5 screens each.\n'
    • Experiment
      Experiment
      • EyeTracker
        EyeTracker
        • left:
          None
        • model:
          None
        • mount:
          None
        • right:
          None
        • sampling_rate:
          1000
        • vendor:
          None
        • version:
          None
      • Screen
        Screen
        • distance_cm:
          68
        • height_cm:
          30.2
        • height_px:
          1024
        • origin:
          'upper left'
        • width_cm:
          38
        • width_px:
          1280
        • x_max_dva:
          15.599386487782953
        • x_min_dva:
          -15.599386487782953
        • y_max_dva:
          12.508044410882546
        • y_min_dva:
          -12.508044410882546
    • list (1 items)
      • ResourceDefinition
        • content:
          'gaze'
        • filename:
          'pymovements-toy-dataset.zip'
        • filename_pattern:
          'trial_{text_id:d}_{page_id:d}.csv'
        • dict (2 items)
          • text_id:
            <class 'int'>
          • page_id:
            <class 'int'>
        • load_function:
          None
        • dict (4 items)
          • time_column:
            'timestamp'
          • time_unit:
            'ms'
          • (2 more)
        • md5:
          '256901852c1c07581d375eef705855d6'
        • mirrors:
          None
        • WebSource
          WebSource(url='https://github.com/pymovements/pymovements-toy-dataset/archive/refs/heads/main.zip', filename='pymovements-toy-dataset.zip', md5='256901852c1c07581d375eef705855d6', mirrors=None)
        • 'https://github.com/pymovements/pymovements-toy-dat...'
          'https://github.com/pymovements/pymovements-toy-dataset/archive/refs/heads/main.zip'
  • tuple (20 items)
    • Events
      • DataFrame (7 columns, 222 rows)
        shape: (222, 7)
        nameonsetoffsetdurationpeak_velocityamplitudedispersion
        stri64i64i64f64f64f64
        "fixation"19881451988563418200.1445582.4928642.712569
        "fixation"19885641988750186249.678232.6511982.865026
        "fixation"19887511989178427211.5987482.5859062.779518
        "fixation"19891791989436257189.1832432.6143472.77424
        "fixation"19894371989600163255.0775092.5946512.729391
        …………………
        "saccade"200437320043851270.3741830.70730.766684
        "saccade"2004688200470416175.6463791.8074851.875716
        "saccade"2004879200490122209.463612.9338183.086169
        "saccade"2005110200512616137.9175941.4053541.501217
        "saccade"2005288200534557352.55066714.68254116.101153
      • trial_columns:
        None
    • Events
      • DataFrame (7 columns, 366 rows)
        shape: (366, 7)
        nameonsetoffsetdurationpeak_velocityamplitudedispersion
        stri64i64i64f64f64f64
        "fixation"20083052008621316167.3438772.2830242.706135
        "fixation"20086222008821199314.3969042.5788542.79657
        "fixation"20088222009214392305.5259172.6128952.908934
        "fixation"20092152009433218216.1952012.6122082.765062
        "fixation"20094342009704270208.051322.5663052.70311
        …………………
        "saccade"203684920368611254.7431370.4721410.529715
        "saccade"2037161203718827223.0561032.3586042.587752
        "saccade"2037412203750391406.70144416.9486318.346458
        "saccade"2037638203765416138.3827671.4116211.827761
        "saccade"2037812203783018240.1932362.7393123.024326
      • trial_columns:
        None
    • (18 more)
  • dict (1 items)
    • DataFrame (3 columns, 20 rows)
      shape: (20, 3)
      text_idpage_idfilepath
      i64i64str
      01"pymovements-toy-dataset-main/d…
      02"pymovements-toy-dataset-main/d…
      03"pymovements-toy-dataset-main/d…
      04"pymovements-toy-dataset-main/d…
      05"pymovements-toy-dataset-main/d…
      ………
      31"pymovements-toy-dataset-main/d…
      32"pymovements-toy-dataset-main/d…
      33"pymovements-toy-dataset-main/d…
      34"pymovements-toy-dataset-main/d…
      35"pymovements-toy-dataset-main/d…
  • list (20 items)
    • Gaze
      • DataFrame (6 columns, 17223 rows)
        shape: (17_223, 6)
        timestimuli_xstimuli_ypixelpositionvelocity
        i64f64f64list[f64]list[f64]list[f64]
        1988145-1.0-1.0[206.8, 152.4][-10.697598, -8.852399][null, null]
        1988146-1.0-1.0[206.9, 152.1][-10.695183, -8.859678][null, null]
        1988147-1.0-1.0[207.0, 151.8][-10.692768, -8.866956][1.610194, -5.256267]
        1988148-1.0-1.0[207.1, 151.7][-10.690352, -8.869381][0.402548, -4.447465]
        1988149-1.0-1.0[207.0, 151.5][-10.692768, -8.874233][0.402561, -3.234462]
        ………………
        2005363-1.0-1.0[361.0, 415.4][-6.932438, -2.386672][-63.266374, -21.085616]
        2005364-1.0-1.0[358.0, 414.5][-7.006376, -2.408998][-63.249652, -19.431326]
        2005365-1.0-1.0[355.8, 413.8][-7.060582, -2.426362][-60.359624, -15.710061]
        2005366-1.0-1.0[353.1, 413.2][-7.12709, -2.441245][null, null]
        2005367-1.0-1.0[351.2, 412.9][-7.173881, -2.448686][null, null]
      • Events
        Events
        • DataFrame (7 columns, 222 rows)
          shape: (222, 7)
          nameonsetoffsetdurationpeak_velocityamplitudedispersion
          stri64i64i64f64f64f64
          "fixation"19881451988563418200.1445582.4928642.712569
          "fixation"19885641988750186249.678232.6511982.865026
          "fixation"19887511989178427211.5987482.5859062.779518
          "fixation"19891791989436257189.1832432.6143472.77424
          "fixation"19894371989600163255.0775092.5946512.729391
          …………………
          "saccade"200437320043851270.3741830.70730.766684
          "saccade"2004688200470416175.6463791.8074851.875716
          "saccade"2004879200490122209.463612.9338183.086169
          "saccade"2005110200512616137.9175941.4053541.501217
          "saccade"2005288200534557352.55066714.68254116.101153
        • trial_columns:
          None
      • trial_columns:
        None
      • Experiment
        Experiment
        • EyeTracker
          EyeTracker
          • left:
            None
          • model:
            None
          • mount:
            None
          • right:
            None
          • sampling_rate:
            1000
          • vendor:
            None
          • version:
            None
        • Screen
          Screen
          • distance_cm:
            68
          • height_cm:
            30.2
          • height_px:
            1024
          • origin:
            'upper left'
          • width_cm:
            38
          • width_px:
            1280
          • x_max_dva:
            15.599386487782953
          • x_min_dva:
            -15.599386487782953
          • y_max_dva:
            12.508044410882546
          • y_min_dva:
            -12.508044410882546
    • Gaze
      • DataFrame (6 columns, 29799 rows)
        shape: (29_799, 6)
        timestimuli_xstimuli_ypixelpositionvelocity
        i64f64f64list[f64]list[f64]list[f64]
        2008305-1.0-1.0[141.4, 153.6][-12.268583, -8.823284][null, null]
        2008306-1.0-1.0[141.1, 153.2][-12.275749, -8.832989][null, null]
        2008307-1.0-1.0[140.7, 152.8][-12.285302, -8.842695][-5.572617, -6.065816]
        2008308-1.0-1.0[140.6, 152.7][-12.28769, -8.845121][-3.582268, -4.043733]
        2008309-1.0-1.0[140.5, 152.6][-12.290078, -8.847547][-2.388085, -2.021821]
        ………………
        2038099-1.0-1.0[273.8, 773.8][-9.071149, 6.490168][1.21962, 1.635403]
        2038100-1.0-1.0[273.8, 774.1][-9.071149, 6.497527][1.626175, 4.497406]
        2038101-1.0-1.0[273.9, 774.5][-9.06871, 6.50734][1.626186, 1.635423]
        2038102-1.0-1.0[274.0, 774.4][-9.066271, 6.504886][null, null]
        2038103-1.0-1.0[274.0, 773.9][-9.066271, 6.492621][null, null]
      • Events
        Events
        • DataFrame (7 columns, 366 rows)
          shape: (366, 7)
          nameonsetoffsetdurationpeak_velocityamplitudedispersion
          stri64i64i64f64f64f64
          "fixation"20083052008621316167.3438772.2830242.706135
          "fixation"20086222008821199314.3969042.5788542.79657
          "fixation"20088222009214392305.5259172.6128952.908934
          "fixation"20092152009433218216.1952012.6122082.765062
          "fixation"20094342009704270208.051322.5663052.70311
          …………………
          "saccade"203684920368611254.7431370.4721410.529715
          "saccade"2037161203718827223.0561032.3586042.587752
          "saccade"2037412203750391406.70144416.9486318.346458
          "saccade"2037638203765416138.3827671.4116211.827761
          "saccade"2037812203783018240.1932362.7393123.024326
        • trial_columns:
          None
      • trial_columns:
        None
      • Experiment
        Experiment
        • EyeTracker
          EyeTracker
          • left:
            None
          • model:
            None
          • mount:
            None
          • right:
            None
          • sampling_rate:
            1000
          • vendor:
            None
          • version:
            None
        • Screen
          Screen
          • distance_cm:
            68
          • height_cm:
            30.2
          • height_px:
            1024
          • origin:
            'upper left'
          • width_cm:
            38
          • width_px:
            1280
          • x_max_dva:
            15.599386487782953
          • x_min_dva:
            -15.599386487782953
          • y_max_dva:
            12.508044410882546
          • y_min_dva:
            -12.508044410882546
    • (18 more)
  • path:
    PosixPath('data/ToyDataset')
  • DatasetPaths
    DatasetPaths
    • dataset:
      PosixPath('data/ToyDataset')
    • downloads:
      PosixPath('data/ToyDataset/downloads')
    • events:
      PosixPath('data/ToyDataset/events')
    • precomputed_events:
      PosixPath('data/ToyDataset/precomputed_events')
    • precomputed_reading_measures:
      PosixPath('data/ToyDataset/precomputed_reading_measures')
    • preprocessed:
      PosixPath('data/ToyDataset/preprocessed')
    • raw:
      PosixPath('data/ToyDataset/raw')
    • root:
      PosixPath('data/ToyDataset')
    • stimuli:
      PosixPath('data/ToyDataset/stimuli')
  • precomputed_events:
    list (0 items)
  • precomputed_reading_measures:
    list (0 items)
  • stimuli:
    list (0 items)

Let’s confirm again by printing all the new files in this alternative directory:

alternative_dirpath = dataset.path / 'events_csv'
print(list(alternative_dirpath.glob('*/*/*')))

[PosixPath('data/ToyDataset/events_csv/pymovements-toy-dataset-main/data/trial_3_1.csv'), PosixPath('data/ToyDataset/events_csv/pymovements-toy-dataset-main/data/trial_2_3.csv'), PosixPath('data/ToyDataset/events_csv/pymovements-toy-dataset-main/data/trial_1_3.csv'), PosixPath('data/ToyDataset/events_csv/pymovements-toy-dataset-main/data/trial_0_4.csv'), PosixPath('data/ToyDataset/events_csv/pymovements-toy-dataset-main/data/trial_2_5.csv'), PosixPath('data/ToyDataset/events_csv/pymovements-toy-dataset-main/data/trial_3_4.csv'), PosixPath('data/ToyDataset/events_csv/pymovements-toy-dataset-main/data/trial_0_5.csv'), PosixPath('data/ToyDataset/events_csv/pymovements-toy-dataset-main/data/trial_1_4.csv'), PosixPath('data/ToyDataset/events_csv/pymovements-toy-dataset-main/data/trial_0_3.csv'), PosixPath('data/ToyDataset/events_csv/pymovements-toy-dataset-main/data/trial_3_3.csv'), PosixPath('data/ToyDataset/events_csv/pymovements-toy-dataset-main/data/trial_3_5.csv'), PosixPath('data/ToyDataset/events_csv/pymovements-toy-dataset-main/data/trial_2_1.csv'), PosixPath('data/ToyDataset/events_csv/pymovements-toy-dataset-main/data/trial_1_1.csv'), PosixPath('data/ToyDataset/events_csv/pymovements-toy-dataset-main/data/trial_2_4.csv'), PosixPath('data/ToyDataset/events_csv/pymovements-toy-dataset-main/data/trial_0_2.csv'), PosixPath('data/ToyDataset/events_csv/pymovements-toy-dataset-main/data/trial_3_2.csv'), PosixPath('data/ToyDataset/events_csv/pymovements-toy-dataset-main/data/trial_1_5.csv'), PosixPath('data/ToyDataset/events_csv/pymovements-toy-dataset-main/data/trial_0_1.csv'), PosixPath('data/ToyDataset/events_csv/pymovements-toy-dataset-main/data/trial_1_2.csv'), PosixPath('data/ToyDataset/events_csv/pymovements-toy-dataset-main/data/trial_2_2.csv')]

Loading Previously Computed Events Data#

Let’s initialize a new dataset object from the same ToyDataset.

preprocessed_dataset = pm.Dataset('ToyDataset', path='data/ToyDataset')

When we load the dataset using load() without any parameters there will be no events loaded:

preprocessed_dataset.load()
Dataset
  • DatasetDefinition
    DatasetDefinition
    • name:
      'ToyDataset'
    • long_name:
      'pymovements Toy Dataset'
    • 'Example toy dataset. This dataset includes monocu...'
      'Example toy dataset.\n\nThis dataset includes monocular eye tracking data from a single participant in a single\nsession. Eye movements are recorded at a sampling frequency of 1000 Hz using an EyeLink Portable\nDuo video-based eye tracker and are provided as pixel coordinates.\n\nThe participant is instructed to read 4 texts with 5 screens each.\n'
    • Experiment
      Experiment
      • EyeTracker
        EyeTracker
        • left:
          None
        • model:
          None
        • mount:
          None
        • right:
          None
        • sampling_rate:
          1000
        • vendor:
          None
        • version:
          None
      • Screen
        Screen
        • distance_cm:
          68
        • height_cm:
          30.2
        • height_px:
          1024
        • origin:
          'upper left'
        • width_cm:
          38
        • width_px:
          1280
        • x_max_dva:
          15.599386487782953
        • x_min_dva:
          -15.599386487782953
        • y_max_dva:
          12.508044410882546
        • y_min_dva:
          -12.508044410882546
    • list (1 items)
      • ResourceDefinition
        • content:
          'gaze'
        • filename:
          'pymovements-toy-dataset.zip'
        • filename_pattern:
          'trial_{text_id:d}_{page_id:d}.csv'
        • dict (2 items)
          • text_id:
            <class 'int'>
          • page_id:
            <class 'int'>
        • load_function:
          None
        • dict (4 items)
          • time_column:
            'timestamp'
          • time_unit:
            'ms'
          • (2 more)
        • md5:
          '256901852c1c07581d375eef705855d6'
        • mirrors:
          None
        • WebSource
          WebSource(url='https://github.com/pymovements/pymovements-toy-dataset/archive/refs/heads/main.zip', filename='pymovements-toy-dataset.zip', md5='256901852c1c07581d375eef705855d6', mirrors=None)
        • 'https://github.com/pymovements/pymovements-toy-dat...'
          'https://github.com/pymovements/pymovements-toy-dataset/archive/refs/heads/main.zip'
  • tuple (20 items)
    • Events
      • DataFrame (4 columns, 0 rows)
        shape: (0, 4)
        nameonsetoffsetduration
        stri64i64i64
      • trial_columns:
        None
    • Events
      • DataFrame (4 columns, 0 rows)
        shape: (0, 4)
        nameonsetoffsetduration
        stri64i64i64
      • trial_columns:
        None
    • (18 more)
  • dict (1 items)
    • DataFrame (3 columns, 20 rows)
      shape: (20, 3)
      text_idpage_idfilepath
      i64i64str
      01"pymovements-toy-dataset-main/d…
      02"pymovements-toy-dataset-main/d…
      03"pymovements-toy-dataset-main/d…
      04"pymovements-toy-dataset-main/d…
      05"pymovements-toy-dataset-main/d…
      ………
      31"pymovements-toy-dataset-main/d…
      32"pymovements-toy-dataset-main/d…
      33"pymovements-toy-dataset-main/d…
      34"pymovements-toy-dataset-main/d…
      35"pymovements-toy-dataset-main/d…
  • list (20 items)
    • Gaze
      • DataFrame (4 columns, 17223 rows)
        shape: (17_223, 4)
        timestimuli_xstimuli_ypixel
        i64f64f64list[f64]
        1988145-1.0-1.0[206.8, 152.4]
        1988146-1.0-1.0[206.9, 152.1]
        1988147-1.0-1.0[207.0, 151.8]
        1988148-1.0-1.0[207.1, 151.7]
        1988149-1.0-1.0[207.0, 151.5]
        …………
        2005363-1.0-1.0[361.0, 415.4]
        2005364-1.0-1.0[358.0, 414.5]
        2005365-1.0-1.0[355.8, 413.8]
        2005366-1.0-1.0[353.1, 413.2]
        2005367-1.0-1.0[351.2, 412.9]
      • Events
        Events
        • DataFrame (4 columns, 0 rows)
          shape: (0, 4)
          nameonsetoffsetduration
          stri64i64i64
        • trial_columns:
          None
      • trial_columns:
        None
      • Experiment
        Experiment
        • EyeTracker
          EyeTracker
          • left:
            None
          • model:
            None
          • mount:
            None
          • right:
            None
          • sampling_rate:
            1000
          • vendor:
            None
          • version:
            None
        • Screen
          Screen
          • distance_cm:
            68
          • height_cm:
            30.2
          • height_px:
            1024
          • origin:
            'upper left'
          • width_cm:
            38
          • width_px:
            1280
          • x_max_dva:
            15.599386487782953
          • x_min_dva:
            -15.599386487782953
          • y_max_dva:
            12.508044410882546
          • y_min_dva:
            -12.508044410882546
    • Gaze
      • DataFrame (4 columns, 29799 rows)
        shape: (29_799, 4)
        timestimuli_xstimuli_ypixel
        i64f64f64list[f64]
        2008305-1.0-1.0[141.4, 153.6]
        2008306-1.0-1.0[141.1, 153.2]
        2008307-1.0-1.0[140.7, 152.8]
        2008308-1.0-1.0[140.6, 152.7]
        2008309-1.0-1.0[140.5, 152.6]
        …………
        2038099-1.0-1.0[273.8, 773.8]
        2038100-1.0-1.0[273.8, 774.1]
        2038101-1.0-1.0[273.9, 774.5]
        2038102-1.0-1.0[274.0, 774.4]
        2038103-1.0-1.0[274.0, 773.9]
      • Events
        Events
        • DataFrame (4 columns, 0 rows)
          shape: (0, 4)
          nameonsetoffsetduration
          stri64i64i64
        • trial_columns:
          None
      • trial_columns:
        None
      • Experiment
        Experiment
        • EyeTracker
          EyeTracker
          • left:
            None
          • model:
            None
          • mount:
            None
          • right:
            None
          • sampling_rate:
            1000
          • vendor:
            None
          • version:
            None
        • Screen
          Screen
          • distance_cm:
            68
          • height_cm:
            30.2
          • height_px:
            1024
          • origin:
            'upper left'
          • width_cm:
            38
          • width_px:
            1280
          • x_max_dva:
            15.599386487782953
          • x_min_dva:
            -15.599386487782953
          • y_max_dva:
            12.508044410882546
          • y_min_dva:
            -12.508044410882546
    • (18 more)
  • path:
    PosixPath('data/ToyDataset')
  • DatasetPaths
    DatasetPaths
    • dataset:
      PosixPath('data/ToyDataset')
    • downloads:
      PosixPath('data/ToyDataset/downloads')
    • events:
      PosixPath('data/ToyDataset/events')
    • precomputed_events:
      PosixPath('data/ToyDataset/precomputed_events')
    • precomputed_reading_measures:
      PosixPath('data/ToyDataset/precomputed_reading_measures')
    • preprocessed:
      PosixPath('data/ToyDataset/preprocessed')
    • raw:
      PosixPath('data/ToyDataset/raw')
    • root:
      PosixPath('data/ToyDataset')
    • stimuli:
      PosixPath('data/ToyDataset/stimuli')
  • precomputed_events:
    list (0 items)
  • precomputed_reading_measures:
    list (0 items)
  • stimuli:
    list (0 items)

But when we load it with the events=True parameter the events will be loaded:

preprocessed_dataset.load(events=True)
Dataset
  • DatasetDefinition
    DatasetDefinition
    • name:
      'ToyDataset'
    • long_name:
      'pymovements Toy Dataset'
    • 'Example toy dataset. This dataset includes monocu...'
      'Example toy dataset.\n\nThis dataset includes monocular eye tracking data from a single participant in a single\nsession. Eye movements are recorded at a sampling frequency of 1000 Hz using an EyeLink Portable\nDuo video-based eye tracker and are provided as pixel coordinates.\n\nThe participant is instructed to read 4 texts with 5 screens each.\n'
    • Experiment
      Experiment
      • EyeTracker
        EyeTracker
        • left:
          None
        • model:
          None
        • mount:
          None
        • right:
          None
        • sampling_rate:
          1000
        • vendor:
          None
        • version:
          None
      • Screen
        Screen
        • distance_cm:
          68
        • height_cm:
          30.2
        • height_px:
          1024
        • origin:
          'upper left'
        • width_cm:
          38
        • width_px:
          1280
        • x_max_dva:
          15.599386487782953
        • x_min_dva:
          -15.599386487782953
        • y_max_dva:
          12.508044410882546
        • y_min_dva:
          -12.508044410882546
    • list (1 items)
      • ResourceDefinition
        • content:
          'gaze'
        • filename:
          'pymovements-toy-dataset.zip'
        • filename_pattern:
          'trial_{text_id:d}_{page_id:d}.csv'
        • dict (2 items)
          • text_id:
            <class 'int'>
          • page_id:
            <class 'int'>
        • load_function:
          None
        • dict (4 items)
          • time_column:
            'timestamp'
          • time_unit:
            'ms'
          • (2 more)
        • md5:
          '256901852c1c07581d375eef705855d6'
        • mirrors:
          None
        • WebSource
          WebSource(url='https://github.com/pymovements/pymovements-toy-dataset/archive/refs/heads/main.zip', filename='pymovements-toy-dataset.zip', md5='256901852c1c07581d375eef705855d6', mirrors=None)
        • 'https://github.com/pymovements/pymovements-toy-dat...'
          'https://github.com/pymovements/pymovements-toy-dataset/archive/refs/heads/main.zip'
  • tuple (20 items)
    • Events
      • DataFrame (7 columns, 222 rows)
        shape: (222, 7)
        nameonsetoffsetdurationpeak_velocityamplitudedispersion
        stri64i64i64f64f64f64
        "fixation"19881451988563418200.1445582.4928642.712569
        "fixation"19885641988750186249.678232.6511982.865026
        "fixation"19887511989178427211.5987482.5859062.779518
        "fixation"19891791989436257189.1832432.6143472.77424
        "fixation"19894371989600163255.0775092.5946512.729391
        …………………
        "saccade"200437320043851270.3741830.70730.766684
        "saccade"2004688200470416175.6463791.8074851.875716
        "saccade"2004879200490122209.463612.9338183.086169
        "saccade"2005110200512616137.9175941.4053541.501217
        "saccade"2005288200534557352.55066714.68254116.101153
      • trial_columns:
        None
    • Events
      • DataFrame (7 columns, 366 rows)
        shape: (366, 7)
        nameonsetoffsetdurationpeak_velocityamplitudedispersion
        stri64i64i64f64f64f64
        "fixation"20083052008621316167.3438772.2830242.706135
        "fixation"20086222008821199314.3969042.5788542.79657
        "fixation"20088222009214392305.5259172.6128952.908934
        "fixation"20092152009433218216.1952012.6122082.765062
        "fixation"20094342009704270208.051322.5663052.70311
        …………………
        "saccade"203684920368611254.7431370.4721410.529715
        "saccade"2037161203718827223.0561032.3586042.587752
        "saccade"2037412203750391406.70144416.9486318.346458
        "saccade"2037638203765416138.3827671.4116211.827761
        "saccade"2037812203783018240.1932362.7393123.024326
      • trial_columns:
        None
    • (18 more)
  • dict (1 items)
    • DataFrame (3 columns, 20 rows)
      shape: (20, 3)
      text_idpage_idfilepath
      i64i64str
      01"pymovements-toy-dataset-main/d…
      02"pymovements-toy-dataset-main/d…
      03"pymovements-toy-dataset-main/d…
      04"pymovements-toy-dataset-main/d…
      05"pymovements-toy-dataset-main/d…
      ………
      31"pymovements-toy-dataset-main/d…
      32"pymovements-toy-dataset-main/d…
      33"pymovements-toy-dataset-main/d…
      34"pymovements-toy-dataset-main/d…
      35"pymovements-toy-dataset-main/d…
  • list (20 items)
    • Gaze
      • DataFrame (4 columns, 17223 rows)
        shape: (17_223, 4)
        timestimuli_xstimuli_ypixel
        i64f64f64list[f64]
        1988145-1.0-1.0[206.8, 152.4]
        1988146-1.0-1.0[206.9, 152.1]
        1988147-1.0-1.0[207.0, 151.8]
        1988148-1.0-1.0[207.1, 151.7]
        1988149-1.0-1.0[207.0, 151.5]
        …………
        2005363-1.0-1.0[361.0, 415.4]
        2005364-1.0-1.0[358.0, 414.5]
        2005365-1.0-1.0[355.8, 413.8]
        2005366-1.0-1.0[353.1, 413.2]
        2005367-1.0-1.0[351.2, 412.9]
      • Events
        Events
        • DataFrame (7 columns, 222 rows)
          shape: (222, 7)
          nameonsetoffsetdurationpeak_velocityamplitudedispersion
          stri64i64i64f64f64f64
          "fixation"19881451988563418200.1445582.4928642.712569
          "fixation"19885641988750186249.678232.6511982.865026
          "fixation"19887511989178427211.5987482.5859062.779518
          "fixation"19891791989436257189.1832432.6143472.77424
          "fixation"19894371989600163255.0775092.5946512.729391
          …………………
          "saccade"200437320043851270.3741830.70730.766684
          "saccade"2004688200470416175.6463791.8074851.875716
          "saccade"2004879200490122209.463612.9338183.086169
          "saccade"2005110200512616137.9175941.4053541.501217
          "saccade"2005288200534557352.55066714.68254116.101153
        • trial_columns:
          None
      • trial_columns:
        None
      • Experiment
        Experiment
        • EyeTracker
          EyeTracker
          • left:
            None
          • model:
            None
          • mount:
            None
          • right:
            None
          • sampling_rate:
            1000
          • vendor:
            None
          • version:
            None
        • Screen
          Screen
          • distance_cm:
            68
          • height_cm:
            30.2
          • height_px:
            1024
          • origin:
            'upper left'
          • width_cm:
            38
          • width_px:
            1280
          • x_max_dva:
            15.599386487782953
          • x_min_dva:
            -15.599386487782953
          • y_max_dva:
            12.508044410882546
          • y_min_dva:
            -12.508044410882546
    • Gaze
      • DataFrame (4 columns, 29799 rows)
        shape: (29_799, 4)
        timestimuli_xstimuli_ypixel
        i64f64f64list[f64]
        2008305-1.0-1.0[141.4, 153.6]
        2008306-1.0-1.0[141.1, 153.2]
        2008307-1.0-1.0[140.7, 152.8]
        2008308-1.0-1.0[140.6, 152.7]
        2008309-1.0-1.0[140.5, 152.6]
        …………
        2038099-1.0-1.0[273.8, 773.8]
        2038100-1.0-1.0[273.8, 774.1]
        2038101-1.0-1.0[273.9, 774.5]
        2038102-1.0-1.0[274.0, 774.4]
        2038103-1.0-1.0[274.0, 773.9]
      • Events
        Events
        • DataFrame (7 columns, 366 rows)
          shape: (366, 7)
          nameonsetoffsetdurationpeak_velocityamplitudedispersion
          stri64i64i64f64f64f64
          "fixation"20083052008621316167.3438772.2830242.706135
          "fixation"20086222008821199314.3969042.5788542.79657
          "fixation"20088222009214392305.5259172.6128952.908934
          "fixation"20092152009433218216.1952012.6122082.765062
          "fixation"20094342009704270208.051322.5663052.70311
          …………………
          "saccade"203684920368611254.7431370.4721410.529715
          "saccade"2037161203718827223.0561032.3586042.587752
          "saccade"2037412203750391406.70144416.9486318.346458
          "saccade"2037638203765416138.3827671.4116211.827761
          "saccade"2037812203783018240.1932362.7393123.024326
        • trial_columns:
          None
      • trial_columns:
        None
      • Experiment
        Experiment
        • EyeTracker
          EyeTracker
          • left:
            None
          • model:
            None
          • mount:
            None
          • right:
            None
          • sampling_rate:
            1000
          • vendor:
            None
          • version:
            None
        • Screen
          Screen
          • distance_cm:
            68
          • height_cm:
            30.2
          • height_px:
            1024
          • origin:
            'upper left'
          • width_cm:
            38
          • width_px:
            1280
          • x_max_dva:
            15.599386487782953
          • x_min_dva:
            -15.599386487782953
          • y_max_dva:
            12.508044410882546
          • y_min_dva:
            -12.508044410882546
    • (18 more)
  • path:
    PosixPath('data/ToyDataset')
  • DatasetPaths
    DatasetPaths
    • dataset:
      PosixPath('data/ToyDataset')
    • downloads:
      PosixPath('data/ToyDataset/downloads')
    • events:
      PosixPath('data/ToyDataset/events')
    • precomputed_events:
      PosixPath('data/ToyDataset/precomputed_events')
    • precomputed_reading_measures:
      PosixPath('data/ToyDataset/precomputed_reading_measures')
    • preprocessed:
      PosixPath('data/ToyDataset/preprocessed')
    • raw:
      PosixPath('data/ToyDataset/raw')
    • root:
      PosixPath('data/ToyDataset')
    • stimuli:
      PosixPath('data/ToyDataset/stimuli')
  • precomputed_events:
    list (0 items)
  • precomputed_reading_measures:
    list (0 items)
  • stimuli:
    list (0 items)

By default, the events directory and the feather extension will be chosen.

In the case of alternative directory names or other file formats, you can use the following:

preprocessed_dataset.load(
    events=True,
    events_dirname='events_csv',
    extension='csv',
)
dataset.events[0]
Events
  • DataFrame (7 columns, 222 rows)
    shape: (222, 7)
    nameonsetoffsetdurationpeak_velocityamplitudedispersion
    stri64i64i64f64f64f64
    "fixation"19881451988563418200.1445582.4928642.712569
    "fixation"19885641988750186249.678232.6511982.865026
    "fixation"19887511989178427211.5987482.5859062.779518
    "fixation"19891791989436257189.1832432.6143472.77424
    "fixation"19894371989600163255.0775092.5946512.729391
    …………………
    "saccade"200437320043851270.3741830.70730.766684
    "saccade"2004688200470416175.6463791.8074851.875716
    "saccade"2004879200490122209.463612.9338183.086169
    "saccade"2005110200512616137.9175941.4053541.501217
    "saccade"2005288200534557352.55066714.68254116.101153
  • trial_columns:
    None

What you have learned in this tutorial:#