{
 "cells": [
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "# Tutorial: Model Selection\n",
    "\n",
    "This notebook demonstrates how to select an appropriate GP model for your data in `pgmuvi`:\n",
    "\n",
    "1. Using automated model selection (`auto_select_model()`)\n",
    "2. Manually comparing models using the PSD and predictive plots\n",
    "3. Adjusting `num_mixtures`\n",
    "4. Using alternative kernels (e.g., spectral mixture + RBF, flicker noise)\n",
    "\n",
    "**Prerequisites:** the `pgmuvi_tutorial` notebook and familiarity with the *Model Selection* how-to guide in the documentation."
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "## 1. Setup\n",
    "\n",
    "We load a light curve with a known quasi-periodic signal plus red noise, to illustrate the difference between model choices."
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {},
   "outputs": [],
   "source": [
    "import numpy as np\n",
    "import matplotlib.pyplot as plt\n",
    "import pgmuvi\n",
    "\n",
    "# TODO: Replace with a real or better-motivated synthetic dataset\n",
    "rng = np.random.default_rng(7)\n",
    "times = np.sort(rng.uniform(0, 800, 250))\n",
    "# Signal: quasi-periodic + red-noise-like trend\n",
    "period = 120.0\n",
    "fluxes = (\n",
    "    1.0\n",
    "    + 0.4 * np.sin(2 * np.pi * times / period)\n",
    "    + 0.1 * np.sin(2 * np.pi * times / (period / 2))\n",
    "    + rng.normal(0, 0.06, len(times))\n",
    ")\n",
    "errors = np.full_like(fluxes, 0.06)\n",
    "lc = pgmuvi.lightcurve.Lightcurve(times, fluxes, errors)"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "## 2. Automated Model Selection\n",
    "\n",
    "`auto_select_model()` evaluates the data characteristics and suggests the most appropriate GP model."
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {},
   "outputs": [],
   "source": [
    "# TODO: Expand with auto_select_model() output and interpretation\n",
    "recommended, diagnostics = lc.auto_select_model()\n",
    "print(f\"Recommended model: {recommended}\")\n",
    "if diagnostics.get(\"reason\"):\n",
    "    print(f\"Reason: {diagnostics['reason']}\")"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "## 3. Comparing Models\n",
    "\n",
    "We fit two candidate models and compare their predictive distributions and inferred PSDs."
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {},
   "outputs": [],
   "source": [
    "# Model A: pure spectral mixture (1D)\n",
    "# TODO: Expand with fit(model=\"1D\") (or set_model(\"1D\"); fit()), then plot_psd()\n",
    "# Optionally call fit_LS() first to inspect candidate periods / diagnostics.\n",
    "\n",
    "# Model B: quasi-periodic (single period + coherence decay)\n",
    "# TODO: Expand with fit(model=\"1DQuasiPeriodic\") (or set_model(\"1DQuasiPeriodic\"); fit()), then plot_psd()\n",
    "# For spectral mixture + RBF combinations see the custom-kernel example script."
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "## 4. Choosing `num_mixtures`\n",
    "\n",
    "Here we compare fits with 1, 2, and 4 spectral mixture components to illustrate the effect of model complexity."
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {},
   "outputs": [],
   "source": [
    "# TODO: Loop over num_mixtures values, compare log-likelihood and BIC"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "## 5. Alternative Kernels\n",
    "\n",
    "For advanced users, `pgmuvi` supports alternative kernel structures.  For example,\n",
    "`'1DMatern'` provides a smooth but aperiodic covariance suitable for red-noise-like\n",
    "sources, while `'1DQuasiPeriodic'` models a coherence-decaying periodic signal.\n",
    "See the `alternative_kernels_1d.py` example script for more kernel configurations."
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {},
   "outputs": [],
   "source": [
    "# TODO: Expand with a custom kernel example (e.g. '1DMatern' for red-noise-like behaviour)\n",
    "# or refer to the alternative_kernels_1d.py example script for custom kernel combinations."
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "## Next Steps\n",
    "\n",
    "- See the *Model Selection* how-to guide in the documentation for a summary of all available models.\n",
    "- Once you have selected a model, see the *Interpreting Results* how-to guide.\n",
    "- For rigorous uncertainty quantification: MCMC support (`mcmc()`) is planned for a future release and is not yet available."
   ]
  }
 ],
 "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
}