.. _forecast:

========
Forecast
========

Forecast series is closely related to (historical) inflow series. The forecast feature
added two extra attributes on the inflow series, ``forecast`` and ``forecast_period``.

``forecast`` is a timeseries (Txy) with a projected inflow.

``forecast_period`` is the range the forecast should be applied for.
It is possible to set ``forecast_period`` on both inflow series and in global settings.

.. toctree::
   :maxdepth: 1
   :glob:

   forecast-notebook.ipynb



Data structure
==============

The forecast and forecast period are the two required timeseries to enable
forecasts. Forecast must be set on the inflow series. Forecast period can be set on either
the inflow series, or in global settings.

Inline and self contained forecast example. It will apply the forecast timeseries in the range ``2023-W25`` - ``2023-W40``.

.. code-block:: json
    :emphasize-lines: 14,21
    :linenos:

    "inflow_series": [
        {
            "name": "testforecast",
            "series": {
                "timestamps": [
                    "1900-01-01T00:00:00Z"
                ],
                "scenarios": [
                    [
                        5.0
                    ]
                ]
            },
            "forecast": {
                "external_reference": {
                    "type": "hdf5",
                    "path": "/inflow/tannsvatn",
                    "filename": "inflow.h5"
                }
            },
            "forecast_period": {
                "timestamps": [
                    "2023-W25",
                    "2023-W45"
                ],
                "scenarios": [
                    [
                        1,
                        0
                    ]
                ]
            }
        },
    ]

To use the same forecast period for all forecasts, global_settings/forecast_period can be set.
For inflow series without forecast_period, they will use the period defined in global_settings.

.. code-block:: json
    :linenos:
    :emphasize-lines: 2

    "global_settings": {
        "forecast_period": {
            "timestamps": [
                "2023-W20",
                "2023-W30"
            ],
            "scenarios": [
                [
                    1,
                    0
                ]
            ]
        }
    }

Inflow explained
----------------

This image copied from the example notebook and it has been annotated with what
the values represent and where they are from. One should expect with a constant
value of ``5.0`` before and after the forecast period, the value should be ``5.0`` and not ``45.0``.

EMPS will normalize the inflow series so the average value is 1.0, and then
apply a scaling (``"average_regulated_inflow": 45``). Both the inflow series
and forecast series will be scaled.

.. figure:: testforecast.excalidraw.png

    Combination of a constant inflow series with a forecast.


How the input data is transformed
---------------------------------

``ForecastData.h5`` has scenario dependent data per forecast series.

.. figure:: scenarios.png

    Forecast used in the example above, with 20 scenarios from 1980 to 2000.

The API can build the data required for a forecast from both a 1D and a 2D timeseries.

.. .. chart:: ltm-api/guides/forecast/chart.json

..     This is the caption of the chart3

These plots visualizes how the forecast is combined from a 1D continuous
time series into a forecast with 20 scenarios.

.. chart:: ltm-api/guides/forecast/constant-inflow.json

    Constant inflow

.. chart:: ltm-api/guides/forecast/forecast-1980-2000.json

    1D variable inflow plotted for years 1980-2000. Highlighted regions are the extracted periods for forecast scenarios 1-20.

For this series, the forecast period is ``2023-W25`` to ``2023-W45``. When using a 1D timeseries,
the API will select data from the corresponding weeks in each historical year.

For 2D inputs there are some hard requirements.

* The data must be defined for the ``forecast_period``.
* Number of dimensions must match number of historical years.

Example with 20 scenarios.

.. chart:: ltm-api/guides/forecast/forecast-2023-2d.json

    2D input time series, with the highlighted region from where data is extracted.