{
 "cells": [
  {
   "cell_type": "markdown",
   "id": "2ef64b5b",
   "metadata": {},
   "source": [
    "# Time Series Plots\n",
    "\n",
    "Time-series EDA assumes the model **y = f(t) + e** — a signal component\n",
    "plus random error.  The plots in this section reveal dominant frequencies,\n",
    "autocorrelation structure, and the amplitude/phase evolution of the\n",
    "signal.\n",
    "\n",
    "All time-series plots require a continuous index variable `t`\n",
    "(not restricted to calendar time — scan number, wavelength, and\n",
    "position all qualify).\n",
    "\n",
    "Reference: [NIST Handbook Chapter 1.3.3](https://www.itl.nist.gov/div898/handbook/eda/section3/eda33.htm)"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "id": "a9f4b6c9",
   "metadata": {},
   "outputs": [],
   "source": [
    "%matplotlib inline\n",
    "import numpy as np\n",
    "import matplotlib.pyplot as plt\n",
    "from drippy import EDAData\n",
    "from drippy import (\n",
    "    run_sequence_plot,\n",
    "    spectral_plot,\n",
    "    autocorrelation_plot,\n",
    "    complex_demodulation_amplitude_plot,\n",
    "    complex_demodulation_phase_plot,\n",
    ")\n",
    "\n",
    "rng = np.random.default_rng(42)\n",
    "\n",
    "# 200-point sinusoidal signal — beam-deflection-like measurement\n",
    "t = np.linspace(0, 10, 200)\n",
    "noise = rng.normal(scale=0.5, size=200)\n",
    "y = 2.0 * np.sin(2 * np.pi * 0.5 * t) + noise\n",
    "data = EDAData(y=y, t=t)"
   ]
  },
  {
   "cell_type": "markdown",
   "id": "f868aa93",
   "metadata": {},
   "source": [
    "## Run Sequence Plot  (NIST 1.3.3.25)\n",
    "\n",
    "The run-sequence plot is the natural first step for time-series data.\n",
    "When `t` is provided, it becomes the x-axis, giving the correct physical\n",
    "scale."
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "id": "fcfee60a",
   "metadata": {},
   "outputs": [],
   "source": [
    "fig, ax = run_sequence_plot(data)\n",
    "plt.show()"
   ]
  },
  {
   "cell_type": "markdown",
   "id": "4fe11b49",
   "metadata": {},
   "source": [
    "## Spectral Plot  (NIST 1.3.3.27)\n",
    "\n",
    "The Lomb-Scargle periodogram estimates the power spectral density,\n",
    "identifying dominant frequencies even for unevenly-sampled data.\n",
    "Optional false alarm probability (FAP) levels flag statistically\n",
    "significant peaks."
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "id": "0e5d6b4b",
   "metadata": {},
   "outputs": [],
   "source": [
    "fig, ax = spectral_plot(data)\n",
    "plt.show()"
   ]
  },
  {
   "cell_type": "markdown",
   "id": "61f8c3e8",
   "metadata": {},
   "source": [
    "The dominant peak at 0.5 Hz recovers the known signal frequency.\n",
    "Without alarm levels:"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "id": "14ad0091",
   "metadata": {},
   "outputs": [],
   "source": [
    "fig, ax = spectral_plot(data, alarm_levels=False)\n",
    "plt.show()"
   ]
  },
  {
   "cell_type": "markdown",
   "id": "5db72aba",
   "metadata": {},
   "source": [
    "## Autocorrelation Plot  (NIST 1.3.3.1)\n",
    "\n",
    "Plots the autocorrelation function (ACF) with 80%, 95%, and 99%\n",
    "confidence bands.  Lags whose bars exceed the bands indicate significant\n",
    "autocorrelation — evidence of non-randomness at that lag."
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "id": "327944c1",
   "metadata": {},
   "outputs": [],
   "source": [
    "fig, ax = autocorrelation_plot(data)\n",
    "plt.show()"
   ]
  },
  {
   "cell_type": "markdown",
   "id": "7a073469",
   "metadata": {},
   "source": [
    "## Complex Demodulation Amplitude Plot  (NIST 1.3.3.11)\n",
    "\n",
    "Demodulates the signal at its dominant frequency and plots the\n",
    "instantaneous amplitude envelope.  A flat envelope indicates a\n",
    "stationary amplitude; rising or falling envelopes reveal non-stationarity."
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "id": "37c49aa9",
   "metadata": {},
   "outputs": [],
   "source": [
    "fig, ax = complex_demodulation_amplitude_plot(data)\n",
    "plt.show()"
   ]
  },
  {
   "cell_type": "markdown",
   "id": "6e8095d7",
   "metadata": {},
   "source": [
    "## Complex Demodulation Phase Plot  (NIST 1.3.3.12)\n",
    "\n",
    "Plots the unwrapped instantaneous phase with a linear trend fit.\n",
    "Deviations from the trend indicate frequency modulation or\n",
    "phase noise in the signal."
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "id": "fb62d676",
   "metadata": {},
   "outputs": [],
   "source": [
    "fig, ax = complex_demodulation_phase_plot(data)\n",
    "plt.show()"
   ]
  }
 ],
 "metadata": {
  "kernelspec": {
   "display_name": "Python 3",
   "language": "python",
   "name": "python3"
  },
  "language_info": {
   "name": "python",
   "version": "3.12.0"
  }
 },
 "nbformat": 4,
 "nbformat_minor": 5
}