The wflow_floodmap model

Introduction

The wflow_floodmap module can generate flood maps from output of a wflow_sbm|hbv| or wflow_routing model.

At the moment there are two approaches for flood mapping 1. wflow_floodmap.py – this is a regular wflow-type model, running at the same resolution as the wflow model used to establish flood maps. The benefit is that it produces dynamic flood maps. The down side is that the results are in the same resolution as the original model. The method is also not volume conservative as it only does a planar inundation and bound to lead to large overestimations in very flat areas.

2. wflow_flood.py (see Scripts folder). This is a postprocessor to results of a wflow model and transforms low-resolution model results into a high-resolution flood map using a (possibly much) higher resolution terrain dataset as input. We recommend to retrieve high resolution terrain from the Bare-Earth SRTM dataset by Bristol University. See https://data.bris.ac.uk/data/dataset/10tv0p32gizt01nh9edcjzd6wa

Method

PM

Configuration

PM

Description of the wflow_floodmap model

Definition of the wflow_floodmap model.

Runs flood mapping (very basic) based on an existing wflow_sbm|hbv model run.

The wflow_sbm|hbv model must have saved mapstacks for water level and discharge for each timestep (run*****.*** and lev*****.***). If the name of you Q and/or H maps are different specify these in the [inputmapstacks] section, e.g:

[inputmapstacks]
Q = runDyn
H = levDyn

If a wflow_bankfull.map map is present in the staticmaps directory that map will be used to determine if the river is flooding, otherwise bankfull is determined using: Bankful = RiverWidth/60 (the RiverWidth map is taken from the runid/outsum directory)

Ini file settings:

[model]
# Maximum distance between a cell to be flooded cell and a river cell
# or already flooded cel. Functions as a max flooding velocity
# Never set lower that the length of one cell.
maxflooddist= 0.3

Usage: wflow_floodmap -C case -R Runid -c inifile -h -I

-C: set the name of the case (directory) to run

-I: generate initial conditions from scratch

-R: set the name runId within the current case

-c name of the config file (in the case directory)

-h displays help information

-l: loglevel (most be one of DEBUG, WARNING, ERROR)

$Author: schelle $ $Id: wflow_floodmap.py 916 2014-02-11 14:49:35Z schelle $ $Rev: 916 $

wflow_floodmap.main(argv=None)

Optional

Perform command line execution of the model. This example uses the getopt module to parse the command line options.

The user can set the caseName, the runDir, the timestep and the configfile.

Description of the wflow_flood post processor

Definition of the wflow_flood post processor.

Performs a planar volume spreading on outputs of a wflow_sbm|hbv|routing model run. The module can be used to post-process model outputs into a flood map that has a (much) higher resolution than the model resolution.

The routine aggregates flooded water volumes occurring across all river pixels across a user-defined strahler order basin scale (typically a quite small subcatchment) and then spreads this volume over a high resolution terrain model. To ensure that the flood volume is not spread in a rice-field kind of way (first filling the lowest cell in the occurring subbasin), the terrain data is first normalised to a Height-Above-Nearest-Drain (HAND) map of the associated typically flooding rivers (to be provided by user through a catchment order) and flooding is estimated from this HAND map.

A sequential flood mapping is performed starting from the user defined Strahler order basin scale to the highest Strahler orders. A HAND map is derived for each river order starting from the lowest order. These maps are then used sequentially to spread flood volumes over the high resolution terrain model starting from the lowest catchment order provided by the user (using the corresponding HAND map) to the highest stream order. Backwater effects from flooding of higher orders catchments to lower order catchments are taken into account by taking the maximum flood level of both.

Preferrably a user should use from the outputs of a wflow_routing model because then the user can use the floodplain water level only (usually saved in a variable name levfp). If estimates from a HBV or SBM (or other wflow) model are used we recommend that the user also provides a “bank-full” water level in the command line arguments. If not provided, wflow_flood will also spread water volumes occuring within the banks of the river, probably leading to an overestimation of flooding.

The wflow_sbm|hbv model must have a saved mapstacks in NetCDF containing (over-bank) water levels The module selects the maximum occurring value in the map stacks provided (NetCDF) and spreads this out over a high resolution terrain dataset using the high resolution terrain, associated ldd and stream order map.

TODO:: enable selection of a time step.

Ini-file settings

The module uses an ini file and a number of command line arguments to run. The ini-file contains inputs that are typically the same across a number of runs with the module for a given study area (e.g. the used DEM, LDD, and some run parameters). For instance, a user can prepare flood maps from different flood events computed with one WFLOW model, using the same .ini file for each event.

The .ini file sections are treated below:

[HighResMaps]
dem_file =SRTM 90m merged/BEST90m_WGS_UTM42N.tif
ldd_file = SRTM 90m merged/LDD/ldd_SRTM0090m_WGS_UTM42N.map
stream_file = Processed DEMs/SRTM 90m merged/stream.map
[wflowResMaps]
riv_length_fact_file = floodhazardsimulations/Stepf_output/river_length_fact.map
riv_width_file = floodhazardsimulations/Stepf_output/wflow_floodplainwidth.map
ldd_wflow = floodhazardsimulations/Stepf_output/wflow_ldd.map
[file_settings]
latlon = 0
file_format = 0

The dem_file contains a file with the high-res terrain data. It MUST be in .tif format. This is because .tif files can contain projection information. At the moment the .tif file must have the same projection as the WFLOW model (can be WGS84, but also any local projection in meters), but we intend to also facilitate projections in the future.

The ldd_file contains the ldd, derived from the dem_file (PCRaster format)

The stream_file contains a stream order file (made with the PCRaster stream order file) derived from the LDD in ldd_file.

riv_length_fact_file and riv_width_file contain the dimensions of the channels within the WFLOW pixels (unit meters) and are therefore in the resolution of the WFLOW model. The riv_length_fact_file is used to derive a riv_length by multiplying the LDD length from cell to cell within the LDD network with the wflow_riverlength_fact.map map, typically located in the staticmaps folder of the used WFLOW model. The width map is also in meters, and should contain the flood plain width in case the wflow_routing model is used (typical name is wflow_floodplainwidth.map). If a HBV or SBM model is used, you should use the river width map instead (typical name wflow_riverwidth.map).

ldd_wflow is the ldd, derived at wflow resolution (typically wflow_ldd.map)

If latlon is 0, the cell-size is given in meters (the default)

If file_format is set to 0, the flood map is expected to be given in netCDF format (in the command line after -F) if set to 1, format is expected to be PCRaster format

[metadata_global]
source=WFLOW model XXX
institution=Deltares
title=fluvial flood hazard from a wflow model
references=http://www.deltares.nl/
Conventions=CF-1.6
project=Afhanistan multi-peril country wide risk assessment

In the metadata_global section the user can enter typical project details as metadata. These are used in the outcoming .tif file. We recommend to follow Climate and Forecast conventions for typical metadata entries (see http://cfconventions.org/). You can insert as many key/value pairs as you like. Some examples are given above.

[tiling]
x_tile=2000
y_tile=2000
x_overlap=500
y_overlap=500

When very large domains are processed, the complete rasters will not fit into memory. In this case, the routine will break the domain into several tiles and process these separately. The x_tile and y_tile parameters are used to set the tile size. If you are confident that the whole domain will fit into memory (typically when the size is smaller than about 5,000 x 5,000 rows and columns) then just enter a number larger than the total amount of rows and columns. The x_overlap and y_overlap parameters should be large enough to prevent edge effects at the edges of each tile where averaging subbasins are cut off from the edge. Slightly larger tiles (defined by the overlap) are therefore processed and the edges are consequently cut off after processing one tile to get a seamless product.

Some trial and error may be required to yield the right tile sizes and overlaps.

[inundation]
iterations=20
initial_level=32

The inundation section contains a number of settings for the flood fill algorithm. The number of iterations can be changed, we recommend to set it to 20 for an accurate results. The initial_level is the largest water level that can occur during flooding. Make sure it is set to a level (much) higher than anticipated to occur but not to a value close to infinity. If you set it orders too high, the solution will not converge to a reasonable estimate.

Command line arguments

When wflow_flood.py is run with the -h argument, you will receive the following feedback:

python wflow_flood.py -h
Usage: wflow_flood.py [options]

Options:
  -h, --help            show this help message and exit
  -q, --quiet           do not print status messages to stdout
  -i INIFILE, --ini=INIFILE
                        ini configuration file
  -f FLOOD_MAP, --flood_map=FLOOD_MAP
                        Flood map file (NetCDF point time series file
  -v FLOOD_VARIABLE, --flood_variable=FLOOD_VARIABLE
                        variable name of flood water level
  -b BANKFULL_MAP, --bankfull_map=BANKFULL_MAP
                        Map containing bank full level (is subtracted from
                        flood map, in NetCDF)
  -c CATCHMENT_STRAHLER, --catchment=CATCHMENT_STRAHLER
                        Smallest Strahler order threshold over which flooding
                        may occur
  -m MAX_CATCHMENT_STRAHLER, --max_catchment=MAX_CATCHMENT_STRAHLER
                        Largest Strahler order over which flooding may occur
  -d DEST_PATH, --destination=DEST_PATH
                        Destination path
  -H HAND_FILE_PREFIX, --hand_file=HAND_FILE_PREFIX
                        optional HAND file prefix of already generated HAND maps
                        for different Strahler orders
  -n neg_HAND, --negHAND=0
            optional functionality to allow HAND maps to become
            negative (if set to 1, default=0)

Further explanation:

-i

the .ini file described in the previous section

-f

The NetCDF output time series or a GeoTIFF containing the flood event to be downscaled. In case of NetCDF, this is a typical NetCDF output file from a WFLOW model. Alternatively, you can provide a GeoTIFF file that contains the exact flood depths for a given time step user defined statistic (for example the maximum value across all time steps)

-v

Variable within the aforementioned file that contains the depth within the flood plain (typical levfp)

-b

Similar file as -f but providing the bank full water level. Can e provided in case you know that a certain water depth is blocked, or remains within banks. In cae a NetCDF is provided, the maximum values are used, alternatively, you can provide a GeoTIFF.

-c

starting point of catchment strahler order over which flood volumes are averaged, before spreading. The Height-Above-Nearest-Drain maps are derived from this Strahler order on (until max Strahler order). NB: This is the strahler order of the high resolution stream order map

-m

maximum strahler order over which flooding may occur (default value is the highest order in high res stream map)

-d

path where the file is stored

-H

HAND file prefix. As interim product, the module produces HAND files. This is a very time consuming process and therefore the user can also supply previously generated HAND files here (GeoTIFF format) The names of the HAND files should be constructed as follows: hand_prefix_{:02d}.format{hand_strahler}, so for example hand_prefix_03 for HAND map with minimum Strahler order 3. (in this case -H hand_prefix should be given) Maps should be made for Strahler orders from -c to -m (or maximum strahler order in the stream map)

-n

allow for negative HAND maps - if this option is set to 1, the user allows the HAND maps to become negative. This can be useful when there are natural embankments which result in a lower elevation than the river bed. However, this option leads to artifacts when the used SRTM is not corrected for elevation and when the river shapefile is not entirely correct (for example if the burned in river is following an old meander. Therefore the user must be very confident about the used data sources (river shape file and digital elevation model corrected for vegetation) when this option is set to 1!

Outputs

wflow_flood produces the following outputs:

Table: outputs of the wflow_flood module

hand_contour_inun.log

log file of the module, contains info and error messages

inun_<-f>_catch_<-c>.tif

resulting inundation map (GeoTIFF)

<dem_file>_hand_strahler_<-c>.tif

HAND file based upon strahler order given with -c (only without -H

Questions can be directed to hessel.winsemius@deltares.nl

$Id: wflow_flood.py $ $Date: 2016-04-07 12:05:38 +0200 (Thu, 7 Apr 2016) $ $Author: winsemi $ $Revision: $ $HeadURL: $ $Keywords: $