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.
[1]:
import pymovements as pm
/home/docs/checkouts/readthedocs.org/user_builds/pymovements/envs/v0.21.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:
[2]:
dataset = pm.Dataset('ToyDataset', path='data/ToyDataset')
dataset.download()
dataset.load()
INFO:pymovements.dataset.dataset_download: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, 206.62it/s]
100%|██████████| 20/20 [00:00<00:00, 26.59it/s]
[2]:
<pymovements.dataset.dataset.Dataset at 0x7adeedf72be0>
Now let’s do some basic preprocessing and detect some saccades:
[3]:
dataset.pix2deg()
dataset.pos2vel('smooth')
dataset.detect_events('microsaccades')
dataset.events[0]
100%|██████████| 20/20 [00:01<00:00, 13.96it/s]
100%|██████████| 20/20 [00:00<00:00, 29.89it/s]
20it [00:00, 43.33it/s]
[3]:
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 │
└─────────┴─────────┴─────────┴─────────┴─────────┴──────────┘
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:
[4]:
dataset.compute_event_properties("peak_velocity")
dataset.events[0]
100%|██████████| 20/20 [00:04<00:00, 4.35it/s]
[4]:
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 │
└─────────┴─────────┴─────────┴─────────┴─────────┴──────────┴───────────────┘
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:
[5]:
dataset.compute_event_properties(["amplitude", "dispersion"])
dataset.events[0]
100%|██████████| 20/20 [00:05<00:00, 3.92it/s]
[5]:
shape: (142, 9)
┌─────────┬─────────┬─────────┬─────────┬───┬──────────┬───────────────┬───────────┬────────────┐
│ text_id ┆ page_id ┆ name ┆ onset ┆ … ┆ duration ┆ peak_velocity ┆ amplitude ┆ dispersion │
│ --- ┆ --- ┆ --- ┆ --- ┆ ┆ --- ┆ --- ┆ --- ┆ --- │
│ i64 ┆ i64 ┆ str ┆ i64 ┆ ┆ i64 ┆ f64 ┆ f64 ┆ f64 │
╞═════════╪═════════╪═════════╪═════════╪═══╪══════════╪═══════════════╪═══════════╪════════════╡
│ 0 ┆ 1 ┆ saccade ┆ 1988323 ┆ … ┆ 14 ┆ 129.856451 ┆ 1.236741 ┆ 1.277295 │
│ 0 ┆ 1 ┆ saccade ┆ 1988342 ┆ … ┆ 8 ┆ 50.527286 ┆ 0.330748 ┆ 0.367263 │
│ 0 ┆ 1 ┆ saccade ┆ 1988547 ┆ … ┆ 20 ┆ 200.144558 ┆ 2.391184 ┆ 2.527725 │
│ 0 ┆ 1 ┆ saccade ┆ 1988571 ┆ … ┆ 11 ┆ 56.048003 ┆ 0.476811 ┆ 0.522859 │
│ 0 ┆ 1 ┆ saccade ┆ 1988737 ┆ … ┆ 23 ┆ 249.67823 ┆ 3.285115 ┆ 3.471233 │
│ … ┆ … ┆ … ┆ … ┆ … ┆ … ┆ … ┆ … ┆ … │
│ 0 ┆ 1 ┆ saccade ┆ 2005110 ┆ … ┆ 16 ┆ 137.917594 ┆ 1.405354 ┆ 1.501217 │
│ 0 ┆ 1 ┆ saccade ┆ 2005128 ┆ … ┆ 10 ┆ 61.197926 ┆ 0.44098 ┆ 0.534678 │
│ 0 ┆ 1 ┆ saccade ┆ 2005288 ┆ … ┆ 57 ┆ 352.550667 ┆ 14.682541 ┆ 16.101153 │
│ 0 ┆ 1 ┆ saccade ┆ 2005347 ┆ … ┆ 9 ┆ 85.484987 ┆ 0.629861 ┆ 0.737591 │
│ 0 ┆ 1 ┆ saccade ┆ 2005359 ┆ … ┆ 6 ┆ 66.68761 ┆ 0.368268 ┆ 0.469185 │
└─────────┴─────────┴─────────┴─────────┴───┴──────────┴───────────────┴───────────┴────────────┘
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()