Heatmap Plotting#
In this tutorial, we will demonstrate how to use the heatmap function from the pymovements.plotting module to create a heatmap of gaze data. The heatmap will show the distribution of gaze positions across the experiment screen, with color values indicating the time spent at each position in seconds.
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.9.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
Loading the Dataset#
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
100%|██████████| 20/20 [00:00<00:00, 207.69it/s]
[2]:
<pymovements.dataset.dataset.Dataset at 0x7f7fb58c7af0>
After loading the dataset, we will transform the pixel coordinates to degrees.
[3]:
dataset.pix2deg()
100%|██████████| 20/20 [00:00<00:00, 749.55it/s]
[3]:
<pymovements.dataset.dataset.Dataset at 0x7f7fb58c7af0>
Now our available columns for each GazeDataFrame are the following. We will use the x_right_pos and y_right_pos columns for plotting. However, it is also possible to use the pixel data columns x_right_pix and y_right_pix.
[4]:
dataset.gaze[5].frame
[4]:
| text_id | page_id | time | x_right_pix | y_right_pix | y_right_pos | x_right_pos |
|---|---|---|---|---|---|---|
| i64 | i64 | f64 | f64 | f64 | f64 | f64 |
| 1 | 1 | 2.415266e6 | 176.8 | 140.2 | -12.297242 | -8.259494 |
| 1 | 1 | 2.415267e6 | 176.7 | 139.8 | -12.306793 | -8.261927 |
| 1 | 1 | 2.415268e6 | 176.7 | 139.3 | -12.318732 | -8.261927 |
| 1 | 1 | 2.415269e6 | 176.6 | 139.3 | -12.318732 | -8.264361 |
| 1 | 1 | 2.41527e6 | 176.7 | 139.3 | -12.318732 | -8.261927 |
| 1 | 1 | 2.415271e6 | 176.8 | 139.5 | -12.313957 | -8.259494 |
| 1 | 1 | 2.415272e6 | 177.3 | 139.8 | -12.306793 | -8.247325 |
| 1 | 1 | 2.415273e6 | 177.8 | 140.0 | -12.302018 | -8.235155 |
| 1 | 1 | 2.415274e6 | 178.3 | 140.0 | -12.302018 | -8.222985 |
| 1 | 1 | 2.415275e6 | 178.3 | 139.9 | -12.304406 | -8.222985 |
| 1 | 1 | 2.415276e6 | 178.0 | 140.2 | -12.297242 | -8.230287 |
| 1 | 1 | 2.415277e6 | 177.7 | 140.4 | -12.292466 | -8.237589 |
| … | … | … | … | … | … | … |
| 1 | 1 | 2.438308e6 | 649.1 | 633.7 | -0.145082 | 3.415265 |
| 1 | 1 | 2.438309e6 | 648.8 | 633.9 | -0.140079 | 3.407836 |
| 1 | 1 | 2.43831e6 | 649.1 | 634.1 | -0.135077 | 3.415265 |
| 1 | 1 | 2.438311e6 | 649.6 | 634.2 | -0.132575 | 3.427645 |
| 1 | 1 | 2.438312e6 | 650.1 | 634.1 | -0.135077 | 3.440025 |
| 1 | 1 | 2.438313e6 | 650.0 | 634.0 | -0.137578 | 3.437549 |
| 1 | 1 | 2.438314e6 | 649.9 | 633.9 | -0.140079 | 3.435073 |
| 1 | 1 | 2.438315e6 | 649.9 | 633.9 | -0.140079 | 3.435073 |
| 1 | 1 | 2.438316e6 | 650.1 | 633.7 | -0.145082 | 3.440025 |
| 1 | 1 | 2.438317e6 | 650.2 | 633.5 | -0.150085 | 3.442501 |
| 1 | 1 | 2.438318e6 | 650.0 | 633.2 | -0.157589 | 3.437549 |
| 1 | 1 | 2.438319e6 | 649.7 | 633.1 | -0.160091 | 3.430121 |
Creating a Heatmap#
Let’s create a heatmap using the heatmap function from the pymovements library. We will use the default gridsize of 10x10 with interpolation and display the colorbar.
[5]:
figure = pm.plotting.heatmap(
gaze=dataset.gaze[5],
position_columns=('x_right_pix', 'y_right_pix'),
origin='upper',
show_cbar=True,
cbar_label='Time [s]',
title='Gaze Heatmap with Interpolation On',
xlabel='X [pix]',
ylabel='Y [pix]',
gridsize=[10, 10]
)
To better understand the effect of the gridsize parameter on the heatmap, we can turn off the interpolation. By doing this, we can clearly visualize the individual bins used to calculate the heatmap. With interpolation turned off, the heatmap will display the raw bin values rather than a smoothed representation.
[6]:
figure = pm.plotting.heatmap(
dataset.gaze[5],
position_columns=('x_right_pix', 'y_right_pix'),
origin='upper',
show_cbar=True,
cbar_label='Time [s]',
title='Gaze Heatmap with Interpolation Off',
xlabel='X [pix]',
ylabel='Y [pix]',
gridsize=[10, 10],
interpolation='none'
)
Increasing the gridsize parameter results in a finer grid and more detailed heatmap representation. With a higher grid size, we divide the plot into smaller bins, which can capture more nuances in the data distribution
[7]:
figure = pm.plotting.heatmap(
dataset.gaze[5],
position_columns=('x_right_pix', 'y_right_pix'),
origin='upper',
show_cbar=True,
cbar_label='Time [s]',
title='Gaze Heatmap with Higher Grid Size',
xlabel='X [pix]',
ylabel='Y [pix]',
gridsize=[25, 25]
)
