Creating Inputs for the Flood Inudation Surface Topology (FIST) Flood Inundation Mapping Software - MikeFHS/automated-rating-curve GitHub Wiki

Once you have ARC output, mainly your Curvefile.csv and/or VDT_Database.txt, we can use these to create flood inundation maps. One option is to use the FIST software.

For the same stream network you used to create your CurveFile.csv, you'll also need to retrieve the streamflow's you'll want to use for your FIST simulation and a means to convert those into inputs for your simulation. For instance, you may want to download the latest GEOGLOWS ECMWF forecast and simulate the mean of the this forecast ensemble. For FIST, the streamflow input will need to be in the same format you generated in Step 1 but have just one streamflow value for each stream reach.

To create the inputs for FIST, the Python script Create_GeoJSON.py was created. The script does two things.

  1. Builds the SEED dataset which determines the upstream extents of the model domain.

  2. Creates a GeoJSON file that will be used by FIST to simulate flood inundation.

Create_GeoJSON.py has two options for determining SEED locations, a stream raster based methodology and a stream vector based methodology.

The process of creating the SEED dataset with a stream raster can be quite a slow process but it is only required before the first simulation. Once the "SEED_Points.txt" file is built, the script can by-pass creating the file and just read it into memory instead.

The function Write_SEED_Data_To_File_Using_Stream_Raster() in the Create_GeoJSON.py script provides us the ability to create the SEED dataset. It has three inputs:

  1. STRM_Raster_File (str): The path to the stream raster that you created as input for ARC in Step 2.
  2. DEM_Raster_File (str): The path to the DEM raster that you used as input for ARC in Step 2.
  3. SEED_Point_File (str): The path to the file where you will store you SEED output. An empty FIST directory was set up in Step 2 as a place to stash this file.

Write_SEED_Data_To_File_Using_Stream_Raster() can be called using an independent Python script, like in example_step4.py, or via command line. If you choose to use the command line, type write-seed-stream-raster -h into the command line for additional instructions.

Once you simulate Write_SEED_Data_To_File_Using_Stream_Raster(), your SEED data output will look something like the image below:

image

The rows in this image describe the location of the furthest upstream stream cells for the streams in your simulation. FIST needs to know this information.

Once Write_SEED_Data_To_File_Using_Stream_Raster() has built the SEED file, the function GetSEED_Data_From_File() can be used to read in your SEED file and thus by-pass the tedious processing needed to create the file. See example_step4.py for how to run this function from a separate Python script.

The Run_Main_Curve_to_GEOJSON_Program_Stream_Raster() then takes the SEED information, Curvefile.csv, and other inputs, and uses this to create GeoJSON files that will be input into FIST. See example_step4.py for how to run this function from a separate Python script.

Run_Main_Curve_to_GEOJSON_Program_Stream_Raster() inputs are:

  1. CurveParam_File (str): The CurveFile.csv you created in Step 3.
  2. COMID_Q_File (str): The file containing the unique ID and streamflow for your area of interest that you intend to simulate flood inundation for using FIST.
  3. STRM_Raster_File (str): The path to the stream raster that you created as input for ARC in Step 2.
  4. OutGeoJSON_File (str): The path to the GeoJSON file that will be used as input into the FIST model. An empty FIST directory was set up in Step 2 as a place to stash this file.
  5. OutProjection (str): The string describing the output coordinate system of of the GeoJSON file (e.g., "EPSG:4269").
  6. SEED_Lat (arr): An array of latitude float values read from the SEED file that describe the locations of SEED points in your domain of interest.
  7. SEED_Lon (arr): An array of longitude float values read from the SEED file that describe the locations of SEED points in your domain of interest.
  8. SEED_COMID (arr): An array of integers that are unique stream identifiers read from the SEED file that identify the streams in your domain of interest.
  9. SEED_r (arr): An array of integers that describe the row values read from the SEED file. These row values are the row where the SEED values are in the stream cell raster.
  10. SEED_c (arr): An array of integers that describe the column values read from the SEED file. These column values are the column where the SEED values are in the stream cell raster.
  11. Thin_Output (bool): True/False of whether or not to filter the output GeoJSON.

Using the stream vector is a faster way to determine SEED values and doesn't require the extra step of building file to store the SEED locations. The function Run_Main_Curve_to_GEOJSON_Program_Stream_Vector() will quickly find the SEED locations, using the stream vector network described in Step 2, and will identify the SEED locations in the resulting GeoJSON file. Run_Main_Curve_to_GEOJSON_Program_Stream_Vector() relies on the Python library Networkx (thank you ChatGPT) to identify all uppermost streams in your domain. The code then finds the uppermost coordinates of those uppermost stream reaches, which are our SEED locations.

Run_Main_Curve_to_GEOJSON_Program_Stream_Vector() requires the following inputs:

  1. CurveParam_File (str): The CurveFile.csv you created in Step 3.
  2. COMID_Q_File (str): The file containing the unique ID and streamflow for your area of interest that you intend to simulate flood inundation for using FIST.
  3. STRM_Raster_File (str): The path to the stream raster that you created as input for ARC in Step 2.
  4. OutGeoJSON_File (str): The path to the GeoJSON file that will be used as input into the FIST model. An empty FIST directory was set up in Step 2 as a place to stash this file.
  5. OutProjection (str): The string describing the output coordinate system of of the GeoJSON file (e.g., "EPSG:4269").
  6. StrmShp (str): The file path and file name of the vector shapefile of flowlines you used in Step 2.
  7. Stream_ID_Field (str): The field in the StrmShp that is the streams unique identifier.
  8. Downstream_ID_Field (str): The field in the StrmShp that is used to identify the stream downstream of the stream.
  9. SEED_Output_File (str): The file path and file name of the output shapefile that contains the SEED locations and the unique ID of the stream each represents. An empty FIST directory was set up in Step 2 as a place to stash this file.
  10. Thin_Output (bool): True/False of whether or not to filter the output GeoJSON.

The output GeoJSON from either the stream raster or stream vector workflow contains point features that look like the image below. These points are stream cell locations from the CurveParam_File where the a and b parameters have been paired with a streamflow to estimate the water surface elevation. This is not a very pretty file, but the unnecessary spacing has been removed from the GeoJSON to reduce the file size.

image

The points in the SEED dataset will be marked as "SEED": "1" in the GeoJSON file. FIST utilizes the water surface elevation ("WaterSurfaceElev_m" in the GeoJSON) and the location of the stream cell from the GeoJSON to produce a flood inundation map.

Also, by marking Thin_Output = True, the stream cells have been filtered in two ways that attempt to reduce the likelihood of outliers and reduce redundancy, these are:

  1. Removes stream cells that have depths that are greater than 3 times the average depth for the stream reach
  2. Removes stream cells that are within 50 meters of other streams and have water surface elevations that are within 0.05% of one another.

The remaining stream cells are fed into FIST producing a flood inundation map like the image below:

image

Run_Main_Curve_to_GEOJSON_Program_Stream_Vector()can be called using an independent Python script, like in example_step4.py, or via command line. If you choose to use the command line, type curve-to-geojson-stream-vector -h into the command line for additional instructions.

If you prefer to use the VDT_Database.txt to create your GeoJSON input, the functions Run_Main_VDT_to_GEOJSON_Program_Stream_Raster() and Run_Main_VDT_to_GEOJSON_Program_Stream_Vector() can be ran just like Run_Main_Curve_to_GEOJSON_Program_Stream_Raster() and Run_Main_Curve_to_GEOJSON_Program_Stream_Vector() are but pointed to the VDT_Database.txt instead of the CurveFile.csv.

If you're following along with the Shields River test case, an example "COMID_Q_File" containing a streamflow forecast can be found here in the "714_ExampleForecast" folder.

Try running this test case on your own using example_step4.py on your local machine using the test case data provided above and the data you produced in Step 2 and Step 3. The example_step4.py assumes we're using the vector methodology we discussed above.