{
 "cells": [
  {
   "cell_type": "markdown",
   "id": "011263bd",
   "metadata": {},
   "source": [
    "# Computing Event Properties"
   ]
  },
  {
   "cell_type": "markdown",
   "id": "2d09e462",
   "metadata": {},
   "source": [
    "## What you will learn in this tutorial:\n",
    "\n",
    "* how to add event properties for peak velocity and amplitude"
   ]
  },
  {
   "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 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 and detect some saccades:"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "id": "50bd564e",
   "metadata": {},
   "outputs": [],
   "source": [
    "dataset.pix2deg()\n",
    "dataset.pos2vel('smooth')\n",
    "\n",
    "dataset.detect_events('microsaccades')\n",
    "\n",
    "dataset.events[0].frame.head()"
   ]
  },
  {
   "cell_type": "markdown",
   "id": "2c14584d",
   "metadata": {},
   "source": [
    "## Computing Event Properties"
   ]
  },
  {
   "cell_type": "markdown",
   "id": "cc12e58d",
   "metadata": {},
   "source": [
    "*pymovements* provides a range of event properties.\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 properties.\n",
    "\n",
    "For this tutorial we will compute several properties of saccades.\n",
    "\n",
    "We start out with the peak velocity:"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "id": "f2919a8e",
   "metadata": {},
   "outputs": [],
   "source": [
    "dataset.compute_event_properties(\"peak_velocity\")\n",
    "\n",
    "dataset.events[0].frame.head()"
   ]
  },
  {
   "cell_type": "markdown",
   "id": "cd7cc417",
   "metadata": {},
   "source": [
    "We notice that a new column with the name `peak_velocity` has appeared in the event dataframe.\n",
    "\n",
    "We can also pass a list of properties. Let's add the amplitude and dispersion:"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "id": "ddd156c0",
   "metadata": {},
   "outputs": [],
   "source": [
    "dataset.compute_event_properties([\"amplitude\", \"dispersion\"])\n",
    "\n",
    "dataset.events[0].frame.head()"
   ]
  },
  {
   "cell_type": "markdown",
   "id": "051ebe61",
   "metadata": {},
   "source": [
    "This way we can compute all of our desired properties in a single run."
   ]
  },
  {
   "cell_type": "markdown",
   "id": "11e1f88e",
   "metadata": {},
   "source": [
    " "
   ]
  },
  {
   "cell_type": "markdown",
   "id": "c448ef0d",
   "metadata": {},
   "source": [
    "## What you have learned in this tutorial:\n",
    "\n",
    "* how to compute event properties by using `Dataset.compute_event_properties()`\n"
   ]
  }
 ],
 "metadata": {},
 "nbformat": 4,
 "nbformat_minor": 5
}