colab_1_Forecasting_workshop.ipynb

{
 "cells": [
  {
   "cell_type": "markdown",
   "id": "5760543e-615a-4612-ab95-9bd5b80ba2fe",
   "metadata": {},
   "source": [
    "# Setup"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "id": "f87dddc4-5a42-415f-9395-b1b5681617e4",
   "metadata": {
    "scrolled": true
   },
   "outputs": [],
   "source": [
    "# setup darts\n",
    "!pip install \"darts @ git+https://github.com/unit8co/darts.git@master\" seaborn openpyxl catboost lightgbm"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "id": "12fd9b5b-31e4-4dfa-bbfe-f252c3f5d109",
   "metadata": {},
   "outputs": [],
   "source": [
    "# Download data from data source to local\n",
    "import io\n",
    "import os\n",
    "import requests\n",
    "import shutil\n",
    "import zipfile\n",
    "\n",
    "import numpy as np\n",
    "import pandas as pd"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "id": "8f916096-3fb2-4fac-afc7-c5c4195adcfe",
   "metadata": {},
   "outputs": [],
   "source": [
    "data_dir = \"data\"\n",
    "fc_dir = os.path.join(data_dir, \"forecasting\")\n",
    "for dir_path in [data_dir, fc_dir]:\n",
    "    if not os.path.exists(dir_path):\n",
    "        os.mkdir(dir_path)"
   ]
  },
  {
   "cell_type": "markdown",
   "id": "d5b2f91c-006f-46c1-96b8-c05884bf1021",
   "metadata": {},
   "source": [
    "## Data Download and Preprocessing: Electricity Dataset"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "id": "8e5b1844-12ee-4f41-9640-69bf5adae3a1",
   "metadata": {},
   "outputs": [],
   "source": [
    "def download_weather_data():\n",
    "    \"\"\"Concatenate the yearly csv files into a single dataframe and reshape it\"\"\"\n",
    "    # download the csv from the url\n",
    "    base_url = \"https://data.stadt-zuerich.ch/dataset/ugz_meteodaten_stundenmittelwerte/download/\"\n",
    "    filenames = [f\"ugz_ogd_meteo_h1_{year}.csv\" for year in range(2015, 2023)]\n",
    "    df = pd.concat([pd.read_csv(base_url + fname) for fname in filenames])\n",
    "    # retain only one weather station\n",
    "    df = df.loc[df[\"Standort\"] == \"Zch_Stampfenbachstrasse\"]\n",
    "    # pivot the df to get all measurements as columns\n",
    "    df[\"param_name\"] = df[\"Parameter\"] + \" [\" + df[\"Einheit\"] + \"]\"\n",
    "    df = df.pivot(index=\"Datum\", columns=\"param_name\", values=\"Wert\")\n",
    "    # convert time index to from CET to UTC and extract the required time range\n",
    "    df.index = pd.DatetimeIndex(pd.to_datetime(df.index, utc=True)).tz_localize(\n",
    "        None\n",
    "    )\n",
    "    df = df.loc[\n",
    "        (pd.Timestamp(\"2015-01-01\") <= df.index)\n",
    "        & (df.index <= pd.Timestamp(\"2022-08-31\"))\n",
    "    ]\n",
    "    return df"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "id": "f7d07c39-4de8-432c-9200-53f06dddbbff",
   "metadata": {},
   "outputs": [],
   "source": [
    "def download_electricity_data():\n",
    "    # URL of the file\n",
    "    energy_url = \"https://data.stadt-zuerich.ch/dataset/ewz_stromabgabe_netzebenen_stadt_zuerich/download/ewz_stromabgabe_netzebenen_stadt_zuerich.csv\"\n",
    "    \n",
    "    file_path = os.path.join(fc_dir, energy_url.split(\"/\")[-1])\n",
    "    processed_path = file_path.replace(\".csv\", \"_proc.csv\")\n",
    "    \n",
    "    if not os.path.exists(processed_path):\n",
    "        if not os.path.exists(file_path):\n",
    "            # Send a GET request to download the zip file\n",
    "            response = requests.get(energy_url)\n",
    "            \n",
    "            # Check if the request was successful\n",
    "            if response.status_code == 200:\n",
    "                # Save the zip file to the local drive\n",
    "                with open(file_path, \"wb\") as file:\n",
    "                    file.write(response.content)\n",
    "                print(\"File downloaded successfully.\")\n",
    "            else:\n",
    "                raise ValueError(\"Failed to download.\")\n",
    "        print(\"Processing file..\")\n",
    "        df = pd.read_csv(file_path, index_col=0)\n",
    "        # convert time index\n",
    "        df.index = pd.DatetimeIndex(pd.to_datetime(df.index, utc=True)).tz_localize(None)\n",
    "        # extract pre-determined period\n",
    "        df = df.loc[(pd.Timestamp(\"2015-01-01\") <= df.index) & (df.index <= pd.Timestamp(\"2022-08-31\"))]\n",
    "        # download and preprocess the weather information\n",
    "        df_weather = download_weather_data()\n",
    "        # add weather data as additional features\n",
    "        df = pd.concat([df, df_weather], axis=1)\n",
    "        # interpolate weather data\n",
    "        df = df.interpolate()\n",
    "        # raining duration is given in minutes -> we divide by 4 from hourly to quarter-hourly records\n",
    "        df[\"RainDur [min]\"] = df[\"RainDur [min]\"] / 4\n",
    "    \n",
    "        # round Electricity cols to 4 decimals, other columns to 2 decimals\n",
    "        cols_precise = [\"Value_NE5\", \"Value_NE7\"]\n",
    "        df = df.round(decimals={col: (4 if col in cols_precise else 2) for col in df.columns})\n",
    "    \n",
    "        # export the dataset\n",
    "        df.index.name = \"Timestamp\"\n",
    "        df.to_csv(processed_path)\n",
    "        os.remove(file_path)\n",
    "        print(\"File successfully processed.\")\n",
    "    else:\n",
    "        print(\"File already downloaded.\")    "
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "id": "0df64ae6-d711-453f-9b17-30a5076b04f1",
   "metadata": {},
   "outputs": [],
   "source": [
    "print(\"Downloading Electricity Data..\")\n",
    "download_electricity_data()"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "id": "1ac06bbe-543d-4571-bc5e-47838b871e50",
   "metadata": {},
   "outputs": [],
   "source": [
    "%load_ext autoreload\n",
    "%autoreload 2\n",
    "%matplotlib inline"
   ]
  },
  {
   "cell_type": "markdown",
   "id": "45bd6e88-1be9-4de1-9933-143eda71d501",
   "metadata": {},
   "source": [
    "# Introduction to Darts\n",
    "In this notebook, we go over some of the key functionalities of the library:\n",
    "\n",
    "* [Basics about the TimeSeries](#Building-and-manipulating-TimeSeries)\n",
    "* [Training forecasting models and making predictions](#Training-forecasting-models-and-making-predictions)\n",
    "* [Covariates: using external data](#Covariates:-using-external-data)\n",
    "* [Probabilistic forecasting](#Probabilistic-forecasting)\n",
    "* [Backtesting and Residuals](#Backtesting-and-Residuals)\n",
    "\n",
    "We will only show some minimal \"get started\" examples here. For more in depth information, you can refer to our [user guide](https://unit8co.github.io/darts/userguide.html) and [example notebooks](https://unit8co.github.io/darts/examples.html)."
   ]
  },
  {
   "cell_type": "markdown",
   "id": "4868c9bc",
   "metadata": {},
   "source": [
    "# Building and manipulating `TimeSeries`\n",
    "`TimeSeries` is the main data class in Darts. A `TimeSeries` represents a univariate or multivariate time series, with a proper time index. The time index can either be of type `pandas.DatetimeIndex` (containing datetimes), or of type `pandas.RangeIndex` (containing integers; useful for representing sequential data without specific timestamps). `TimeSeries` can also represent *probabilistic* series, which are generated when performing a probabilistic/stochastic forecast. In this case the `TimeSeries` holds multiple samples per time step and column, from which we can obtain confidence intervals, or characteristics of the distribution. \n",
    "\n",
    "All models in Darts consume `TimeSeries` and produce `TimeSeries`.\n",
    "\n",
    "## Read data and build a `TimeSeries`\n",
    "`TimeSeries` can be built easily using our factory methods `TimeSeries.from_*()` (e.g. from a Pandas `DataFrame` with `TimeSeries.from_dataframe()`, also numpy, csv, ...). You can find all supported methods [here](https://unit8co.github.io/darts/generated_api/darts.timeseries.html#darts.timeseries.TimeSeries).\n",
    "\n",
    "Below, we load one of the datasets downloaded at in the workshop setup notebook: Zurich's electricity consumption including weather measurements:"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "id": "fdb639cc-b984-4a8b-92d7-b569410abda4",
   "metadata": {},
   "outputs": [],
   "source": [
    "import os\n",
    "\n",
    "import matplotlib.pyplot as plt\n",
    "import pandas as pd\n",
    "\n",
    "from darts import TimeSeries\n",
    "\n",
    "fpath = os.path.join(\"data\", \"forecasting\", \"ewz_stromabgabe_netzebenen_stadt_zuerich_proc.csv\")\n",
    "ts_energy = TimeSeries.from_csv(fpath, time_col=\"Timestamp\")"
   ]
  },
  {
   "cell_type": "markdown",
   "id": "53e9a22a",
   "metadata": {},
   "source": [
    "Technical information about this dataset:\n",
    "\n",
    "**Frequency**: quarter-hourly (15-minutes time intervals), but resampled to hourly for the sake of simplicity.\n",
    "\n",
    "**Target series** (the series we want to forecast):\n",
    "- **Value_NE5**: Electricity consumption by households on grid level 5 (in kWh).\n",
    "\n",
    "**Covariates** (external data to help improve forecasts):\n",
    "The dataset also comes with weather measurements that we can use as covariates. For simplicity, we use:\n",
    "- **T [°C]**: Measured temperature\n",
    "- **StrGlo [W/m2]**: Measured solar irradation\n",
    "- **RainDur [min]**: Measured raining duration\n",
    "\n",
    "The `TimeSeries` can then easily be manipulated to extract the desired time range and dimensions:"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "id": "71123557",
   "metadata": {},
   "outputs": [],
   "source": [
    "train_start = pd.Timestamp(\"2017-01-01\")\n",
    "train_end = pd.Timestamp(\"2018-10-31\")\n",
    "val_end = pd.Timestamp(\"2018-12-31\")\n",
    "test_end = pd.Timestamp(\"2019-01-31\")\n",
    "\n",
    "\"\"\"\n",
    "Slice the TimeSeries to extract the values between 01-01-2017 and 13-01-2019\n",
    "\n",
    "Hint: use `[]` operator (as you would do for list/arrays) or the `slice()` method\n",
    "\n",
    "Documentation: https://unit8co.github.io/darts/generated_api/darts.timeseries.html#darts.timeseries.TimeSeries.slice\n",
    "\"\"\"\n",
    "ts_energy = # your code here\n",
    "\n",
    "\"\"\"\n",
    "Resample the TimeSeries to an hourly frequency\n",
    "\n",
    "Hint: use the `TimeSeries.resample()` method to plot the series\n",
    "\n",
    "Documentation: https://unit8co.github.io/darts/generated_api/darts.timeseries.html#darts.timeseries.TimeSeries.resample\n",
    "\"\"\"\n",
    "ts_energy = # your code here\n",
    "\n",
    "\"\"\"\n",
    "Create a new `TimeSeries` by extracting the following compoments: temperature, solar irradiation and rain duration\n",
    "\n",
    "Hint: use the `[]` operator and the name of the desired compoments: \"T [°C]\", \"StrGlo [W/m2]\", \"RainDur [min]\"\n",
    "\"\"\"\n",
    "ts_weather = # your code here\n",
    "\n",
    "# extract households energy consumption\n",
    "ts_energy = ts_energy[\"Value_NE5\"]\n",
    "\n",
    "# create train, validation, and test splits\n",
    "ts_energy_train = ts_energy[train_start:train_end]\n",
    "ts_energy_val = ts_energy[train_end + ts_energy.freq:val_end]\n",
    "ts_energy_test = ts_energy[val_end + ts_energy.freq:test_end]\n",
    "\n",
    "\"\"\"\n",
    "Visualize the target and future covariates series in two separate plots\n",
    "\n",
    "Hint: use the `TimeSeries.plot()` method to plot the series, and plt.show() to plot one figure.\n",
    "\n",
    "Documentation: https://unit8co.github.io/darts/generated_api/darts.timeseries.html?highlight=plot#darts.timeseries.TimeSeries.plot\n",
    "\"\"\"\n",
    "# your code here"
   ]
  },
  {
   "cell_type": "markdown",
   "id": "507e4f91",
   "metadata": {},
   "source": [
    "# Training forecasting models and making predictions\n",
    "\n",
    "Darts offers a unified API for 40+ different forecasting models. \n",
    "- classic statistical models (`ARIMA`, ...)\n",
    "- regression models for any sklearn-like regression model (also decision trees gradient boosted methods such as `LightGBM`, `XGBoost`, `CatBoost`, ...)\n",
    "- state-of-the art neural network/deep learning models such as `TiDE`, `DLinear` or `TSMixer`\n",
    "\n",
    "For the sake of simplicity, let's focus on Regression Models.\n",
    "\n",
    "In Darts, the forecasting problem is translated into a regression problem by converting the time series into two tabular arrays:\n",
    "- `X`: features or input array with the shape (number of samples/observations, number of features)\n",
    "  - The number of features is given by the total number of (feature specific) target, past covariates and future covariates lags.\n",
    "- `y`: target or label array with the shape (number of samples/observations, number of targets)\n",
    "  - The number of targets is given by the model parameters `output_chunk_length`.\n",
    "\n",
    "### Target and covariates lags\n",
    "\n",
    "A lagged feature is the value of a feature at a previous or future time step compared to some reference point. \n",
    "\n",
    "In Darts, the value of the lag specifies the position of the feature value relative to the first predicted target time step `y_t0` for each observation/sample (a row in `X`).\n",
    "\n",
    "- `lag == 0`: position of the first predicted time step `t0`, e.g. position of `y_t0`\n",
    "- `lag < 0`: all positions in the past of the first predicted time step `t-1`, `t-2`, ...\n",
    "- `lag > 0`: all positions in the future of the first predicted time step `t+1`, `t+2`, ...\n",
    "\n",
    "The choice of lags is critical in achieving good predictive accuracy. We want the model to receive relevant information to capture the temporal properties/dependencies our target series (patterns, seasonalities, trends, ...). It also has a considerable impact on the model performance/complexity, as each additional lag adds a new feature to `X`.\n",
    "\n",
    "At model creation, we can set lags for the target and the covariates series separately.\n",
    "\n",
    "- `lags`: lags for the target series (the one we want to forecast)\n",
    "- `lags_past_covariates`: optionally, lags for a past covariates series (external past-observed features to help improve forecasts)\n",
    "- `lags_future_covariates`: optionally, lags for a future covariates series (external future-known features to help improve forecasts)\n",
    "\n",
    "There are multiple ways to define your lags `(int, List[int], Tuple[int, int], ...)`. You can find out more about this in the [RegressionModel docs](https://unit8co.github.io/darts/generated_api/darts.models.forecasting.regression_model.html#darts.models.forecasting.regression_model.RegressionModel).\n",
    "\n",
    "### Lagged data extraction\n",
    "Now, let's have a look at how `X` and `y` is extracted for training using the scenario from below:\n",
    "\n",
    "- `lags=[-4,-3,-2,-1]`: use the last 4 target values (green) before the first predicted time step (orange) as `X` features.\n",
    "- `output_chunk_length=1`: predict the target value `y` of next (`1`) time step (orange).\n",
    "- we have a target series with 7 time steps `t_i, ..., t_i+6` (blue).\n",
    "\n",
    "*Note: This example only shows target `lags` extraction, but the same is applied to `lags_past/future_covariates`.*\n",
    "\n",
    "![forecast_single_model_ocl3](./images/regression_model_train.png)\n",
    "\n",
    "### Examples\n",
    "Let's try to apply this to our electricity dataset. Assume we want to predict the consumption of the next couple of hours after the end of our training set. \n",
    "\n",
    "As input features, we give it the consumption at the same hour from one and two days ago -> `lags=[-24, -48]`."
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "id": "76feeb30",
   "metadata": {},
   "outputs": [],
   "source": [
    "from darts.models import LinearRegressionModel\n",
    "\n",
    "\"\"\"\n",
    "Create a `LinearRegressionModel`, fit it on the energy series (train split) and forecast 12 values.\n",
    "\n",
    "Documentation: https://unit8co.github.io/darts/generated_api/darts.models.forecasting.linear_regression_model.html\n",
    "\"\"\"\n",
    "model = # your code here\n",
    "\n",
    "# store your forecasted values in `pred`\n",
    "\n",
    "ts_energy_train[-48:].plot(label=\"training\")\n",
    "ts_energy_val[:12].plot(label=\"validation\")\n",
    "pred.plot(label=\"forecast\")"
   ]
  },
  {
   "cell_type": "markdown",
   "id": "4ee3fdcf-72f8-4a63-a1e6-50e668746a09",
   "metadata": {},
   "source": [
    "And let's also compute the Mean Absolute Percentage Error for this forecast.\n",
    "\n",
    "The cool thing is that Darts handles the extraction of relevant time frames between the true values and predicted values for us!\n",
    "\n",
    "So we can give the entire `ts_energy` series without having to worry about that."
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "id": "ffcfaf9d-378e-4a90-b4dd-e7156603c27b",
   "metadata": {},
   "outputs": [],
   "source": [
    "from darts.metrics import mape\n",
    "\n",
    "\"\"\"\n",
    "Compute the mape score between the ground truth and predicted series.\n",
    "\n",
    "Documentation: https://unit8co.github.io/darts/generated_api/darts.metrics.metrics.html?highlight=mape#darts.metrics.metrics.mape\n",
    "\"\"\"\n",
    "# your code here\n",
    "\n",
    "# same as with the exact time frames\n",
    "print(\"MAPE:\", mape(ts_energy[pred.start_time():pred.end_time()], pred))"
   ]
  },
  {
   "cell_type": "markdown",
   "id": "a86b69fc",
   "metadata": {},
   "source": [
    "### Covariates: using external data\n",
    "\n",
    "To improve the quality of the forecasts, it is possible to provide external information to the model; these are called `covariates` in Darts.\n",
    "\n",
    "![covariates-illustration](./images/covariates-highlevel.png)\n",
    "\n",
    "To use external data next to the history of our target series, we can pass `past_covariates` and/or `future_covariates` to `fit()` and `predict()`.\n",
    "\n",
    "For regression models, we have to specify which lags to use from the covariates with `lags_past_covariates`, and `lags_future_covariates`.\n",
    "\n",
    "Let's assume that instead of having weather measurements, we actually have weather forecasts. Then we could use them as `future_covariates`. **We only do this here for demonstration purposes!**\n",
    "\n",
    "Below is an example that uses the last 24 hours (`24`) from hour target series (electricity consumption) and the values at the predicted time step (`[0]`) of our weather \"forecasts\"."
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "id": "98428d6e",
   "metadata": {},
   "outputs": [],
   "source": [
    "\"\"\"\n",
    "Create a `LinearRegressionModel` with target and future_covariates lags, fit it on the energy series (train split) and the weather covariates.\n",
    "\n",
    "Documentation: https://unit8co.github.io/darts/generated_api/darts.models.forecasting.linear_regression_model.html\n",
    "\"\"\"\n",
    "# your code here\n",
    "pred = model.predict(12)\n",
    "\n",
    "ts_energy_train[-48:].plot(label=\"training\")\n",
    "ts_energy_val[:12].plot(label=\"validation\")\n",
    "pred.plot(label=\"forecast\")"
   ]
  },
  {
   "cell_type": "markdown",
   "id": "60b814c6",
   "metadata": {},
   "source": [
    "### Using only covariates as features/predictors\n",
    "\n",
    "Sometimes, we might also be interested in a forecasting model that purely relies on the covariates values.\n",
    "\n",
    "To do this, specify at least one of `lags_past_covariates` or `lags_future_covariates` and set `lags=None`. \n",
    "Darts regression models are trained in a supervised manner, so we still have to provide the target series for training but it'll not be accessed when calling `predict()`.\n",
    "\n",
    "How well can we predict the electricity consumption using only the weather \"forecasts\" and some calendar information (generated for free with `add_encoders`) as input?\n",
    "\n",
    "The lags tuple `(24, 1)` means (number of lags in the past, number of lags in the future)."
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "id": "76bac933",
   "metadata": {},
   "outputs": [],
   "source": [
    "\"\"\"\n",
    "Create a `LinearRegressionModel` that uses encoders to generate future_covariates based on the \"hour\", \"month\" and \"dayofweek\" components of\n",
    "the series' time index.\n",
    "\n",
    "Hint: Make sure to use the cyclic representation\n",
    "\n",
    "Documentation: https://unit8co.github.io/darts/generated_api/darts.models.forecasting.linear_regression_model.html, see code example \n",
    "for the `add_encoders` argument\n",
    "\"\"\"\n",
    "\n",
    "model = # your code here\n",
    "model.fit(series=ts_energy_train, future_covariates=ts_weather)\n",
    "pred = model.predict(12)\n",
    "\n",
    "ts_energy_train[-48:].plot(label=\"training\")\n",
    "ts_energy_val[:12].plot(label=\"validation\")\n",
    "pred.plot(label=\"forecast\")"
   ]
  },
  {
   "cell_type": "markdown",
   "id": "af170e70-0c06-45f9-a093-df36dd9373c1",
   "metadata": {},
   "source": [
    "### Model's output chunk length\n",
    "\n",
    "This key parameter sets the *number of time steps that can be predicted at once by the internal regression or neural network model*.\n",
    "\n",
    "It is not the same as forecast horizon `n` from `model.predict()` which is the **desired** the number of generated prediction points, that is achieved either with:\n",
    "- a single shot forecast (if `n <= output_chunk_length`), or\n",
    "- an auto-regressive forecast, consuming its own forecast (and future values of covariates) as input for additional predictions (otherwise)\n",
    "\n",
    "For example, if we want our model to forecast the next 24 hours of electricity consumption based on the last day of consumption, setting `output_chunk_length=24` ensures that the model will not consume its forecasts or future values of our covariates to predict the entire day."
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "id": "b376f792-d374-4c6c-b47a-644621248efd",
   "metadata": {},
   "outputs": [],
   "source": [
    "model_auto_regression = LinearRegressionModel(lags=24, output_chunk_length=1)\n",
    "model_single_shot = LinearRegressionModel(lags=24, output_chunk_length=24)\n",
    "\n",
    "model_auto_regression.fit(ts_energy_train)\n",
    "model_single_shot.fit(ts_energy_train)\n",
    "\n",
    "pred_auto_regression = model_auto_regression.predict(24)\n",
    "pred_single_shot = model_single_shot.predict(24)\n",
    "\n",
    "ts_energy_train[-48:].plot(label=\"training data\")\n",
    "ts_energy_val[:24].plot(label=\"validation data\")\n",
    "pred_auto_regression.plot(label=\"forecast (auto-regression)\")\n",
    "pred_single_shot.plot(label=\"forecast (single-shot)\")"
   ]
  },
  {
   "cell_type": "markdown",
   "id": "53e4b709-c0de-4efb-8755-9c87c1e471fc",
   "metadata": {},
   "source": [
    "### Gradient Boosted Models and Validations Sets\n",
    "\n",
    "With the gradient boosted models (`LightGBMModel`, `XGBoostModel`, and `CatBoostModel`), you can pass a validation set to `model.fit()` to reduce overfitting.\n",
    "You simply have to supply `val_series` (and `val_past_covariates`, `val_future_covariates` if you use covariates).\n",
    "\n",
    "Since we use the validation set for early stopping, we should not evaluate the model on this set. So, let's generate the forecasts this time on the test set."
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "id": "49a4fb0b-e1f5-4d82-8765-5ecb9fca58f2",
   "metadata": {},
   "outputs": [],
   "source": [
    "from darts.models import LightGBMModel\n",
    "\n",
    "model = LightGBMModel(\n",
    "    lags=24, \n",
    "    lags_future_covariates=(24, 1),\n",
    "    add_encoders={\"cyclic\": {\"future\": [\"hour\", \"month\", \"dayofweek\"]}},\n",
    "    output_chunk_length=1\n",
    ")\n",
    "\n",
    "\"\"\"\n",
    "Fit the LightGBMModel using validation series (target and covariates)\n",
    "\n",
    "Documentation: https://unit8co.github.io/darts/generated_api/darts.models.forecasting.lgbm.html\n",
    "\"\"\"\n",
    "\n",
    "model.fit(\n",
    "    # your code here\n",
    ")\n",
    "\n",
    "preds_test = model.predict(24, series=ts_energy_val, future_covariates=ts_weather)\n",
    "\n",
    "ts_energy_val[-7*24:].plot(label=\"test data\")\n",
    "ts_energy_test[:24].plot(label=\"test data\")\n",
    "preds_test.plot(label=\"forecast\")"
   ]
  },
  {
   "cell_type": "markdown",
   "id": "fdc2cfab-3b39-41c4-8701-ac6ee67b4b63",
   "metadata": {},
   "source": [
    "### Probabilistic forecasting\n",
    "\n",
    "To make a model probablistic, set parameter `likelihood` to `quantile` or `poisson` when creating a `RegressionModel`. At prediction time, probabilistic models can either :\n",
    "- use Monte Carlo sampling to generate samples based on the fitted distribution parameters (or quantiles) when `num_samples > 1`\n",
    "- return the fitted distribution parameters (or quantiles) directly when `predict_likelihood_parameters=True`\n",
    "\n",
    "Note that when using the `quantile` regressor, each quantile will be fitted by a different model.\n",
    "\n",
    "Probabilistic models will generate different forecasts each time `predict()` is called with `num_samples > 1`. To get reproducible results, set the random seed when creating the model and call the methods in the exact same order."
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "id": "38de016d-4029-4c80-bbf8-2fd73716f8cd",
   "metadata": {},
   "outputs": [],
   "source": [
    "\"\"\"\n",
    "Create a probabilistic `LightGBMModel` with lags=24, output_chunk_length=1 and quantiles=[0.1, 0.5, 0.9].\n",
    "\n",
    "Hint: don't forget to specify the likelihood!\n",
    "\n",
    "Documentation: https://unit8co.github.io/darts/generated_api/darts.models.forecasting.lgbm\n",
    "\"\"\"\n",
    "model = LightGBMModel(\n",
    "    # your code here\n",
    ")\n",
    "\n",
    "model.fit(ts_energy_train)\n",
    "\n",
    "\"\"\"\n",
    "Use the probabilistic model to predict 24 steps, with 200 samples\n",
    "\n",
    "Documentation: https://unit8co.github.io/darts/generated_api/darts.models.forecasting.lgbm\n",
    "\"\"\"\n",
    "pred_samples = # your code here\n",
    "pred_params = model.predict(n=1, predict_likelihood_parameters=True)\n",
    "\n",
    "for val, comp in zip(pred_params.values()[0], pred_params.components):\n",
    "    print(f\"{comp} : {round(val, 3)}\")\n",
    "\n",
    "ts_energy_train[-48:].plot(label=\"training\")\n",
    "ts_energy_val[:24].plot(label=\"validation\")\n",
    "pred_samples.plot(label=\"forecasts\")\n",
    "pred_params.plot(label=\"forecasted quantiles\")\n",
    "plt.tight_layout()"
   ]
  },
  {
   "attachments": {},
   "cell_type": "markdown",
   "id": "60f94fe4",
   "metadata": {},
   "source": [
    "## Backtesting and Residuals\n",
    "\n",
    "So at this point, we know how to use a model to generate single forecasts and evaluate them. This is great but not enough. Better would be to know how the model would have performed over time, if used historically.\n",
    "\n",
    "For this we can use Darts historical forecast, backtest, and residuals support. These methods are comparable to cross-validation for tabular data.\n",
    "\n",
    "#### Historical Forecasts (`model.historical_forecasts()`): \n",
    "- compute forecasts with a moving forecasting (reference) point over the history of a time series.\n",
    "- For **classic models** (`ARIMA`, ...) the model needs to be **retrained** at each step. It uses the past of the moving forecasting point for training. This can take quite a while to compute.\n",
    "- For our **regression** and **neural network models**, you can also use a **pre-trained** model to generate all forecasts directly. **This is really fast!**\n",
    "\n",
    "![covariates-illustration](./images/historical_forecasts.png)\n",
    "\n",
    "\n",
    "#### Backtesting (`model.backtest()`):\n",
    "- computes one or multiple metrics for each historical forecast\n",
    "- by default it will give the Mean Absolute Percentage Error (MAPE) aggregated per forecast\n",
    "- you can use any of Darts' [aggregated metrics](https://unit8co.github.io/darts/generated_api/darts.metrics.html#metrics).\n",
    "\n",
    "![covariates-illustration](./images/backtest.png)\n",
    "\n",
    "\n",
    "#### Residuals (`model.residuals()`):\n",
    "- computes a metric value for each historical forecast and predicted time.\n",
    "- by default it computes the deviation between the forecasts and actual values\n",
    "- you can use any of Darts' [*per-time-step* metrics](https://unit8co.github.io/darts/generated_api/darts.metrics.html#metrics).\n",
    "\n",
    "\n",
    "In the example below, we simulate forecasts with 24 hours horizon. By default (with `last_points_only=True`) it will return a single `TimeSeries` containing only the last predicted point per forecast.\n",
    "If `last_points_only=False`, it would give a list of forecasts, each covering the entire 24 hour horizon."
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "id": "5abb5ae6",
   "metadata": {},
   "outputs": [],
   "source": [
    "\"\"\"\n",
    "Generate historical forecasts for the model_single_shot using the `historical_forecasts()` method\n",
    "\n",
    "Hint: it should start after the end of the train split, use an horizon of 24, not retrain the model & keep only the last point of each forecast\n",
    "\n",
    "Documentation: https://unit8co.github.io/darts/generated_api/darts.models.forecasting.linear_regression_model.html?highlight=linearregressionmodel#darts.models.forecasting.linear_regression_model.LinearRegressionModel.historical_forecasts\n",
    "\"\"\"\n",
    "hf_single = model_single_shot.historical_forecasts(\n",
    "    # your code here\n",
    ")"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "id": "af6074ae",
   "metadata": {},
   "outputs": [],
   "source": [
    "fig, ax = plt.subplots(figsize=(12,6))\n",
    "ts_energy[train_end + ts_energy.freq:].plot(lw=1)\n",
    "hf_single.plot(lw=1, label=\"historical forecasts\")\n",
    "plt.show()"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "id": "f87494f9-0177-4ff0-9916-e1e90d28c6a4",
   "metadata": {},
   "outputs": [],
   "source": [
    "# And the backtest for these forecasts\n",
    "backtest_single = model_single_shot.backtest(\n",
    "    ts_energy, \n",
    "    historical_forecasts=hf_single,\n",
    "    metric=mape,\n",
    "    last_points_only=True\n",
    ")\n",
    "print(f\"Obtained a mape of {backtest_single} over the historical forecasts.\")"
   ]
  },
  {
   "cell_type": "markdown",
   "id": "16c97836-b142-425f-820e-2104540bcb8d",
   "metadata": {},
   "source": [
    "Now, let’s look at residuals/deviation of each predicted value compared to the actual values:"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "id": "453a59e5-1da5-438f-933b-f349a636bae5",
   "metadata": {},
   "outputs": [],
   "source": [
    "from darts.utils.statistics import plot_residuals_analysis\n",
    "\n",
    "\"\"\"\n",
    "Compute the residuals using the `residuals()` method\n",
    "\n",
    "Hint: you can reuse the historical forecasts generated above (`hf_single`) to save time!\n",
    "\n",
    "Documentation: https://unit8co.github.io/darts/generated_api/darts.models.forecasting.linear_regression_model.html?highlight=linearregressionmodel#darts.models.forecasting.linear_regression_model.LinearRegressionModel.residuals\n",
    "\"\"\"\n",
    "residuals = # your code here\n",
    "\n",
    "# visualize some stats\n",
    "plot_residuals_analysis(residuals, acf_max_lag=7*24)"
   ]
  },
  {
   "cell_type": "markdown",
   "id": "d08db0cf-d89c-44fb-8bcc-11159d27f918",
   "metadata": {},
   "source": [
    "For a robust model, we would expect:\n",
    "- Residual values over time should show constant variance and mean=0\n",
    "- Residuals ACF should not show signs of auto-correlation with past lags (e.g. the ACF values are randomly scattered on the plot, without ramps or sinusoidal patterns)\n",
    "- The residuals destribution should be similar to a gaussian with mean 0\n",
    "\n",
    "We see that our model doesn't really perform that well:\n",
    "- residuals over time show temporal patterns, varying variance over time\n",
    "- ACF shows very strong correlation with the residuals from the most recent past, and residuals from a week ago (lag=24*7=168)\n",
    "- ..."
   ]
  },
  {
   "cell_type": "markdown",
   "id": "9b0a0b82-5d79-4633-af38-58eb9b56fcfd",
   "metadata": {},
   "source": [
    "## Conclusion\n",
    "\n",
    "- Darts offers a simple data-structure, the `TimeSeries`, to provide a lot of features as well as safeguards for ingestion and manipulation of timeseries.\n",
    "- Through a unified API across libraries (classic models, regression model, and neural networks) Darts makes it very east to experiment with a large variety of models and obtain forecasts in just a few lines of codes\n",
    "- By tabularizing the data, Darts closes the gap between traditional regression problems and timeseries forecasting\n",
    "- With Darts' metrics, historical forecasts, backtest, and residuals support, we have all the tools requried to properly evaluate a model and assess it's performance over time time"
   ]
  }
 ],
 "metadata": {
  "kernelspec": {
   "display_name": "Python 3 (ipykernel)",
   "language": "python",
   "name": "python3"
  },
  "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.10.13"
  },
  "widgets": {
   "application/vnd.jupyter.widget-state+json": {
    "state": {},
    "version_major": 2,
    "version_minor": 0
   }
  }
 },
 "nbformat": 4,
 "nbformat_minor": 5
}