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

Loading and preprocessing your data

We import pymovements as the alias pm for convenience.

import pymovements as pm

/home/docs/checkouts/readthedocs.org/user_builds/pymovements/envs/v0.14.0/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()

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

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

<pymovements.dataset.dataset.Dataset at 0x7f66a482b7f0>

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

dataset.pix2deg()

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

<pymovements.dataset.dataset.Dataset at 0x7f66a482b7f0>

Next we can convert these positions into velocitites.

dataset.pos2vel()

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

<pymovements.dataset.dataset.Dataset at 0x7f66a482b7f0>

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

dataset.gaze[0].frame.head()

shape: (5, 9)

text_id	page_id	time	x_right_pix	y_right_pix	y_right_pos	x_right_pos	y_right_vel	x_right_vel
i64	i64	f64	f64	f64	f64	f64	f64	f64
0	1	1.988145e6	206.8	152.4	-12.005591	-7.528075	-3.589697	1.221164
0	1	1.988146e6	206.9	152.1	-12.01277	-7.525633	-7.179203	2.442343
0	1	1.988147e6	207.0	151.8	-12.019949	-7.52319	-5.184827	1.628238
0	1	1.988148e6	207.1	151.7	-12.022342	-7.520748	-4.386968	0.407059
0	1	1.988149e6	207.0	151.5	-12.027128	-7.52319	-3.190445	0.407069

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

20it [00:00, 78.04it/s]

<pymovements.dataset.dataset.Dataset at 0x7f66a482b7f0>

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

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

20it [00:22,  1.13s/it]

<pymovements.dataset.dataset.Dataset at 0x7f66a482b7f0>

Let’s verify that we have detected some saccades and have the desired columns available.

dataset.events[0].frame.head()

shape: (5, 8)

name	onset	offset	duration	text_id	page_id	amplitude	peak_velocity
str	i64	i64	i64	i64	i64	f64	f64
"saccade"	1988323	1988337	14	0	1	1.252096	131.445157
"saccade"	1988342	1988350	8	0	1	0.335018	51.184996
"saccade"	1988547	1988567	20	0	1	2.416716	202.367951
"saccade"	1988571	1988582	11	0	1	0.480982	56.535391
"saccade"	1988737	1988760	23	0	1	3.304035	250.889337

Plot the main sequence

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

# only showing the first three event dataframes here.
for event_df in dataset.events[:3]:
    print(
        f'Showing main sequence plot for '
        f'text {event_df[0, "text_id"]}, '
        f'page {event_df[0, "page_id"]}:')
    pm.plotting.main_sequence_plot(event_df)

Showing main sequence plot for text 0, page 1:

Showing main sequence plot for text 0, page 2:

Showing main sequence plot for text 0, page 3:

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