{
  "cells": [
    {
      "cell_type": "markdown",
      "metadata": {},
      "source": [
        "# Lesson 17: Capstone Senior Readiness Project\n",
        "\n",
        "**CS230 inspiration:** Project proposal, milestone, final report, poster session, and reading research papers.\n",
        "\n",
        "**Demand forecasting focus:** Plan and execute an end-to-end demand forecasting project with senior-level rigor.\n",
        "\n",
        "**Learning objectives**\n",
        "\n",
        "- Define a project proposal with data, metrics, baselines, risks, and expected decisions.\n",
        "- Run a milestone review using evidence instead of narrative alone.\n",
        "- Prepare a final report and presentation that withstand technical scrutiny.\n",
        "\n",
        "**Senior-readiness checkpoint:** You can own a forecasting project from ambiguous problem statement to production-ready recommendation.\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": [
        "## Capstone Brief\n",
        "\n",
        "Choose a retail, marketplace, supply-chain, staffing, or capacity-planning demand problem. Your job is to produce forecasts and a decision-ready recommendation. The final artifact should include baselines, at least one deep learning model, uncertainty, error analysis, operational constraints, and a deployment or monitoring plan.\n"
      ]
    },
    {
      "cell_type": "markdown",
      "metadata": {},
      "source": [
        "## Code Cell 2 Explanation\n",
        "\n",
        "**What this cell does:** This cell advances **Capstone Senior Readiness Project** by working on the lesson workflow. It creates or updates `rubric` 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: Plan and execute an end-to-end demand forecasting project with senior-level rigor. 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": [
        "rubric = pd.DataFrame(\n",
        "    [\n",
        "        (\"Problem framing\", 10, \"Target, horizon, grain, decision, and cost of errors are explicit.\"),\n",
        "        (\"Data quality\", 15, \"Leakage, missingness, stockouts, and feature availability are addressed.\"),\n",
        "        (\"Baselines\", 10, \"Seasonal naive and at least one strong classical baseline are included.\"),\n",
        "        (\"Deep learning\", 20, \"Architecture is justified and compared fairly.\"),\n",
        "        (\"Uncertainty\", 10, \"Quantiles or intervals support a business decision.\"),\n",
        "        (\"Error analysis\", 15, \"Failures are sliced by meaningful operational segments.\"),\n",
        "        (\"System readiness\", 10, \"Inference, monitoring, retraining, and fallback plans are credible.\"),\n",
        "        (\"Communication\", 10, \"Results are clear, honest, and decision-focused.\"),\n",
        "    ],\n",
        "    columns=[\"category\", \"points\", \"evidence\"],\n",
        ")\n",
        "rubric\n"
      ]
    },
    {
      "cell_type": "markdown",
      "metadata": {},
      "source": [
        "## Code Cell 3 Explanation\n",
        "\n",
        "**What this cell does:** This cell advances **Capstone Senior Readiness Project** by working on the lesson workflow. It creates or updates `milestones` 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: Plan and execute an end-to-end demand forecasting project with senior-level rigor. 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": [
        "milestones = pd.DataFrame(\n",
        "    [\n",
        "        (\"Proposal\", \"Define forecast grain, horizon, metric, data sources, and baseline plan.\"),\n",
        "        (\"Milestone 1\", \"Deliver clean backtest split, baselines, and first neural model.\"),\n",
        "        (\"Milestone 2\", \"Deliver tuned model, uncertainty, and error analysis.\"),\n",
        "        (\"Final\", \"Deliver report, reproducible notebooks, model card, and deployment plan.\"),\n",
        "    ],\n",
        "    columns=[\"milestone\", \"acceptance criteria\"],\n",
        ")\n",
        "milestones\n"
      ]
    },
    {
      "cell_type": "markdown",
      "metadata": {},
      "source": [
        "## Code Cell 4 Explanation\n",
        "\n",
        "**What this cell does:** This cell advances **Capstone Senior Readiness Project** by working on forecast metrics. It creates or updates `sample_actual`, `sample_model`, `sample_baseline` 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: Plan and execute an end-to-end demand forecasting project with senior-level rigor. Each object is kept inspectable so the learner can connect code, assumptions, and modeling consequences.\n",
        "\n",
        "**Key operations to notice:** evaluates scale-weighted forecast error\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": [
        "def grade_forecast_run(actual, prediction, baseline_prediction, max_wmape=0.35):\n",
        "    model_wmape = wmape(actual, prediction)\n",
        "    baseline_wmape = wmape(actual, baseline_prediction)\n",
        "    return {\n",
        "        \"model_wmape\": model_wmape,\n",
        "        \"baseline_wmape\": baseline_wmape,\n",
        "        \"beats_baseline\": model_wmape < baseline_wmape,\n",
        "        \"meets_quality_bar\": model_wmape <= max_wmape,\n",
        "        \"relative_improvement\": (baseline_wmape - model_wmape) / baseline_wmape,\n",
        "    }\n",
        "\n",
        "sample_actual = np.array([100, 120, 80, 90])\n",
        "sample_model = np.array([95, 126, 88, 92])\n",
        "sample_baseline = np.array([110, 110, 100, 100])\n",
        "grade_forecast_run(sample_actual, sample_model, sample_baseline)\n"
      ]
    },
    {
      "cell_type": "markdown",
      "metadata": {},
      "source": [
        "## Lesson Recap\n",
        "\n",
        "In this lesson, we used 4 runnable code cells to work through **Capstone Senior Readiness Project**. The practical focus was: Plan and execute an end-to-end demand forecasting project with senior-level rigor.\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",
        "- Define a project proposal with data, metrics, baselines, risks, and expected decisions.\n",
        "- Run a milestone review using evidence instead of narrative alone.\n",
        "- Prepare a final report and presentation that withstand technical scrutiny.\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 own a forecasting project from ambiguous problem statement to production-ready recommendation.\n"
      ]
    },
    {
      "cell_type": "markdown",
      "metadata": {},
      "source": [
        "## Exercises\n",
        "\n",
        "- Write your capstone proposal in one page.\n",
        "- Choose which architecture you will defend and which baseline you fear most.\n",
        "- Create a final report outline with figures and tables you expect to include.\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
}