{
 "cells": [
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "# Tutorial: Preprocessing and Data Quality Assessment\n",
    "\n",
    "This notebook walks through the preprocessing tools available in `pgmuvi`:\n",
    "\n",
    "1. Checking whether a source is variable\n",
    "2. Assessing sampling quality (Nyquist period, detectable range)\n",
    "3. Filtering poorly sampled or non-variable bands\n",
    "4. Subsampling dense datasets\n",
    "\n",
    "**Prerequisites:** you should be familiar with loading data into a `Lightcurve` object (see the *Loading Data* how-to guide and the basic `pgmuvi_tutorial` notebook)."
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "## 1. Setup\n",
    "\n",
    "We begin by generating a synthetic light curve with known properties so that we can verify the outputs of the preprocessing tools.\n",
    "\n",
    "> **TODO:** Replace the synthetic example below with a real observational dataset once this tutorial is expanded."
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {},
   "outputs": [],
   "source": [
    "import numpy as np\n",
    "import pgmuvi\n",
    "\n",
    "# --- Placeholder: generate synthetic data ---\n",
    "# TODO: expand with pgmuvi.synthetic once the synthetic tutorial is complete\n",
    "rng = np.random.default_rng(42)\n",
    "times = np.sort(rng.uniform(0, 1000, 300))\n",
    "period = 100.0\n",
    "fluxes = 1.0 + 0.3 * np.sin(2 * np.pi * times / period) + rng.normal(0, 0.05, len(times))\n",
    "errors = np.full_like(fluxes, 0.05)\n",
    "\n",
    "lc = pgmuvi.lightcurve.Lightcurve(times, fluxes, errors)\n",
    "print(f\"Number of observations: {len(times)}\")"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "## 2. Variability Detection\n",
    "\n",
    "`pgmuvi` provides three complementary variability statistics:\n",
    "- **Weighted χ²** against a constant-flux null model\n",
    "- **F_var** (fractional excess variance)\n",
    "- **Stetson K** index\n",
    "\n",
    "See the *Concepts* page in the documentation for a description of each statistic."
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {},
   "outputs": [],
   "source": [
    "# TODO: expand once API is verified\n",
    "result = lc.check_variability()\n",
    "print(result)"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "## 3. Sampling Quality Assessment\n",
    "\n",
    "Before fitting, it is important to know the range of periods that can be detected given the cadence and baseline of the observations."
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {},
   "outputs": [],
   "source": [
    "# TODO: expand with interpretation of output\n",
    "metrics = lc.compute_sampling_metrics()\n",
    "print(metrics)\n",
    "\n",
    "# Plain-language assessment\n",
    "lc.assess_sampling_quality()"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "## 4. Subsampling Dense Datasets\n",
    "\n",
    "GP inference scales as O(N³), so subsampling can dramatically reduce computation time while retaining the information content needed to detect variability.\n",
    "\n",
    "The `subsample_lightcurve` function in `pgmuvi.preprocess` performs gap-preserving random subsampling."
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {},
   "outputs": [],
   "source": [
    "from pgmuvi.preprocess import subsample_lightcurve\n",
    "\n",
    "# subsample_lightcurve takes only the 1-D time array and returns indices\n",
    "t = lc.xdata.cpu().numpy()\n",
    "f = lc.ydata.cpu().numpy()\n",
    "e = lc.yerr.cpu().numpy()\n",
    "\n",
    "# TODO: expand with visualisation of before/after subsampling\n",
    "idx = subsample_lightcurve(t, max_samples=100)\n",
    "print(f\"Subsampled from {len(t)} to {len(idx)} observations\")\n",
    "\n",
    "lc_sub = pgmuvi.lightcurve.Lightcurve(t[idx], f[idx], e[idx])\n",
    "lc_sub.assess_sampling_quality()"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "## Next Steps\n",
    "\n",
    "- Once you have verified data quality, proceed to the `pgmuvi_tutorial` notebook for GP fitting.\n",
    "- For multiband data, see the `pgmuvi_tutorial_2d` notebook.\n",
    "- For more detail on the preprocessing API, see the `pgmuvi.preprocess` API reference in the documentation."
   ]
  }
 ],
 "metadata": {
  "kernelspec": {
   "display_name": "Python 3",
   "language": "python",
   "name": "python3"
  },
  "language_info": {
   "name": "python",
   "version": "3.10.0"
  },
  "nbsphinx": {
   "execute": "never"
  }
 },
 "nbformat": 4,
 "nbformat_minor": 4
}