{
 "cells": [
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "# Tutorial: Generating Synthetic Light Curves\n",
    "\n",
    "This notebook demonstrates how to use the `pgmuvi.synthetic` module to:\n",
    "\n",
    "1. Draw synthetic light curves from a GP with known hyperparameters\n",
    "2. Verify that `pgmuvi` can recover those hyperparameters\n",
    "3. Simulate multiband observations with different cadences\n",
    "\n",
    "**Why synthetic data?**\n",
    "\n",
    "Synthetic experiments (sometimes called *simulation-based calibration* or *parameter recovery tests*) are essential for:\n",
    "- Validating that the fitting pipeline is correctly implemented\n",
    "- Understanding parameter degeneracies\n",
    "- Setting realistic expectations about what the data can constrain\n",
    "- Survey planning (e.g., what cadence is needed to detect a given period?)\n",
    "\n",
    "**Prerequisites:** the `pgmuvi_tutorial` notebook."
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "## 1. Setup"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {},
   "outputs": [],
   "source": [
    "import numpy as np\n",
    "import matplotlib.pyplot as plt\n",
    "import pgmuvi\n",
    "import pgmuvi.synthetic"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "## 2. Generating a Synthetic Single-Band Light Curve\n",
    "\n",
    "We specify a set of hyperparameters — one mixture component with a period of 100 days and a modest bandwidth — and draw a realisation from the corresponding GP."
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {},
   "outputs": [],
   "source": [
    "# TODO: Expand with pgmuvi.synthetic API calls once this tutorial is developed\n",
    "# The pgmuvi.synthetic module contains tools for drawing GP samples.\n",
    "\n",
    "# Placeholder: define observation grid\n",
    "rng = np.random.default_rng(0)\n",
    "times = np.sort(rng.uniform(0, 500, 200))\n",
    "print(f\"Synthetic observation grid: {len(times)} points over {times[-1]:.0f} days\")"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "## 3. Fitting the Synthetic Data\n",
    "\n",
    "We fit a GP model to the synthetic data and check that the inferred period matches the input period."
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {},
   "outputs": [],
   "source": [
    "# TODO: Expand with GP MAP fitting via fit(model=\"1D\") and compare inferred\n",
    "# parameters against the true synthetic values. Optionally call fit_LS() first\n",
    "# to inspect candidate periods / diagnostics."
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "## 4. Parameter Recovery: Varying Cadence\n",
    "\n",
    "Here we repeat the synthetic experiment with different observation cadences to understand the minimum sampling required to detect the 100-day period."
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {},
   "outputs": [],
   "source": [
    "# TODO: Loop over cadences and summarise recovery fraction"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "## 5. Multiband Synthetic Data\n",
    "\n",
    "We demonstrate generating a synthetic two-band light curve where the variability amplitude changes with wavelength."
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {},
   "outputs": [],
   "source": [
    "# TODO: Expand with 2D synthetic example using pgmuvi.synthetic"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "## Next Steps\n",
    "\n",
    "- See the `pgmuvi.synthetic` API reference in the documentation for the full list of available functions.\n",
    "- For MCMC-based parameter uncertainty: MCMC support (`mcmc()`) is planned for a future release and is not yet available.\n",
    "- For sampling quality assessment, see the *Preprocessing* tutorial."
   ]
  }
 ],
 "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
}