Computing Event Properties

What you will learn in this tutorial:

• how to add event properties for peak velocity and amplitude

Preparations

We import pymovements as the alias pm for convenience.

import pymovements as pm

/home/docs/checkouts/readthedocs.org/user_builds/pymovements/envs/v0.22.2/lib/python3.9/site-packages/tqdm/auto.py:21: TqdmWarning: IProgress not found. Please update jupyter and ipywidgets. See https://ipywidgets.readthedocs.io/en/stable/user_install.html
  from .autonotebook import tqdm as notebook_tqdm

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, 323.84it/s]
100%|██████████| 20/20 [00:00<00:00, 61.21it/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_files:
    dict (3 items)
    • gaze:
      True
      True
    • precomputed_events:
      False
      False
    • (1 more)
  • 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:
    dict (1 items)
    • gaze:
      list (1 items)
      • • resource:
          str
          'http://github.com/aeye-lab/pymovements-toy-dataset/zipball/6cb5d663317bf418cec0c9abe1dde5085a8a8ebd/'
        • filename:
          'pymovements-toy-dataset.zip'
          'pymovements-toy-dataset.zip'
        • (1 more)
  • 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)
  • GazeDataFrame
    • frame:
      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:
      EventDataFrame
      EventDataFrame

      • 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
  • GazeDataFrame
    • frame:
      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:
      EventDataFrame
      EventDataFrame

      • 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 let’s do some basic preprocessing and detect some saccades:

dataset.pix2deg()
dataset.pos2vel('smooth')

dataset.detect_events('microsaccades')

dataset.events[0]

100%|██████████| 20/20 [00:00<00:00, 32.25it/s]
100%|██████████| 20/20 [00:00<00:00, 65.21it/s]
20it [00:00, 54.71it/s]

EventDataFrame

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

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]

100%|██████████| 20/20 [00:02<00:00,  7.99it/s]

EventDataFrame

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

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

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

We notice 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]

100%|██████████| 20/20 [00:02<00:00,  7.24it/s]

EventDataFrame

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

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

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

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

What you have learned in this tutorial:

• how to compute event properties by using Dataset.compute_event_properties()