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 http://github.com/aeye-lab/pymovements-toy-dataset/zipball/6cb5d663317bf418cec0c9abe1dde5085a8a8ebd/ to data/ToyDataset/downloads/pymovements-toy-dataset.zip

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

100%|██████████| 23/23 [00:00<00:00, 341.33it/s]

Dataset

• definition:
  DatasetDefinition
  DatasetDefinition

  • acceleration_columns:
    None
    None
  • column_map:
    dict (0 items)
  • custom_read_kwargs:
    dict (1 items)
    • gaze:
      dict (4 items)
      • columns:
        list (5 items)
        • 'timestamp'
        • 'x'
        • (3 more)
      • schema_overrides:
        dict (5 items)
        • timestamp:
          Float64
          Float64
        • x:
          Float64
          Float64
        • (3 more)
      • (2 more)
  • distance_column:
    None
    None
  • experiment:
    Experiment
    Experiment

    • eyetracker:
      EyeTracker
      EyeTracker

      • left:
        None
        None
      • model:
        None
        None
      • mount:
        None
        None
      • right:
        None
        None
      • sampling_rate:
        1000
        1000
      • vendor:
        None
        None
      • version:
        None
        None
    • sampling_rate:
      1000
      1000
    • screen:
      Screen
      Screen

      • distance_cm:
        68
        68
      • height_cm:
        30.2
        30.2
      • height_px:
        1024
        1024
      • origin:
        'upper left'
        'upper left'
      • width_cm:
        38
        38
      • width_px:
        1280
        1280
      • x_max_dva:
        15.599386487782953
        15.599386487782953
      • x_min_dva:
        -15.599386487782953
        -15.599386487782953
      • y_max_dva:
        12.508044410882546
        12.508044410882546
      • y_min_dva:
        -12.508044410882546
        -12.508044410882546
  • extract:
    None
    None
  • filename_format:
    dict (1 items)
    • gaze:
      'trial_{text_id:d}_{page_id:d}.csv'
      'trial_{text_id:d}_{page_id:d}.csv'
  • filename_format_schema_overrides:
    dict (1 items)
    • gaze:
      dict (2 items)
      • text_id:
        <class 'int'>
        <class 'int'>
      • page_id:
        <class 'int'>
        <class 'int'>
  • has_resources:
    True
    True
  • long_name:
    'pymovements Toy Dataset'
    'pymovements Toy Dataset'
  • mirrors:
    dict (0 items)
  • name:
    'ToyDataset'
    'ToyDataset'
  • pixel_columns:
    list (2 items)
    • 'x'
    • 'y'
  • position_columns:
    None
    None
  • resources:
    list (1 items)
    • ResourceDefinition
      • content:
        'gaze'
        'gaze'
      • filename:
        'pymovements-toy-dataset.zip'
        'pymovements-toy-dataset.zip'
      • filename_pattern:
        'trial_{text_id:d}_{page_id:d}.csv'
        'trial_{text_id:d}_{page_id:d}.csv'
      • filename_pattern_schema_overrides:
        dict (2 items)
        • text_id:
          <class 'int'>
          <class 'int'>
        • page_id:
          <class 'int'>
          <class 'int'>
      • md5:
        '4da622457637a8181d86601fe17f3aa8'
        '4da622457637a8181d86601fe17f3aa8'
      • url:
        str
        'http://github.com/aeye-lab/pymovements-toy-dataset/zipball/6cb5d663317bf418cec0c9abe1dde5085a8a8ebd/'
  • time_column:
    'timestamp'
    'timestamp'
  • time_unit:
    'ms'
    'ms'
  • trial_columns:
    None
    None
  • velocity_columns:
    None
    None
• events:
  list (0 items)
• fileinfo:
  dict (1 items)
  • gaze:
    DataFrame (3 columns, 20 rows)
    shape: (20, 3)

    text_id	page_id	filepath
    i64	i64	str
    0	1	"aeye-lab-pymovements-toy-datas…
    0	2	"aeye-lab-pymovements-toy-datas…
    0	3	"aeye-lab-pymovements-toy-datas…
    0	4	"aeye-lab-pymovements-toy-datas…
    0	5	"aeye-lab-pymovements-toy-datas…
    …	…	…
    3	1	"aeye-lab-pymovements-toy-datas…
    3	2	"aeye-lab-pymovements-toy-datas…
    3	3	"aeye-lab-pymovements-toy-datas…
    3	4	"aeye-lab-pymovements-toy-datas…
    3	5	"aeye-lab-pymovements-toy-datas…

• gaze:
  list (20 items)
  • Gaze
    • samples:
      DataFrame (6 columns, 17223 rows)
      shape: (17_223, 6)

      time	stimuli_x	stimuli_y	text_id	page_id	pixel
      i64	f64	f64	i64	i64	list[f64]
      1988145	-1.0	-1.0	0	1	[206.8, 152.4]
      1988146	-1.0	-1.0	0	1	[206.9, 152.1]
      1988147	-1.0	-1.0	0	1	[207.0, 151.8]
      1988148	-1.0	-1.0	0	1	[207.1, 151.7]
      1988149	-1.0	-1.0	0	1	[207.0, 151.5]
      …	…	…	…	…	…
      2005363	-1.0	-1.0	0	1	[361.0, 415.4]
      2005364	-1.0	-1.0	0	1	[358.0, 414.5]
      2005365	-1.0	-1.0	0	1	[355.8, 413.8]
      2005366	-1.0	-1.0	0	1	[353.1, 413.2]
      2005367	-1.0	-1.0	0	1	[351.2, 412.9]

    • events:
      Events
      Events

      • frame:
        DataFrame (6 columns, 0 rows)
        shape: (0, 6)

        text_id	page_id	name	onset	offset	duration
        i64	i64	str	i64	i64	i64

      • trial_columns:
        list (2 items)
        • 'text_id'
        • 'page_id'
    • trial_columns:
      list (2 items)
      • 'text_id'
      • 'page_id'
    • experiment:
      Experiment
      Experiment

      • eyetracker:
        EyeTracker
        EyeTracker

        • left:
          None
          None
        • model:
          None
          None
        • mount:
          None
          None
        • right:
          None
          None
        • sampling_rate:
          1000
          1000
        • vendor:
          None
          None
        • version:
          None
          None
      • sampling_rate:
        1000
        1000
      • screen:
        Screen
        Screen

        • distance_cm:
          68
          68
        • height_cm:
          30.2
          30.2
        • height_px:
          1024
          1024
        • origin:
          'upper left'
          'upper left'
        • width_cm:
          38
          38
        • width_px:
          1280
          1280
        • x_max_dva:
          15.599386487782953
          15.599386487782953
        • x_min_dva:
          -15.599386487782953
          -15.599386487782953
        • y_max_dva:
          12.508044410882546
          12.508044410882546
        • y_min_dva:
          -12.508044410882546
          -12.508044410882546
  • Gaze
    • samples:
      DataFrame (6 columns, 29799 rows)
      shape: (29_799, 6)

      time	stimuli_x	stimuli_y	text_id	page_id	pixel
      i64	f64	f64	i64	i64	list[f64]
      2008305	-1.0	-1.0	0	2	[141.4, 153.6]
      2008306	-1.0	-1.0	0	2	[141.1, 153.2]
      2008307	-1.0	-1.0	0	2	[140.7, 152.8]
      2008308	-1.0	-1.0	0	2	[140.6, 152.7]
      2008309	-1.0	-1.0	0	2	[140.5, 152.6]
      …	…	…	…	…	…
      2038099	-1.0	-1.0	0	2	[273.8, 773.8]
      2038100	-1.0	-1.0	0	2	[273.8, 774.1]
      2038101	-1.0	-1.0	0	2	[273.9, 774.5]
      2038102	-1.0	-1.0	0	2	[274.0, 774.4]
      2038103	-1.0	-1.0	0	2	[274.0, 773.9]

    • events:
      Events
      Events

      • frame:
        DataFrame (6 columns, 0 rows)
        shape: (0, 6)

        text_id	page_id	name	onset	offset	duration
        i64	i64	str	i64	i64	i64

      • trial_columns:
        list (2 items)
        • 'text_id'
        • 'page_id'
    • trial_columns:
      list (2 items)
      • 'text_id'
      • 'page_id'
    • experiment:
      Experiment
      Experiment

      • eyetracker:
        EyeTracker
        EyeTracker

        • left:
          None
          None
        • model:
          None
          None
        • mount:
          None
          None
        • right:
          None
          None
        • sampling_rate:
          1000
          1000
        • vendor:
          None
          None
        • version:
          None
          None
      • sampling_rate:
        1000
        1000
      • screen:
        Screen
        Screen

        • distance_cm:
          68
          68
        • height_cm:
          30.2
          30.2
        • height_px:
          1024
          1024
        • origin:
          'upper left'
          'upper left'
        • width_cm:
          38
          38
        • width_px:
          1280
          1280
        • x_max_dva:
          15.599386487782953
          15.599386487782953
        • x_min_dva:
          -15.599386487782953
          -15.599386487782953
        • y_max_dva:
          12.508044410882546
          12.508044410882546
        • y_min_dva:
          -12.508044410882546
          -12.508044410882546
  • (18 more)
• path:
  PosixPath('data/ToyDataset')
  PosixPath('data/ToyDataset')
• paths:
  DatasetPaths
  DatasetPaths

  • dataset:
    PosixPath('data/ToyDataset')
    PosixPath('data/ToyDataset')
  • downloads:
    PosixPath('data/ToyDataset/downloads')
    PosixPath('data/ToyDataset/downloads')
  • events:
    PosixPath('data/ToyDataset/events')
    PosixPath('data/ToyDataset/events')
  • precomputed_events:
    PosixPath('data/ToyDataset/precomputed_events')
    PosixPath('data/ToyDataset/precomputed_events')
  • precomputed_reading_measures:
    PosixPath
    PosixPath('data/ToyDataset/precomputed_reading_measures')
  • preprocessed:
    PosixPath('data/ToyDataset/preprocessed')
    PosixPath('data/ToyDataset/preprocessed')
  • raw:
    PosixPath('data/ToyDataset/raw')
    PosixPath('data/ToyDataset/raw')
  • root:
    PosixPath('data/ToyDataset')
    PosixPath('data/ToyDataset')
• precomputed_events:
  list (0 items)
• precomputed_reading_measures:
  list (0 items)

The dataset consist 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:

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

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

dataset.pix2deg()
dataset.pos2vel('smooth')
dataset.gaze[0]

Gaze

• samples:
  DataFrame (8 columns, 17223 rows)
  shape: (17_223, 8)

  time	stimuli_x	stimuli_y	text_id	page_id	pixel	position	velocity
  i64	f64	f64	i64	i64	list[f64]	list[f64]	list[f64]
  1988145	-1.0	-1.0	0	1	[206.8, 152.4]	[-10.697598, -8.852399]	[null, null]
  1988146	-1.0	-1.0	0	1	[206.9, 152.1]	[-10.695183, -8.859678]	[null, null]
  1988147	-1.0	-1.0	0	1	[207.0, 151.8]	[-10.692768, -8.866956]	[1.610194, -5.256267]
  1988148	-1.0	-1.0	0	1	[207.1, 151.7]	[-10.690352, -8.869381]	[0.402548, -4.447465]
  1988149	-1.0	-1.0	0	1	[207.0, 151.5]	[-10.692768, -8.874233]	[0.402561, -3.234462]
  …	…	…	…	…	…	…	…
  2005363	-1.0	-1.0	0	1	[361.0, 415.4]	[-6.932438, -2.386672]	[-63.266374, -21.085616]
  2005364	-1.0	-1.0	0	1	[358.0, 414.5]	[-7.006376, -2.408998]	[-63.249652, -19.431326]
  2005365	-1.0	-1.0	0	1	[355.8, 413.8]	[-7.060582, -2.426362]	[-60.359624, -15.710061]
  2005366	-1.0	-1.0	0	1	[353.1, 413.2]	[-7.12709, -2.441245]	[null, null]
  2005367	-1.0	-1.0	0	1	[351.2, 412.9]	[-7.173881, -2.448686]	[null, null]

• events:
  Events
  Events

  • frame:
    DataFrame (6 columns, 0 rows)
    shape: (0, 6)

    text_id	page_id	name	onset	offset	duration
    i64	i64	str	i64	i64	i64

  • trial_columns:
    list (2 items)
    • 'text_id'
    • 'page_id'
• trial_columns:
  list (2 items)
  • 'text_id'
  • 'page_id'
• experiment:
  Experiment
  Experiment

  • eyetracker:
    EyeTracker
    EyeTracker

    • left:
      None
      None
    • model:
      None
      None
    • mount:
      None
      None
    • right:
      None
      None
    • sampling_rate:
      1000
      1000
    • vendor:
      None
      None
    • version:
      None
      None
  • sampling_rate:
    1000
    1000
  • screen:
    Screen
    Screen

    • distance_cm:
      68
      68
    • height_cm:
      30.2
      30.2
    • height_px:
      1024
      1024
    • origin:
      'upper left'
      'upper left'
    • width_cm:
      38
      38
    • width_px:
      1280
      1280
    • x_max_dva:
      15.599386487782953
      15.599386487782953
    • x_min_dva:
      -15.599386487782953
      -15.599386487782953
    • y_max_dva:
      12.508044410882546
      12.508044410882546
    • y_min_dva:
      -12.508044410882546
      -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 pymovements.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

• definition:
  DatasetDefinition
  DatasetDefinition

  • acceleration_columns:
    None
    None
  • column_map:
    dict (0 items)
  • custom_read_kwargs:
    dict (1 items)
    • gaze:
      dict (4 items)
      • columns:
        list (5 items)
        • 'timestamp'
        • 'x'
        • (3 more)
      • schema_overrides:
        dict (5 items)
        • timestamp:
          Float64
          Float64
        • x:
          Float64
          Float64
        • (3 more)
      • (2 more)
  • distance_column:
    None
    None
  • experiment:
    Experiment
    Experiment

    • eyetracker:
      EyeTracker
      EyeTracker

      • left:
        None
        None
      • model:
        None
        None
      • mount:
        None
        None
      • right:
        None
        None
      • sampling_rate:
        1000
        1000
      • vendor:
        None
        None
      • version:
        None
        None
    • sampling_rate:
      1000
      1000
    • screen:
      Screen
      Screen

      • distance_cm:
        68
        68
      • height_cm:
        30.2
        30.2
      • height_px:
        1024
        1024
      • origin:
        'upper left'
        'upper left'
      • width_cm:
        38
        38
      • width_px:
        1280
        1280
      • x_max_dva:
        15.599386487782953
        15.599386487782953
      • x_min_dva:
        -15.599386487782953
        -15.599386487782953
      • y_max_dva:
        12.508044410882546
        12.508044410882546
      • y_min_dva:
        -12.508044410882546
        -12.508044410882546
  • extract:
    None
    None
  • filename_format:
    dict (1 items)
    • gaze:
      'trial_{text_id:d}_{page_id:d}.csv'
      'trial_{text_id:d}_{page_id:d}.csv'
  • filename_format_schema_overrides:
    dict (1 items)
    • gaze:
      dict (2 items)
      • text_id:
        <class 'int'>
        <class 'int'>
      • page_id:
        <class 'int'>
        <class 'int'>
  • has_resources:
    True
    True
  • long_name:
    'pymovements Toy Dataset'
    'pymovements Toy Dataset'
  • mirrors:
    dict (0 items)
  • name:
    'ToyDataset'
    'ToyDataset'
  • pixel_columns:
    list (2 items)
    • 'x'
    • 'y'
  • position_columns:
    None
    None
  • resources:
    list (1 items)
    • ResourceDefinition
      • content:
        'gaze'
        'gaze'
      • filename:
        'pymovements-toy-dataset.zip'
        'pymovements-toy-dataset.zip'
      • filename_pattern:
        'trial_{text_id:d}_{page_id:d}.csv'
        'trial_{text_id:d}_{page_id:d}.csv'
      • filename_pattern_schema_overrides:
        dict (2 items)
        • text_id:
          <class 'int'>
          <class 'int'>
        • page_id:
          <class 'int'>
          <class 'int'>
      • md5:
        '4da622457637a8181d86601fe17f3aa8'
        '4da622457637a8181d86601fe17f3aa8'
      • url:
        str
        'http://github.com/aeye-lab/pymovements-toy-dataset/zipball/6cb5d663317bf418cec0c9abe1dde5085a8a8ebd/'
  • time_column:
    'timestamp'
    'timestamp'
  • time_unit:
    'ms'
    'ms'
  • trial_columns:
    None
    None
  • velocity_columns:
    None
    None
• events:
  list (20 items)
  • Events
    • frame:
      DataFrame (6 columns, 56 rows)
      shape: (56, 6)

      text_id	page_id	name	onset	offset	duration
      i64	i64	str	i64	i64	i64
      0	1	"fixation"	1988145	1988563	418
      0	1	"fixation"	1988564	1988750	186
      0	1	"fixation"	1988751	1989178	427
      0	1	"fixation"	1989179	1989436	257
      0	1	"fixation"	1989437	1989600	163
      …	…	…	…	…	…
      0	1	"fixation"	2003929	2004090	161
      0	1	"fixation"	2004091	2004363	272
      0	1	"fixation"	2004364	2004883	519
      0	1	"fixation"	2004885	2005116	231
      0	1	"fixation"	2005117	2005298	181

    • trial_columns:
      list (2 items)
      • 'text_id'
      • 'page_id'
  • Events
    • frame:
      DataFrame (6 columns, 94 rows)
      shape: (94, 6)

      text_id	page_id	name	onset	offset	duration
      i64	i64	str	i64	i64	i64
      0	2	"fixation"	2008305	2008621	316
      0	2	"fixation"	2008622	2008821	199
      0	2	"fixation"	2008822	2009214	392
      0	2	"fixation"	2009215	2009433	218
      0	2	"fixation"	2009434	2009704	270
      …	…	…	…	…	…
      0	2	"fixation"	2036840	2037175	335
      0	2	"fixation"	2037176	2037424	248
      0	2	"fixation"	2037462	2037644	182
      0	2	"fixation"	2037645	2037824	179
      0	2	"fixation"	2037825	2038103	278

    • trial_columns:
      list (2 items)
      • 'text_id'
      • 'page_id'
  • (18 more)
• fileinfo:
  dict (1 items)
  • gaze:
    DataFrame (3 columns, 20 rows)
    shape: (20, 3)

    text_id	page_id	filepath
    i64	i64	str
    0	1	"aeye-lab-pymovements-toy-datas…
    0	2	"aeye-lab-pymovements-toy-datas…
    0	3	"aeye-lab-pymovements-toy-datas…
    0	4	"aeye-lab-pymovements-toy-datas…
    0	5	"aeye-lab-pymovements-toy-datas…
    …	…	…
    3	1	"aeye-lab-pymovements-toy-datas…
    3	2	"aeye-lab-pymovements-toy-datas…
    3	3	"aeye-lab-pymovements-toy-datas…
    3	4	"aeye-lab-pymovements-toy-datas…
    3	5	"aeye-lab-pymovements-toy-datas…

• gaze:
  list (20 items)
  • Gaze
    • samples:
      DataFrame (8 columns, 17223 rows)
      shape: (17_223, 8)

      time	stimuli_x	stimuli_y	text_id	page_id	pixel	position	velocity
      i64	f64	f64	i64	i64	list[f64]	list[f64]	list[f64]
      1988145	-1.0	-1.0	0	1	[206.8, 152.4]	[-10.697598, -8.852399]	[null, null]
      1988146	-1.0	-1.0	0	1	[206.9, 152.1]	[-10.695183, -8.859678]	[null, null]
      1988147	-1.0	-1.0	0	1	[207.0, 151.8]	[-10.692768, -8.866956]	[1.610194, -5.256267]
      1988148	-1.0	-1.0	0	1	[207.1, 151.7]	[-10.690352, -8.869381]	[0.402548, -4.447465]
      1988149	-1.0	-1.0	0	1	[207.0, 151.5]	[-10.692768, -8.874233]	[0.402561, -3.234462]
      …	…	…	…	…	…	…	…
      2005363	-1.0	-1.0	0	1	[361.0, 415.4]	[-6.932438, -2.386672]	[-63.266374, -21.085616]
      2005364	-1.0	-1.0	0	1	[358.0, 414.5]	[-7.006376, -2.408998]	[-63.249652, -19.431326]
      2005365	-1.0	-1.0	0	1	[355.8, 413.8]	[-7.060582, -2.426362]	[-60.359624, -15.710061]
      2005366	-1.0	-1.0	0	1	[353.1, 413.2]	[-7.12709, -2.441245]	[null, null]
      2005367	-1.0	-1.0	0	1	[351.2, 412.9]	[-7.173881, -2.448686]	[null, null]

    • events:
      Events
      Events

      • frame:
        DataFrame (6 columns, 56 rows)
        shape: (56, 6)

        text_id	page_id	name	onset	offset	duration
        i64	i64	str	i64	i64	i64
        0	1	"fixation"	1988145	1988563	418
        0	1	"fixation"	1988564	1988750	186
        0	1	"fixation"	1988751	1989178	427
        0	1	"fixation"	1989179	1989436	257
        0	1	"fixation"	1989437	1989600	163
        …	…	…	…	…	…
        0	1	"fixation"	2003929	2004090	161
        0	1	"fixation"	2004091	2004363	272
        0	1	"fixation"	2004364	2004883	519
        0	1	"fixation"	2004885	2005116	231
        0	1	"fixation"	2005117	2005298	181

      • trial_columns:
        list (2 items)
        • 'text_id'
        • 'page_id'
    • trial_columns:
      list (2 items)
      • 'text_id'
      • 'page_id'
    • experiment:
      Experiment
      Experiment

      • eyetracker:
        EyeTracker
        EyeTracker

        • left:
          None
          None
        • model:
          None
          None
        • mount:
          None
          None
        • right:
          None
          None
        • sampling_rate:
          1000
          1000
        • vendor:
          None
          None
        • version:
          None
          None
      • sampling_rate:
        1000
        1000
      • screen:
        Screen
        Screen

        • distance_cm:
          68
          68
        • height_cm:
          30.2
          30.2
        • height_px:
          1024
          1024
        • origin:
          'upper left'
          'upper left'
        • width_cm:
          38
          38
        • width_px:
          1280
          1280
        • x_max_dva:
          15.599386487782953
          15.599386487782953
        • x_min_dva:
          -15.599386487782953
          -15.599386487782953
        • y_max_dva:
          12.508044410882546
          12.508044410882546
        • y_min_dva:
          -12.508044410882546
          -12.508044410882546
  • Gaze
    • samples:
      DataFrame (8 columns, 29799 rows)
      shape: (29_799, 8)

      time	stimuli_x	stimuli_y	text_id	page_id	pixel	position	velocity
      i64	f64	f64	i64	i64	list[f64]	list[f64]	list[f64]
      2008305	-1.0	-1.0	0	2	[141.4, 153.6]	[-12.268583, -8.823284]	[null, null]
      2008306	-1.0	-1.0	0	2	[141.1, 153.2]	[-12.275749, -8.832989]	[null, null]
      2008307	-1.0	-1.0	0	2	[140.7, 152.8]	[-12.285302, -8.842695]	[-5.572617, -6.065816]
      2008308	-1.0	-1.0	0	2	[140.6, 152.7]	[-12.28769, -8.845121]	[-3.582268, -4.043733]
      2008309	-1.0	-1.0	0	2	[140.5, 152.6]	[-12.290078, -8.847547]	[-2.388085, -2.021821]
      …	…	…	…	…	…	…	…
      2038099	-1.0	-1.0	0	2	[273.8, 773.8]	[-9.071149, 6.490168]	[1.21962, 1.635403]
      2038100	-1.0	-1.0	0	2	[273.8, 774.1]	[-9.071149, 6.497527]	[1.626175, 4.497406]
      2038101	-1.0	-1.0	0	2	[273.9, 774.5]	[-9.06871, 6.50734]	[1.626186, 1.635423]
      2038102	-1.0	-1.0	0	2	[274.0, 774.4]	[-9.066271, 6.504886]	[null, null]
      2038103	-1.0	-1.0	0	2	[274.0, 773.9]	[-9.066271, 6.492621]	[null, null]

    • events:
      Events
      Events

      • frame:
        DataFrame (6 columns, 94 rows)
        shape: (94, 6)

        text_id	page_id	name	onset	offset	duration
        i64	i64	str	i64	i64	i64
        0	2	"fixation"	2008305	2008621	316
        0	2	"fixation"	2008622	2008821	199
        0	2	"fixation"	2008822	2009214	392
        0	2	"fixation"	2009215	2009433	218
        0	2	"fixation"	2009434	2009704	270
        …	…	…	…	…	…
        0	2	"fixation"	2036840	2037175	335
        0	2	"fixation"	2037176	2037424	248
        0	2	"fixation"	2037462	2037644	182
        0	2	"fixation"	2037645	2037824	179
        0	2	"fixation"	2037825	2038103	278

      • trial_columns:
        list (2 items)
        • 'text_id'
        • 'page_id'
    • trial_columns:
      list (2 items)
      • 'text_id'
      • 'page_id'
    • experiment:
      Experiment
      Experiment

      • eyetracker:
        EyeTracker
        EyeTracker

        • left:
          None
          None
        • model:
          None
          None
        • mount:
          None
          None
        • right:
          None
          None
        • sampling_rate:
          1000
          1000
        • vendor:
          None
          None
        • version:
          None
          None
      • sampling_rate:
        1000
        1000
      • screen:
        Screen
        Screen

        • distance_cm:
          68
          68
        • height_cm:
          30.2
          30.2
        • height_px:
          1024
          1024
        • origin:
          'upper left'
          'upper left'
        • width_cm:
          38
          38
        • width_px:
          1280
          1280
        • x_max_dva:
          15.599386487782953
          15.599386487782953
        • x_min_dva:
          -15.599386487782953
          -15.599386487782953
        • y_max_dva:
          12.508044410882546
          12.508044410882546
        • y_min_dva:
          -12.508044410882546
          -12.508044410882546
  • (18 more)
• path:
  PosixPath('data/ToyDataset')
  PosixPath('data/ToyDataset')
• paths:
  DatasetPaths
  DatasetPaths

  • dataset:
    PosixPath('data/ToyDataset')
    PosixPath('data/ToyDataset')
  • downloads:
    PosixPath('data/ToyDataset/downloads')
    PosixPath('data/ToyDataset/downloads')
  • events:
    PosixPath('data/ToyDataset/events')
    PosixPath('data/ToyDataset/events')
  • precomputed_events:
    PosixPath('data/ToyDataset/precomputed_events')
    PosixPath('data/ToyDataset/precomputed_events')
  • precomputed_reading_measures:
    PosixPath
    PosixPath('data/ToyDataset/precomputed_reading_measures')
  • preprocessed:
    PosixPath('data/ToyDataset/preprocessed')
    PosixPath('data/ToyDataset/preprocessed')
  • raw:
    PosixPath('data/ToyDataset/raw')
    PosixPath('data/ToyDataset/raw')
  • root:
    PosixPath('data/ToyDataset')
    PosixPath('data/ToyDataset')
• precomputed_events:
  list (0 items)
• precomputed_reading_measures:
  list (0 items)

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

dataset.events[0]

Events

• frame:
  DataFrame (6 columns, 56 rows)
  shape: (56, 6)

  text_id	page_id	name	onset	offset	duration
  i64	i64	str	i64	i64	i64
  0	1	"fixation"	1988145	1988563	418
  0	1	"fixation"	1988564	1988750	186
  0	1	"fixation"	1988751	1989178	427
  0	1	"fixation"	1989179	1989436	257
  0	1	"fixation"	1989437	1989600	163
  …	…	…	…	…	…
  0	1	"fixation"	2003929	2004090	161
  0	1	"fixation"	2004091	2004363	272
  0	1	"fixation"	2004364	2004883	519
  0	1	"fixation"	2004885	2005116	231
  0	1	"fixation"	2005117	2005298	181

• trial_columns:
  list (2 items)
  • 'text_id'
  • 'page_id'

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

• frame:
  DataFrame (6 columns, 129 rows)
  shape: (129, 6)

  text_id	page_id	name	onset	offset	duration
  i64	i64	str	i64	i64	i64
  0	1	"fixation"	1988145	1988563	418
  0	1	"fixation"	1988564	1988750	186
  0	1	"fixation"	1988751	1989178	427
  0	1	"fixation"	1989179	1989436	257
  0	1	"fixation"	1989437	1989600	163
  …	…	…	…	…	…
  0	1	"fixation.ivt"	2004132	2004331	199
  0	1	"fixation.ivt"	2004399	2004687	288
  0	1	"fixation.ivt"	2004714	2004878	164
  0	1	"fixation.ivt"	2004931	2005109	178
  0	1	"fixation.ivt"	2005138	2005287	149

• trial_columns:
  list (2 items)
  • 'text_id'
  • 'page_id'

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

• definition:
  DatasetDefinition
  DatasetDefinition

  • acceleration_columns:
    None
    None
  • column_map:
    dict (0 items)
  • custom_read_kwargs:
    dict (1 items)
    • gaze:
      dict (4 items)
      • columns:
        list (5 items)
        • 'timestamp'
        • 'x'
        • (3 more)
      • schema_overrides:
        dict (5 items)
        • timestamp:
          Float64
          Float64
        • x:
          Float64
          Float64
        • (3 more)
      • (2 more)
  • distance_column:
    None
    None
  • experiment:
    Experiment
    Experiment

    • eyetracker:
      EyeTracker
      EyeTracker

      • left:
        None
        None
      • model:
        None
        None
      • mount:
        None
        None
      • right:
        None
        None
      • sampling_rate:
        1000
        1000
      • vendor:
        None
        None
      • version:
        None
        None
    • sampling_rate:
      1000
      1000
    • screen:
      Screen
      Screen

      • distance_cm:
        68
        68
      • height_cm:
        30.2
        30.2
      • height_px:
        1024
        1024
      • origin:
        'upper left'
        'upper left'
      • width_cm:
        38
        38
      • width_px:
        1280
        1280
      • x_max_dva:
        15.599386487782953
        15.599386487782953
      • x_min_dva:
        -15.599386487782953
        -15.599386487782953
      • y_max_dva:
        12.508044410882546
        12.508044410882546
      • y_min_dva:
        -12.508044410882546
        -12.508044410882546
  • extract:
    None
    None
  • filename_format:
    dict (1 items)
    • gaze:
      'trial_{text_id:d}_{page_id:d}.csv'
      'trial_{text_id:d}_{page_id:d}.csv'
  • filename_format_schema_overrides:
    dict (1 items)
    • gaze:
      dict (2 items)
      • text_id:
        <class 'int'>
        <class 'int'>
      • page_id:
        <class 'int'>
        <class 'int'>
  • has_resources:
    True
    True
  • long_name:
    'pymovements Toy Dataset'
    'pymovements Toy Dataset'
  • mirrors:
    dict (0 items)
  • name:
    'ToyDataset'
    'ToyDataset'
  • pixel_columns:
    list (2 items)
    • 'x'
    • 'y'
  • position_columns:
    None
    None
  • resources:
    list (1 items)
    • ResourceDefinition
      • content:
        'gaze'
        'gaze'
      • filename:
        'pymovements-toy-dataset.zip'
        'pymovements-toy-dataset.zip'
      • filename_pattern:
        'trial_{text_id:d}_{page_id:d}.csv'
        'trial_{text_id:d}_{page_id:d}.csv'
      • filename_pattern_schema_overrides:
        dict (2 items)
        • text_id:
          <class 'int'>
          <class 'int'>
        • page_id:
          <class 'int'>
          <class 'int'>
      • md5:
        '4da622457637a8181d86601fe17f3aa8'
        '4da622457637a8181d86601fe17f3aa8'
      • url:
        str
        'http://github.com/aeye-lab/pymovements-toy-dataset/zipball/6cb5d663317bf418cec0c9abe1dde5085a8a8ebd/'
  • time_column:
    'timestamp'
    'timestamp'
  • time_unit:
    'ms'
    'ms'
  • trial_columns:
    None
    None
  • velocity_columns:
    None
    None
• events:
  list (20 items)
  • Events
    • frame:
      DataFrame (6 columns, 222 rows)
      shape: (222, 6)

      text_id	page_id	name	onset	offset	duration
      i64	i64	str	i64	i64	i64
      0	1	"fixation"	1988145	1988563	418
      0	1	"fixation"	1988564	1988750	186
      0	1	"fixation"	1988751	1989178	427
      0	1	"fixation"	1989179	1989436	257
      0	1	"fixation"	1989437	1989600	163
      …	…	…	…	…	…
      0	1	"saccade"	2004373	2004385	12
      0	1	"saccade"	2004688	2004704	16
      0	1	"saccade"	2004879	2004901	22
      0	1	"saccade"	2005110	2005126	16
      0	1	"saccade"	2005288	2005345	57

    • trial_columns:
      list (2 items)
      • 'text_id'
      • 'page_id'
  • Events
    • frame:
      DataFrame (6 columns, 366 rows)
      shape: (366, 6)

      text_id	page_id	name	onset	offset	duration
      i64	i64	str	i64	i64	i64
      0	2	"fixation"	2008305	2008621	316
      0	2	"fixation"	2008622	2008821	199
      0	2	"fixation"	2008822	2009214	392
      0	2	"fixation"	2009215	2009433	218
      0	2	"fixation"	2009434	2009704	270
      …	…	…	…	…	…
      0	2	"saccade"	2036849	2036861	12
      0	2	"saccade"	2037161	2037188	27
      0	2	"saccade"	2037412	2037503	91
      0	2	"saccade"	2037638	2037654	16
      0	2	"saccade"	2037812	2037830	18

    • trial_columns:
      list (2 items)
      • 'text_id'
      • 'page_id'
  • (18 more)
• fileinfo:
  dict (1 items)
  • gaze:
    DataFrame (3 columns, 20 rows)
    shape: (20, 3)

    text_id	page_id	filepath
    i64	i64	str
    0	1	"aeye-lab-pymovements-toy-datas…
    0	2	"aeye-lab-pymovements-toy-datas…
    0	3	"aeye-lab-pymovements-toy-datas…
    0	4	"aeye-lab-pymovements-toy-datas…
    0	5	"aeye-lab-pymovements-toy-datas…
    …	…	…
    3	1	"aeye-lab-pymovements-toy-datas…
    3	2	"aeye-lab-pymovements-toy-datas…
    3	3	"aeye-lab-pymovements-toy-datas…
    3	4	"aeye-lab-pymovements-toy-datas…
    3	5	"aeye-lab-pymovements-toy-datas…

• gaze:
  list (20 items)
  • Gaze
    • samples:
      DataFrame (8 columns, 17223 rows)
      shape: (17_223, 8)

      time	stimuli_x	stimuli_y	text_id	page_id	pixel	position	velocity
      i64	f64	f64	i64	i64	list[f64]	list[f64]	list[f64]
      1988145	-1.0	-1.0	0	1	[206.8, 152.4]	[-10.697598, -8.852399]	[null, null]
      1988146	-1.0	-1.0	0	1	[206.9, 152.1]	[-10.695183, -8.859678]	[null, null]
      1988147	-1.0	-1.0	0	1	[207.0, 151.8]	[-10.692768, -8.866956]	[1.610194, -5.256267]
      1988148	-1.0	-1.0	0	1	[207.1, 151.7]	[-10.690352, -8.869381]	[0.402548, -4.447465]
      1988149	-1.0	-1.0	0	1	[207.0, 151.5]	[-10.692768, -8.874233]	[0.402561, -3.234462]
      …	…	…	…	…	…	…	…
      2005363	-1.0	-1.0	0	1	[361.0, 415.4]	[-6.932438, -2.386672]	[-63.266374, -21.085616]
      2005364	-1.0	-1.0	0	1	[358.0, 414.5]	[-7.006376, -2.408998]	[-63.249652, -19.431326]
      2005365	-1.0	-1.0	0	1	[355.8, 413.8]	[-7.060582, -2.426362]	[-60.359624, -15.710061]
      2005366	-1.0	-1.0	0	1	[353.1, 413.2]	[-7.12709, -2.441245]	[null, null]
      2005367	-1.0	-1.0	0	1	[351.2, 412.9]	[-7.173881, -2.448686]	[null, null]

    • events:
      Events
      Events

      • frame:
        DataFrame (6 columns, 222 rows)
        shape: (222, 6)

        text_id	page_id	name	onset	offset	duration
        i64	i64	str	i64	i64	i64
        0	1	"fixation"	1988145	1988563	418
        0	1	"fixation"	1988564	1988750	186
        0	1	"fixation"	1988751	1989178	427
        0	1	"fixation"	1989179	1989436	257
        0	1	"fixation"	1989437	1989600	163
        …	…	…	…	…	…
        0	1	"saccade"	2004373	2004385	12
        0	1	"saccade"	2004688	2004704	16
        0	1	"saccade"	2004879	2004901	22
        0	1	"saccade"	2005110	2005126	16
        0	1	"saccade"	2005288	2005345	57

      • trial_columns:
        list (2 items)
        • 'text_id'
        • 'page_id'
    • trial_columns:
      list (2 items)
      • 'text_id'
      • 'page_id'
    • experiment:
      Experiment
      Experiment

      • eyetracker:
        EyeTracker
        EyeTracker

        • left:
          None
          None
        • model:
          None
          None
        • mount:
          None
          None
        • right:
          None
          None
        • sampling_rate:
          1000
          1000
        • vendor:
          None
          None
        • version:
          None
          None
      • sampling_rate:
        1000
        1000
      • screen:
        Screen
        Screen

        • distance_cm:
          68
          68
        • height_cm:
          30.2
          30.2
        • height_px:
          1024
          1024
        • origin:
          'upper left'
          'upper left'
        • width_cm:
          38
          38
        • width_px:
          1280
          1280
        • x_max_dva:
          15.599386487782953
          15.599386487782953
        • x_min_dva:
          -15.599386487782953
          -15.599386487782953
        • y_max_dva:
          12.508044410882546
          12.508044410882546
        • y_min_dva:
          -12.508044410882546
          -12.508044410882546
  • Gaze
    • samples:
      DataFrame (8 columns, 29799 rows)
      shape: (29_799, 8)

      time	stimuli_x	stimuli_y	text_id	page_id	pixel	position	velocity
      i64	f64	f64	i64	i64	list[f64]	list[f64]	list[f64]
      2008305	-1.0	-1.0	0	2	[141.4, 153.6]	[-12.268583, -8.823284]	[null, null]
      2008306	-1.0	-1.0	0	2	[141.1, 153.2]	[-12.275749, -8.832989]	[null, null]
      2008307	-1.0	-1.0	0	2	[140.7, 152.8]	[-12.285302, -8.842695]	[-5.572617, -6.065816]
      2008308	-1.0	-1.0	0	2	[140.6, 152.7]	[-12.28769, -8.845121]	[-3.582268, -4.043733]
      2008309	-1.0	-1.0	0	2	[140.5, 152.6]	[-12.290078, -8.847547]	[-2.388085, -2.021821]
      …	…	…	…	…	…	…	…
      2038099	-1.0	-1.0	0	2	[273.8, 773.8]	[-9.071149, 6.490168]	[1.21962, 1.635403]
      2038100	-1.0	-1.0	0	2	[273.8, 774.1]	[-9.071149, 6.497527]	[1.626175, 4.497406]
      2038101	-1.0	-1.0	0	2	[273.9, 774.5]	[-9.06871, 6.50734]	[1.626186, 1.635423]
      2038102	-1.0	-1.0	0	2	[274.0, 774.4]	[-9.066271, 6.504886]	[null, null]
      2038103	-1.0	-1.0	0	2	[274.0, 773.9]	[-9.066271, 6.492621]	[null, null]

    • events:
      Events
      Events

      • frame:
        DataFrame (6 columns, 366 rows)
        shape: (366, 6)

        text_id	page_id	name	onset	offset	duration
        i64	i64	str	i64	i64	i64
        0	2	"fixation"	2008305	2008621	316
        0	2	"fixation"	2008622	2008821	199
        0	2	"fixation"	2008822	2009214	392
        0	2	"fixation"	2009215	2009433	218
        0	2	"fixation"	2009434	2009704	270
        …	…	…	…	…	…
        0	2	"saccade"	2036849	2036861	12
        0	2	"saccade"	2037161	2037188	27
        0	2	"saccade"	2037412	2037503	91
        0	2	"saccade"	2037638	2037654	16
        0	2	"saccade"	2037812	2037830	18

      • trial_columns:
        list (2 items)
        • 'text_id'
        • 'page_id'
    • trial_columns:
      list (2 items)
      • 'text_id'
      • 'page_id'
    • experiment:
      Experiment
      Experiment

      • eyetracker:
        EyeTracker
        EyeTracker

        • left:
          None
          None
        • model:
          None
          None
        • mount:
          None
          None
        • right:
          None
          None
        • sampling_rate:
          1000
          1000
        • vendor:
          None
          None
        • version:
          None
          None
      • sampling_rate:
        1000
        1000
      • screen:
        Screen
        Screen

        • distance_cm:
          68
          68
        • height_cm:
          30.2
          30.2
        • height_px:
          1024
          1024
        • origin:
          'upper left'
          'upper left'
        • width_cm:
          38
          38
        • width_px:
          1280
          1280
        • x_max_dva:
          15.599386487782953
          15.599386487782953
        • x_min_dva:
          -15.599386487782953
          -15.599386487782953
        • y_max_dva:
          12.508044410882546
          12.508044410882546
        • y_min_dva:
          -12.508044410882546
          -12.508044410882546
  • (18 more)
• path:
  PosixPath('data/ToyDataset')
  PosixPath('data/ToyDataset')
• paths:
  DatasetPaths
  DatasetPaths

  • dataset:
    PosixPath('data/ToyDataset')
    PosixPath('data/ToyDataset')
  • downloads:
    PosixPath('data/ToyDataset/downloads')
    PosixPath('data/ToyDataset/downloads')
  • events:
    PosixPath('data/ToyDataset/events')
    PosixPath('data/ToyDataset/events')
  • precomputed_events:
    PosixPath('data/ToyDataset/precomputed_events')
    PosixPath('data/ToyDataset/precomputed_events')
  • precomputed_reading_measures:
    PosixPath
    PosixPath('data/ToyDataset/precomputed_reading_measures')
  • preprocessed:
    PosixPath('data/ToyDataset/preprocessed')
    PosixPath('data/ToyDataset/preprocessed')
  • raw:
    PosixPath('data/ToyDataset/raw')
    PosixPath('data/ToyDataset/raw')
  • root:
    PosixPath('data/ToyDataset')
    PosixPath('data/ToyDataset')
• precomputed_events:
  list (0 items)
• precomputed_reading_measures:
  list (0 items)

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

dataset.events[0]

Events

• frame:
  DataFrame (6 columns, 222 rows)
  shape: (222, 6)

  text_id	page_id	name	onset	offset	duration
  i64	i64	str	i64	i64	i64
  0	1	"fixation"	1988145	1988563	418
  0	1	"fixation"	1988564	1988750	186
  0	1	"fixation"	1988751	1989178	427
  0	1	"fixation"	1989179	1989436	257
  0	1	"fixation"	1989437	1989600	163
  …	…	…	…	…	…
  0	1	"saccade"	2004373	2004385	12
  0	1	"saccade"	2004688	2004704	16
  0	1	"saccade"	2004879	2004901	22
  0	1	"saccade"	2005110	2005126	16
  0	1	"saccade"	2005288	2005345	57

• trial_columns:
  list (2 items)
  • 'text_id'
  • 'page_id'

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 pymovements.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

• frame:
  DataFrame (7 columns, 222 rows)
  shape: (222, 7)

  text_id	page_id	name	onset	offset	duration	peak_velocity
  i64	i64	str	i64	i64	i64	f64
  0	1	"fixation"	1988145	1988563	418	200.144558
  0	1	"fixation"	1988564	1988750	186	249.67823
  0	1	"fixation"	1988751	1989178	427	211.598748
  0	1	"fixation"	1989179	1989436	257	189.183243
  0	1	"fixation"	1989437	1989600	163	255.077509
  …	…	…	…	…	…	…
  0	1	"saccade"	2004373	2004385	12	70.374183
  0	1	"saccade"	2004688	2004704	16	175.646379
  0	1	"saccade"	2004879	2004901	22	209.46361
  0	1	"saccade"	2005110	2005126	16	137.917594
  0	1	"saccade"	2005288	2005345	57	352.550667

• trial_columns:
  list (2 items)
  • 'text_id'
  • 'page_id'

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

• frame:
  DataFrame (9 columns, 222 rows)
  shape: (222, 9)

  text_id	page_id	name	onset	offset	duration	peak_velocity	amplitude	dispersion
  i64	i64	str	i64	i64	i64	f64	f64	f64
  0	1	"fixation"	1988145	1988563	418	200.144558	2.492864	2.712569
  0	1	"fixation"	1988564	1988750	186	249.67823	2.651198	2.865026
  0	1	"fixation"	1988751	1989178	427	211.598748	2.585906	2.779518
  0	1	"fixation"	1989179	1989436	257	189.183243	2.614347	2.77424
  0	1	"fixation"	1989437	1989600	163	255.077509	2.594651	2.729391
  …	…	…	…	…	…	…	…	…
  0	1	"saccade"	2004373	2004385	12	70.374183	0.7073	0.766684
  0	1	"saccade"	2004688	2004704	16	175.646379	1.807485	1.875716
  0	1	"saccade"	2004879	2004901	22	209.46361	2.933818	3.086169
  0	1	"saccade"	2005110	2005126	16	137.917594	1.405354	1.501217
  0	1	"saccade"	2005288	2005345	57	352.550667	14.682541	16.101153

• trial_columns:
  list (2 items)
  • 'text_id'
  • 'page_id'

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

• definition:
  DatasetDefinition
  DatasetDefinition

  • acceleration_columns:
    None
    None
  • column_map:
    dict (0 items)
  • custom_read_kwargs:
    dict (1 items)
    • gaze:
      dict (4 items)
      • columns:
        list (5 items)
        • 'timestamp'
        • 'x'
        • (3 more)
      • schema_overrides:
        dict (5 items)
        • timestamp:
          Float64
          Float64
        • x:
          Float64
          Float64
        • (3 more)
      • (2 more)
  • distance_column:
    None
    None
  • experiment:
    Experiment
    Experiment

    • eyetracker:
      EyeTracker
      EyeTracker

      • left:
        None
        None
      • model:
        None
        None
      • mount:
        None
        None
      • right:
        None
        None
      • sampling_rate:
        1000
        1000
      • vendor:
        None
        None
      • version:
        None
        None
    • sampling_rate:
      1000
      1000
    • screen:
      Screen
      Screen

      • distance_cm:
        68
        68
      • height_cm:
        30.2
        30.2
      • height_px:
        1024
        1024
      • origin:
        'upper left'
        'upper left'
      • width_cm:
        38
        38
      • width_px:
        1280
        1280
      • x_max_dva:
        15.599386487782953
        15.599386487782953
      • x_min_dva:
        -15.599386487782953
        -15.599386487782953
      • y_max_dva:
        12.508044410882546
        12.508044410882546
      • y_min_dva:
        -12.508044410882546
        -12.508044410882546
  • extract:
    None
    None
  • filename_format:
    dict (1 items)
    • gaze:
      'trial_{text_id:d}_{page_id:d}.csv'
      'trial_{text_id:d}_{page_id:d}.csv'
  • filename_format_schema_overrides:
    dict (1 items)
    • gaze:
      dict (2 items)
      • text_id:
        <class 'int'>
        <class 'int'>
      • page_id:
        <class 'int'>
        <class 'int'>
  • has_resources:
    True
    True
  • long_name:
    'pymovements Toy Dataset'
    'pymovements Toy Dataset'
  • mirrors:
    dict (0 items)
  • name:
    'ToyDataset'
    'ToyDataset'
  • pixel_columns:
    list (2 items)
    • 'x'
    • 'y'
  • position_columns:
    None
    None
  • resources:
    list (1 items)
    • ResourceDefinition
      • content:
        'gaze'
        'gaze'
      • filename:
        'pymovements-toy-dataset.zip'
        'pymovements-toy-dataset.zip'
      • filename_pattern:
        'trial_{text_id:d}_{page_id:d}.csv'
        'trial_{text_id:d}_{page_id:d}.csv'
      • filename_pattern_schema_overrides:
        dict (2 items)
        • text_id:
          <class 'int'>
          <class 'int'>
        • page_id:
          <class 'int'>
          <class 'int'>
      • md5:
        '4da622457637a8181d86601fe17f3aa8'
        '4da622457637a8181d86601fe17f3aa8'
      • url:
        str
        'http://github.com/aeye-lab/pymovements-toy-dataset/zipball/6cb5d663317bf418cec0c9abe1dde5085a8a8ebd/'
  • time_column:
    'timestamp'
    'timestamp'
  • time_unit:
    'ms'
    'ms'
  • trial_columns:
    None
    None
  • velocity_columns:
    None
    None
• events:
  list (20 items)
  • Events
    • frame:
      DataFrame (9 columns, 222 rows)
      shape: (222, 9)

      text_id	page_id	name	onset	offset	duration	peak_velocity	amplitude	dispersion
      i64	i64	str	i64	i64	i64	f64	f64	f64
      0	1	"fixation"	1988145	1988563	418	200.144558	2.492864	2.712569
      0	1	"fixation"	1988564	1988750	186	249.67823	2.651198	2.865026
      0	1	"fixation"	1988751	1989178	427	211.598748	2.585906	2.779518
      0	1	"fixation"	1989179	1989436	257	189.183243	2.614347	2.77424
      0	1	"fixation"	1989437	1989600	163	255.077509	2.594651	2.729391
      …	…	…	…	…	…	…	…	…
      0	1	"saccade"	2004373	2004385	12	70.374183	0.7073	0.766684
      0	1	"saccade"	2004688	2004704	16	175.646379	1.807485	1.875716
      0	1	"saccade"	2004879	2004901	22	209.46361	2.933818	3.086169
      0	1	"saccade"	2005110	2005126	16	137.917594	1.405354	1.501217
      0	1	"saccade"	2005288	2005345	57	352.550667	14.682541	16.101153

    • trial_columns:
      list (2 items)
      • 'text_id'
      • 'page_id'
  • Events
    • frame:
      DataFrame (9 columns, 366 rows)
      shape: (366, 9)

      text_id	page_id	name	onset	offset	duration	peak_velocity	amplitude	dispersion
      i64	i64	str	i64	i64	i64	f64	f64	f64
      0	2	"fixation"	2008305	2008621	316	167.343877	2.283024	2.706135
      0	2	"fixation"	2008622	2008821	199	314.396904	2.578854	2.79657
      0	2	"fixation"	2008822	2009214	392	305.525917	2.612895	2.908934
      0	2	"fixation"	2009215	2009433	218	216.195201	2.612208	2.765062
      0	2	"fixation"	2009434	2009704	270	208.05132	2.566305	2.70311
      …	…	…	…	…	…	…	…	…
      0	2	"saccade"	2036849	2036861	12	54.743137	0.472141	0.529715
      0	2	"saccade"	2037161	2037188	27	223.056103	2.358604	2.587752
      0	2	"saccade"	2037412	2037503	91	406.701444	16.94863	18.346458
      0	2	"saccade"	2037638	2037654	16	138.382767	1.411621	1.827761
      0	2	"saccade"	2037812	2037830	18	240.193236	2.739312	3.024326

    • trial_columns:
      list (2 items)
      • 'text_id'
      • 'page_id'
  • (18 more)
• fileinfo:
  dict (1 items)
  • gaze:
    DataFrame (3 columns, 20 rows)
    shape: (20, 3)

    text_id	page_id	filepath
    i64	i64	str
    0	1	"aeye-lab-pymovements-toy-datas…
    0	2	"aeye-lab-pymovements-toy-datas…
    0	3	"aeye-lab-pymovements-toy-datas…
    0	4	"aeye-lab-pymovements-toy-datas…
    0	5	"aeye-lab-pymovements-toy-datas…
    …	…	…
    3	1	"aeye-lab-pymovements-toy-datas…
    3	2	"aeye-lab-pymovements-toy-datas…
    3	3	"aeye-lab-pymovements-toy-datas…
    3	4	"aeye-lab-pymovements-toy-datas…
    3	5	"aeye-lab-pymovements-toy-datas…

• gaze:
  list (20 items)
  • Gaze
    • samples:
      DataFrame (8 columns, 17223 rows)
      shape: (17_223, 8)

      time	stimuli_x	stimuli_y	text_id	page_id	pixel	position	velocity
      i64	f64	f64	i64	i64	list[f64]	list[f64]	list[f64]
      1988145	-1.0	-1.0	0	1	[206.8, 152.4]	[-10.697598, -8.852399]	[null, null]
      1988146	-1.0	-1.0	0	1	[206.9, 152.1]	[-10.695183, -8.859678]	[null, null]
      1988147	-1.0	-1.0	0	1	[207.0, 151.8]	[-10.692768, -8.866956]	[1.610194, -5.256267]
      1988148	-1.0	-1.0	0	1	[207.1, 151.7]	[-10.690352, -8.869381]	[0.402548, -4.447465]
      1988149	-1.0	-1.0	0	1	[207.0, 151.5]	[-10.692768, -8.874233]	[0.402561, -3.234462]
      …	…	…	…	…	…	…	…
      2005363	-1.0	-1.0	0	1	[361.0, 415.4]	[-6.932438, -2.386672]	[-63.266374, -21.085616]
      2005364	-1.0	-1.0	0	1	[358.0, 414.5]	[-7.006376, -2.408998]	[-63.249652, -19.431326]
      2005365	-1.0	-1.0	0	1	[355.8, 413.8]	[-7.060582, -2.426362]	[-60.359624, -15.710061]
      2005366	-1.0	-1.0	0	1	[353.1, 413.2]	[-7.12709, -2.441245]	[null, null]
      2005367	-1.0	-1.0	0	1	[351.2, 412.9]	[-7.173881, -2.448686]	[null, null]

    • events:
      Events
      Events

      • frame:
        DataFrame (9 columns, 222 rows)
        shape: (222, 9)

        text_id	page_id	name	onset	offset	duration	peak_velocity	amplitude	dispersion
        i64	i64	str	i64	i64	i64	f64	f64	f64
        0	1	"fixation"	1988145	1988563	418	200.144558	2.492864	2.712569
        0	1	"fixation"	1988564	1988750	186	249.67823	2.651198	2.865026
        0	1	"fixation"	1988751	1989178	427	211.598748	2.585906	2.779518
        0	1	"fixation"	1989179	1989436	257	189.183243	2.614347	2.77424
        0	1	"fixation"	1989437	1989600	163	255.077509	2.594651	2.729391
        …	…	…	…	…	…	…	…	…
        0	1	"saccade"	2004373	2004385	12	70.374183	0.7073	0.766684
        0	1	"saccade"	2004688	2004704	16	175.646379	1.807485	1.875716
        0	1	"saccade"	2004879	2004901	22	209.46361	2.933818	3.086169
        0	1	"saccade"	2005110	2005126	16	137.917594	1.405354	1.501217
        0	1	"saccade"	2005288	2005345	57	352.550667	14.682541	16.101153

      • trial_columns:
        list (2 items)
        • 'text_id'
        • 'page_id'
    • trial_columns:
      list (2 items)
      • 'text_id'
      • 'page_id'
    • experiment:
      Experiment
      Experiment

      • eyetracker:
        EyeTracker
        EyeTracker

        • left:
          None
          None
        • model:
          None
          None
        • mount:
          None
          None
        • right:
          None
          None
        • sampling_rate:
          1000
          1000
        • vendor:
          None
          None
        • version:
          None
          None
      • sampling_rate:
        1000
        1000
      • screen:
        Screen
        Screen

        • distance_cm:
          68
          68
        • height_cm:
          30.2
          30.2
        • height_px:
          1024
          1024
        • origin:
          'upper left'
          'upper left'
        • width_cm:
          38
          38
        • width_px:
          1280
          1280
        • x_max_dva:
          15.599386487782953
          15.599386487782953
        • x_min_dva:
          -15.599386487782953
          -15.599386487782953
        • y_max_dva:
          12.508044410882546
          12.508044410882546
        • y_min_dva:
          -12.508044410882546
          -12.508044410882546
  • Gaze
    • samples:
      DataFrame (8 columns, 29799 rows)
      shape: (29_799, 8)

      time	stimuli_x	stimuli_y	text_id	page_id	pixel	position	velocity
      i64	f64	f64	i64	i64	list[f64]	list[f64]	list[f64]
      2008305	-1.0	-1.0	0	2	[141.4, 153.6]	[-12.268583, -8.823284]	[null, null]
      2008306	-1.0	-1.0	0	2	[141.1, 153.2]	[-12.275749, -8.832989]	[null, null]
      2008307	-1.0	-1.0	0	2	[140.7, 152.8]	[-12.285302, -8.842695]	[-5.572617, -6.065816]
      2008308	-1.0	-1.0	0	2	[140.6, 152.7]	[-12.28769, -8.845121]	[-3.582268, -4.043733]
      2008309	-1.0	-1.0	0	2	[140.5, 152.6]	[-12.290078, -8.847547]	[-2.388085, -2.021821]
      …	…	…	…	…	…	…	…
      2038099	-1.0	-1.0	0	2	[273.8, 773.8]	[-9.071149, 6.490168]	[1.21962, 1.635403]
      2038100	-1.0	-1.0	0	2	[273.8, 774.1]	[-9.071149, 6.497527]	[1.626175, 4.497406]
      2038101	-1.0	-1.0	0	2	[273.9, 774.5]	[-9.06871, 6.50734]	[1.626186, 1.635423]
      2038102	-1.0	-1.0	0	2	[274.0, 774.4]	[-9.066271, 6.504886]	[null, null]
      2038103	-1.0	-1.0	0	2	[274.0, 773.9]	[-9.066271, 6.492621]	[null, null]

    • events:
      Events
      Events

      • frame:
        DataFrame (9 columns, 366 rows)
        shape: (366, 9)

        text_id	page_id	name	onset	offset	duration	peak_velocity	amplitude	dispersion
        i64	i64	str	i64	i64	i64	f64	f64	f64
        0	2	"fixation"	2008305	2008621	316	167.343877	2.283024	2.706135
        0	2	"fixation"	2008622	2008821	199	314.396904	2.578854	2.79657
        0	2	"fixation"	2008822	2009214	392	305.525917	2.612895	2.908934
        0	2	"fixation"	2009215	2009433	218	216.195201	2.612208	2.765062
        0	2	"fixation"	2009434	2009704	270	208.05132	2.566305	2.70311
        …	…	…	…	…	…	…	…	…
        0	2	"saccade"	2036849	2036861	12	54.743137	0.472141	0.529715
        0	2	"saccade"	2037161	2037188	27	223.056103	2.358604	2.587752
        0	2	"saccade"	2037412	2037503	91	406.701444	16.94863	18.346458
        0	2	"saccade"	2037638	2037654	16	138.382767	1.411621	1.827761
        0	2	"saccade"	2037812	2037830	18	240.193236	2.739312	3.024326

      • trial_columns:
        list (2 items)
        • 'text_id'
        • 'page_id'
    • trial_columns:
      list (2 items)
      • 'text_id'
      • 'page_id'
    • experiment:
      Experiment
      Experiment

      • eyetracker:
        EyeTracker
        EyeTracker

        • left:
          None
          None
        • model:
          None
          None
        • mount:
          None
          None
        • right:
          None
          None
        • sampling_rate:
          1000
          1000
        • vendor:
          None
          None
        • version:
          None
          None
      • sampling_rate:
        1000
        1000
      • screen:
        Screen
        Screen

        • distance_cm:
          68
          68
        • height_cm:
          30.2
          30.2
        • height_px:
          1024
          1024
        • origin:
          'upper left'
          'upper left'
        • width_cm:
          38
          38
        • width_px:
          1280
          1280
        • x_max_dva:
          15.599386487782953
          15.599386487782953
        • x_min_dva:
          -15.599386487782953
          -15.599386487782953
        • y_max_dva:
          12.508044410882546
          12.508044410882546
        • y_min_dva:
          -12.508044410882546
          -12.508044410882546
  • (18 more)
• path:
  PosixPath('data/ToyDataset')
  PosixPath('data/ToyDataset')
• paths:
  DatasetPaths
  DatasetPaths

  • dataset:
    PosixPath('data/ToyDataset')
    PosixPath('data/ToyDataset')
  • downloads:
    PosixPath('data/ToyDataset/downloads')
    PosixPath('data/ToyDataset/downloads')
  • events:
    PosixPath('data/ToyDataset/events')
    PosixPath('data/ToyDataset/events')
  • precomputed_events:
    PosixPath('data/ToyDataset/precomputed_events')
    PosixPath('data/ToyDataset/precomputed_events')
  • precomputed_reading_measures:
    PosixPath
    PosixPath('data/ToyDataset/precomputed_reading_measures')
  • preprocessed:
    PosixPath('data/ToyDataset/preprocessed')
    PosixPath('data/ToyDataset/preprocessed')
  • raw:
    PosixPath('data/ToyDataset/raw')
    PosixPath('data/ToyDataset/raw')
  • root:
    PosixPath('data/ToyDataset')
    PosixPath('data/ToyDataset')
• precomputed_events:
  list (0 items)
• precomputed_reading_measures:
  list (0 items)

All of 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/aeye-lab-pymovements-toy-dataset-6cb5d66/data/trial_0_1.feather'), PosixPath('data/ToyDataset/events/aeye-lab-pymovements-toy-dataset-6cb5d66/data/trial_1_2.feather'), PosixPath('data/ToyDataset/events/aeye-lab-pymovements-toy-dataset-6cb5d66/data/trial_0_2.feather'), PosixPath('data/ToyDataset/events/aeye-lab-pymovements-toy-dataset-6cb5d66/data/trial_3_5.feather'), PosixPath('data/ToyDataset/events/aeye-lab-pymovements-toy-dataset-6cb5d66/data/trial_1_4.feather'), PosixPath('data/ToyDataset/events/aeye-lab-pymovements-toy-dataset-6cb5d66/data/trial_0_4.feather'), PosixPath('data/ToyDataset/events/aeye-lab-pymovements-toy-dataset-6cb5d66/data/trial_3_4.feather'), PosixPath('data/ToyDataset/events/aeye-lab-pymovements-toy-dataset-6cb5d66/data/trial_2_3.feather'), PosixPath('data/ToyDataset/events/aeye-lab-pymovements-toy-dataset-6cb5d66/data/trial_2_2.feather'), PosixPath('data/ToyDataset/events/aeye-lab-pymovements-toy-dataset-6cb5d66/data/trial_3_1.feather'), PosixPath('data/ToyDataset/events/aeye-lab-pymovements-toy-dataset-6cb5d66/data/trial_1_5.feather'), PosixPath('data/ToyDataset/events/aeye-lab-pymovements-toy-dataset-6cb5d66/data/trial_3_3.feather'), PosixPath('data/ToyDataset/events/aeye-lab-pymovements-toy-dataset-6cb5d66/data/trial_2_4.feather'), PosixPath('data/ToyDataset/events/aeye-lab-pymovements-toy-dataset-6cb5d66/data/trial_3_2.feather'), PosixPath('data/ToyDataset/events/aeye-lab-pymovements-toy-dataset-6cb5d66/data/trial_2_5.feather'), PosixPath('data/ToyDataset/events/aeye-lab-pymovements-toy-dataset-6cb5d66/data/trial_1_3.feather'), PosixPath('data/ToyDataset/events/aeye-lab-pymovements-toy-dataset-6cb5d66/data/trial_0_3.feather'), PosixPath('data/ToyDataset/events/aeye-lab-pymovements-toy-dataset-6cb5d66/data/trial_1_1.feather'), PosixPath('data/ToyDataset/events/aeye-lab-pymovements-toy-dataset-6cb5d66/data/trial_0_5.feather'), PosixPath('data/ToyDataset/events/aeye-lab-pymovements-toy-dataset-6cb5d66/data/trial_2_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

• definition:
  DatasetDefinition
  DatasetDefinition

  • acceleration_columns:
    None
    None
  • column_map:
    dict (0 items)
  • custom_read_kwargs:
    dict (1 items)
    • gaze:
      dict (4 items)
      • columns:
        list (5 items)
        • 'timestamp'
        • 'x'
        • (3 more)
      • schema_overrides:
        dict (5 items)
        • timestamp:
          Float64
          Float64
        • x:
          Float64
          Float64
        • (3 more)
      • (2 more)
  • distance_column:
    None
    None
  • experiment:
    Experiment
    Experiment

    • eyetracker:
      EyeTracker
      EyeTracker

      • left:
        None
        None
      • model:
        None
        None
      • mount:
        None
        None
      • right:
        None
        None
      • sampling_rate:
        1000
        1000
      • vendor:
        None
        None
      • version:
        None
        None
    • sampling_rate:
      1000
      1000
    • screen:
      Screen
      Screen

      • distance_cm:
        68
        68
      • height_cm:
        30.2
        30.2
      • height_px:
        1024
        1024
      • origin:
        'upper left'
        'upper left'
      • width_cm:
        38
        38
      • width_px:
        1280
        1280
      • x_max_dva:
        15.599386487782953
        15.599386487782953
      • x_min_dva:
        -15.599386487782953
        -15.599386487782953
      • y_max_dva:
        12.508044410882546
        12.508044410882546
      • y_min_dva:
        -12.508044410882546
        -12.508044410882546
  • extract:
    None
    None
  • filename_format:
    dict (1 items)
    • gaze:
      'trial_{text_id:d}_{page_id:d}.csv'
      'trial_{text_id:d}_{page_id:d}.csv'
  • filename_format_schema_overrides:
    dict (1 items)
    • gaze:
      dict (2 items)
      • text_id:
        <class 'int'>
        <class 'int'>
      • page_id:
        <class 'int'>
        <class 'int'>
  • has_resources:
    True
    True
  • long_name:
    'pymovements Toy Dataset'
    'pymovements Toy Dataset'
  • mirrors:
    dict (0 items)
  • name:
    'ToyDataset'
    'ToyDataset'
  • pixel_columns:
    list (2 items)
    • 'x'
    • 'y'
  • position_columns:
    None
    None
  • resources:
    list (1 items)
    • ResourceDefinition
      • content:
        'gaze'
        'gaze'
      • filename:
        'pymovements-toy-dataset.zip'
        'pymovements-toy-dataset.zip'
      • filename_pattern:
        'trial_{text_id:d}_{page_id:d}.csv'
        'trial_{text_id:d}_{page_id:d}.csv'
      • filename_pattern_schema_overrides:
        dict (2 items)
        • text_id:
          <class 'int'>
          <class 'int'>
        • page_id:
          <class 'int'>
          <class 'int'>
      • md5:
        '4da622457637a8181d86601fe17f3aa8'
        '4da622457637a8181d86601fe17f3aa8'
      • url:
        str
        'http://github.com/aeye-lab/pymovements-toy-dataset/zipball/6cb5d663317bf418cec0c9abe1dde5085a8a8ebd/'
  • time_column:
    'timestamp'
    'timestamp'
  • time_unit:
    'ms'
    'ms'
  • trial_columns:
    None
    None
  • velocity_columns:
    None
    None
• events:
  list (20 items)
  • Events
    • frame:
      DataFrame (9 columns, 222 rows)
      shape: (222, 9)

      text_id	page_id	name	onset	offset	duration	peak_velocity	amplitude	dispersion
      i64	i64	str	i64	i64	i64	f64	f64	f64
      0	1	"fixation"	1988145	1988563	418	200.144558	2.492864	2.712569
      0	1	"fixation"	1988564	1988750	186	249.67823	2.651198	2.865026
      0	1	"fixation"	1988751	1989178	427	211.598748	2.585906	2.779518
      0	1	"fixation"	1989179	1989436	257	189.183243	2.614347	2.77424
      0	1	"fixation"	1989437	1989600	163	255.077509	2.594651	2.729391
      …	…	…	…	…	…	…	…	…
      0	1	"saccade"	2004373	2004385	12	70.374183	0.7073	0.766684
      0	1	"saccade"	2004688	2004704	16	175.646379	1.807485	1.875716
      0	1	"saccade"	2004879	2004901	22	209.46361	2.933818	3.086169
      0	1	"saccade"	2005110	2005126	16	137.917594	1.405354	1.501217
      0	1	"saccade"	2005288	2005345	57	352.550667	14.682541	16.101153

    • trial_columns:
      list (2 items)
      • 'text_id'
      • 'page_id'
  • Events
    • frame:
      DataFrame (9 columns, 366 rows)
      shape: (366, 9)

      text_id	page_id	name	onset	offset	duration	peak_velocity	amplitude	dispersion
      i64	i64	str	i64	i64	i64	f64	f64	f64
      0	2	"fixation"	2008305	2008621	316	167.343877	2.283024	2.706135
      0	2	"fixation"	2008622	2008821	199	314.396904	2.578854	2.79657
      0	2	"fixation"	2008822	2009214	392	305.525917	2.612895	2.908934
      0	2	"fixation"	2009215	2009433	218	216.195201	2.612208	2.765062
      0	2	"fixation"	2009434	2009704	270	208.05132	2.566305	2.70311
      …	…	…	…	…	…	…	…	…
      0	2	"saccade"	2036849	2036861	12	54.743137	0.472141	0.529715
      0	2	"saccade"	2037161	2037188	27	223.056103	2.358604	2.587752
      0	2	"saccade"	2037412	2037503	91	406.701444	16.94863	18.346458
      0	2	"saccade"	2037638	2037654	16	138.382767	1.411621	1.827761
      0	2	"saccade"	2037812	2037830	18	240.193236	2.739312	3.024326

    • trial_columns:
      list (2 items)
      • 'text_id'
      • 'page_id'
  • (18 more)
• fileinfo:
  dict (1 items)
  • gaze:
    DataFrame (3 columns, 20 rows)
    shape: (20, 3)

    text_id	page_id	filepath
    i64	i64	str
    0	1	"aeye-lab-pymovements-toy-datas…
    0	2	"aeye-lab-pymovements-toy-datas…
    0	3	"aeye-lab-pymovements-toy-datas…
    0	4	"aeye-lab-pymovements-toy-datas…
    0	5	"aeye-lab-pymovements-toy-datas…
    …	…	…
    3	1	"aeye-lab-pymovements-toy-datas…
    3	2	"aeye-lab-pymovements-toy-datas…
    3	3	"aeye-lab-pymovements-toy-datas…
    3	4	"aeye-lab-pymovements-toy-datas…
    3	5	"aeye-lab-pymovements-toy-datas…

• gaze:
  list (20 items)
  • Gaze
    • samples:
      DataFrame (8 columns, 17223 rows)
      shape: (17_223, 8)

      time	stimuli_x	stimuli_y	text_id	page_id	pixel	position	velocity
      i64	f64	f64	i64	i64	list[f64]	list[f64]	list[f64]
      1988145	-1.0	-1.0	0	1	[206.8, 152.4]	[-10.697598, -8.852399]	[null, null]
      1988146	-1.0	-1.0	0	1	[206.9, 152.1]	[-10.695183, -8.859678]	[null, null]
      1988147	-1.0	-1.0	0	1	[207.0, 151.8]	[-10.692768, -8.866956]	[1.610194, -5.256267]
      1988148	-1.0	-1.0	0	1	[207.1, 151.7]	[-10.690352, -8.869381]	[0.402548, -4.447465]
      1988149	-1.0	-1.0	0	1	[207.0, 151.5]	[-10.692768, -8.874233]	[0.402561, -3.234462]
      …	…	…	…	…	…	…	…
      2005363	-1.0	-1.0	0	1	[361.0, 415.4]	[-6.932438, -2.386672]	[-63.266374, -21.085616]
      2005364	-1.0	-1.0	0	1	[358.0, 414.5]	[-7.006376, -2.408998]	[-63.249652, -19.431326]
      2005365	-1.0	-1.0	0	1	[355.8, 413.8]	[-7.060582, -2.426362]	[-60.359624, -15.710061]
      2005366	-1.0	-1.0	0	1	[353.1, 413.2]	[-7.12709, -2.441245]	[null, null]
      2005367	-1.0	-1.0	0	1	[351.2, 412.9]	[-7.173881, -2.448686]	[null, null]

    • events:
      Events
      Events

      • frame:
        DataFrame (9 columns, 222 rows)
        shape: (222, 9)

        text_id	page_id	name	onset	offset	duration	peak_velocity	amplitude	dispersion
        i64	i64	str	i64	i64	i64	f64	f64	f64
        0	1	"fixation"	1988145	1988563	418	200.144558	2.492864	2.712569
        0	1	"fixation"	1988564	1988750	186	249.67823	2.651198	2.865026
        0	1	"fixation"	1988751	1989178	427	211.598748	2.585906	2.779518
        0	1	"fixation"	1989179	1989436	257	189.183243	2.614347	2.77424
        0	1	"fixation"	1989437	1989600	163	255.077509	2.594651	2.729391
        …	…	…	…	…	…	…	…	…
        0	1	"saccade"	2004373	2004385	12	70.374183	0.7073	0.766684
        0	1	"saccade"	2004688	2004704	16	175.646379	1.807485	1.875716
        0	1	"saccade"	2004879	2004901	22	209.46361	2.933818	3.086169
        0	1	"saccade"	2005110	2005126	16	137.917594	1.405354	1.501217
        0	1	"saccade"	2005288	2005345	57	352.550667	14.682541	16.101153

      • trial_columns:
        list (2 items)
        • 'text_id'
        • 'page_id'
    • trial_columns:
      list (2 items)
      • 'text_id'
      • 'page_id'
    • experiment:
      Experiment
      Experiment

      • eyetracker:
        EyeTracker
        EyeTracker

        • left:
          None
          None
        • model:
          None
          None
        • mount:
          None
          None
        • right:
          None
          None
        • sampling_rate:
          1000
          1000
        • vendor:
          None
          None
        • version:
          None
          None
      • sampling_rate:
        1000
        1000
      • screen:
        Screen
        Screen

        • distance_cm:
          68
          68
        • height_cm:
          30.2
          30.2
        • height_px:
          1024
          1024
        • origin:
          'upper left'
          'upper left'
        • width_cm:
          38
          38
        • width_px:
          1280
          1280
        • x_max_dva:
          15.599386487782953
          15.599386487782953
        • x_min_dva:
          -15.599386487782953
          -15.599386487782953
        • y_max_dva:
          12.508044410882546
          12.508044410882546
        • y_min_dva:
          -12.508044410882546
          -12.508044410882546
  • Gaze
    • samples:
      DataFrame (8 columns, 29799 rows)
      shape: (29_799, 8)

      time	stimuli_x	stimuli_y	text_id	page_id	pixel	position	velocity
      i64	f64	f64	i64	i64	list[f64]	list[f64]	list[f64]
      2008305	-1.0	-1.0	0	2	[141.4, 153.6]	[-12.268583, -8.823284]	[null, null]
      2008306	-1.0	-1.0	0	2	[141.1, 153.2]	[-12.275749, -8.832989]	[null, null]
      2008307	-1.0	-1.0	0	2	[140.7, 152.8]	[-12.285302, -8.842695]	[-5.572617, -6.065816]
      2008308	-1.0	-1.0	0	2	[140.6, 152.7]	[-12.28769, -8.845121]	[-3.582268, -4.043733]
      2008309	-1.0	-1.0	0	2	[140.5, 152.6]	[-12.290078, -8.847547]	[-2.388085, -2.021821]
      …	…	…	…	…	…	…	…
      2038099	-1.0	-1.0	0	2	[273.8, 773.8]	[-9.071149, 6.490168]	[1.21962, 1.635403]
      2038100	-1.0	-1.0	0	2	[273.8, 774.1]	[-9.071149, 6.497527]	[1.626175, 4.497406]
      2038101	-1.0	-1.0	0	2	[273.9, 774.5]	[-9.06871, 6.50734]	[1.626186, 1.635423]
      2038102	-1.0	-1.0	0	2	[274.0, 774.4]	[-9.066271, 6.504886]	[null, null]
      2038103	-1.0	-1.0	0	2	[274.0, 773.9]	[-9.066271, 6.492621]	[null, null]

    • events:
      Events
      Events

      • frame:
        DataFrame (9 columns, 366 rows)
        shape: (366, 9)

        text_id	page_id	name	onset	offset	duration	peak_velocity	amplitude	dispersion
        i64	i64	str	i64	i64	i64	f64	f64	f64
        0	2	"fixation"	2008305	2008621	316	167.343877	2.283024	2.706135
        0	2	"fixation"	2008622	2008821	199	314.396904	2.578854	2.79657
        0	2	"fixation"	2008822	2009214	392	305.525917	2.612895	2.908934
        0	2	"fixation"	2009215	2009433	218	216.195201	2.612208	2.765062
        0	2	"fixation"	2009434	2009704	270	208.05132	2.566305	2.70311
        …	…	…	…	…	…	…	…	…
        0	2	"saccade"	2036849	2036861	12	54.743137	0.472141	0.529715
        0	2	"saccade"	2037161	2037188	27	223.056103	2.358604	2.587752
        0	2	"saccade"	2037412	2037503	91	406.701444	16.94863	18.346458
        0	2	"saccade"	2037638	2037654	16	138.382767	1.411621	1.827761
        0	2	"saccade"	2037812	2037830	18	240.193236	2.739312	3.024326

      • trial_columns:
        list (2 items)
        • 'text_id'
        • 'page_id'
    • trial_columns:
      list (2 items)
      • 'text_id'
      • 'page_id'
    • experiment:
      Experiment
      Experiment

      • eyetracker:
        EyeTracker
        EyeTracker

        • left:
          None
          None
        • model:
          None
          None
        • mount:
          None
          None
        • right:
          None
          None
        • sampling_rate:
          1000
          1000
        • vendor:
          None
          None
        • version:
          None
          None
      • sampling_rate:
        1000
        1000
      • screen:
        Screen
        Screen

        • distance_cm:
          68
          68
        • height_cm:
          30.2
          30.2
        • height_px:
          1024
          1024
        • origin:
          'upper left'
          'upper left'
        • width_cm:
          38
          38
        • width_px:
          1280
          1280
        • x_max_dva:
          15.599386487782953
          15.599386487782953
        • x_min_dva:
          -15.599386487782953
          -15.599386487782953
        • y_max_dva:
          12.508044410882546
          12.508044410882546
        • y_min_dva:
          -12.508044410882546
          -12.508044410882546
  • (18 more)
• path:
  PosixPath('data/ToyDataset')
  PosixPath('data/ToyDataset')
• paths:
  DatasetPaths
  DatasetPaths

  • dataset:
    PosixPath('data/ToyDataset')
    PosixPath('data/ToyDataset')
  • downloads:
    PosixPath('data/ToyDataset/downloads')
    PosixPath('data/ToyDataset/downloads')
  • events:
    PosixPath('data/ToyDataset/events')
    PosixPath('data/ToyDataset/events')
  • precomputed_events:
    PosixPath('data/ToyDataset/precomputed_events')
    PosixPath('data/ToyDataset/precomputed_events')
  • precomputed_reading_measures:
    PosixPath
    PosixPath('data/ToyDataset/precomputed_reading_measures')
  • preprocessed:
    PosixPath('data/ToyDataset/preprocessed')
    PosixPath('data/ToyDataset/preprocessed')
  • raw:
    PosixPath('data/ToyDataset/raw')
    PosixPath('data/ToyDataset/raw')
  • root:
    PosixPath('data/ToyDataset')
    PosixPath('data/ToyDataset')
• precomputed_events:
  list (0 items)
• precomputed_reading_measures:
  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/aeye-lab-pymovements-toy-dataset-6cb5d66/data/trial_2_2.csv'), PosixPath('data/ToyDataset/events_csv/aeye-lab-pymovements-toy-dataset-6cb5d66/data/trial_2_5.csv'), PosixPath('data/ToyDataset/events_csv/aeye-lab-pymovements-toy-dataset-6cb5d66/data/trial_3_1.csv'), PosixPath('data/ToyDataset/events_csv/aeye-lab-pymovements-toy-dataset-6cb5d66/data/trial_2_1.csv'), PosixPath('data/ToyDataset/events_csv/aeye-lab-pymovements-toy-dataset-6cb5d66/data/trial_1_1.csv'), PosixPath('data/ToyDataset/events_csv/aeye-lab-pymovements-toy-dataset-6cb5d66/data/trial_3_3.csv'), PosixPath('data/ToyDataset/events_csv/aeye-lab-pymovements-toy-dataset-6cb5d66/data/trial_3_2.csv'), PosixPath('data/ToyDataset/events_csv/aeye-lab-pymovements-toy-dataset-6cb5d66/data/trial_3_4.csv'), PosixPath('data/ToyDataset/events_csv/aeye-lab-pymovements-toy-dataset-6cb5d66/data/trial_1_3.csv'), PosixPath('data/ToyDataset/events_csv/aeye-lab-pymovements-toy-dataset-6cb5d66/data/trial_2_3.csv'), PosixPath('data/ToyDataset/events_csv/aeye-lab-pymovements-toy-dataset-6cb5d66/data/trial_0_5.csv'), PosixPath('data/ToyDataset/events_csv/aeye-lab-pymovements-toy-dataset-6cb5d66/data/trial_0_2.csv'), PosixPath('data/ToyDataset/events_csv/aeye-lab-pymovements-toy-dataset-6cb5d66/data/trial_1_4.csv'), PosixPath('data/ToyDataset/events_csv/aeye-lab-pymovements-toy-dataset-6cb5d66/data/trial_2_4.csv'), PosixPath('data/ToyDataset/events_csv/aeye-lab-pymovements-toy-dataset-6cb5d66/data/trial_0_3.csv'), PosixPath('data/ToyDataset/events_csv/aeye-lab-pymovements-toy-dataset-6cb5d66/data/trial_1_5.csv'), PosixPath('data/ToyDataset/events_csv/aeye-lab-pymovements-toy-dataset-6cb5d66/data/trial_1_2.csv'), PosixPath('data/ToyDataset/events_csv/aeye-lab-pymovements-toy-dataset-6cb5d66/data/trial_0_4.csv'), PosixPath('data/ToyDataset/events_csv/aeye-lab-pymovements-toy-dataset-6cb5d66/data/trial_0_1.csv'), PosixPath('data/ToyDataset/events_csv/aeye-lab-pymovements-toy-dataset-6cb5d66/data/trial_3_5.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

• definition:
  DatasetDefinition
  DatasetDefinition

  • acceleration_columns:
    None
    None
  • column_map:
    dict (0 items)
  • custom_read_kwargs:
    dict (1 items)
    • gaze:
      dict (4 items)
      • columns:
        list (5 items)
        • 'timestamp'
        • 'x'
        • (3 more)
      • schema_overrides:
        dict (5 items)
        • timestamp:
          Float64
          Float64
        • x:
          Float64
          Float64
        • (3 more)
      • (2 more)
  • distance_column:
    None
    None
  • experiment:
    Experiment
    Experiment

    • eyetracker:
      EyeTracker
      EyeTracker

      • left:
        None
        None
      • model:
        None
        None
      • mount:
        None
        None
      • right:
        None
        None
      • sampling_rate:
        1000
        1000
      • vendor:
        None
        None
      • version:
        None
        None
    • sampling_rate:
      1000
      1000
    • screen:
      Screen
      Screen

      • distance_cm:
        68
        68
      • height_cm:
        30.2
        30.2
      • height_px:
        1024
        1024
      • origin:
        'upper left'
        'upper left'
      • width_cm:
        38
        38
      • width_px:
        1280
        1280
      • x_max_dva:
        15.599386487782953
        15.599386487782953
      • x_min_dva:
        -15.599386487782953
        -15.599386487782953
      • y_max_dva:
        12.508044410882546
        12.508044410882546
      • y_min_dva:
        -12.508044410882546
        -12.508044410882546
  • extract:
    None
    None
  • filename_format:
    dict (1 items)
    • gaze:
      'trial_{text_id:d}_{page_id:d}.csv'
      'trial_{text_id:d}_{page_id:d}.csv'
  • filename_format_schema_overrides:
    dict (1 items)
    • gaze:
      dict (2 items)
      • text_id:
        <class 'int'>
        <class 'int'>
      • page_id:
        <class 'int'>
        <class 'int'>
  • has_resources:
    True
    True
  • long_name:
    'pymovements Toy Dataset'
    'pymovements Toy Dataset'
  • mirrors:
    dict (0 items)
  • name:
    'ToyDataset'
    'ToyDataset'
  • pixel_columns:
    list (2 items)
    • 'x'
    • 'y'
  • position_columns:
    None
    None
  • resources:
    list (1 items)
    • ResourceDefinition
      • content:
        'gaze'
        'gaze'
      • filename:
        'pymovements-toy-dataset.zip'
        'pymovements-toy-dataset.zip'
      • filename_pattern:
        'trial_{text_id:d}_{page_id:d}.csv'
        'trial_{text_id:d}_{page_id:d}.csv'
      • filename_pattern_schema_overrides:
        dict (2 items)
        • text_id:
          <class 'int'>
          <class 'int'>
        • page_id:
          <class 'int'>
          <class 'int'>
      • md5:
        '4da622457637a8181d86601fe17f3aa8'
        '4da622457637a8181d86601fe17f3aa8'
      • url:
        str
        'http://github.com/aeye-lab/pymovements-toy-dataset/zipball/6cb5d663317bf418cec0c9abe1dde5085a8a8ebd/'
  • time_column:
    'timestamp'
    'timestamp'
  • time_unit:
    'ms'
    'ms'
  • trial_columns:
    None
    None
  • velocity_columns:
    None
    None
• events:
  list (0 items)
• fileinfo:
  dict (1 items)
  • gaze:
    DataFrame (3 columns, 20 rows)
    shape: (20, 3)

    text_id	page_id	filepath
    i64	i64	str
    0	1	"aeye-lab-pymovements-toy-datas…
    0	2	"aeye-lab-pymovements-toy-datas…
    0	3	"aeye-lab-pymovements-toy-datas…
    0	4	"aeye-lab-pymovements-toy-datas…
    0	5	"aeye-lab-pymovements-toy-datas…
    …	…	…
    3	1	"aeye-lab-pymovements-toy-datas…
    3	2	"aeye-lab-pymovements-toy-datas…
    3	3	"aeye-lab-pymovements-toy-datas…
    3	4	"aeye-lab-pymovements-toy-datas…
    3	5	"aeye-lab-pymovements-toy-datas…

• gaze:
  list (20 items)
  • Gaze
    • samples:
      DataFrame (6 columns, 17223 rows)
      shape: (17_223, 6)

      time	stimuli_x	stimuli_y	text_id	page_id	pixel
      i64	f64	f64	i64	i64	list[f64]
      1988145	-1.0	-1.0	0	1	[206.8, 152.4]
      1988146	-1.0	-1.0	0	1	[206.9, 152.1]
      1988147	-1.0	-1.0	0	1	[207.0, 151.8]
      1988148	-1.0	-1.0	0	1	[207.1, 151.7]
      1988149	-1.0	-1.0	0	1	[207.0, 151.5]
      …	…	…	…	…	…
      2005363	-1.0	-1.0	0	1	[361.0, 415.4]
      2005364	-1.0	-1.0	0	1	[358.0, 414.5]
      2005365	-1.0	-1.0	0	1	[355.8, 413.8]
      2005366	-1.0	-1.0	0	1	[353.1, 413.2]
      2005367	-1.0	-1.0	0	1	[351.2, 412.9]

    • events:
      Events
      Events

      • frame:
        DataFrame (6 columns, 0 rows)
        shape: (0, 6)

        text_id	page_id	name	onset	offset	duration
        i64	i64	str	i64	i64	i64

      • trial_columns:
        list (2 items)
        • 'text_id'
        • 'page_id'
    • trial_columns:
      list (2 items)
      • 'text_id'
      • 'page_id'
    • experiment:
      Experiment
      Experiment

      • eyetracker:
        EyeTracker
        EyeTracker

        • left:
          None
          None
        • model:
          None
          None
        • mount:
          None
          None
        • right:
          None
          None
        • sampling_rate:
          1000
          1000
        • vendor:
          None
          None
        • version:
          None
          None
      • sampling_rate:
        1000
        1000
      • screen:
        Screen
        Screen

        • distance_cm:
          68
          68
        • height_cm:
          30.2
          30.2
        • height_px:
          1024
          1024
        • origin:
          'upper left'
          'upper left'
        • width_cm:
          38
          38
        • width_px:
          1280
          1280
        • x_max_dva:
          15.599386487782953
          15.599386487782953
        • x_min_dva:
          -15.599386487782953
          -15.599386487782953
        • y_max_dva:
          12.508044410882546
          12.508044410882546
        • y_min_dva:
          -12.508044410882546
          -12.508044410882546
  • Gaze
    • samples:
      DataFrame (6 columns, 29799 rows)
      shape: (29_799, 6)

      time	stimuli_x	stimuli_y	text_id	page_id	pixel
      i64	f64	f64	i64	i64	list[f64]
      2008305	-1.0	-1.0	0	2	[141.4, 153.6]
      2008306	-1.0	-1.0	0	2	[141.1, 153.2]
      2008307	-1.0	-1.0	0	2	[140.7, 152.8]
      2008308	-1.0	-1.0	0	2	[140.6, 152.7]
      2008309	-1.0	-1.0	0	2	[140.5, 152.6]
      …	…	…	…	…	…
      2038099	-1.0	-1.0	0	2	[273.8, 773.8]
      2038100	-1.0	-1.0	0	2	[273.8, 774.1]
      2038101	-1.0	-1.0	0	2	[273.9, 774.5]
      2038102	-1.0	-1.0	0	2	[274.0, 774.4]
      2038103	-1.0	-1.0	0	2	[274.0, 773.9]

    • events:
      Events
      Events

      • frame:
        DataFrame (6 columns, 0 rows)
        shape: (0, 6)

        text_id	page_id	name	onset	offset	duration
        i64	i64	str	i64	i64	i64

      • trial_columns:
        list (2 items)
        • 'text_id'
        • 'page_id'
    • trial_columns:
      list (2 items)
      • 'text_id'
      • 'page_id'
    • experiment:
      Experiment
      Experiment

      • eyetracker:
        EyeTracker
        EyeTracker

        • left:
          None
          None
        • model:
          None
          None
        • mount:
          None
          None
        • right:
          None
          None
        • sampling_rate:
          1000
          1000
        • vendor:
          None
          None
        • version:
          None
          None
      • sampling_rate:
        1000
        1000
      • screen:
        Screen
        Screen

        • distance_cm:
          68
          68
        • height_cm:
          30.2
          30.2
        • height_px:
          1024
          1024
        • origin:
          'upper left'
          'upper left'
        • width_cm:
          38
          38
        • width_px:
          1280
          1280
        • x_max_dva:
          15.599386487782953
          15.599386487782953
        • x_min_dva:
          -15.599386487782953
          -15.599386487782953
        • y_max_dva:
          12.508044410882546
          12.508044410882546
        • y_min_dva:
          -12.508044410882546
          -12.508044410882546
  • (18 more)
• path:
  PosixPath('data/ToyDataset')
  PosixPath('data/ToyDataset')
• paths:
  DatasetPaths
  DatasetPaths

  • dataset:
    PosixPath('data/ToyDataset')
    PosixPath('data/ToyDataset')
  • downloads:
    PosixPath('data/ToyDataset/downloads')
    PosixPath('data/ToyDataset/downloads')
  • events:
    PosixPath('data/ToyDataset/events')
    PosixPath('data/ToyDataset/events')
  • precomputed_events:
    PosixPath('data/ToyDataset/precomputed_events')
    PosixPath('data/ToyDataset/precomputed_events')
  • precomputed_reading_measures:
    PosixPath
    PosixPath('data/ToyDataset/precomputed_reading_measures')
  • preprocessed:
    PosixPath('data/ToyDataset/preprocessed')
    PosixPath('data/ToyDataset/preprocessed')
  • raw:
    PosixPath('data/ToyDataset/raw')
    PosixPath('data/ToyDataset/raw')
  • root:
    PosixPath('data/ToyDataset')
    PosixPath('data/ToyDataset')
• precomputed_events:
  list (0 items)
• precomputed_reading_measures:
  list (0 items)

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

preprocessed_dataset.load(events=True)

Dataset

• definition:
  DatasetDefinition
  DatasetDefinition

  • acceleration_columns:
    None
    None
  • column_map:
    dict (0 items)
  • custom_read_kwargs:
    dict (1 items)
    • gaze:
      dict (4 items)
      • columns:
        list (5 items)
        • 'timestamp'
        • 'x'
        • (3 more)
      • schema_overrides:
        dict (5 items)
        • timestamp:
          Float64
          Float64
        • x:
          Float64
          Float64
        • (3 more)
      • (2 more)
  • distance_column:
    None
    None
  • experiment:
    Experiment
    Experiment

    • eyetracker:
      EyeTracker
      EyeTracker

      • left:
        None
        None
      • model:
        None
        None
      • mount:
        None
        None
      • right:
        None
        None
      • sampling_rate:
        1000
        1000
      • vendor:
        None
        None
      • version:
        None
        None
    • sampling_rate:
      1000
      1000
    • screen:
      Screen
      Screen

      • distance_cm:
        68
        68
      • height_cm:
        30.2
        30.2
      • height_px:
        1024
        1024
      • origin:
        'upper left'
        'upper left'
      • width_cm:
        38
        38
      • width_px:
        1280
        1280
      • x_max_dva:
        15.599386487782953
        15.599386487782953
      • x_min_dva:
        -15.599386487782953
        -15.599386487782953
      • y_max_dva:
        12.508044410882546
        12.508044410882546
      • y_min_dva:
        -12.508044410882546
        -12.508044410882546
  • extract:
    None
    None
  • filename_format:
    dict (1 items)
    • gaze:
      'trial_{text_id:d}_{page_id:d}.csv'
      'trial_{text_id:d}_{page_id:d}.csv'
  • filename_format_schema_overrides:
    dict (1 items)
    • gaze:
      dict (2 items)
      • text_id:
        <class 'int'>
        <class 'int'>
      • page_id:
        <class 'int'>
        <class 'int'>
  • has_resources:
    True
    True
  • long_name:
    'pymovements Toy Dataset'
    'pymovements Toy Dataset'
  • mirrors:
    dict (0 items)
  • name:
    'ToyDataset'
    'ToyDataset'
  • pixel_columns:
    list (2 items)
    • 'x'
    • 'y'
  • position_columns:
    None
    None
  • resources:
    list (1 items)
    • ResourceDefinition
      • content:
        'gaze'
        'gaze'
      • filename:
        'pymovements-toy-dataset.zip'
        'pymovements-toy-dataset.zip'
      • filename_pattern:
        'trial_{text_id:d}_{page_id:d}.csv'
        'trial_{text_id:d}_{page_id:d}.csv'
      • filename_pattern_schema_overrides:
        dict (2 items)
        • text_id:
          <class 'int'>
          <class 'int'>
        • page_id:
          <class 'int'>
          <class 'int'>
      • md5:
        '4da622457637a8181d86601fe17f3aa8'
        '4da622457637a8181d86601fe17f3aa8'
      • url:
        str
        'http://github.com/aeye-lab/pymovements-toy-dataset/zipball/6cb5d663317bf418cec0c9abe1dde5085a8a8ebd/'
  • time_column:
    'timestamp'
    'timestamp'
  • time_unit:
    'ms'
    'ms'
  • trial_columns:
    None
    None
  • velocity_columns:
    None
    None
• events:
  list (20 items)
  • Events
    • frame:
      DataFrame (9 columns, 222 rows)
      shape: (222, 9)

      text_id	page_id	name	onset	offset	duration	peak_velocity	amplitude	dispersion
      i64	i64	str	i64	i64	i64	f64	f64	f64
      0	1	"fixation"	1988145	1988563	418	200.144558	2.492864	2.712569
      0	1	"fixation"	1988564	1988750	186	249.67823	2.651198	2.865026
      0	1	"fixation"	1988751	1989178	427	211.598748	2.585906	2.779518
      0	1	"fixation"	1989179	1989436	257	189.183243	2.614347	2.77424
      0	1	"fixation"	1989437	1989600	163	255.077509	2.594651	2.729391
      …	…	…	…	…	…	…	…	…
      0	1	"saccade"	2004373	2004385	12	70.374183	0.7073	0.766684
      0	1	"saccade"	2004688	2004704	16	175.646379	1.807485	1.875716
      0	1	"saccade"	2004879	2004901	22	209.46361	2.933818	3.086169
      0	1	"saccade"	2005110	2005126	16	137.917594	1.405354	1.501217
      0	1	"saccade"	2005288	2005345	57	352.550667	14.682541	16.101153

    • trial_columns:
      None
      None
  • Events
    • frame:
      DataFrame (9 columns, 366 rows)
      shape: (366, 9)

      text_id	page_id	name	onset	offset	duration	peak_velocity	amplitude	dispersion
      i64	i64	str	i64	i64	i64	f64	f64	f64
      0	2	"fixation"	2008305	2008621	316	167.343877	2.283024	2.706135
      0	2	"fixation"	2008622	2008821	199	314.396904	2.578854	2.79657
      0	2	"fixation"	2008822	2009214	392	305.525917	2.612895	2.908934
      0	2	"fixation"	2009215	2009433	218	216.195201	2.612208	2.765062
      0	2	"fixation"	2009434	2009704	270	208.05132	2.566305	2.70311
      …	…	…	…	…	…	…	…	…
      0	2	"saccade"	2036849	2036861	12	54.743137	0.472141	0.529715
      0	2	"saccade"	2037161	2037188	27	223.056103	2.358604	2.587752
      0	2	"saccade"	2037412	2037503	91	406.701444	16.94863	18.346458
      0	2	"saccade"	2037638	2037654	16	138.382767	1.411621	1.827761
      0	2	"saccade"	2037812	2037830	18	240.193236	2.739312	3.024326

    • trial_columns:
      None
      None
  • (18 more)
• fileinfo:
  dict (1 items)
  • gaze:
    DataFrame (3 columns, 20 rows)
    shape: (20, 3)

    text_id	page_id	filepath
    i64	i64	str
    0	1	"aeye-lab-pymovements-toy-datas…
    0	2	"aeye-lab-pymovements-toy-datas…
    0	3	"aeye-lab-pymovements-toy-datas…
    0	4	"aeye-lab-pymovements-toy-datas…
    0	5	"aeye-lab-pymovements-toy-datas…
    …	…	…
    3	1	"aeye-lab-pymovements-toy-datas…
    3	2	"aeye-lab-pymovements-toy-datas…
    3	3	"aeye-lab-pymovements-toy-datas…
    3	4	"aeye-lab-pymovements-toy-datas…
    3	5	"aeye-lab-pymovements-toy-datas…

• gaze:
  list (20 items)
  • Gaze
    • samples:
      DataFrame (6 columns, 17223 rows)
      shape: (17_223, 6)

      time	stimuli_x	stimuli_y	text_id	page_id	pixel
      i64	f64	f64	i64	i64	list[f64]
      1988145	-1.0	-1.0	0	1	[206.8, 152.4]
      1988146	-1.0	-1.0	0	1	[206.9, 152.1]
      1988147	-1.0	-1.0	0	1	[207.0, 151.8]
      1988148	-1.0	-1.0	0	1	[207.1, 151.7]
      1988149	-1.0	-1.0	0	1	[207.0, 151.5]
      …	…	…	…	…	…
      2005363	-1.0	-1.0	0	1	[361.0, 415.4]
      2005364	-1.0	-1.0	0	1	[358.0, 414.5]
      2005365	-1.0	-1.0	0	1	[355.8, 413.8]
      2005366	-1.0	-1.0	0	1	[353.1, 413.2]
      2005367	-1.0	-1.0	0	1	[351.2, 412.9]

    • events:
      Events
      Events

      • frame:
        DataFrame (9 columns, 222 rows)
        shape: (222, 9)

        text_id	page_id	name	onset	offset	duration	peak_velocity	amplitude	dispersion
        i64	i64	str	i64	i64	i64	f64	f64	f64
        0	1	"fixation"	1988145	1988563	418	200.144558	2.492864	2.712569
        0	1	"fixation"	1988564	1988750	186	249.67823	2.651198	2.865026
        0	1	"fixation"	1988751	1989178	427	211.598748	2.585906	2.779518
        0	1	"fixation"	1989179	1989436	257	189.183243	2.614347	2.77424
        0	1	"fixation"	1989437	1989600	163	255.077509	2.594651	2.729391
        …	…	…	…	…	…	…	…	…
        0	1	"saccade"	2004373	2004385	12	70.374183	0.7073	0.766684
        0	1	"saccade"	2004688	2004704	16	175.646379	1.807485	1.875716
        0	1	"saccade"	2004879	2004901	22	209.46361	2.933818	3.086169
        0	1	"saccade"	2005110	2005126	16	137.917594	1.405354	1.501217
        0	1	"saccade"	2005288	2005345	57	352.550667	14.682541	16.101153

      • trial_columns:
        None
        None
    • trial_columns:
      list (2 items)
      • 'text_id'
      • 'page_id'
    • experiment:
      Experiment
      Experiment

      • eyetracker:
        EyeTracker
        EyeTracker

        • left:
          None
          None
        • model:
          None
          None
        • mount:
          None
          None
        • right:
          None
          None
        • sampling_rate:
          1000
          1000
        • vendor:
          None
          None
        • version:
          None
          None
      • sampling_rate:
        1000
        1000
      • screen:
        Screen
        Screen

        • distance_cm:
          68
          68
        • height_cm:
          30.2
          30.2
        • height_px:
          1024
          1024
        • origin:
          'upper left'
          'upper left'
        • width_cm:
          38
          38
        • width_px:
          1280
          1280
        • x_max_dva:
          15.599386487782953
          15.599386487782953
        • x_min_dva:
          -15.599386487782953
          -15.599386487782953
        • y_max_dva:
          12.508044410882546
          12.508044410882546
        • y_min_dva:
          -12.508044410882546
          -12.508044410882546
  • Gaze
    • samples:
      DataFrame (6 columns, 29799 rows)
      shape: (29_799, 6)

      time	stimuli_x	stimuli_y	text_id	page_id	pixel
      i64	f64	f64	i64	i64	list[f64]
      2008305	-1.0	-1.0	0	2	[141.4, 153.6]
      2008306	-1.0	-1.0	0	2	[141.1, 153.2]
      2008307	-1.0	-1.0	0	2	[140.7, 152.8]
      2008308	-1.0	-1.0	0	2	[140.6, 152.7]
      2008309	-1.0	-1.0	0	2	[140.5, 152.6]
      …	…	…	…	…	…
      2038099	-1.0	-1.0	0	2	[273.8, 773.8]
      2038100	-1.0	-1.0	0	2	[273.8, 774.1]
      2038101	-1.0	-1.0	0	2	[273.9, 774.5]
      2038102	-1.0	-1.0	0	2	[274.0, 774.4]
      2038103	-1.0	-1.0	0	2	[274.0, 773.9]

    • events:
      Events
      Events

      • frame:
        DataFrame (9 columns, 366 rows)
        shape: (366, 9)

        text_id	page_id	name	onset	offset	duration	peak_velocity	amplitude	dispersion
        i64	i64	str	i64	i64	i64	f64	f64	f64
        0	2	"fixation"	2008305	2008621	316	167.343877	2.283024	2.706135
        0	2	"fixation"	2008622	2008821	199	314.396904	2.578854	2.79657
        0	2	"fixation"	2008822	2009214	392	305.525917	2.612895	2.908934
        0	2	"fixation"	2009215	2009433	218	216.195201	2.612208	2.765062
        0	2	"fixation"	2009434	2009704	270	208.05132	2.566305	2.70311
        …	…	…	…	…	…	…	…	…
        0	2	"saccade"	2036849	2036861	12	54.743137	0.472141	0.529715
        0	2	"saccade"	2037161	2037188	27	223.056103	2.358604	2.587752
        0	2	"saccade"	2037412	2037503	91	406.701444	16.94863	18.346458
        0	2	"saccade"	2037638	2037654	16	138.382767	1.411621	1.827761
        0	2	"saccade"	2037812	2037830	18	240.193236	2.739312	3.024326

      • trial_columns:
        None
        None
    • trial_columns:
      list (2 items)
      • 'text_id'
      • 'page_id'
    • experiment:
      Experiment
      Experiment

      • eyetracker:
        EyeTracker
        EyeTracker

        • left:
          None
          None
        • model:
          None
          None
        • mount:
          None
          None
        • right:
          None
          None
        • sampling_rate:
          1000
          1000
        • vendor:
          None
          None
        • version:
          None
          None
      • sampling_rate:
        1000
        1000
      • screen:
        Screen
        Screen

        • distance_cm:
          68
          68
        • height_cm:
          30.2
          30.2
        • height_px:
          1024
          1024
        • origin:
          'upper left'
          'upper left'
        • width_cm:
          38
          38
        • width_px:
          1280
          1280
        • x_max_dva:
          15.599386487782953
          15.599386487782953
        • x_min_dva:
          -15.599386487782953
          -15.599386487782953
        • y_max_dva:
          12.508044410882546
          12.508044410882546
        • y_min_dva:
          -12.508044410882546
          -12.508044410882546
  • (18 more)
• path:
  PosixPath('data/ToyDataset')
  PosixPath('data/ToyDataset')
• paths:
  DatasetPaths
  DatasetPaths

  • dataset:
    PosixPath('data/ToyDataset')
    PosixPath('data/ToyDataset')
  • downloads:
    PosixPath('data/ToyDataset/downloads')
    PosixPath('data/ToyDataset/downloads')
  • events:
    PosixPath('data/ToyDataset/events')
    PosixPath('data/ToyDataset/events')
  • precomputed_events:
    PosixPath('data/ToyDataset/precomputed_events')
    PosixPath('data/ToyDataset/precomputed_events')
  • precomputed_reading_measures:
    PosixPath
    PosixPath('data/ToyDataset/precomputed_reading_measures')
  • preprocessed:
    PosixPath('data/ToyDataset/preprocessed')
    PosixPath('data/ToyDataset/preprocessed')
  • raw:
    PosixPath('data/ToyDataset/raw')
    PosixPath('data/ToyDataset/raw')
  • root:
    PosixPath('data/ToyDataset')
    PosixPath('data/ToyDataset')
• precomputed_events:
  list (0 items)
• precomputed_reading_measures:
  list (0 items)

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

In 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

• frame:
  DataFrame (9 columns, 222 rows)
  shape: (222, 9)

  text_id	page_id	name	onset	offset	duration	peak_velocity	amplitude	dispersion
  i64	i64	str	i64	i64	i64	f64	f64	f64
  0	1	"fixation"	1988145	1988563	418	200.144558	2.492864	2.712569
  0	1	"fixation"	1988564	1988750	186	249.67823	2.651198	2.865026
  0	1	"fixation"	1988751	1989178	427	211.598748	2.585906	2.779518
  0	1	"fixation"	1989179	1989436	257	189.183243	2.614347	2.77424
  0	1	"fixation"	1989437	1989600	163	255.077509	2.594651	2.729391
  …	…	…	…	…	…	…	…	…
  0	1	"saccade"	2004373	2004385	12	70.374183	0.7073	0.766684
  0	1	"saccade"	2004688	2004704	16	175.646379	1.807485	1.875716
  0	1	"saccade"	2004879	2004901	22	209.46361	2.933818	3.086169
  0	1	"saccade"	2005110	2005126	16	137.917594	1.405354	1.501217
  0	1	"saccade"	2005288	2005345	57	352.550667	14.682541	16.101153

• trial_columns:
  list (2 items)
  • 'text_id'
  • 'page_id'

What you have learned in this tutorial:

• detecting different events with different algorithms by using Dataset.detect_events()

• computing event properties by using Dataset.compute_event_properties()

• saving your preprocesed data using Dataset.save_preprocessed()

• load your preprocesed data using Dataset.load(events=True)

• using custom directory names by specifying preprocessed_dirname

• using other file formats than the default feather format by specifying extension