Tutorial - Using the GIS routing model to produce streamflow

This document contains a basic tutorial and training exercise for using the GIS routing model to route output from the Running a spatial domain simulation tutorial. Source code and documenation for the GIS routing model, including related literature and in-depth discussion of commands can be found at the GIS-Routing-Model GitHub page.

This tutorial assumes that you have a working knowledge of Linux/Unix, and that you have access to a Purdue Linux cluster.

• If you are a member of PHIG then you can request access to the cluster computer account through Dr. Cherkauer.

• If you are a member of another research group with access to an RCAC cluster, you can request access through your advisor.

• If you are enrolled in ABE 65100 Environmental Informatics you should have access to the scholar cluster during the class.

Step 1: Download or copy the GIS model input files

This tutorial is based on existing GIS routing model input files for the Red River of the North, which was the focus of the tutorial on running a spatial VIC model simulation. If you already know how to use the GIS routing model to route surface runoff and baseflow from the VIC model output files, and need to setup GIS routing model input files for a new watershed, refer to the more complete tutorial on setting up the GIS routing model.

1. Log into the Linux cluster front-end system for this tutorial, and open a terminal.

2. Change into the main folder you used for the VIC model spatial tutorial, create a new folder called RoutingModelParams.

3. Change into the directory.

4. There are several ways to access the required parameter files (a list of the required files can be found on the GitHub page for training materials:

   • If you are on the PHIG depot drive, you can copy all files directly using the command cp /depot/phig/apps/GitHub/GIS-Routing-Model/TrainingMaterials/RunningModelTutorial/* ..

   • You can clone the full repository to another location, and copy all files from the TrainingMaterials/RunningModelTutorial/ folder into the current location.

   • You can download the files individually from the GitHub page.

Step 2: Create the fractional area file

Next, the ASCII raster file containing the contributing area for each grid cell (ws1090_area.txt) must be converted into a list as required by the routing model. An example of the list file is shown below:

    # Sample File Contents
1       1       fluxes_47.1875_-95.5625 38.870000
2       2       fluxes_47.1875_-95.4375 43.110000
3       3       fluxes_47.0625_-95.6875 30.680000
4       4       fluxes_47.0625_-95.5625 119.400000
5       5       fluxes_47.0625_-95.4375 48.210000
6       6       fluxes_46.9375_-95.9375 5.590000
7       7       fluxes_46.9375_-95.8125 62.430000
8       8       fluxes_46.9375_-95.6875 53.170000
9       9       fluxes_46.9375_-95.5625 118.560000
10      10      fluxes_46.9375_-95.4375 25.600000
11      11      fluxes_46.8125_-96.9375 11.860000
12      12      fluxes_46.8125_-96.8125 103.270000
...

The contents of this file are as follows:

• The first two columns in this file are not used by the original model and are preserved for backwards compatability only. They can be filled with any integers.
• The third column is the name of the flux file for each VIC simulation cell.
• The fourth column is the fractional area (square meters) of the simulation cell that contributes to discharge for the current watershed.

The ArcGIS toolbox currently develops an ASCII (plain text) raster file, so a simple script such as the one provided here can be used to convert that file into the format required by the routing model.

Here is a sample script example for converting the ASCII raster file to the required list file:

arcgrid_to_xyz.script <watershed>_fract.txt | awk '{ printf( "%i\t%i\tfluxes_%.4f_%.4f\t%f\n", NR, NR, $2, $1, $3 ) }' > fract_area_<watershed>.list

Note

The awk command in this example uses the %.4f formatting command to limit the number of decimal places used in creating the flux file name to four. This is the standard when running the model using a 1/8th degree grid. If the model is run using a different resolution, such as 1/16th degree, the number of decimal places to maintain in the flux file name will need to be adjusted.

To build this file for this tutorial:

1. Change into the folder RoutingModelParams, which should contain the ws1090 watershed files.

2. Enter the command:

   arcgrid_to_xyz.script ws1090_fract.txt | awk '{ printf( "%i\t%i\tfluxes_%.4f_%.4f\t%f\n", NR, NR, $2, $1, $3 ) }' > fract_area_ws1090.list
   

Step 3: Create the Unit Hydrograph file

With the model parameter files in place, the next step is to use them to create a unit hydrograph file. This file will tell the routing model how long it takes for water from each grid cell to reach the outlet, and how much of the VIC model surface runoff and baseflow for a given time step arrives at the outlet by the hour. Timing is based on the mean and standard deviation of travel time (in hours) calculated using the ArcGIS pre-processing toolbox. This information is contained in the files ws1090_ttmean.txt (mean travel time) and ws1090_ttstd.txt (standard deviation of travel time) that you copied in the previous step of the tutorial.

Note

The prefix of the parameter files will always be "ws" for watershed followed by a number. The number is derived from ArcHydro delineation process. The actual number does not matter, as long as it is not changed, since that is the primary way to relate the files used by the routing model back to the ArcGIS pre-processing database, which includes streamlines, Manning N values, travel times and the original USGS gage number.

Note

The routing model can be used with any acceptable VIC model time step (typically 24, 3, 2, or 1 hours) but the routing model and all input files MUST be run at the same time step as the model output is stored in the flux files. If OUT_RUNOFF and OUT_BASEFLOW are stored on a daily basis, the routing model must also be run on a daily basis - even if the model was run with a subdaily time step. If they are stored hourly, then the routing model must be run using the same hourly time step.

1. Change into the folder RoutingModelParams.

2. Confirm that you have access to an executable version of MakeUnitHydrographFiles program.

   • If you are a member of PHIG, then you should be able to run the program directly on a Linux cluster. If you cannot, refer to the instructions for setting up your account at the PHIG Configuration Files GitHub repository.

   • Otherwise, you may need to compile the GIS routing model yourself:

     • Clone the GIS Routing Model reposity using git clone https://github.itap.purdue.edu/PHIGOrganization/GIS-Routing-Model.git.
     • Then change into the lib directory.
     • If you are on a Purdue cluster, load the gcc module using module laod gcc.
     • Build the library files using the command make.
     • Then change into the src directory and build the model executables with the command make.
     • If desired, you can edit the Makefile to set the correct location to install the executable files, and then run make install to copy the executables to the install folder. If the install folder is in your environmental PATH (e.g., defined in .bashrc, .bash_profile, .cshrc) then the code will work once you re-source your configuration file or start a new shell.

3. Create the unit hydrograph file by running the MakeUnitHydrographFiles program. The usage message for the program is as follows, where the routing time step should match the time step of OUT_RUNOFF and OUT_BASEFLOW as they appear in the VIC model output file being routed:

   Usage: MakeUnitHydrographFiles <mask grid> <mean time grid> <std time grid> <out file> <routing time step (hrs)>
   
       This will generate the unit hydrograph file required by the GIS 
       routing model.  Routing model parameter files must be created using 
       ArcGIS toolbox before the unit hydrograph can be created, and the 
       unit hydrograph must match the time step of the 
       VIC model flux files.
   
       <mask grid> is the ArcGIS ASCII gridfile mask of the watershed being 
           routed;
       <mean time grid> is the ArcGIS ASCII gridfile of mean travel times 
           from each grid cell to the outlet;
       <std time grid> is the ArcGIS ASCII gridfile of travel times standard 
           deviation from each grid cell to the outlet;
       <out file> is the name of the unit hydrograph file to be created;
       <routing time step (hrs)> is the time step in hours of the data to 
           be routed - MUST match the time step of the VIC model 
           output file.
   

4. The program requires the watershed mask file(ws1090_mask.txt), as well as the mean and standard deviation of travel time files.

5. For the purpose of this tutorial, use the following command:

   MakeUnitHydrographFiles RoutingParamFiles/ws1090_mask.txt ws1090_ttmean.txt ws1090_ttstd.txt ws1090_iuh_3hr.txt 3
   

Step 4: Run the routing model

The current version of the routing model will use the header in the VIC model output files to identify the columns where OUT_RUNOFF and OUT_BASEFLOW are stored. For this to work, you need to make sure that you activated the output file header in the VIC model global file before running the simulation.

Note

The time step and column definitions were hard-wired in the original Fortran based GIS routing model code, which required that the model be edited and recompiled or that multiple version be kept on hand to handle changes to time step and output columns.

1. Change into the home directory of the spatial model tutorial, which has subdirectories for the routing model parameters and VIC model output files.

2. Confirm that you have access to an executable version of GisStreamflowRouting program, if not follow the instructions for installing code fromt he previous step.

3. This program will route OUT_RUNOFF and OUT_BASEFLOW from the selected VIC model output files to the watershed outlet defined in the pre-processing steps. The usage message for the program is shown below:

   Usage: GisStreamflowRouting <flux path> <discharge time step> <mask grid> <unit hydrograph file> <fract file> <out file>
   
       GIS routing model will generate streamflow discharge for the 
       selected watershed using output from the current VIC model 
       simulation.  Routing model parameter files must be created using 
       ArcGIS toolbox before the model is run, and must match the time 
       step of the VIC model flux files.
   
       <flux path> is the path where the flux files to be routed are stored;
       <discharge time step> is the time step of the VIC model output files 
           (should match that used to create unit hydrograph file);
       <mask grid> is the ArcGid ASCII Raster file with watershed mask;
       <unit hydrograph file> is the unit hydrograph for the watershed;
       <fract file> is a list of VIC model output files with the contributing 
           area (sq km) from each grid cell in the watershed; and
       <out file> is the output discharge file with two columns:
           [1] datetime (MM-DD-YYYY or MM-DD-YYYYTHH, 
               MM = Month, DD = Day, YYYY = year, HH = hour), 
           [2] discharge (cubic meters per second).
   

4. The GIS routing model requires access to the VIC model output files, the watershed mask file, the unit hydrograph file created in Step 3, and the fractional area file created in Step 2. With that information, it will create a single output file with datetime and discharge in cubic meters per second based on the defined time step. Here is the usage message from the GisStreamflowRouting model:

5. For the tutorial, OUT_RUNOFF and OUT_BASEFLOW are routed to a location on the Red River near Fargo, ND that is the location of a USGS streamflow gage (USGS 05054000). For the purposes of this tutorial, that is known as watershed 1090.

6. Create a new folder for the discharge file called Streamflow., using the command mkdir Streamflow.

7. For the purpose of this tutorial, use the following command to run the routing model:

   GisStreamflowRouting ./Results 3 RoutingModelParams/ws1090_mask.txt RoutingModelParams/ws1090_iuh_3hr.txt RoutingModelParams/fract_area_ws1090.list Streamflow/RedRiver-discharge.txt

The routing model can be run any number of times for the same watershed, using any number of VIC model output file sets - as long as the output file time step does not change. To change the time step of routing, you must rerun the step to build the unit hydrograph, since the unit hydrograph files are constructed specifically for the time step used by the VIC model output. To change the effects of land use or channel you must redo the ArcGIS pre-processing steps as they affect the travel time of water through the watershed.

Step 5: View the discharge

Note

Waiting for someone to complete this tutorial and share their figure and plotting code.

Finally, create a plot of the routed discharge from the VIC model in the file Streamflow/RedRiver-discharge.txt versus the observed discharge fromt he USGS station. Remember that the USGS streamflow is typically in cubic feet per second (cfs), while the routing model returns discharge in cubic meters per second.

Would be interesting for that plotting code to use Python and the USGS API for accessing streamflow data.