Description: Starting with geospatially attributed one-dimensional HEC-RAS floodplain models, these scripts are used to create a library of flood depth inundation rasters for a range of storm water discharges (flow). HEC-RAS models are cut to roughly match the limits of the National Water Model's {NWM} stream designations (hydrofabric). For each matching NWM stream, a synthetic rating curve is created based on 'reach averaged' flood depths as determined from the HEC-RAS simulations. The intent it to create a library of flood depth inundation grids with a ccorresponding rating curve that can be paired with the National Water Model's discharges determination and forecasting to create real-time and predictive floodplain mapping from a detailed HEC-RAS 1-D model.

• Technology stack: Scripts were all developed in Python 3.8.11. Use is intended within a custom 'ras2fim' Anaconda environment running on a Windows OS. Prior to running these scripts, the user is required to install and run HEC-RAS v 6.3.
  
  
• Status: Version 1 - Inital release. Refer to to the CHANGELOG.
  
  
• Related Project: Inspiration for this repository was to develop flood inundation map libraries to replace Height Above Nearest Drainage (HAND) as calculated with the FIM inundation mapping repository.
  
  
• Overview Video: Link to overview video of ras2fim
  Since the video was first produced, ras2fim has continued to evolve, but there is still valuable information in the video that you want to view. Notes for viewing:
  The total runtime is 5 min and 41 seconds.
  - The first part of the video shows folder pathing that has since been update and this part should be ignored. Updated folder pathing including donwloading from ESIP S3 is discussed later in this document.
  - The second part, at appx 1:00 in, shows examples of how to run ras2fim.py and its parameters. This is also now out of date and should be ignored.
  - When the video gets too appx 1:45 seconds and shows the ras2fim.py actively processing, it is still largely applicable.
  

RAS2FIM Wiki: More detail regarding RAS2FIM is located on the project's Wiki page.

Overview:

While ras2fim.py and other tools have optional parameters allowing pathing to any folder(s), we do recommended folder structure as shown below based on your c: drive.

All documentation in this repo are based on the default folder structure.

There are folders and files that will need to be downloaded locally prior to running the RAS2FIM code. This data can be found in an Amazon S3 Bucket hosted by Earth Science Information Partners (ESIP). The data can be accessed using the AWS Command Line Interface (CLI) tools. AWS CLI installation details are shown below. This S3 Bucket (s3://noaa-nws-owp-fim) is set up as a "Requester Pays" bucket. Read more about what that means here.

You will need permission from ESIP to access this data. Please contact Carson Pruitt ([email protected]) or Fernando Salas ([email protected]) for assistance.

1. Install AWS CLI tools
2. Configure AWS CLI tools

To list folders prior to download:

aws s3 ls s3://noaa-nws-owp-fim --requester-pays

If you want to review a sample output for ras2fim.py, you can dowload a folder that was generated using five models in 12090301 HUC8.

aws s3 sync s3://noaa-nws-owp-fim/ras2fim/output_ras2fim C:\ras2fim_data\output_ras2fim --requester-pays

To do some test processing, you will need to download additional ESIP folders which include the inputs and the OWP_ras_models folders. We have provided a small sample set of five models based on 12090301 HUC8. The model folder includes a number of sub-folders, one per model, that has gone through preprocessing steps to convert some raw HEC-RAS data to data which can be processed by ras2fim.py. ras2fim.py will create output rating curves, REMs and other output files.

While not yet determined, we may publish more models later, however, you are also welcome to create our own models and use the ras2fim.py tools.

The OWP tools to preprocess HEC-RAS data to OWP_ras_models is not yet available.

The downloaded inputs folder is appx 14.3 Gb.

aws s3 sync s3://noaa-nws-owp-fim/ras2fim/inputs c:\ras2fim_data\inputs --requester-pays

This download will include the following files / folders:

1. Watershed Boundary Dataset (WBD): WBD_National.gpkg
2. The WBD_National.gkpg split into different gpkg files by HUC8: /WBD_HUC8/*
3. National Water Model (NWM) Flowline Hydrofabric: nwm_flows.gpkg
4. National Water Model to Watershed Boundary Lookup: nwm_wbd_lookup.nc
5. National Water Model (NWM) Catchments file: nwm_catchments.gpkg
   
   

At this point, ras2fim.py needs a file named OWP_ras_models_catalog.csv, or similar, and we have loaded a sample for you. It has some meta data that is used in the final output files. While the file must exist with the correct schema, it will not fail if records in it do not match. This file may become optional at a later point, but for now, please include it and also add the -mc argument to ras2fim.py. eg. -mc c:\ras2fim_data\OWP_ras_models\OWP_ras_models_catalog.csv (or pathing of your choice of course, as is with most arguments).

To download the OWP_ras_models folder, you AWS CLI command will be (adjusting for path overrides if you like):

aws s3 sync s3://noaa-nws-owp-fim/ras2fim/OWP_ras_models c:\ras2fim_data\OWP_ras_models --requester-pays

These RAS2FIM scripts are written to utilize the computational engine and supporting APIs from the U.S Army Corp of Engineers' Hydrologic Engineering Center's River Analysis System {HEC-RAS}. Download and install HEC-RAS version 6.3 to your local machine. Note: the version (6.3) matters!

The install package can be downloaded from the USACE website. Once installed, open HEC-RAS on that machine to accept the terrms and conditions and ensure that it will function on that machine prior to running any RAS2FIM scripts. Close HEC-RAS.

Install git onto your Windows machine. Next, clone this ras2fim reporitory on to your Windows machine (see note below). Path to the windows folder of your choice, then type:

git clone https://github.com/NOAA-OWP/ras2fim.git (see note below)

Note: ras2fim V2 series has started development as of early November 2023. Initial check-ins for the default branch will fail for the short term future until an advanced version is ready. When the CHANGELOG.md shows version check-ins starting with the phrase V2.0.beta.x, means the branch is not yet operational but you are still welcome to contibute to the new WIP branch. Once the usable versions have been merged, the CHANGELOG.md will start with the number of v2.0.0.0.
If you want to view the last stable V1 series, use the following git clone command which will come from the ras2fim main (V1) branch.

git clone https://github.com/NOAA-OWP/ras2fim.git -b V1

Detailed instructions on setting up a ras2fim anaconda environment and running the ras2fim script can be in the INSTALL document.

• HEC-RAS Version 6.3.
• Anaconda or Miniconda for Windows.
• National datasets - from AWS - See "Get AWS Folder - Inputs" section above.
• Runs on a Windows OS only - Tested on Windows 10.
• Tested on HEC-RAS 6.3 and default pathing is also set against v6.3.

Details coming soon.

Please see the issue tracker on GitHub and the Ras2Fim Wiki for known issues and getting help.

NOAA's National Water Center welcomes anyone to contribute to the RAS2FIM repository to improve flood inundation mapping capabilities. Please contact Carson Pruitt ([email protected]) or Fernando Salas ([email protected]) to get started.

1. TERMS
2. LICENSE

1. Office of Water Prediction (OWP)
2. Goodell, C. R. (2014). Breaking the Hec-Ras Code: A User’s Guide to Automating Hec-Ras. H2ls.
3. Executive Summary, & Guidance, S. (n.d.). InFRM Flood Decision Support Toolbox. Usgs.Gov. Retrieved October 22, 2021
4. Collete, A. (2013). Python and HDF5: Unlocking Scientific Data. O’Reilly Media.
5. Board on Earth Sciences and Resources/Mapping Science Committee, Committee on FEMA Flood Maps, Mapping Science Committee, Board on Earth Sciences & Resources, Water Science and Technology Board, Division on Earth and Life Studies, & National Research Council. (2009). Mapping the zone: Improving flood map accuracy. National Academies Press.
6. Dysarz, Tomasz. (2018). Application of Python Scripting Techniques for Control and Automation of HEC-RAS Simulations. Water. 10. 1382. 10.3390/w10101382.
7. Documentation. (n.d.). River Analysis System. Army.Mil.

Special Thanks to: Cam Ackerman (US Army Corp of Engineers), Kristine Blickenstaff (US Geological Survey), Chris Goodell (Kleinschmidt Associates), Witold Krajewski (Iowa Flood Center), RoseMarie Klee (Texas Department of Transportation), David Maidment (University of Texas), Saul Nuccitelli (Texas Water Development Board), Paola Passalacqua (University of Texas), Jason Stocker (US Geological Survey), Justin Terry (Harris County Flood Control District)