Page tree
Skip to end of metadata
Go to start of metadata

Introduction

The FANFAR forecast service is a software run on the Hydrology-TEP platform that produces up-to-date forecasts of hydrological variables across West Africa 1-10days ahead. It constitutes the hydrological model engine of of the FANFAR forecasting and alert system. The service utilize the HYPE model applied to the West African domain to calculate hydrological variables (e.g. river discharge, evapotranspiration, runoff, and water level) based on historical meteorological data, meteorological forecasts, and optionally assimilation of local observations and satellite data. The service is executed in the sequence described in the system overview.

This page provides a brief documentation of what the service does, its inputs and outputs. A guide explaining how to use the service in practice is also available here.

The first date of the forecast is called "Forecast issue date". In this service, it is possible to set the forecast issue date to the current date, or to any other date back to 2017-01-01. The service always makes two simulations: first a warm-up simulation (the hindcast) ending on the day before the forecast issue date, then the actual forecast simulation beginning from the end of the warm-up simulation and running 10 days ahead (the forecast). The figure below illustrates the workflow of the service.

Input parameters

The processing service takes the following input parameters

ParameterDescription
Job titleTitle of the job
Model configuration

This entry provides a drop-down list with pre-configured model configurations.  A model configuration is the specific combination of meteorological data for the historic period (hindcast), meteorological data for the forecast period, and the hydrological model. The available model configurations are listed here.

Forecast issue dateThe first date in the forecast period. Here it is possible to choose either the current date or any date back to 2017-01-01 (in order to recreate a past situation)
Hindcast period lengthThe number of days to use to warm-up the hydrological model. This is done in order to stabilize hydrological stores in the model. Typically several years are needed for the largest reservoirs and lakes. The default value of 10 years is normally sufficient.
Run type

The service can be run with three different run modes:

1) Reforecast: Use this mode to recreate a forecast for a date in the past. In this mode, the software only utilizes data that were available at the defined forecast issue date. We recommend to use this mode in most cases.

2) Operational: This mode is used to make the best possible forecast for the current date and it is intended to be used primarily in automatic production. In this mode, the software utilizes the currently best available data. Normally this will be the same data as in the Reforecast mode for today's date, but sometimes input data production is delayed and then other data sources will be used instead. Note the Operational mode should NOT be used to recreate a forecast for a past date since it will use all available data, and not consider what was available at the time of the forecast.

3) Statefile creation: This mode is only for experts / developers, and is intended to optimize simulation speed. It will create a HYPE statefile for the selected forecast issue date, and only uses best-quality datasets in the meteorological hindcast period (e.g. HydroGFD-EI data for HydroGFD2.0). Note in this mode, only one simulation is made for the historic period (hindcast).

Output variables

The hydrological variables that the service should provide output for. By default the service produces output for discharge (COUT), precipitation (adjusted according to HYPE settings, CPRC), surface runoff (CROS), and evapotranspiration (EVAP). If desired, more output variables can be selected here.

A detailed description of all the HYPE output variables is available here: http://www.smhi.net/hype/wiki/doku.php?id=start:hype_file_reference:info.txt:variables

A detailed description of all the HYPE output files is available here: http://www.smhi.net/hype/wiki/doku.php?id=start:hype_file_reference#output_files

Output sub-basins (SUBID)

Optional: If output is desired for a specific model catchment it can be obtained by entering its SUBID here. To know which SUBID correspond to which catchment one can either

1) check at https://fanfar.eu/ivp/ by clicking on a catchment, or by searching for a gauge, city or SUBID in the Location search functionality.

2) Utilize the subbasin_shp.zip output file in a GIS software to see the catchments and corresponding SUBID.

Xobs file(s) with EO or in-situ dataOptional: HYPE Xobs.txt file containing EO or in-situ data
Assimilation on/off

Define if the observations shall be assimilated or not.

Available modes are:

1) off: Assimilation disabled (default).

2) on: Assimilation using local streamflow observations.

3) on with auto-regressive updating: Assimilation using local streamflow observations and applying an auto-regressive updating method.

Assimilation observations

Optional: The type of observation to be assimilated.

Available output variables:

1) Lake Water Level - altimetry AOWL WCOM: AOWL (preliminary, variable is in development state), Water level at lake output (WCOM).

2) River Discharge - in-situ ROUT COUT: Observed outflow (ROUT), Computed outflow (COUT).

Model configuration fileOptional: A file containing the specifications of which model configuration to use. This can be used alternatively to the model configuration drop-down menu above.

Outputs

The service produces a set of output files defined below. The first table defines the generic syntax of specific keywords used in a number of subsequent files. The second table then defines which file types are produced. Subsequently follows specific examples of output files for each Run type.

Generic syntax

Note: <> indicates that this part of the file name is replaced by something else for each specific output file, and '*' means any character(s).

SyntaxDefinition
r<YYYYMMDD_HHMM><*>r - run date of the simulation. YYYY = year, MM = month, DD = day, HH = hour, MM = minute.
i<YYYYMMDD><*>

i - forecast issue date of the simulation. YYYY = year, MM = month, DD = day.

<*>forecast<*>Data belonging to the forecast period, produced during the forecast simulation.
<*>hindcast<*>Data belonging to the hindcast period (warm-up period before the forecast issue date), produced during the hindcast simulation.

File types

Note: <> indicates that this part of the file name is replaced by something else for each specific output file, and '*' means any character(s).

File typeDescription
info<*>.txtFile to define input settings for the HYPE simulations (info.txt)
<*>timeXXXX.txtHYPE time output files for each variable defined by the four-letter code XXXX after 'time'.
<*>hypeapps-forecast.logLog file of of how the Fanfar-forecast service was executed on Hydrology-TEP
<*>hyss_<seq number>_<run date>_<time stamp>.<index>.logHYPE general log file documenting how the HYPE run was executed (one for the hindcast simulation and one for the forecast simulation)

<*>tests_<seq number>_<run date>_<time stamp>.<index>.log

HYPE test log file, created for model tests.
<*>simass.txtsimulation assessment, summarising performance criteria over model domain (simass.txt). Note this file is only meaningful if observations are provided to evaluate the model.
<*>subass1.txtsubbasin assessment, performance criteria for all applicable subbasins (subassX.txt). Note this file is only meaningful if observations are provided to evaluate the model.
subbasin_shp.zipESRI shapefile with the subbasin/catchment boundaries and corresponding SUBID for each subbasin. This can be used in GIS software.
<*>-rp-cout.txtModel specific file with a table of discharge levels for the return periods of 2 years, 5 years and 30 years for several SUBID (* is e.g. westafrica-hype)
<*>XXXXXXX.txtOptional HYPE basin output file. XXXXXXX is the SUBID of the subbasin/catchment. Only produced if the "Output sub-basins" is defined.
state_saveYYYYMMDD.txtOptional HYPE state file.  YYYY = year, MM = month, DD = day

Example outputs for run types Reforecast and Operational

File nameDescription
r20200129_0740_i20170103_hindcast_hyss_000_200129_080532.3.logHYPE general log file for the hindcast simulation
r20200129_0740_i20170103_forecast_hyss_000_200129_080925.5.logHYPE general log file for the forecast simulation
info-for-forecast.txtinfo.txt file for forecast simulation
info-for-hindcast.txtinfo.txt file for hindcast simulation
r20200129_0740_hypeapps-forecast.logLog file for the FANFAR forecast service. This example run was executed on 2020-01-29 at 07:40.
r20200129_0740_i20170103_forecast_simass.txtsimass.txt file for a simulation run (r) on 2020-01-29 at 07:40 and with forecast issue date (i): 2017-01-03, for the forecast period.
r20200129_0740_i20170103_forecast_subass1.txtsubass1.txt file for a simulation run (r) on 2020-01-29 at 07:40 and with forecast issue date (i): 2017-01-03, for the forecast period.
r20200129_0740_i20170103_forecast_timeCOUT.txttime-output file with simulated river discharge data for all sub-basins and time steps, for a simulation run (r) on 2020-01-29 at 07:40 and with forecast issue date (i): 2017-01-03, for the forecast period.
r20200129_0740_i20170103_forecast_timeCPRC.txttime-output file with simulated corrected precipitation data for all sub-basins and time steps, for a simulation run (r) on 2020-01-29 at 07:40 and with forecast issue date (i): 2017-01-03, for the forecast period.
r20200129_0740_i20170103_forecast_timeCROS.txttime-output file with simulated surface runoff data for all sub-basins and time steps, for a simulation run (r) on 2020-01-29 at 07:40 and with forecast issue date (i): 2017-01-03, for the forecast period.
r20200129_0740_i20170103_forecast_timeEVAP.txttime-output file with simulated evapotranspiration data for all sub-basins and time steps, for a simulation run (r) on 2020-01-29 at 07:40 and with forecast issue date (i): 2017-01-03, for the forecast period.
r20200129_0740_i20170103_forecast_0207002.txtbasin-output file for sub-basin 207002, providing several output variables for the specific sub-basin (SUBID=XXXXXXX), for a simulation run (r) on 2020-01-29 at 07:40 and with forecast issue date (i): 2017-01-03, for the forecast period.
r20200129_0740_i20170103_hindcast_simass.txtsimass.txt file for a simulation run (r) on 2020-01-29 at 07:40 and with forecast issue date (i): 2017-01-03, for the hindcast period.
r20200129_0740_i20170103_hindcast_subass1.txtsubass1.txt file for a simulation run (r) on 2020-01-29 at 07:40 and with forecast issue date (i): 2017-01-03, for the hindcast period.
r20200129_0740_i20170103_hindcast_timeCOUT.txttime-output file with simulated river discharge data for all sub-basins and time steps, for a simulation run (r) on 2020-01-29 at 07:40 and with forecast issue date (i): 2017-01-03, for the hindcast period.
r20200129_0740_i20170103_hindcast_timeCPRC.txttime-output file with simulated corrected precipitation data for all sub-basins and time steps, for a simulation run (r) on 2020-01-29 at 07:40 and with forecast issue date (i): 2017-01-03, for the hincast period.
r20200129_0740_i20170103_hindcast_timeCROS.txttime-output file with simulated surface runoff data for all sub-basins and time steps, for a simulation run (r) on 2020-01-29 at 07:40 and with forecast issue date (i): 2017-01-03, for the hindcast period.
r20200129_0740_i20170103_hindcast_timeEVAP.txttime-output file with simulated evapotranspiration data for all sub-basins and time steps, for a simulation run (r) on 2020-01-29 at 07:40 and with forecast issue date (i): 2017-01-03, for the hindcast period.
r20200129_0740_i20170103_hindcast_0207002.txtbasin-output file for sub-basin 207002, providing several output variables for the specific sub-basin (SUBID=XXXXXXX), for a simulation run (r) on 2020-01-29 at 07:40 and with forecast issue date (i): 2017-01-03, for the hindcast period.
subbasin_shp.zip

ESRI shapefile with the subbasin/catchment boundaries and corresponding SUBID for each subbasin.

niger-hype-rp-cout.txt or

westafrica-hype-rp-cout.txt or

thresholds-rp-cout.txt

Model specific file with table of discharge levels for the return periods of 2 years, 5 years and 30 years for several SUBID
r20200129_0740_i20170103_hindcast_tests_000_200129_080532.3.logHYPE test log file for the hindcast simulation
r20200129_0740_i20170103_forecast_tests_000_200129_080925.5.logHYPE test log file for the forecast simulation

Example output for run type Statefile creation

File nameDescription
r20200205_1520_i20191130_hindcast_hyss_000_200205_153940.7.logHYPE general log file for the hindcast simulation
info-for-hindcast.txtinfo.txt file for hindcast simulation
r20200205_1520_hypeapps-forecast.logLog file for the FANFAR forecast service. This example run was executed on 2020-02-05 at 15:20.
r20200205_1520_i20191130_hindcast_simass.txtsimass.txt file for a simulation run (r) on 2020-02-05 at 15:20 and with forecast issue date (i): 2019-11-30, for the hindcast period.
r20200205_1520_i20191130_hindcast_subass1.txtsubass1.txt file for a simulation run (r) on 2020-02-05 at 15:20 and with forecast issue date (i): 2019-11-30, for the hindcast period.
r20200205_1520_i20191130_hindcast_timeCOUT.txttime-output file with simulated river discharge data for all sub-basins and time steps, for a simulation run (r) on 2020-02-05 at 15:20 and with forecast issue date (i): 2019-11-30, for the hindcast period.
r20200205_1520_i20191130_hindcast_timeCPRC.txttime-output file with simulated corrected precipitation data for all sub-basins and time steps, for a simulation run (r) on 2020-02-05 at 15:20 and with forecast issue date (i): 2019-11-30, for the hindcast period.
r20200205_1520_i20191130_hindcast_timeCROS.txttime-output file with simulated surface runoff data for all sub-basins and time steps, for a simulation run (r) on 2020-02-05 at 15:20 and with forecast issue date (i): 2019-11-30, for the hindcast period.
r20200205_1520_i20191130_hindcast_timeEVAP.txttime-output file with simulated evapotranspiration data for all sub-basins and time steps, for a simulation run (r) on 2020-02-05 at 15:20 and with forecast issue date (i): 2019-11-30, for the hindcast period.
state_save20191130.txtHYPE state file valid for 2019-11-30
subbasin_shp.zipESRI shapefile with the subbasin/catchment boundaries and corresponding SUBID for each subbasin.

niger-hype-rp-cout.txt or

westafrica-hype-rp-cout.txt or

thresholds-rp-cout.txt

Model specific file with table of discharge levels for the return periods of 2 years, 5 years and 30 years for several SUBID
r20200205_1520_i20191130_hindcast_tests_000_200205_153940.7.logHYPE test log file for the hindcast simulation

More information

The source code of the service is available at https://github.com/hydrology-tep/fanfar-forecast



  • No labels