{
 "cells": [
  {
   "cell_type": "markdown",
   "id": "17b91b54",
   "metadata": {},
   "source": "# Inspecting Data Quality"
  },
  {
   "cell_type": "markdown",
   "id": "7abb9eed",
   "metadata": {},
   "source": [
    "After loading and initial inspection of raw gaze data, the next step is to\n",
    "assess data quality. High-quality data is essential for reliable analysis\n",
    "and interpretation of eye-tracking results. Common data quality issues\n",
    "include missing data, noise, drift, and artifacts caused by blinks or\n",
    "head movements."
   ]
  },
  {
   "cell_type": "markdown",
   "id": "8410aa2f",
   "metadata": {},
   "source": [
    "## Inspecting Data Loss\n",
    "\n",
    "Data loss can occur during tracking due to blinks, tracking errors, or\n",
    "participants looking away from the screen. The length and frequency of\n",
    "consecutive data-loss segments are useful indicators of overall dataset\n",
    "usability. The function {py:func}`~pymovements.plotting.data_loss_histogram` plots\n",
    "the distribution of consecutive missing-data chunk lengths (expressed in\n",
    "samples or time), which makes it easy to see whether loss is mostly\n",
    "brief (e.g. short blinks) or prolonged (e.g. long tracking failures)."
   ]
  },
  {
   "metadata": {
    "tags": [
     "hide-input",
     "remove-stderr"
    ]
   },
   "cell_type": "code",
   "outputs": [],
   "execution_count": null,
   "source": [
    "import matplotlib.pyplot as plt\n",
    "\n",
    "import pymovements as pm\n",
    "from pymovements.gaze.experiment import Experiment\n",
    "\n",
    "# Create an Experiment with the appropriate display geometry\n",
    "experiment = Experiment(\n",
    "    screen_width_px=1280,\n",
    "    screen_height_px=1024,\n",
    "    screen_width_cm=38,\n",
    "    screen_height_cm=30.2,\n",
    "    distance_cm=68,\n",
    "    origin='upper left',\n",
    "    sampling_rate=250.0,\n",
    ")\n",
    "\n",
    "# Load a dataset that contains simulated blinks / tracking loss\n",
    "gaze_with_loss = pm.gaze.from_csv(\n",
    "    '../examples/gaze-with-loss.csv',\n",
    "    experiment=experiment,\n",
    "    time_column='time',\n",
    "    pixel_columns=['x', 'y']\n",
    ")\n",
    "\n",
    "# Plot the data-loss histogram in units of time\n",
    "pm.plotting.data_loss_histogram(\n",
    "    gaze_with_loss,\n",
    "    column='pixel',\n",
    "    unit='time',\n",
    "    sampling_rate=experiment.sampling_rate,\n",
    ")\n",
    "plt.show()"
   ],
   "id": "344fd16b21942330"
  },
  {
   "cell_type": "markdown",
   "id": "f2eae4df",
   "metadata": {},
   "source": [
    "### Interpretation\n",
    "\n",
    "Short, infrequent gaps often reflect normal blinks or brief signal dropouts\n",
    "and are commonly tolerated or interpolated in preprocessing. A large number\n",
    "of long gaps suggests severe tracking problems and may warrant re-collection\n",
    "or exclusion of affected trials or participants.\n"
   ]
  }
 ],
 "metadata": {},
 "nbformat": 4,
 "nbformat_minor": 5
}