Saving and Loading Event Data#
What you will learn in this tutorial:#
how to save your event data
how to load your event data
Preparations#
We import pymovements as the alias pm for convenience.
[1]:
import pymovements as pm
/home/docs/checkouts/readthedocs.org/user_builds/pymovements/envs/v0.7.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 and extracting our ToyDataset:
[2]:
dataset = pm.datasets.ToyDataset(root='data/')
dataset.download()
dataset.extract()
Using already downloaded and verified file: data/ToyDataset/downloads/pymovements-toy-dataset.zip
Now let’s load in the data and do some preprocessing:
[3]:
dataset.load()
dataset.pix2deg()
dataset.pos2vel()
dataset.gaze[0].frame.head()
100%|██████████| 20/20 [00:00<00:00, 194.18it/s]
100%|██████████| 20/20 [00:00<00:00, 782.15it/s]
100%|██████████| 20/20 [00:00<00:00, 713.37it/s]
[3]:
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 |
Detect some events:
[4]:
dataset.detect_events(pm.events.ivt)
dataset.events[0].frame.head()
20it [00:00, 262.15it/s]
[4]:
shape: (5, 6)
| text_id | page_id | name | onset | offset | duration |
|---|---|---|---|---|---|
| i64 | i64 | str | i64 | i64 | i64 |
| 0 | 1 | "fixation" | 1988145 | 1988322 | 177 |
| 0 | 1 | "fixation" | 1988351 | 1988546 | 195 |
| 0 | 1 | "fixation" | 1988592 | 1988736 | 144 |
| 0 | 1 | "fixation" | 1988788 | 1989013 | 225 |
| 0 | 1 | "fixation" | 1989060 | 1989170 | 110 |
[5]:
dataset.detect_events(pm.events.microsaccades)
dataset.events[0].frame.head()
20it [00:00, 66.28it/s]
[5]:
shape: (5, 6)
| text_id | page_id | name | onset | offset | duration |
|---|---|---|---|---|---|
| i64 | i64 | str | i64 | i64 | i64 |
| 0 | 1 | "fixation" | 1988145 | 1988322 | 177 |
| 0 | 1 | "fixation" | 1988351 | 1988546 | 195 |
| 0 | 1 | "fixation" | 1988592 | 1988736 | 144 |
| 0 | 1 | "fixation" | 1988788 | 1989013 | 225 |
| 0 | 1 | "fixation" | 1989060 | 1989170 | 110 |
We now have event dataframes available with our detected event data.
Saving#
Saving your event data is as simple as:
[6]:
dataset.save_events()
100%|██████████| 20/20 [00:00<00:00, 3537.26it/s]
All of the event data is saved into this directory:
[7]:
dataset.events_rootpath
[7]:
PosixPath('data/ToyDataset/events')
Let’s confirm it by printing all the new files in this directory:
[8]:
print(list(dataset.events_rootpath.glob('*/*/*')))
[PosixPath('data/ToyDataset/events/aeye-lab-pymovements-toy-dataset-6cb5d66/data/trial_0_1.feather'), PosixPath('data/ToyDataset/events/aeye-lab-pymovements-toy-dataset-6cb5d66/data/trial_1_3.feather'), PosixPath('data/ToyDataset/events/aeye-lab-pymovements-toy-dataset-6cb5d66/data/trial_2_2.feather'), PosixPath('data/ToyDataset/events/aeye-lab-pymovements-toy-dataset-6cb5d66/data/trial_3_3.feather'), PosixPath('data/ToyDataset/events/aeye-lab-pymovements-toy-dataset-6cb5d66/data/trial_0_3.feather'), PosixPath('data/ToyDataset/events/aeye-lab-pymovements-toy-dataset-6cb5d66/data/trial_2_5.feather'), PosixPath('data/ToyDataset/events/aeye-lab-pymovements-toy-dataset-6cb5d66/data/trial_0_4.feather'), PosixPath('data/ToyDataset/events/aeye-lab-pymovements-toy-dataset-6cb5d66/data/trial_2_4.feather'), PosixPath('data/ToyDataset/events/aeye-lab-pymovements-toy-dataset-6cb5d66/data/trial_3_2.feather'), PosixPath('data/ToyDataset/events/aeye-lab-pymovements-toy-dataset-6cb5d66/data/trial_2_1.feather'), PosixPath('data/ToyDataset/events/aeye-lab-pymovements-toy-dataset-6cb5d66/data/trial_1_2.feather'), PosixPath('data/ToyDataset/events/aeye-lab-pymovements-toy-dataset-6cb5d66/data/trial_3_4.feather'), PosixPath('data/ToyDataset/events/aeye-lab-pymovements-toy-dataset-6cb5d66/data/trial_3_5.feather'), PosixPath('data/ToyDataset/events/aeye-lab-pymovements-toy-dataset-6cb5d66/data/trial_1_1.feather'), PosixPath('data/ToyDataset/events/aeye-lab-pymovements-toy-dataset-6cb5d66/data/trial_2_3.feather'), PosixPath('data/ToyDataset/events/aeye-lab-pymovements-toy-dataset-6cb5d66/data/trial_1_5.feather'), PosixPath('data/ToyDataset/events/aeye-lab-pymovements-toy-dataset-6cb5d66/data/trial_0_5.feather'), PosixPath('data/ToyDataset/events/aeye-lab-pymovements-toy-dataset-6cb5d66/data/trial_0_2.feather'), PosixPath('data/ToyDataset/events/aeye-lab-pymovements-toy-dataset-6cb5d66/data/trial_3_1.feather'), PosixPath('data/ToyDataset/events/aeye-lab-pymovements-toy-dataset-6cb5d66/data/trial_1_4.feather')]
All of the files have been saved into the events_rootpath as feather files.
If we want to save the data into an alternative directory and also use a different file format like csv we can use the following:
[9]:
dataset.save_events(events_dirname='events_csv', extension='csv')
100%|██████████| 20/20 [00:00<00:00, 2127.58it/s]
Let’s confirm again by printing all the new files in this alternative directory:
[10]:
alternative_dirpath = dataset.path / 'events_csv'
print(list(alternative_dirpath.glob('*/*/*')))
[PosixPath('data/ToyDataset/events_csv/aeye-lab-pymovements-toy-dataset-6cb5d66/data/trial_3_2.csv'), PosixPath('data/ToyDataset/events_csv/aeye-lab-pymovements-toy-dataset-6cb5d66/data/trial_0_4.csv'), PosixPath('data/ToyDataset/events_csv/aeye-lab-pymovements-toy-dataset-6cb5d66/data/trial_0_5.csv'), PosixPath('data/ToyDataset/events_csv/aeye-lab-pymovements-toy-dataset-6cb5d66/data/trial_0_1.csv'), PosixPath('data/ToyDataset/events_csv/aeye-lab-pymovements-toy-dataset-6cb5d66/data/trial_1_2.csv'), PosixPath('data/ToyDataset/events_csv/aeye-lab-pymovements-toy-dataset-6cb5d66/data/trial_3_5.csv'), PosixPath('data/ToyDataset/events_csv/aeye-lab-pymovements-toy-dataset-6cb5d66/data/trial_2_2.csv'), PosixPath('data/ToyDataset/events_csv/aeye-lab-pymovements-toy-dataset-6cb5d66/data/trial_2_5.csv'), PosixPath('data/ToyDataset/events_csv/aeye-lab-pymovements-toy-dataset-6cb5d66/data/trial_1_4.csv'), PosixPath('data/ToyDataset/events_csv/aeye-lab-pymovements-toy-dataset-6cb5d66/data/trial_1_5.csv'), PosixPath('data/ToyDataset/events_csv/aeye-lab-pymovements-toy-dataset-6cb5d66/data/trial_0_2.csv'), PosixPath('data/ToyDataset/events_csv/aeye-lab-pymovements-toy-dataset-6cb5d66/data/trial_3_3.csv'), PosixPath('data/ToyDataset/events_csv/aeye-lab-pymovements-toy-dataset-6cb5d66/data/trial_1_3.csv'), PosixPath('data/ToyDataset/events_csv/aeye-lab-pymovements-toy-dataset-6cb5d66/data/trial_0_3.csv'), PosixPath('data/ToyDataset/events_csv/aeye-lab-pymovements-toy-dataset-6cb5d66/data/trial_2_3.csv'), PosixPath('data/ToyDataset/events_csv/aeye-lab-pymovements-toy-dataset-6cb5d66/data/trial_2_1.csv'), PosixPath('data/ToyDataset/events_csv/aeye-lab-pymovements-toy-dataset-6cb5d66/data/trial_3_4.csv'), PosixPath('data/ToyDataset/events_csv/aeye-lab-pymovements-toy-dataset-6cb5d66/data/trial_1_1.csv'), PosixPath('data/ToyDataset/events_csv/aeye-lab-pymovements-toy-dataset-6cb5d66/data/trial_2_4.csv'), PosixPath('data/ToyDataset/events_csv/aeye-lab-pymovements-toy-dataset-6cb5d66/data/trial_3_1.csv')]
Loading#
Now let’s imagine that this preprocessing and saving was done in another file and we only want to load the preprocessed data.
We simulate this by initializing a new dataset. We don’t need to download any additional data.
[11]:
preprocessed_dataset = pm.datasets.ToyDataset(root='data/')
The preprocessed data can now simply be loaded by setting preprocessed to True:
[12]:
preprocessed_dataset.load(events=True)
dataset.events[0].frame.head()
100%|██████████| 20/20 [00:00<00:00, 205.09it/s]
100%|██████████| 20/20 [00:00<00:00, 1509.86it/s]
[12]:
shape: (5, 6)
| text_id | page_id | name | onset | offset | duration |
|---|---|---|---|---|---|
| i64 | i64 | str | i64 | i64 | i64 |
| 0 | 1 | "fixation" | 1988145 | 1988322 | 177 |
| 0 | 1 | "fixation" | 1988351 | 1988546 | 195 |
| 0 | 1 | "fixation" | 1988592 | 1988736 | 144 |
| 0 | 1 | "fixation" | 1988788 | 1989013 | 225 |
| 0 | 1 | "fixation" | 1989060 | 1989170 | 110 |
By default, the events directory and the feather extension will be chosen.
In case of alternative directory names or other file formats you can use the following:
[13]:
preprocessed_dataset.load(
events=True,
events_dirname='events_csv',
extension='csv',
)
dataset.events[0].frame.head()
100%|██████████| 20/20 [00:00<00:00, 204.26it/s]
100%|██████████| 20/20 [00:00<00:00, 973.70it/s]
[13]:
shape: (5, 6)
| text_id | page_id | name | onset | offset | duration |
|---|---|---|---|---|---|
| i64 | i64 | str | i64 | i64 | i64 |
| 0 | 1 | "fixation" | 1988145 | 1988322 | 177 |
| 0 | 1 | "fixation" | 1988351 | 1988546 | 195 |
| 0 | 1 | "fixation" | 1988592 | 1988736 | 144 |
| 0 | 1 | "fixation" | 1988788 | 1989013 | 225 |
| 0 | 1 | "fixation" | 1989060 | 1989170 | 110 |
What you have learned in this tutorial:#
saving your preprocesed data using
Dataset.save_preprocessed()load your preprocesed data using
Dataset.load(preprocessed=True)using custom directory names by specifying
preprocessed_dirnameusing other file formats than the default
featherformat by specifyingextension