{
 "cells": [
  {
   "cell_type": "markdown",
   "id": "011263bd",
   "metadata": {},
   "source": [
    "# Detecting Gaze Events"
   ]
  },
  {
   "cell_type": "markdown",
   "id": "2d09e462",
   "metadata": {},
   "source": [
    "## What you will learn in this tutorial:\n",
    "\n",
    "* how to detect saccades using the microsaccades algorithm\n",
    "* how to detect fixations using the I-DT and I-VT algorithms"
   ]
  },
  {
   "cell_type": "markdown",
   "id": "d6365d21",
   "metadata": {},
   "source": [
    "## Preparations"
   ]
  },
  {
   "cell_type": "markdown",
   "id": "58f22201",
   "metadata": {},
   "source": [
    "We import `pymovements` as the alias `pm` for convenience."
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "id": "a3caa146",
   "metadata": {},
   "outputs": [],
   "source": [
    "import polars as pl\n",
    "\n",
    "import pymovements as pm"
   ]
  },
  {
   "cell_type": "markdown",
   "id": "532d4aa6",
   "metadata": {},
   "source": [
    "Let's start by downloading our `ToyDataset` and loading in its data:"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "id": "375b5f97",
   "metadata": {},
   "outputs": [],
   "source": [
    "dataset = pm.Dataset('ToyDataset', path='data/ToyDataset')\n",
    "dataset.download()\n",
    "dataset.load()"
   ]
  },
  {
   "cell_type": "markdown",
   "id": "6b57001a",
   "metadata": {},
   "source": [
    "Now let's do some basic preprocessing:"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "id": "5df0408a",
   "metadata": {},
   "outputs": [],
   "source": [
    "dataset.pix2deg()\n",
    "dataset.pos2vel('smooth')\n",
    "\n",
    "dataset.gaze[0].frame.head()"
   ]
  },
  {
   "cell_type": "markdown",
   "id": "2c14584d",
   "metadata": {},
   "source": [
    "## Detecting Events"
   ]
  },
  {
   "cell_type": "markdown",
   "id": "cc12e58d",
   "metadata": {},
   "source": [
    "*pymovements* provides a range of event detection methods for several types of gaze events.\n",
    "\n",
    "See the reference for [pymovements.events](https://pymovements.readthedocs.io/en/latest/reference/pymovements.events.html) to get an overview of all the supported methods.\n",
    "\n",
    "For this tutorial we will use the `microsaccades` algorithm for detecting saccades and the I-DT and I-VT algorithms for detecting fixations."
   ]
  },
  {
   "cell_type": "markdown",
   "id": "b10421cf",
   "metadata": {},
   "source": [
    "We start out by detecting saccades."
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "id": "a2e450ea",
   "metadata": {},
   "outputs": [],
   "source": [
    "dataset.detect_events('microsaccades', minimum_duration=12)"
   ]
  },
  {
   "cell_type": "markdown",
   "id": "5a0b1bc1",
   "metadata": {},
   "source": [
    "The detected events are added as rows with the name `saccade` to the event dataframe:"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "id": "b1b05082",
   "metadata": {},
   "outputs": [],
   "source": [
    "dataset.events[0].frame.head()"
   ]
  },
  {
   "cell_type": "markdown",
   "id": "a9968885",
   "metadata": {},
   "source": [
    "Next we will detect fixations using the I-DT and I-VT algorithms.\n",
    "\n",
    "To be able to differentiate between the detected events, we specify custom event names for each algorithm:"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "id": "32d700e9",
   "metadata": {},
   "outputs": [],
   "source": [
    "dataset.detect_events('idt', dispersion_threshold=2.7, name='fixation.idt')\n",
    "dataset.detect_events('ivt', velocity_threshold=20, name='fixation.ivt')"
   ]
  },
  {
   "cell_type": "markdown",
   "id": "acdfbf60",
   "metadata": {},
   "source": [
    "This has added new rows with the fixation events to the event dataframe."
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "id": "8f3ea55b",
   "metadata": {},
   "outputs": [],
   "source": [
    "dataset.events[0].frame.filter(pl.col('name') == 'fixation.idt').head()"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "id": "5ebab23c",
   "metadata": {},
   "outputs": [],
   "source": [
    "dataset.events[0].frame.filter(pl.col('name') == 'fixation.ivt').head()"
   ]
  },
  {
   "cell_type": "markdown",
   "id": "11e1f88e",
   "metadata": {},
   "source": [
    " "
   ]
  },
  {
   "cell_type": "markdown",
   "id": "c448ef0d",
   "metadata": {},
   "source": [
    "## What you have learned in this tutorial:\n",
    "\n",
    "* detecting saccades by using the microsaccades algorithm\n",
    "* detecting fixations by using the I-DT and I-VT algorithms"
   ]
  }
 ],
 "metadata": {},
 "nbformat": 4,
 "nbformat_minor": 5
}