Plot saccadic main sequence

In this notebook we show how you can load a dataset, compute all the necessary properties and the plot the main sequence.

What you will learn in this tutorial:

• how to prepare your data to plot the saccadic main sequence

• how to create a main sequence plot of your saccade events and style it to your liking

Loading and preprocessing your data

We import pymovements as the alias pm for convenience.

import pymovements as pm

Let’s start by downloading our ToyDataset and loading in 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.

Using already downloaded and verified file: data/ToyDataset/downloads/pymovements-toy-dataset.zip
Extracting pymovements-toy-dataset.zip to data/ToyDataset/raw

100%|██████████| 23/23 [00:00<00:00, 310.49it/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)

Now, you have to convert the raw x and y coordinates in pixels to degrees in visual angle.

dataset.pix2deg()

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 (7 columns, 17223 rows)
      shape: (17_223, 7)

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

    • 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 (7 columns, 29799 rows)
      shape: (29_799, 7)

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

    • 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)

Next we can convert these positions into velocitites.

dataset.pos2vel()

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 (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
  • 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, 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)

Let’s check if we now have all our expected columns:

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

Detecting your events and compute properties

In the next step we have to detect our saccades and compute the event properties amplitude and peak_velocity.

We can run the microsaccade detection algorithm with its default parameters:

dataset.detect_events('microsaccades')

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, 142 rows)
      shape: (142, 6)

      text_id	page_id	name	onset	offset	duration
      i64	i64	str	i64	i64	i64
      0	1	"saccade"	1988323	1988337	14
      0	1	"saccade"	1988342	1988350	8
      0	1	"saccade"	1988547	1988567	20
      0	1	"saccade"	1988571	1988582	11
      0	1	"saccade"	1988737	1988760	23
      …	…	…	…	…	…
      0	1	"saccade"	2005110	2005126	16
      0	1	"saccade"	2005128	2005138	10
      0	1	"saccade"	2005288	2005345	57
      0	1	"saccade"	2005347	2005356	9
      0	1	"saccade"	2005359	2005365	6

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

      text_id	page_id	name	onset	offset	duration
      i64	i64	str	i64	i64	i64
      0	2	"saccade"	2008474	2008497	23
      0	2	"saccade"	2008604	2008620	16
      0	2	"saccade"	2008807	2008838	31
      0	2	"saccade"	2008840	2008851	11
      0	2	"saccade"	2008855	2008861	6
      …	…	…	…	…	…
      0	2	"saccade"	2037638	2037654	16
      0	2	"saccade"	2037656	2037666	10
      0	2	"saccade"	2037812	2037830	18
      0	2	"saccade"	2037832	2037839	7
      0	2	"saccade"	2037845	2037851	6

    • 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, 142 rows)
        shape: (142, 6)

        text_id	page_id	name	onset	offset	duration
        i64	i64	str	i64	i64	i64
        0	1	"saccade"	1988323	1988337	14
        0	1	"saccade"	1988342	1988350	8
        0	1	"saccade"	1988547	1988567	20
        0	1	"saccade"	1988571	1988582	11
        0	1	"saccade"	1988737	1988760	23
        …	…	…	…	…	…
        0	1	"saccade"	2005110	2005126	16
        0	1	"saccade"	2005128	2005138	10
        0	1	"saccade"	2005288	2005345	57
        0	1	"saccade"	2005347	2005356	9
        0	1	"saccade"	2005359	2005365	6

      • 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, 233 rows)
        shape: (233, 6)

        text_id	page_id	name	onset	offset	duration
        i64	i64	str	i64	i64	i64
        0	2	"saccade"	2008474	2008497	23
        0	2	"saccade"	2008604	2008620	16
        0	2	"saccade"	2008807	2008838	31
        0	2	"saccade"	2008840	2008851	11
        0	2	"saccade"	2008855	2008861	6
        …	…	…	…	…	…
        0	2	"saccade"	2037638	2037654	16
        0	2	"saccade"	2037656	2037666	10
        0	2	"saccade"	2037812	2037830	18
        0	2	"saccade"	2037832	2037839	7
        0	2	"saccade"	2037845	2037851	6

      • 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)

Next we compute the event properties ‘amplitude’ and ‘peak velocity’ for the detected saccades.

dataset.compute_event_properties(['amplitude', 'peak_velocity'])

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 (8 columns, 142 rows)
      shape: (142, 8)

      text_id	page_id	name	onset	offset	duration	amplitude	peak_velocity
      i64	i64	str	i64	i64	i64	f64	f64
      0	1	"saccade"	1988323	1988337	14	1.236741	129.856451
      0	1	"saccade"	1988342	1988350	8	0.330748	50.527286
      0	1	"saccade"	1988547	1988567	20	2.391184	200.144558
      0	1	"saccade"	1988571	1988582	11	0.476811	56.048003
      0	1	"saccade"	1988737	1988760	23	3.285115	249.67823
      …	…	…	…	…	…	…	…
      0	1	"saccade"	2005110	2005126	16	1.405354	137.917594
      0	1	"saccade"	2005128	2005138	10	0.44098	61.197926
      0	1	"saccade"	2005288	2005345	57	14.682541	352.550667
      0	1	"saccade"	2005347	2005356	9	0.629861	85.484987
      0	1	"saccade"	2005359	2005365	6	0.368268	66.68761

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

      text_id	page_id	name	onset	offset	duration	amplitude	peak_velocity
      i64	i64	str	i64	i64	i64	f64	f64
      0	2	"saccade"	2008474	2008497	23	0.743998	82.147203
      0	2	"saccade"	2008604	2008620	16	1.729582	167.343877
      0	2	"saccade"	2008807	2008838	31	4.866513	314.396904
      0	2	"saccade"	2008840	2008851	11	0.896983	116.795984
      0	2	"saccade"	2008855	2008861	6	0.29733	60.328955
      …	…	…	…	…	…	…	…
      0	2	"saccade"	2037638	2037654	16	1.411621	138.382767
      0	2	"saccade"	2037656	2037666	10	0.659646	86.536773
      0	2	"saccade"	2037812	2037830	18	2.739312	240.193236
      0	2	"saccade"	2037832	2037839	7	0.353243	66.529044
      0	2	"saccade"	2037845	2037851	6	0.197825	42.49047

    • 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 (8 columns, 142 rows)
        shape: (142, 8)

        text_id	page_id	name	onset	offset	duration	amplitude	peak_velocity
        i64	i64	str	i64	i64	i64	f64	f64
        0	1	"saccade"	1988323	1988337	14	1.236741	129.856451
        0	1	"saccade"	1988342	1988350	8	0.330748	50.527286
        0	1	"saccade"	1988547	1988567	20	2.391184	200.144558
        0	1	"saccade"	1988571	1988582	11	0.476811	56.048003
        0	1	"saccade"	1988737	1988760	23	3.285115	249.67823
        …	…	…	…	…	…	…	…
        0	1	"saccade"	2005110	2005126	16	1.405354	137.917594
        0	1	"saccade"	2005128	2005138	10	0.44098	61.197926
        0	1	"saccade"	2005288	2005345	57	14.682541	352.550667
        0	1	"saccade"	2005347	2005356	9	0.629861	85.484987
        0	1	"saccade"	2005359	2005365	6	0.368268	66.68761

      • 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 (8 columns, 233 rows)
        shape: (233, 8)

        text_id	page_id	name	onset	offset	duration	amplitude	peak_velocity
        i64	i64	str	i64	i64	i64	f64	f64
        0	2	"saccade"	2008474	2008497	23	0.743998	82.147203
        0	2	"saccade"	2008604	2008620	16	1.729582	167.343877
        0	2	"saccade"	2008807	2008838	31	4.866513	314.396904
        0	2	"saccade"	2008840	2008851	11	0.896983	116.795984
        0	2	"saccade"	2008855	2008861	6	0.29733	60.328955
        …	…	…	…	…	…	…	…
        0	2	"saccade"	2037638	2037654	16	1.411621	138.382767
        0	2	"saccade"	2037656	2037666	10	0.659646	86.536773
        0	2	"saccade"	2037812	2037830	18	2.739312	240.193236
        0	2	"saccade"	2037832	2037839	7	0.353243	66.529044
        0	2	"saccade"	2037845	2037851	6	0.197825	42.49047

      • 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 verify that we have detected some saccades and have the desired columns available.

dataset.events[0]

Events

• frame:
  DataFrame (8 columns, 142 rows)
  shape: (142, 8)

  text_id	page_id	name	onset	offset	duration	amplitude	peak_velocity
  i64	i64	str	i64	i64	i64	f64	f64
  0	1	"saccade"	1988323	1988337	14	1.236741	129.856451
  0	1	"saccade"	1988342	1988350	8	0.330748	50.527286
  0	1	"saccade"	1988547	1988567	20	2.391184	200.144558
  0	1	"saccade"	1988571	1988582	11	0.476811	56.048003
  0	1	"saccade"	1988737	1988760	23	3.285115	249.67823
  …	…	…	…	…	…	…	…
  0	1	"saccade"	2005110	2005126	16	1.405354	137.917594
  0	1	"saccade"	2005128	2005138	10	0.44098	61.197926
  0	1	"saccade"	2005288	2005345	57	14.682541	352.550667
  0	1	"saccade"	2005347	2005356	9	0.629861	85.484987
  0	1	"saccade"	2005359	2005365	6	0.368268	66.68761

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

Plot the main sequence

Now we just pass the event dataframe to the plotting function:

# only showing the first three event dataframes here.
# note that you can adjust the styling of the plot, e.g. setting a low
# alpha value allows you to see overlapping data points
for event_df in dataset.events[:3]:
    pm.plotting.main_sequence_plot(
        event_df,
        title='Main sequence plot for '
        f'text {event_df[0, "text_id"]}, '
        f'page {event_df[0, "page_id"]}',
        alpha=0.3,
        color='green',
        marker='x',
        marker_size=30,
    )

What you have learned in this tutorial:

• how to prepare your data to plot a main sequence

• how to create a main sequence plot by using main_sequence_plot