Preprocessing Raw Gaze Data#
What you will learn in this tutorial:#
how to transform pixel coordinates into degrees of visual angle
how to transform positional data into velocity 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.12.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:
[2]:
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, 177.66it/s]
[2]:
<pymovements.dataset.dataset.Dataset at 0x7fb4fdac6a60>
We can verify that all files have been loaded in by checking the fileinfo attribute:
[3]:
dataset.fileinfo
[3]:
| text_id | page_id | filepath |
|---|---|---|
| i64 | i64 | str |
| 0 | 1 | "aeye-lab-pymov… |
| 0 | 2 | "aeye-lab-pymov… |
| 0 | 3 | "aeye-lab-pymov… |
| 0 | 4 | "aeye-lab-pymov… |
| 0 | 5 | "aeye-lab-pymov… |
| 1 | 1 | "aeye-lab-pymov… |
| 1 | 2 | "aeye-lab-pymov… |
| 1 | 3 | "aeye-lab-pymov… |
| 1 | 4 | "aeye-lab-pymov… |
| 1 | 5 | "aeye-lab-pymov… |
| 2 | 1 | "aeye-lab-pymov… |
| 2 | 2 | "aeye-lab-pymov… |
| 2 | 3 | "aeye-lab-pymov… |
| 2 | 4 | "aeye-lab-pymov… |
| 2 | 5 | "aeye-lab-pymov… |
| 3 | 1 | "aeye-lab-pymov… |
| 3 | 2 | "aeye-lab-pymov… |
| 3 | 3 | "aeye-lab-pymov… |
| 3 | 4 | "aeye-lab-pymov… |
| 3 | 5 | "aeye-lab-pymov… |
Now let’s inpect our gaze dataframe:
[4]:
dataset.gaze[0].frame.head()
[4]:
| text_id | page_id | time | x_right_pix | y_right_pix |
|---|---|---|---|---|
| i64 | i64 | f64 | f64 | f64 |
| 0 | 1 | 1.988145e6 | 206.8 | 152.4 |
| 0 | 1 | 1.988146e6 | 206.9 | 152.1 |
| 0 | 1 | 1.988147e6 | 207.0 | 151.8 |
| 0 | 1 | 1.988148e6 | 207.1 | 151.7 |
| 0 | 1 | 1.988149e6 | 207.0 | 151.5 |
Apart from some additional labels we see the following columns: time, x_right_pix and y_right_pix.
Preprocessing#
We now want to transform these pixel position coordinates into coordinates in degrees of visual angle. This is simply done by:
[5]:
dataset.pix2deg()
dataset.gaze[0].frame
100%|██████████| 20/20 [00:00<00:00, 713.83it/s]
[5]:
| text_id | page_id | time | x_right_pix | y_right_pix | y_right_pos | x_right_pos |
|---|---|---|---|---|---|---|
| i64 | i64 | f64 | f64 | f64 | f64 | f64 |
| 0 | 1 | 1.988145e6 | 206.8 | 152.4 | -12.005591 | -7.528075 |
| 0 | 1 | 1.988146e6 | 206.9 | 152.1 | -12.01277 | -7.525633 |
| 0 | 1 | 1.988147e6 | 207.0 | 151.8 | -12.019949 | -7.52319 |
| 0 | 1 | 1.988148e6 | 207.1 | 151.7 | -12.022342 | -7.520748 |
| 0 | 1 | 1.988149e6 | 207.0 | 151.5 | -12.027128 | -7.52319 |
| 0 | 1 | 1.98815e6 | 207.0 | 151.3 | -12.031913 | -7.52319 |
| 0 | 1 | 1.988151e6 | 207.2 | 151.4 | -12.02952 | -7.518305 |
| 0 | 1 | 1.988152e6 | 207.4 | 151.6 | -12.024735 | -7.513421 |
| 0 | 1 | 1.988153e6 | 207.6 | 151.9 | -12.017556 | -7.508536 |
| 0 | 1 | 1.988154e6 | 207.7 | 152.1 | -12.01277 | -7.506093 |
| 0 | 1 | 1.988155e6 | 207.7 | 152.1 | -12.01277 | -7.506093 |
| 0 | 1 | 1.988156e6 | 207.7 | 152.2 | -12.010377 | -7.506093 |
| … | … | … | … | … | … | … |
| 0 | 1 | 2.005356e6 | 370.4 | 419.0 | -5.498696 | -3.501922 |
| 0 | 1 | 2.005357e6 | 371.2 | 419.0 | -5.498696 | -3.482116 |
| 0 | 1 | 2.005358e6 | 371.1 | 418.9 | -5.501175 | -3.484592 |
| 0 | 1 | 2.005359e6 | 369.9 | 418.7 | -5.506132 | -3.5143 |
| 0 | 1 | 2.00536e6 | 368.1 | 418.1 | -5.521002 | -3.558859 |
| 0 | 1 | 2.005361e6 | 365.9 | 417.1 | -5.545783 | -3.613315 |
| 0 | 1 | 2.005362e6 | 363.3 | 416.3 | -5.565607 | -3.677663 |
| 0 | 1 | 2.005363e6 | 361.0 | 415.4 | -5.587907 | -3.734578 |
| 0 | 1 | 2.005364e6 | 358.0 | 414.5 | -5.610206 | -3.808805 |
| 0 | 1 | 2.005365e6 | 355.8 | 413.8 | -5.627548 | -3.863229 |
| 0 | 1 | 2.005366e6 | 353.1 | 413.2 | -5.642412 | -3.930014 |
| 0 | 1 | 2.005367e6 | 351.2 | 412.9 | -5.649843 | -3.977003 |
The processed result has been added as new columns to our gaze dataframe: x_right_pos, y_right_pos.
Additionally we would like to have velocity data available too. We have four different methods available:
preceding: this will just take the single preceding sample in account for velocity calculation. Most noisy variant.neighbors: this will take the neighboring samples in account for velocity calculation. A bit less noisy.smooth: this will increase the neighboring samples to two on each side. You can get a smooth conversion this way.savitzky_golay: this is using the Savitzky-Golay differentiation filter for conversion. You can specify additional parameters likewindow_lengthandpolyorder. Depending on your parameters this will lead to the best results.
Let’s use the smooth method first:
[6]:
dataset.pos2vel(method='smooth')
dataset.gaze[0].frame
100%|██████████| 20/20 [00:00<00:00, 665.00it/s]
[6]:
| 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 |
| 0 | 1 | 1.98815e6 | 207.0 | 151.3 | -12.031913 | -7.52319 | -0.797611 | 2.035352 |
| 0 | 1 | 1.988151e6 | 207.2 | 151.4 | -12.02952 | -7.518305 | 2.79166 | 4.070736 |
| 0 | 1 | 1.988152e6 | 207.4 | 151.6 | -12.024735 | -7.513421 | 5.184593 | 4.477864 |
| 0 | 1 | 1.988153e6 | 207.6 | 151.9 | -12.017556 | -7.508536 | 4.785873 | 3.256672 |
| 0 | 1 | 1.988154e6 | 207.7 | 152.1 | -12.01277 | -7.506093 | 3.190657 | 1.628352 |
| 0 | 1 | 1.988155e6 | 207.7 | 152.1 | -12.01277 | -7.506093 | 1.595371 | 0.0 |
| 0 | 1 | 1.988156e6 | 207.7 | 152.2 | -12.010377 | -7.506093 | 1.196552 | -0.814183 |
| … | … | … | … | … | … | … | … | … |
| 0 | 1 | 2.005356e6 | 370.4 | 419.0 | -5.498696 | -3.501922 | 1.652276 | 30.943909 |
| 0 | 1 | 2.005357e6 | 371.2 | 419.0 | -5.498696 | -3.482116 | -1.239212 | 7.426888 |
| 0 | 1 | 2.005358e6 | 371.1 | 418.9 | -5.501175 | -3.484592 | -4.956757 | -14.853638 |
| 0 | 1 | 2.005359e6 | 369.9 | 418.7 | -5.506132 | -3.5143 | -11.152291 | -34.244438 |
| 0 | 1 | 2.00536e6 | 368.1 | 418.1 | -5.521002 | -3.558859 | -17.347327 | -48.680946 |
| 0 | 1 | 2.005361e6 | 365.9 | 417.1 | -5.545783 | -3.613315 | -21.063531 | -56.513558 |
| 0 | 1 | 2.005362e6 | 363.3 | 416.3 | -5.565607 | -3.677663 | -21.888043 | -61.868102 |
| 0 | 1 | 2.005363e6 | 361.0 | 415.4 | -5.587907 | -3.734578 | -21.060565 | -63.509382 |
| 0 | 1 | 2.005364e6 | 358.0 | 414.5 | -5.610206 | -3.808805 | -19.40755 | -63.500293 |
| 0 | 1 | 2.005365e6 | 355.8 | 413.8 | -5.627548 | -3.863229 | -15.690342 | -60.605681 |
| 0 | 1 | 2.005366e6 | 353.1 | 413.2 | -5.642412 | -3.930014 | -11.147739 | -56.887102 |
| 0 | 1 | 2.005367e6 | 351.2 | 412.9 | -5.649843 | -3.977003 | -3.715818 | -23.494968 |
This added the following new velocity columns to our gaze dataframe: x_right_vel, y_right_vel
We can also use the Savitzky-Golay differentiation filter with some additional parameters like this:
[7]:
dataset.pos2vel(method='savitzky_golay', window_length=7, polyorder=2)
dataset.gaze[0].frame
100%|██████████| 20/20 [00:00<00:00, 415.38it/s]
[7]:
| 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 | -8.119266 | 1.918969 |
| 0 | 1 | 1.988146e6 | 206.9 | 152.1 | -12.01277 | -7.525633 | -6.80873 | 1.686374 |
| 0 | 1 | 1.988147e6 | 207.0 | 151.8 | -12.019949 | -7.52319 | -5.498195 | 1.453779 |
| 0 | 1 | 1.988148e6 | 207.1 | 151.7 | -12.022342 | -7.520748 | -4.187659 | 1.221184 |
| 0 | 1 | 1.988149e6 | 207.0 | 151.5 | -12.027128 | -7.52319 | -2.307447 | 1.570121 |
| 0 | 1 | 1.98815e6 | 207.0 | 151.3 | -12.031913 | -7.52319 | 0.000012 | 2.267985 |
| 0 | 1 | 1.988151e6 | 207.2 | 151.4 | -12.02952 | -7.518305 | 1.965619 | 2.965849 |
| 0 | 1 | 1.988152e6 | 207.4 | 151.6 | -12.024735 | -7.513421 | 3.332988 | 3.402009 |
| 0 | 1 | 1.988153e6 | 207.6 | 151.9 | -12.017556 | -7.508536 | 3.931231 | 2.965868 |
| 0 | 1 | 1.988154e6 | 207.7 | 152.1 | -12.01277 | -7.506093 | 3.247586 | 1.657408 |
| 0 | 1 | 1.988155e6 | 207.7 | 152.1 | -12.01277 | -7.506093 | 2.393016 | 0.523394 |
| 0 | 1 | 1.988156e6 | 207.7 | 152.2 | -12.010377 | -7.506093 | 0.940131 | -0.261702 |
| … | … | … | … | … | … | … | … | … |
| 0 | 1 | 2.005356e6 | 370.4 | 419.0 | -5.498696 | -3.501922 | 2.212816 | 30.233706 |
| 0 | 1 | 2.005357e6 | 371.2 | 419.0 | -5.498696 | -3.482116 | -1.770247 | 8.133334 |
| 0 | 1 | 2.005358e6 | 371.1 | 418.9 | -5.501175 | -3.484592 | -6.638259 | -12.907492 |
| 0 | 1 | 2.005359e6 | 369.9 | 418.7 | -5.506132 | -3.5143 | -11.240462 | -30.853149 |
| 0 | 1 | 2.00536e6 | 368.1 | 418.1 | -5.521002 | -3.558859 | -15.576756 | -44.376559 |
| 0 | 1 | 2.005361e6 | 365.9 | 417.1 | -5.545783 | -3.613315 | -19.116071 | -54.71422 |
| 0 | 1 | 2.005362e6 | 363.3 | 416.3 | -5.565607 | -3.677663 | -20.885051 | -59.569318 |
| 0 | 1 | 2.005363e6 | 361.0 | 415.4 | -5.587907 | -3.734578 | -20.441377 | -62.301177 |
| 0 | 1 | 2.005364e6 | 358.0 | 414.5 | -5.610206 | -3.808805 | -18.051086 | -61.58637 |
| 0 | 1 | 2.005365e6 | 355.8 | 413.8 | -5.627548 | -3.863229 | -15.454523 | -59.751855 |
| 0 | 1 | 2.005366e6 | 353.1 | 413.2 | -5.642412 | -3.930014 | -12.857961 | -57.917341 |
| 0 | 1 | 2.005367e6 | 351.2 | 412.9 | -5.649843 | -3.977003 | -10.261398 | -56.082826 |
This has overwritten our velocity columns. As we see, the values in the velocity columns are slightly different.
What you have learned in this tutorial:#
transforming pixel coordinates into degrees of visual angle by using
Dataset.pix2deg()transforming positional data into velocity data by using
Dataset.pos2vel()passing additional keyword arguments when using the Savitzky-Golay differentiation filter