{
 "cells": [
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "# Heatmap Plotting\n",
    "\n",
    "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."
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "## Preparations"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "We import `pymovements` as the alias `pm` for convenience."
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {},
   "outputs": [],
   "source": [
    "import pymovements as pm"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "## Loading the Dataset\n",
    "\n",
    "Let's start by downloading our `ToyDataset` and loading in its data:"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {},
   "outputs": [],
   "source": [
    "dataset = pm.Dataset('ToyDataset', path='data/ToyDataset')\n",
    "dataset.download()\n",
    "dataset.load()"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "After loading the dataset, we will transform the pixel coordinates to degrees."
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {},
   "outputs": [],
   "source": [
    "dataset.pix2deg()"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "We now have a `position` column available: "
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {},
   "outputs": [],
   "source": [
    "dataset.gaze[5].frame"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "## Creating a Heatmap\n",
    "\n",
    "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."
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {},
   "outputs": [],
   "source": [
    "figure = pm.plotting.heatmap(\n",
    "    gaze=dataset.gaze[5],\n",
    "    position_column='pixel',\n",
    "    origin='upper',\n",
    "    show_cbar=True,\n",
    "    cbar_label='Time [s]',\n",
    "    title='Gaze Heatmap with Interpolation On',\n",
    "    xlabel='X [pix]',\n",
    "    ylabel='Y [pix]',\n",
    "    gridsize=[10, 10]\n",
    ")"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "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."
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {},
   "outputs": [],
   "source": [
    "figure = pm.plotting.heatmap(\n",
    "    dataset.gaze[5],\n",
    "    position_column='pixel',\n",
    "    origin='upper',\n",
    "    show_cbar=True,\n",
    "    cbar_label='Time [s]',\n",
    "    title='Gaze Heatmap with Interpolation Off',\n",
    "    xlabel='X [pix]',\n",
    "    ylabel='Y [pix]',\n",
    "    gridsize=[10, 10],\n",
    "    interpolation='none'\n",
    ")"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "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"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {},
   "outputs": [],
   "source": [
    "figure = pm.plotting.heatmap(\n",
    "    dataset.gaze[5],\n",
    "    position_column='pixel',\n",
    "    origin='upper',\n",
    "    show_cbar=True,\n",
    "    cbar_label='Time [s]',\n",
    "    title='Gaze Heatmap with Higher Grid Size',\n",
    "    xlabel='X [pix]',\n",
    "    ylabel='Y [pix]',\n",
    "    gridsize=[25, 25]\n",
    ")"
   ]
  }
 ],
 "metadata": {},
 "nbformat": 4,
 "nbformat_minor": 1
}