WRF-Hydro Logo

Open Source GIS Pre-Processing Tutorial

This notebook will rely on the WRF-Hydro GIS Pre-processing tools, found here:

Table of Contents

  1. Create domain boundary shapefile
  2. Build GeoTiff raster from a WPS Geogrid file
  3. Building the hydrologic routing grids, aka the "routing stack"
  4. Understanding the outputs
  5. Examine outputs of GIS pre-processor
  6. Vizualize the output grids
  7. Optional - Build Non-NWM WRF-Hydro Configurations of the Pocono, PA Test Case

First, set the file paths for inputs and outputs

Throughout this exercise, we will use python variables to store directory paths and other variables. However, we will call all GIS Pre-processing functionality as though it were on the command line. This is done by adding ! syntax before the command-line syntax, to execute the line using bash.

In this cell, Python variables are created that point to the file paths of the test-case data and an output directory is defined to store the data created by these tools.

1. Create domain boundary shapefile

The tool Create_Domain_Boundary_Shapefile.py takes a WRF (WPS) output file, aka "Geogrid file", and creates a polygon shapefile that defines the boundary of the domain as a single rectangular polygon in projected coordinates. The script will read metadata in the geogrid file and the output shapefile will be in the projection of the WRF domain. The unstaggered grid, or "Mass" grid (e.g. "HGT_M" variable), is used as the routing grid domain by WRF-Hydro.

Request help message from the script

This is an example of the syntax for calling the Create_Domain_Boundary_Shapefile.py tool on the command line. By following the tool with -h or --help, we are able to call the help argument which explains the purpose of the tool, shows the different arguments we can use for this tool, as well as the descriptions for each argument.

When the tool is run in the terminal, it is not necessary to use the exclamation point. In Jupyter Notebook, we can execute command-line syntax using "!".


You will see in the messages above that the tool provides a brief explanation of the expected input and output parameters. This tool requires a geogrid file as input (-i) and a directory to write the outputs into (-o)

Execute the script using command-line syntax

Now that we know what arguments are needed for this tool, we can enter those arguments and run the tool. For this script, we only need to specify the file path to the WPS geogrid file and an output folder to save the result. The result of this tool is a shapefile that shows the geographic boundary of the domain, as defined in the geogrid file.

When running this tool in Jupyter, we can use brackets around our python variable names, and Jupyter will substitute the variable values when executing the syntax. This is akin to using an environment variable on the command-line. For the sake of repeatability, we also print the full syntax for reference. This can be copied into the terminal if desired.


The messages returned by the tool can be quite useful. You will see the coordinate system information printed to the screen and any other progress messages.

Visualize the domain boundary shapefile created in the above example

Now that the domain boundary shapefile has been created, we want to see where the domain is relative to other features on a map. The next cell creates a map and adds the domain boundary as a layer. Use the map to explore the domain. A swipe feature allows the basemap to be changed between OpenStreetMap and satellite imagery.

2. Build GeoTiff raster from a WPS Geogrid file

The tool Build_GeoTiff_From_Geogrid_File.py is a program to export variables from a WRF-Hydro input file (geogrid or Fulldom_hires) file to an output raster format, with all spatial and coordinate system metadata. If a 3-dimensional variable is selected, individual raster bands will be created in the output raster for each index in the 3rd dimension. If a 4-dimensional variable is selected, the first index in the 4th dimension will be selected and the variable will be treated as a 3-dimensional variable described above.

This tool is handy for performing a quick vizualization using GIS or othe software to examine the contents of the WRF-Hydro input file and overlay these grids with other goespatial data.

The tool takes three input parameters: an input Geogrid or Fulldom_hires netCDF file (-i), a variable name (-v), and an output GeoTiff raster file (-o) that the tool will create. For this example, we will export the variable "HGT_M", or surface elevation in meters above sea level.

Request help message from the script


Execute the script using command-line syntax

View outputs

Now that the tool has completed, we want to take a look at the output. We will create another interactive map and load the data as a layer.

Above, you will see the elevation grid applied to the map. This grid is 1km, so there is not much detail, but it is still useful to see if the topographic features are in the correct geographic locations according to the basemap. Also, there is no color-ramp for reference. This is a limitation of using the web browser over a GIS application.

3. Building the hydrologic routing grids, aka the "routing stack"

The Build_Routing_Stack.py script is a program to build the full set of hydrologically-processed routing grids and additional data required by WRF-Hydro. This is the main utility for performing WRF-Hydro GIS pre-processing. The required inputs are the domain file (WPS geogrid file), desired routing grid resolution as a function of geogrid resolution, and other options and parameter values. The output will be a "routing stack" zip file with WRF-Hydro domain and parameter files.

• Required Parameters:
-i -WRF/WPS GEOGRID file (geo_em.d0*.nc)
-d -High-resolution Elevation raster file (Esri GRID, GeoTIFF, VRT, etc.)
-R -Regridding Factor – nesting relationship of routing:land surface model grid cells
-t -Minimum basin area threshold (in routing grid cells)
-o -Output ZIP File containing all script outputs

• Optional Parameters:
--CSV -Station Locations location file (.csv)
-b -Option to mask channel grids not contributing to provided station locations
-r -Reach based (Muskingum / Muskingum-Cunge) routing option
-l -Lake Polygons (polygon feature class or .shp)
-O -OVROUGHRTFAC – Multiplier on Manning's roughness for overland flow. default=1.0
-T -RETDEPRTFAC – Multiplier on maximum retention depth before flow is routed as overland flow. default=1.0
 -LKSATFAC – (script global variable) Multiplier on saturated hydraulic conductivity in lateral flow direction. default=1000.0
--starts -Path to point shapefile or feature class containing channel initiation locations (overrides -t parameter)
--gw -Path to polygon shapefile or feature class containing prescribed groundwater basin locations

Request help message from the script

This tool has many different parameters and possible configurations. Using the command line, we can take a look at the different arguments that can be used, if they are required or optional, and what their default values are.


Execute the script using command-line syntax

We will begin by assigning file paths to python variables, then substitude those values in the command line syntax.

4. Understanding the outputs

The Build_Routing_Stack.py script creates a Zip archive of output files according to the options provided to the tool. There will be at least four netCDF files. The output Zip file may additionally include shapefiles (.shp and accompanying files) describing the geometry of modeled lakes or the vector stream network. Below is an alphabetically sorted list of gridded variables that are created by the Build_Routing_Stack.py tool.

Fulldom_hires.nc file. This file stores 2D gridded variables that describe the hydro routing grid:

Other files:

5. Examine outputs of GIS pre-processor

The Examine_Outputs_of_GIS_Preprocessor.py script is a tool used to create easy-to-use geospatial files for examining the resulting WRF-Hydro input files in a GIS. This script takes the output ZIP file generated using the Process Geogrid script (executed above) and creates a raster from each 2D variable in each WRF-Hydro input netCDF file. In addition, other data will be extracted such as any shapefiles, 1D netCDF tables, etc. The input to the tool should be a .zip file that was created using the WRF Hydro pre-processing tools. The tool will create the output folder if it does not already exist, and write all results to that location.

Request help message from the script

This tool has a single input and single output parameter. Using the command line, we can take a look at the arguments.


Execute the script using command-line syntax

We will define the output directory for the tool to create, then use defined variables to execute the command line tool.

6. Vizualize the output grids

Finally, we want to take a look at some of the output rasters. Below, we utilize a Jupyter widget to choose each raster from a drop down menu. Each of the 2D variables in Fulldom_hires.nc (the routing grid netCDF file) will be displayed as a rectangular grid. Take a look at some of the outputs.

We can also look at the raster data projected onto a map. Use the dropdown widget below the map to add rasters as layers to the map. Use the menu in the top right corner of the map to turn layers on and off. Behind the scenes, each model grid is being reprojected to Web Mercator for overlay on a WMS basemap for some interactivity.

### 7. [Optional] Build Non-NWM WRF-Hydro Configurations of the Pocono, PA Test Case We will run command-line arguments to create output directories for each of the test cases. Then, each cell will run the WRF-Hydro GIS Pre-processor to build the 'routing stack' files. The final command is used to unzip the outputs so they can be more readily used by WRF-Hydro. There are 4 Non-NWM test-case configurations which can all be created using different combinations of arguments to the GIS pre-processor. Currently missing at this time is the Reach-with-Lakes capability as well as the ability to build wrfinput, hydro2dtbl, and soil_properties files.

A. Gridded channel routing configuration with reservoirs and forecast points

This domain is a gridded domain with lakes, gages and a regridding factor of 4 and threshold of 20

B. Gridded channel routing configuration with forecast points, and channel masking

This domain is a gridded domain without lakes. It contains gages, masked basins and a regridding factor of 4 and threshold of 20

C. Reach-based channel routing configuration with forecast points

This domain is a reach-based routing configuration with gages, no masking, no lakes. Regridding factor of 4 and threshold of 20

You have reached the end of Lesson S2