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

/home/docs/checkouts/readthedocs.org/user_builds/pymovements/envs/v0.17.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, 44.87it/s]

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

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

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

Next we can convert these positions into velocitites.

dataset.pos2vel()

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

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

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

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

shape: (5, 8)

text_id	page_id	time	stimuli_x	stimuli_y	pixel	position	velocity
i64	i64	f64	f64	f64	list[f64]	list[f64]	list[f64]
0	1	1.988145e6	-1.0	-1.0	[206.8, 152.4]	[-10.697598, -8.852399]	[null, null]
0	1	1.988146e6	-1.0	-1.0	[206.9, 152.1]	[-10.695183, -8.859678]	[null, null]
0	1	1.988147e6	-1.0	-1.0	[207.0, 151.8]	[-10.692768, -8.866956]	[1.610194, -5.256267]
0	1	1.988148e6	-1.0	-1.0	[207.1, 151.7]	[-10.690352, -8.869381]	[0.402548, -4.447465]
0	1	1.988149e6	-1.0	-1.0	[207.0, 151.5]	[-10.692768, -8.874233]	[0.402561, -3.234462]

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

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

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

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

20it [01:50,  5.52s/it]

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

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

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