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.11.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, 195.03it/s]

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

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, 715.28it/s]

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

Next we can convert these positions into velocitites.

dataset.pos2vel()

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

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

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	x_right_vel	y_right_vel
i64	i64	f64	f64	f64	f64	f64	f64	f64
0	1	1.988145e6	206.8	152.4	-12.005591	-7.528075	1.221164	-3.589697
0	1	1.988146e6	206.9	152.1	-12.01277	-7.525633	2.442343	-7.179203
0	1	1.988147e6	207.0	151.8	-12.019949	-7.52319	1.628238	-5.184827
0	1	1.988148e6	207.1	151.7	-12.022342	-7.520748	0.407059	-4.386968
0	1	1.988149e6	207.0	151.5	-12.027128	-7.52319	0.407069	-3.190445

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(pm.events.microsaccades)

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

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

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

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

20it [00:13,  1.43it/s]

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

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

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

shape: (5, 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.252096	131.445157
0	1	"saccade"	1988342	1988350	8	0.335018	51.184996
0	1	"saccade"	1988547	1988567	20	0.567382	63.970097
0	1	"saccade"	1988571	1988582	11	1.956328	188.711437
0	1	"saccade"	1988737	1988760	23	0.418455	56.562731

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