{
  "cells": [
    {
      "cell_type": "markdown",
      "metadata": {},
      "source": [
        "# Lesson 00: Course Orientation and Forecasting Dataset\n",
        "\n",
        "**CS230 inspiration:** Course introduction, examples of deep learning projects, and full-cycle project thinking.\n",
        "\n",
        "**Demand forecasting focus:** Map the curriculum to a realistic retail demand panel with seasonality, prices, promotions, holidays, and stockouts.\n",
        "\n",
        "**Learning objectives**\n",
        "\n",
        "- Understand the course path from neural-network basics to production forecasting systems.\n",
        "- Inspect the synthetic demand data used across lessons.\n",
        "- Connect CS230 themes to demand forecasting decisions.\n",
        "\n",
        "**Senior-readiness checkpoint:** You can explain how data generation, evaluation, modeling, and deployment concerns fit into one forecasting project.\n"
      ]
    },
    {
      "cell_type": "markdown",
      "metadata": {},
      "source": [
        "## Code Cell 1 Explanation\n",
        "\n",
        "**What this cell does:** This setup cell imports the shared scientific Python stack and the curriculum helpers used by later cells. It also establishes the deterministic seed convention so repeated runs are comparable.\n",
        "\n",
        "**Why it matters:** A restart-and-run notebook should make its dependencies explicit before any modeling work begins. For forecasting, reproducibility is especially important because small data or seed changes can change validation conclusions.\n",
        "\n",
        "**Key operations to notice:** confirm that shared helper imports match the lesson's code path; check that `SEED` is defined before any generated data or model training\n",
        "\n",
        "**What to inspect:** Check that imports are grouped by purpose: general analysis packages, forecasting data helpers, metrics, plotting utilities, and any lesson-specific libraries.\n"
      ]
    },
    {
      "cell_type": "code",
      "execution_count": null,
      "metadata": {},
      "outputs": [],
      "source": [
        "import matplotlib.pyplot as plt\n",
        "import numpy as np\n",
        "import pandas as pd\n",
        "\n",
        "from demand_forecasting_curriculum.data import (\n",
        "    DEFAULT_FEATURE_COLUMNS,\n",
        "    generate_daily_demand,\n",
        "    make_sequence_dataset,\n",
        "    make_supervised_table,\n",
        "    time_series_split,\n",
        ")\n",
        "from demand_forecasting_curriculum.metrics import (\n",
        "    interval_coverage,\n",
        "    mase,\n",
        "    pinball_loss,\n",
        "    smape,\n",
        "    wmape,\n",
        ")\n",
        "from demand_forecasting_curriculum.plotting import plot_predictions, plot_series\n",
        "\n",
        "SEED = 42\n",
        "np.random.seed(SEED)\n"
      ]
    },
    {
      "cell_type": "markdown",
      "metadata": {},
      "source": [
        "## Code Cell 2 Explanation\n",
        "\n",
        "**What this cell does:** This cell advances **Course Orientation and Forecasting Dataset** by working on synthetic demand generation, time-based splitting. It creates or updates `df`, `train_df`, `valid_df`, `test_df` and prepares evidence that later cells use rather than hiding state in prose.\n",
        "\n",
        "**Why it matters:** The goal is tied to this lesson's forecasting focus: Map the curriculum to a realistic retail demand panel with seasonality, prices, promotions, holidays, and stockouts. Each object is kept inspectable so the learner can connect code, assumptions, and modeling consequences.\n",
        "\n",
        "**Key operations to notice:** creates a synthetic retail panel with known demand drivers; keeps train, validation, and test windows ordered by date\n",
        "\n",
        "**What to inspect:** Before moving on, inspect shapes, date ranges, metric values, segment behavior, or generated tables. If a value looks surprisingly good, surprisingly bad, or unavailable at forecast time, treat that as a modeling clue.\n"
      ]
    },
    {
      "cell_type": "code",
      "execution_count": null,
      "metadata": {},
      "outputs": [],
      "source": [
        "df = generate_daily_demand(n_stores=4, n_items=6, periods=540, seed=SEED)\n",
        "train_df, valid_df, test_df = time_series_split(df, valid_days=60, test_days=60)\n",
        "\n",
        "print(df.shape)\n",
        "df.head()\n"
      ]
    },
    {
      "cell_type": "markdown",
      "metadata": {},
      "source": [
        "## Code Cell 3 Explanation\n",
        "\n",
        "**What this cell does:** This cell advances **Course Orientation and Forecasting Dataset** by working on the lesson workflow. It creates or updates `split_summary` and prepares evidence that later cells use rather than hiding state in prose.\n",
        "\n",
        "**Why it matters:** The goal is tied to this lesson's forecasting focus: Map the curriculum to a realistic retail demand panel with seasonality, prices, promotions, holidays, and stockouts. Each object is kept inspectable so the learner can connect code, assumptions, and modeling consequences.\n",
        "\n",
        "**Key operations to notice:** creates an inspectable table for assumptions, metrics, or decisions\n",
        "\n",
        "**What to inspect:** Before moving on, inspect shapes, date ranges, metric values, segment behavior, or generated tables. If a value looks surprisingly good, surprisingly bad, or unavailable at forecast time, treat that as a modeling clue.\n"
      ]
    },
    {
      "cell_type": "code",
      "execution_count": null,
      "metadata": {},
      "outputs": [],
      "source": [
        "split_summary = pd.DataFrame(\n",
        "    {\n",
        "        \"split\": [\"train\", \"valid\", \"test\"],\n",
        "        \"rows\": [len(train_df), len(valid_df), len(test_df)],\n",
        "        \"start\": [train_df[\"date\"].min(), valid_df[\"date\"].min(), test_df[\"date\"].min()],\n",
        "        \"end\": [train_df[\"date\"].max(), valid_df[\"date\"].max(), test_df[\"date\"].max()],\n",
        "    }\n",
        ")\n",
        "split_summary\n"
      ]
    },
    {
      "cell_type": "markdown",
      "metadata": {},
      "source": [
        "## Code Cell 4 Explanation\n",
        "\n",
        "**What this cell does:** This cell advances **Course Orientation and Forecasting Dataset** by working on visualization. It creates or updates `ax` and prepares evidence that later cells use rather than hiding state in prose.\n",
        "\n",
        "**Why it matters:** The goal is tied to this lesson's forecasting focus: Map the curriculum to a realistic retail demand panel with seasonality, prices, promotions, holidays, and stockouts. Each object is kept inspectable so the learner can connect code, assumptions, and modeling consequences.\n",
        "\n",
        "**Key operations to notice:** visualizes model behavior or data quality\n",
        "\n",
        "**What to inspect:** Before moving on, inspect shapes, date ranges, metric values, segment behavior, or generated tables. If a value looks surprisingly good, surprisingly bad, or unavailable at forecast time, treat that as a modeling clue.\n"
      ]
    },
    {
      "cell_type": "code",
      "execution_count": null,
      "metadata": {},
      "outputs": [],
      "source": [
        "ax = plot_series(df, store_id=0, item_id=0)\n",
        "ax.set_title(\"Observed demand for one store-item series\")\n",
        "plt.show()\n"
      ]
    },
    {
      "cell_type": "markdown",
      "metadata": {},
      "source": [
        "## Curriculum Map\n",
        "\n",
        "The path follows CS230's broad progression: foundations, training deep networks, ML strategy, CNNs, sequence models, attention/transformers, interpretability, and project work. Every lesson translates the concept into demand forecasting rather than image or language examples.\n"
      ]
    },
    {
      "cell_type": "markdown",
      "metadata": {},
      "source": [
        "## Code Cell 5 Explanation\n",
        "\n",
        "**What this cell does:** This cell advances **Course Orientation and Forecasting Dataset** by working on the lesson workflow. It creates or updates `curriculum` and prepares evidence that later cells use rather than hiding state in prose.\n",
        "\n",
        "**Why it matters:** The goal is tied to this lesson's forecasting focus: Map the curriculum to a realistic retail demand panel with seasonality, prices, promotions, holidays, and stockouts. Each object is kept inspectable so the learner can connect code, assumptions, and modeling consequences.\n",
        "\n",
        "**Key operations to notice:** creates an inspectable table for assumptions, metrics, or decisions\n",
        "\n",
        "**What to inspect:** Before moving on, inspect shapes, date ranges, metric values, segment behavior, or generated tables. If a value looks surprisingly good, surprisingly bad, or unavailable at forecast time, treat that as a modeling clue.\n"
      ]
    },
    {
      "cell_type": "code",
      "execution_count": null,
      "metadata": {},
      "outputs": [],
      "source": [
        "curriculum = pd.DataFrame(\n",
        "    [\n",
        "        (\"Foundations\", \"What is the target, horizon, baseline, and loss?\"),\n",
        "        (\"Optimization\", \"How do network depth, initialization, regularization, and learning rates change forecast quality?\"),\n",
        "        (\"ML strategy\", \"How do we avoid leakage and diagnose segment failures?\"),\n",
        "        (\"Architectures\", \"When do MLPs, CNNs, RNNs, and transformers help?\"),\n",
        "        (\"Uncertainty\", \"How do quantiles and intervals support inventory decisions?\"),\n",
        "        (\"Production\", \"How do we monitor drift, retrain, and communicate risk?\"),\n",
        "    ],\n",
        "    columns=[\"theme\", \"forecasting question\"],\n",
        ")\n",
        "curriculum\n"
      ]
    },
    {
      "cell_type": "markdown",
      "metadata": {},
      "source": [
        "## Lesson Recap\n",
        "\n",
        "In this lesson, we used 5 runnable code cells to work through **Course Orientation and Forecasting Dataset**. The practical focus was: Map the curriculum to a realistic retail demand panel with seasonality, prices, promotions, holidays, and stockouts.\n",
        "\n",
        "We did this because deep learning for demand forecasting is not only about choosing an architecture. The learner needs to understand the data contract, the target and horizon, the validation path, the metric, and the operational decision supported by the forecast.\n",
        "\n",
        "The core takeaways were:\n",
        "\n",
        "- Understand the course path from neural-network basics to production forecasting systems.\n",
        "- Inspect the synthetic demand data used across lessons.\n",
        "- Connect CS230 themes to demand forecasting decisions.\n",
        "\n",
        "By the end, you should be able to explain not just what the code produced, but why each step was necessary and what could go wrong if the same step were skipped or performed with leakage.\n",
        "\n",
        "**Senior-readiness reminder:** You can explain how data generation, evaluation, modeling, and deployment concerns fit into one forecasting project.\n"
      ]
    },
    {
      "cell_type": "markdown",
      "metadata": {},
      "source": [
        "## Exercises\n",
        "\n",
        "- Pick one item-store series and list three demand drivers you can see or infer.\n",
        "- Change `n_items` or `periods` and inspect how dataset size affects the learning workflow.\n",
        "- Write down one failure mode that a naive random train/test split would hide.\n"
      ]
    }
  ],
  "metadata": {
    "kernelspec": {
      "display_name": "Python (deep-learning-demand)",
      "language": "python",
      "name": "deep-learning-demand"
    },
    "language_info": {
      "codemirror_mode": {
        "name": "ipython",
        "version": 3
      },
      "file_extension": ".py",
      "mimetype": "text/x-python",
      "name": "python",
      "nbconvert_exporter": "python",
      "pygments_lexer": "ipython3",
      "version": "3.12"
    }
  },
  "nbformat": 4,
  "nbformat_minor": 5
}