{
 "cells": [
  {
   "cell_type": "markdown",
   "id": "markdown-1",
   "metadata": {},
   "source": [
    "# 3. Parameters, periods and steps\n",
    "\n",
    "Your first model answered one day, at one hour a value, with nothing to set.\n",
    "Real use asks more of a model. Three questions decide whether it holds up:\n",
    "\n",
    "1. **Parameters**: what may the person calling it change?\n",
    "2. **Periods**: how much may they ask for?\n",
    "3. **Steps**: how often does the data tick?\n",
    "\n",
    "We will answer each with the example `profile_mean`."
   ]
  },
  {
   "cell_type": "code",
   "id": "code-2",
   "metadata": {},
   "source": [
    "import pandas as pd\n",
    "\n",
    "from bff import lab\n",
    "\n",
    "PROFILE = \"../examples/profile_mean\"\n",
    "print(open(f\"{PROFILE}/main.py\").read())"
   ],
   "execution_count": null,
   "outputs": []
  },
  {
   "cell_type": "markdown",
   "id": "markdown-3",
   "metadata": {},
   "source": [
    "## Parameters\n",
    "\n",
    "`profile_mean` forecasts each moment of the day as the mean of the same moment\n",
    "over the last few days. Its declaration names two parameters, each with a\n",
    "default:\n",
    "\n",
    "- `days`, a whole number from 1 to 28: how many past days to average;\n",
    "- `alike`, a choice: `every_day`, or `same_kind`, which averages only working\n",
    "  days for a working day and only weekend days for a weekend day.\n",
    "\n",
    "A screen shows these as a form; the person calling the model fills it\n",
    "in. Here, you pass them to `lab.run` by name.\n",
    "\n",
    "Predict: is the mean of the last day or of the last 28 days the better forecast\n",
    "for a Thursday? Run it to find out."
   ]
  },
  {
   "cell_type": "code",
   "id": "code-4",
   "metadata": {},
   "source": [
    "THURSDAY = dict(start=\"2017-03-08T23:00:00Z\", end=\"2017-03-09T23:00:00Z\",\n",
    "                as_of=\"2017-03-08T08:00:00Z\")\n",
    "\n",
    "def mae(answer):\n",
    "    forecast = answer[\"forecast\"][\"value\"]\n",
    "    actual = lab.series(\"epf.price\", answer.start, answer.end)\n",
    "    return round((forecast - actual.reindex(forecast.index)).abs().mean(), 1)\n",
    "\n",
    "{days: mae(lab.run(PROFILE, **THURSDAY, days=days)) for days in (1, 3, 7, 14, 28)}"
   ],
   "execution_count": null,
   "outputs": []
  },
  {
   "cell_type": "markdown",
   "id": "markdown-5",
   "metadata": {},
   "source": [
    "A short memory follows recent changes but carries their noise. A long memory\n",
    "smooths the noise but forgets that the weather changed. No setting is right for\n",
    "every day; that is why the caller may choose.\n",
    "\n",
    "Now try `alike` on a Sunday, when the kind of day matters most:"
   ]
  },
  {
   "cell_type": "code",
   "id": "code-6",
   "metadata": {},
   "source": [
    "SUNDAY = dict(start=\"2017-03-11T23:00:00Z\", end=\"2017-03-12T23:00:00Z\",\n",
    "              as_of=\"2017-03-11T08:00:00Z\")\n",
    "{alike: mae(lab.run(PROFILE, **SUNDAY, days=4, alike=alike))\n",
    " for alike in (\"every_day\", \"same_kind\")}"
   ],
   "execution_count": null,
   "outputs": []
  },
  {
   "cell_type": "markdown",
   "id": "markdown-7",
   "metadata": {},
   "source": [
    "## Periods: the caller decides\n",
    "\n",
    "A screen asks a model for the period its chart shows: a day, a week, a month.\n",
    "The cut-off is the chart's moment, or now. **A model must answer whatever\n",
    "period it is asked**. It should never refuse one for being too long.\n",
    "\n",
    "Some of the period may not be knowable, though. Ask both `profile_mean` and\n",
    "`naive` for a whole week, as known on the Sunday morning before it:"
   ]
  },
  {
   "cell_type": "code",
   "id": "code-8",
   "metadata": {},
   "source": [
    "WEEK = dict(start=\"2017-03-05T23:00:00Z\", end=\"2017-03-12T23:00:00Z\",\n",
    "            as_of=\"2017-03-05T08:00:00Z\")\n",
    "profile = lab.run(PROFILE, **WEEK)\n",
    "naive = lab.run(\"../examples/naive\", **WEEK)\n",
    "print(profile)\n",
    "print(naive)"
   ],
   "execution_count": null,
   "outputs": []
  },
  {
   "cell_type": "markdown",
   "id": "markdown-9",
   "metadata": {},
   "source": [
    "Both answer 168 values, one for each hour of the week. But most of naive's are\n",
    "null (NaN), and none of profile_mean's are. Why?\n",
    "\n",
    "Think about Wednesday. Naive forecasts it from Tuesday's prices. On Sunday\n",
    "morning, nobody knew Tuesday's prices, so naive has nothing to copy and leaves\n",
    "Wednesday empty. Monday, Saturday and Sunday are filled: they copy the week\n",
    "before, which was known. Profile_mean averages days that were known on Sunday,\n",
    "so it can fill every day of the week.\n",
    "\n",
    "Neither is wrong. Each answers the whole period and leaves out only what it\n",
    "cannot know. That is the rule. If a model would need longer than its time\n",
    "allows to compute the whole period, it computes what it can, leaves out the\n",
    "rest, and says so in its log, `call.log`."
   ]
  },
  {
   "cell_type": "code",
   "id": "code-10",
   "metadata": {},
   "source": [
    "profile.plot();"
   ],
   "execution_count": null,
   "outputs": []
  },
  {
   "cell_type": "markdown",
   "id": "markdown-11",
   "metadata": {},
   "source": [
    "## Steps: an hour or a quarter-hour\n",
    "\n",
    "The 2017 prices come one an hour. Since October 2025, Europe's day-ahead\n",
    "auction has set a price for every quarter-hour: 96 values a day, not 24. The\n",
    "platform's ENTSO-E series, such as `entsoe.de_lu_price`, come that way.\n",
    "\n",
    "A model that assumes hours would answer one value an hour and silently drop\n",
    "three in four. So every example takes the step from the data it reads, with a\n",
    "small function, `step_of`: the most common gap between two values."
   ]
  },
  {
   "cell_type": "code",
   "id": "code-12",
   "metadata": {},
   "source": [
    "def step_of(known):\n",
    "    gaps = known.index.to_series().diff().dropna()\n",
    "    gaps = gaps[gaps > pd.Timedelta(0)]\n",
    "    return gaps.mode().iloc[0] if len(gaps) else pd.Timedelta(hours=1)\n",
    "\n",
    "hourly = lab.series(\"epf.price\", \"2017-03-01T23:00:00Z\", \"2017-03-02T23:00:00Z\")\n",
    "quarters = pd.Series(range(96), index=pd.date_range(\"2026-11-16T23:00:00Z\", periods=96,\n",
    "                                                    freq=\"15min\"))\n",
    "step_of(hourly), step_of(quarters)"
   ],
   "execution_count": null,
   "outputs": []
  },
  {
   "cell_type": "markdown",
   "id": "markdown-13",
   "metadata": {},
   "source": [
    "With the step known, the rest of a model need not change. Naive moves each value\n",
    "24 hours ahead, or a week, whatever the step. Profile_mean averages the same\n",
    "moment of the day, whether that is 08:00 or 08:15.\n",
    "\n",
    "## Try it yourself\n",
    "\n",
    "1. Find the best `days` for the Thursday above. Is it the best for the Tuesday\n",
    "   before it too?\n",
    "2. Ask `profile_mean` for the whole of April 2017 as known on 31 March. How\n",
    "   many values does it answer? How many are null?\n",
    "3. In this notebook, read `entsoe.de_lu_price` for yesterday and count its values.\n",
    "   Then run `../examples/naive` on it: pass `series=\"entsoe.de_lu_price\"` and\n",
    "   yesterday's period."
   ]
  }
 ],
 "nbformat": 4,
 "nbformat_minor": 5,
 "metadata": {
  "kernelspec": {
   "display_name": "Python 3 (ipykernel)",
   "language": "python",
   "name": "python3"
  },
  "language_info": {
   "name": "python"
  }
 }
}
