GageInterp has officially been retired. Moving forward, one of the routes to take point precipitation data into gridded precipitation data is utilizing HEC-MetVue's MetInterp. 

Applications packaged with CWMS 3.5  were used in this tutorial. (HEC-MetVue 3.4.1 and CWMS-Vue 4.0.0)

Material

DSS_SupInfo_set-location.py

PointPrecip.dss

GageInterp.control

LocationScriptConfig.csv

Goal

This tutorial will work through the process of taking a GageInterp Control file and dss data that does not have spatial attributes noted to be able to utilize MetInterp. Then once we have MetInterp setup, using HEC-RTS script editor to take the gage data from their respective location directly into the forecast.dss file. 

Process 

Step 1: Data Preparation 

  1. Open the Gage Interp Control File.
  2. Starting at line 100 of the GageInterp.control file, we have our gage name, lat and long, path and timezone.
  3. Open the PointPrecip.dss file and check the gage's supplemental information. 
    1. Select the data of interest → Display (top ribbon) → Supplemental Information
  4. There is no location information associated with the gages we are interested in, so we need to add it. We will use the DSS_SupInfo_set-location.py script within DSSVue or CWMS-Vue
  5. If you open the DSS_SupInfo_set-location.py within CWMS-Vue, there are two user inputted values needed at lines 34 and 35. 
    1. Line 34 needs to be switched to the path of your CSV we are discussing in the next few steps.
    2. Line 35 will be the path to your DSS file that houses the gage data for gageInterp/MetInter
  6. The DSS file is the data we are going to reformat to include location information. The csv file is a configuration file that we will create. 
  7. To create a csv for this script, we will use the following headers: pathname,x,y,xyDatum,xyUnits,coordSys,coordID,timeZone
    1. If you are using excel to do formatting, it is suggested to check the encoding in an application such as Notepad++. We are looking for an encoding of UTF-8 for this process. 
    2. Pathname: The dss pathname such as //HarpethR_Bellevue/PRECIP-INC//15MIN/ExampleData/
    3. x: In this example, it is the longitude
    4. y: In this example, it is the latitude. 
    5. xyDatum: In this example, we are using data in NAD27, so we will put in a value of "2"
      1. 0: unset
      2. 1: NAD83
      3. 2: NAD27
      4. 3: WGS84
      5. 4: WGS72
      6. 5: Local (other)
    6. xyUnits: Our example is in feet, so we will use "3"
      1. 0: unset
      2. 1: English
      3. 2: SI
      4. 3: Decimal Degrees
      5. 4: Degrees Minutes Seconds
    7. CoordSys: We are using lat/lon values, so we will use option "1"
      1. 0: No Coordinate System Set
      2. 1: lat/lon
      3. 2: State Plane, FIPS
      4. 3: State Plane, ADS
      5. 4: UTM
      6. 5: Local (other)
    8. CoordID is not needed unless the UTM or State Plane Coordinate systems are used. So we will leave it blank in this example
      1. This also coincides with a commented out line in the script. If you do want to associate a CoordID, you will also need to uncomment line 51
    9. timeZone: We are using GMT from the GageInterp Control file
  8. Now that we have the csv file setup with the needed parameters and updated the paths to point to our dss file and csv, we can run the script in CWMS-Vue. 
  9. If we look at the DSS file and go to the supplemental information, we can see that information has been generating giving the records location information. Additionally, there will be new DSS records with a C-Part of "Location Info" in the DSS file. 

Step 2: Create MetInterp Control File 

  1. Go to HEC-MetVue and generate the session and map you want to use with MetInterp.
    1. We will not walk through this process in this tutorial. Please refer to Creating an HEC-MetVue Project for instructions on how to create a session. 
  2. Click on map for GageInterp/MetInterp and then select the MetInterp icon on the main ribbon. This will open the main MetInterp Editor
  3. The interface should be rather blank for the first time (HEC-MetVue will retain the information for times latest and will fill the interface)
  4. We will select the New at the top to create a new control file. We will be using "Tutorial.metinterp" in this walk through. 
  5. The first portion of the interface (Time, Parameter and Unit Settings), we are going to use the Create Multiple Images and note a timeperiod of interest and then select the output parameters we desire for the MetInterp grids
    1. Start Time: 09Feb2025 0000
    2. End Time: 16Feb2025 0000
    3. Time Step: 15 Minutes
    4. Time Zone: GMT
    5. Parameter: PRECIP-INC
    6. Data Type: PER-CUM
    7. Units: IN
  6. Moving to the spatial domain, this will also be the outputted grids. If we are wanting to feed results from MetInter to HEC-HMS, it is best to select a coordinate system of Standard Hydrologic Grid (SHG). 
    1. We can figure out the spatial domain using references such as can be found in HEC-HMS documentation. 
    2. Another option is that once we add the gages in a later step, HEC-MetVue will note the gage locations
    3. For this example, we can go ahead and use some known values:
      1. Lower Left X: 380
      2. Width: 60
      3. Lower Left Y: 725
      4. Height: 35
      5. Grid Cell Size 1
  7. For the Missing Data Options, we are going to do a 20% Allowable Missing Data and a default value of 0.0.
    1. Allowable Missing Data: This is the threshold for when the gage will or will not be considered in the MetInterp Calculations. 
      1. We will use 20% in this example
    2. Default Value: This is the value that will replace any missing data
      1. When it comes to missing rainfall values, the value is commonly set to zero. 
    3. So if a gage in our example has more than 20% of its data missing between 09 February 2025 0000 and 16 February 2025 0000, it will not be used in the MetInterp calculations for grids. If the gage is missing less than 20% of the timeseries data, it will be used in the MetInterp calculations and any missing data will be listed as "0".
  8. Now we will move on to the Gage Settings tab of the MetInterp Editor. Here we will add the gages of interest. 
  9. Click on the Add Time Series and navigate to the HEC-DSS file that has your gages.
    1. Select the gages and then Add Pathnames
    2. This is where we will utilize the GageInterp control file and go through the HEC-DSS file and select the gages we included in the control file.
  10. Once we have all the gages selected, our interface should like this

    1. As noted earlier in step 6 we can see the X and Y value corresponding to each gage in the output coordinate system we selected. So we can utilize this to help figure out our spatial domain. 
    2. Additionally, we can plot all the data utilizing the Plot All Time Series button to check the data. 
  11. Moving to the Interpolation and Adjustment Settings tab of the editor, we will add an interpolator. 
    1. We are going to name ours "ID2W" and select the Spatial Interpolation Method of InverseDisntanceSquared while leaving the Vertical Adjustment Method and Temporal Sampling Method as their default of None.
  12. Moving the last tab, we have the Output Settings.
  13. For the Save Location, we will use the following parameters
    1. We are going to have a Provider of DSS
    2. Save Type: SHG
    3. DSS File: This will be the output location of the MetInterp grids
    4. Path Parts:
      1. A: SHG
      2. B: NASHVILLE
      3. F: INT-ID2W
      4. F-Part Modifier: Replace
  14. For Results Display Settings, we will have our Interpolator Name (ID2W) and Map Window is set to None by default, lets switch that to our Map Window. 
  15. Select Apply and click Run.
  16. This is what our MetInterp results should look like: 
  17. We can see our gage locations and areas of impact from the visual. Then in the bottom, we can see how much rainfall each polygon registered and then see the basin average values. 

Step 3: Using the MetInterp command Utility with the control file 

  1. Go to your HEC_MetVue instance and through the utilities/windows folders to get to the "MetInterp.cmd"
  2. Copy the "MetInterp.cmd" and rename the cmd
  3. Edit the new cmd in notepad or some other application. Do not run the cmd file yet
  4. On line 45, we are going to switch from set usage_help=-?  to set usage_help=%* .This is to change the utility from initiated the usage help to utilizing the information we are going to feed the utility to run. 
  5. Remove the pause at the end of the cmd as well.
    1. This is a pause so if you were to run it in cmd, you would be able to see the results. Our end goal is to run it via a script, so we do not want this user inputted value. 

Step 4: Utilizing HEC-RTS scripting to access MetInterp within a Forecast 

These steps will be to utilize MetInterp from a HEC-RTS forecast via scripting. This will take the MetInterp Control file we have created, make it dynamic with the forecast for the start and end time as well as the output location of the control file.

Here is an example script: runMetInterp.py 

This script is mostly dynamic with your forecast and control files but there are two variable you will need to modify to work with your model. At line 11, we have MetInterp_Control = "Richland.metinterp", this will need to be changed to the name of your MetInterp control file. It is also assumed that this control file is within your HEC-MetVue project of your HEC-RTS model. Then we have CustomMetInterpInstance = "MetroNashvilleMetInterp.cmd" which is the command utility that we slightly modified modified to run MetInterp. This is assumed to be within the HEC-MetVue/utilities/window packaged within the instance of HEC-RTS being used. 

  1. Open HEC-RTS and watershed we are desiring MetInterp grids within
  2. Open/Create a forecast for MetInterp to be used as model inputs
  3. Collect all the required data for MetInterp to run (precipitation gages used in the control file).
  4. Run the "runMetInterp.py" script within the HEC-RTS Script Editor.
  5. Once the runMetInterp.py script finishes, should get a dialog noting that it has completed.
    1. There is error handling throughout the script that should catch most user errors.
    2. The MetInterp Grids should be within the forecast.dss file now

Additional Resources

Additional information on location information from the HEC-DSS documentation: Location information

Additional information on MetInterp from the HEC-MetVue documentation: MetInterp