Explanation of the Base Scripts ras2fim
Script name: ras2fim.py
RAS2FIM is computed from a base orchestration python script named ras2fim.py. This script kicks off eight (8) steps in a serial process to create the desired RAS2FIM depth grids and rating curves. An explanation of these scripts is detailed below. Please note that each of these scripts was written such that it could run in a stand-alone mode. An overview of the use of each script is provided below.
Script name: create_shapes_from_hecras.py
The user provides a path to a directory containing HEC-RAS model files. This routine walks the directory and finds all the HEC-RAS projects (.prj). It determines the geometry that is set in the active HEC-RAS plan of each project. If a corresponding HEC-RAS Hierarchical Data Format (g01.hdf) of the geometry does not exist, the script will compute the active HEC-RAS plan so that one is generated. After running all the models, stream centerlines and cross-section vector geometries, and attribute data are read from the HDF files. These data are merged into two shapefiles, named stream_LN_from_ras.shp and cross_section_LN_from_ras.shp.
Note: Considerations create_shapes_from_hecras.py :
- All models must be on the same coordinate reference system (CRS)
- If a HEC-RAS model has multiple reaches and rivers - only the first (main) reach/river is extracted
Script name: conflate_hecras_to_nwm.py
The National Water Model defines rivers and streams within the contiguous United States (CONUS) through the assignment of a unique numeric code known as a feature-id. Within CONUS there are currently approximately 2.7 million stream-reaches defined. The National Water Model configurations calculate stream flows for each of these reaches.
This script determines what portion of the user-provided HEC-RAS models best represents each of the National Water Model streams within the subject HUC-8 watershed. This is determined by:
- Clipping the National Water Model (NWM) streams to the subject HUC-8 watershed boundary
- Setting and attributing points on clipped NWM streams at a regular interval (default = 150 feet)
- Read the stream centerline shapefile for all the HEC-RAS models.
- Buffer the HEC-RAS stream centerline (default = 600 ft) and delete NWM stream points that are not within this buffer
- Snap the remaining points to the HEC-RAS streamlines and retain NWM feature-id attributes.
- Rank and determine the HEC-RAS model with the most snapped feature-id points
- Determine the starting and ending HEC-RAS cross-section for the most popular HEC-RAS model for each feature-id
- Create a CSV lookup
XXXXXXXX_stream_qc.csvwhere XXXXXXXX is the HUC-8. The CSV file Contains feature-id, conflated HEC-RAS models path, cross-section station limits, and peak flow rate from the HEC-RAS model. - Creates a CSV lookup
conflated_ras_models.csvcontaining conflated HEC-RAS models path, corresponding model_IDs and key_model_names from OWP_ras_models_catalog.
Note: Considerations conflate_hecras_to_nwm.py :
- Conflation may return the wrong HEC-RAS model. Check the
XXXXXXXX_interim_list_of_streams.csvfor matches with low counts of snapped points - Two HEC-RAS models may 'split' a feature-id. The most popular wins, however a portion of each HEC-RAS model may be more correct. RAS2FIM simply picks the most popular and ignores the other.
- Confluences are the most likely area for a false snap.
Script name: clip_dem_from_shape.py
This script creates a GeoTIFF for each conflated HEC-RAS model. For flood inundation mapping, a raster digital elevation model (DEM) is required for the floodplain. For RAS2FIM, the terrain is compiled on a HUC-12 watershed basis. The script reads the cross-section shapefile for each conflated HEC-RAS model, and identifies all HUC-12s that intersect with the cross-sections. It then merges the intersected HUC-12s and assigns a name based on the model ID.
The user should supply a path to a terrain surface which will be used for the creation of the flood depth grids. Note that this surface is not used to alter or modify the supplied HEC-RAS models. It is only used for flood depth delineation. These surface data need to be in the same coordinate reference system (CRS) as the provided HEC-RAS models. The user-supplied terrain can be either a GeoTIFF or a Virtual Raster (VRT). Vertical data is converted to feet if the user specifies that HEC-RAS models are in English (SI) units.
Script name: convert_tif_to_ras_hdf5
For the terrain to be used automatically with HEC-RAS, each generated GeoTIFF will need to be converted to a HEC-RAS compliant HDF5 file. This script creates the files using a command line interface with the RasProcess.exe that is packaged and installed with HEC-RAS.
Script names: worker_fim_rasters and create_fim_rasters
This is where the bulk of the RAS2FIM workflow is performed. The conflated 1D HEC-RAS models are executed using their original boundary conditions (BCs) of Water Surface Elevation (WSE) or Normal Depth (ND).
A first pass steady flow file is created for each HEC-RAS model. The script is hard coded to multiply the provided peak discharge at each flow change location by 1.2 and split that resulting value into 76 flow values. For example, a flow of 5100 cfs is broken into flow values at an interval of 68 cfs. Then, a depth is simulated for each cross-section across the HEC-RAS model streamline for 75 flow values, starting with 1 cfs [1 cfs, 69 cfs, 137 cfs … 4964 cfs, 5032 cfs, 5100 cfs]** and a 'first-pass rating curve' is determined for each cross-section.
From the first-pass depth values, a cross-section that has the highest depth is selected and the highest depth is divided into 0.5-foot intervals. For instance, a highest depth of 50 feet is broken into [0.5, 1, 1.5, … 49, 49.5, 50 feet] depth values. From the first-pass rating curve for the highest-depth cross-section, flows are interpolated at points where it is assumed that the HEC-RAS model will compute flood depths at the desired depth intervals (here at 0.5-foot). The interpolated flows are called second-pass flow. Finally, the HEC-RAS model is executed using these flows and RAS2FIM second-pass depth grids are generated at approximately every 0.5 feet.
From these interpolated values, a revised flow file is created and HEC-RAS is recomputed. For this second pass, a RAS Mapper files is written that requests that a flood inundation grid be generated for each depth interval. Note that for all HEC-RAS simulations, flow rates are constant down the reach. All flow is assumed to be sub-critical and downstream energy is set at 'normal depth' with a slope of 0.5%.
Note: Considerations worker_fim_rasters.py :
- This script currently only processes HEC-RAS models that utilize Water Surface Elevation (WSE) or Normal Depth (ND) as boundary conditions (BCs). Support for two less common boundary conditions, "Critical Depth" and "Rating Curve," will be included in future versions of RAS2FIM.
Script names: create_rating_curves
The provided 'cut' to a spatial limits between cross sections that approximate the conflated limits of the National Water Model reach. From these cut models, a synthetic rating curve is computed by running multiple flow rates down the river and computing a reach averaged depth for each discharge. The provided terrain is used in conjunction with RAS Mapper to simulate the model and generate flood depth grids at the prescribed even reach averaged depth increments.
In the conflation output XXXXXXXX_interim_list_of_streams.csv in step #2, each feature-id from the National Water Model that conflates to a HEC-RAS model will note the (1) path to the corresponding HEC-RAS model [ras_path], (2) the cross-section limits upstream [us_xs] and downstream [ds_xs] and (3) the peak flow rate for all cross sections and the profiles within these cross sections [peak_flow].
For example, feature-id #6974668 conflates to the Hunter_Cr model between cross sections 22805 and 20261 with a peak discharge of 135.29 cms.
A new HEC-RAS model is created for the feature-id that is 'clipped' to the limits determined in the conflation process. If available, two (2) additional cross sections area added upstream and downstream of the limits. This is to minimize flood inundation mapping gaps when compositing adjacent reaches' depth grids.
Script names: calculate_all_terrain_stats (optional)
RAS Mapper will delineate any terrain that is provided. It does not determine that the terrain on which the delineation is performed matches the cross-section vertical point data. It is possible that the terrain that is harvested in step #3 from the USGS 3DEP does not match or have the same accuracy as the terrain used to create the provided HEC-RAS models. This script calculates each 'clipped' (step #5) HEC-RAS model and determines the vertical difference between the terrain and the model.
After the completion of the RAS2FIM workflow, it is advised that a maximum threshold for the median, mean and standard deviation of the vertical error be evaluated on each run. If the error is too great, then it is further advised that the flood inundation rasters be disregarded. If this is the case, it would be a good idea to locate a better alternative terrain source that more closely matches the provided HEC-RAS geometry.
This script creates a point at every station-elevation pair along every cross-section in a HEC-RAS model. At each point, the elevation in the model is compared to the elevation of the terrain digital elevation model (DEM). The difference in these points is aggregated on a 'per model' basis and statistics are reported for each model.
Script names: create_geocurves (optional)