.. _forecast:

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

|rameau| is able to run an ensemble forecast. Forecast can be activated in the
TOML configuration file.

.. code-block:: toml

    [forecast]
    forecast = true

.. _forecast_settings:

Forecast settings
=================

Emission date
-------------

The date and time for which to issue a forecast is defined through the
``emission_date`` key. If omitted, the default value corresponds to the last
date of the meteorological input data.

.. code-block:: toml

    [forecast]
    emission_date = 2009-01-01

Scope
-----

The ``scope`` key is the time between the ``emission_date`` and the end of
the probabilistic forecast.

Default value is one day.

.. code-block:: toml

    [forecast]
    scope = { days = 30 } # Format : { days = 30, minutes = 0, hours = 0, seconds = 0 }

Ensemble forecast members
-------------------------

|rameau| uses the past climatology to produce the ensemble forecast members.
Each year of the past climatology corresponds to a member. The years to consider
to form the forecast ensemble members are provided through the ``year_members``
key. If not provided, all years in record are considered.

For example, we consider a 30-day forecast issued on 2009-01-01. Inputs
provide meteorological data from 2000-01-01 to 2009-12-31. Therefore, the
forecast ensemble will consists in 10 simulations all starting from
2009-01-02 using the following meteorological inputs: 

* 1\ :sup:`st` member: from 2000-01-02 to 2000-01-31
* 2\ :sup:`nd` member: from 2001-01-02 to 2001-01-31
* ...
* ...
* 10\ :sup:`th` member: from 2009-01-02 to 2009

We could have also used the ``year_members`` key for selecting specific
years, for example 2000 and 2001 to have a 2-members ensemble forecast.

.. code-block:: toml

    [forecast]
    year_members = [2000, 2001]

No rain member
--------------

An additional member using a rain-free scenario can be added to the ensemble
by turning the ``norain`` key to true.

Default value is false.

.. code-block:: toml

    [forecast]
    norain = false

Quantiles output
----------------

By default, |rameau| provides river flow and groundwater level forecast
outputs for each member. If the ``quantiles_output`` key is set to
true, outputs correspond to quantiles defined by the ``quantiles`` key.

Default value to false for ``quantiles_outputs``.

Default values for ``quantiles`` are 10%, 20%, 50%, 80% and 90%.

.. code-block:: toml

    [forecast]
    quantiles_output = false
    quantiles = [10, 20, 50, 80, 90]

Forecast correction method
--------------------------

Two correction methods are available for the ensemble forecast. The key
``correction`` can be set to one of the following:

* "no" does not apply any correction
* "halflife" applies a correction to the forecast : the forecast values
  are corrected to match the observed values on the emission date. The
  initial correction is then propagated through time by applying a decay
  factor to the difference between the forecasted and observed values.

Default value is "no".

.. code-block:: toml

    [forecast]
    correction = "no"

Pumping date to consider
------------------------

Pumping can be applied to the forecast ensemble members. The ``pumping_date``
key is used to define the date from which to apply the pumping.

.. code-block:: toml

    [forecast]
    pumping_date = 1999-07-01

.. _forecast_parameters:

Forecast correction parameters
==============================

Forecast correction parameters correspond to the halflife times of the
output correction method when issuing a forecast. Two keys
``forecast.river.halflife`` and ``forecast.groundwater.halflife``
for river flows and groundwater levels, respectively, can be set for
each watershed of the model. These keys accept float values. A
value of zero means no half-life correction.

Default values are 0.

.. code-block:: toml

    [watershed.1]
    forecast.river.halflife = 2
    forecast.groundwater.halflife = 1
    [watershed.2]
    forecast.river.halflife = 0
    forecast.groundwater.halflife = 1

Note that these parameters are taken into account only if the key ``correction``
is set to ``halflife`` in the `forecast settings <:ref:_forecast_settings>`_.

A full example
==============

The example below set the forecast settings for a 30-day forecast issued on
2009-01-01 using the years 2000 and 2001 as ensemble members. A rain-free
scenario is added to the ensemble. The forecast outputs are quantiles 25%,
50%, and 75%. Halflife output method is applied to groundwater level and river
flow for watershed 1, and only to river flow for watershed 2.

.. code-block:: toml

    [forecast]
    forecast = true
    emision_date = 2009-01-01
    scope = { days = 30 }
    year_members = [2000, 2001]
    norain = true
    quantiles_output = true
    quantiles = [25, 50, 75]
    correction = "halflife"
    pumping_date = 1999-07-01
    [watershed.1]
    forecast.river.halflife = 1
    forecast.groundwater.halflife = 1
    [watershed.2]
    forecast.river.halflife = 2
    forecast.groundwater.halflife = 0