{
 "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 fixations using the I-VT algorithm\n",
    "* how to detect saccades using the microsaccades algorithm"
   ]
  },
  {
   "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 I-VT algorithm for detecting fixations and the `microsaccades` algorithm for detecting saccades.\n",
    "\n",
    "We start with the I-VT algorithm to detect fixations using the default parameteres:"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "id": "25b7d79a",
   "metadata": {},
   "outputs": [],
   "source": [
    "dataset.detect_events(pm.events.ivt)"
   ]
  },
  {
   "cell_type": "markdown",
   "id": "5a0b1bc1",
   "metadata": {},
   "source": [
    "The detected events are added 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 detect some saccades. This time we don't use the default parameters but specify our own:"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "id": "a2e450ea",
   "metadata": {},
   "outputs": [],
   "source": [
    "dataset.detect_events(pm.events.microsaccades, minimum_duration=12)\n",
    "\n",
    "dataset.events[0].frame.filter(pl.col('name') == 'saccade').head()"
   ]
  },
  {
   "cell_type": "markdown",
   "id": "acdfbf60",
   "metadata": {},
   "source": [
    "This has added new rows with the saccade events to the event dataframe."
   ]
  },
  {
   "cell_type": "markdown",
   "id": "11e1f88e",
   "metadata": {},
   "source": [
    " "
   ]
  },
  {
   "cell_type": "markdown",
   "id": "c448ef0d",
   "metadata": {},
   "source": [
    "## What you have learned in this tutorial:\n",
    "\n",
    "* detecting fixations by using `Dataset.detect_events(pm.events.fixations)`\n",
    "* detecting saccades by using `Dataset.detect_events(pm.events.microsaccades)`\n"
   ]
  }
 ],
 "metadata": {},
 "nbformat": 4,
 "nbformat_minor": 5
}