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
| Parameter | Description |
|---|---|
| Job title | Title 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 date | The 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 length | The 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 data | Optional: 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 file | Optional: 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).
| Syntax | Definition |
|---|---|
| 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 type | Description |
|---|---|
| info<*>.txt | File to define input settings for the HYPE simulations (info.txt) |
| <*>timeXXXX.txt | HYPE time output files for each variable defined by the four-letter code XXXX after 'time'. |
| <*>hypeapps-forecast.log | Log file of of how the Fanfar-forecast service was executed on Hydrology-TEP |
| <*>hyss_<seq number>_<run date>_<time stamp>.<index>.log | HYPE 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.txt | simulation assessment, summarising performance criteria over model domain (simass.txt). Note this file is only meaningful if observations are provided to evaluate the model. |
| <*>subass1.txt | subbasin 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.zip | ESRI shapefile with the subbasin/catchment boundaries and corresponding SUBID for each subbasin. This can be used in GIS software. |
| <*>-rp-cout.txt | Model 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.txt | Optional HYPE basin output file. XXXXXXX is the SUBID of the subbasin/catchment. Only produced if the "Output sub-basins" is defined. |
| state_saveYYYYMMDD.txt | Optional HYPE state file. YYYY = year, MM = month, DD = day |
Example outputs for run types Reforecast and Operational
| File name | Description |
|---|---|
| r20200129_0740_i20170103_hindcast_hyss_000_200129_080532.3.log | HYPE general log file for the hindcast simulation |
| r20200129_0740_i20170103_forecast_hyss_000_200129_080925.5.log | HYPE general log file for the forecast simulation |
| info-for-forecast.txt | info.txt file for forecast simulation |
| info-for-hindcast.txt | info.txt file for hindcast simulation |
| r20200129_0740_hypeapps-forecast.log | Log file for the FANFAR forecast service. This example run was executed on 2020-01-29 at 07:40. |
| r20200129_0740_i20170103_forecast_simass.txt | simass.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.txt | subass1.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.txt | time-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.txt | time-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.txt | time-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.txt | time-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.txt | basin-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.txt | simass.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.txt | subass1.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.txt | time-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.txt | time-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.txt | time-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.txt | time-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.txt | basin-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.log | HYPE test log file for the hindcast simulation |
| r20200129_0740_i20170103_forecast_tests_000_200129_080925.5.log | HYPE test log file for the forecast simulation |
Example output for run type Statefile creation
| File name | Description |
|---|---|
| r20200205_1520_i20191130_hindcast_hyss_000_200205_153940.7.log | HYPE general log file for the hindcast simulation |
| info-for-hindcast.txt | info.txt file for hindcast simulation |
| r20200205_1520_hypeapps-forecast.log | Log file for the FANFAR forecast service. This example run was executed on 2020-02-05 at 15:20. |
| r20200205_1520_i20191130_hindcast_simass.txt | simass.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.txt | subass1.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.txt | time-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.txt | time-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.txt | time-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.txt | time-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.txt | HYPE state file valid for 2019-11-30 |
| 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 |
| r20200205_1520_i20191130_hindcast_tests_000_200205_153940.7.log | HYPE 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