With the official retirement of GageInterp, this tutorial outlines how to convert point precipitation data into gridded precipitation data using HEC-MetVue's MetInterp. This process covers adding spatial attributes to DSS data using a configuration file, generating a MetInterp control file, configuring the command-line utility, and automating the run using an HEC-RTS Python script.

Software Version Used

CWMS 3.5 (HEC-MetVue 3.4.1 and CWMS-Vue 4.0.0) was used to develop this tutorial.

Tutorial Data

Download the following files to follow along with this tutorial:

Consolidated download of the 5 files above: 

Step 1: Prepare the CSV File

GageInterp control files store gage names, coordinates, DSS paths, and time zones (starting around line 100). Because older point precipitation DSS files often lack spatial attributes, you must assign spatial metadata before MetInterp can process them.

  1. Create a CSV file with the following exact headers: pathname,x,y,xyDatum,xyUnits,coordSys,coordID,timeZone
    1. Pathname: The DSS pathname (e.g., //HarpethR_Bellevue/PRECIP-INC//15MIN/ExampleData/)
    2. X: Longitude
    3. Y: Latitude
    4. xyDatum: 2 for this example
      1. 0: Unset, 1: NAD83, 2: NAD27, 3: WGS84, 4: WGS72, 5: Local
    5. xyUnits: 3 for this example
      1. 0: Unset, 1: English, 2: SI, 3: Decimal Degrees, 4: DMS
    6. CoordSys: 1 for this example
      1.  0: None, 1: Lat/Lon, 2: State Plane FIPS, 3: State Plane ADS, 4: UTM, 5: Local
    7. CoordID: leave blank for this example
      1. If using UTM or State Plane, uncomment line 51 in the script
    8. TimeZone: Match the GMT setting from your original GageInterp control file
  2. Ensure your CSV is saved with UTF-8 encoding (verified via Notepad++).

A CSV file (LocationScriptConfig.csv) with all necessary information is provided to follow along with this tutorial. You can use it as a template to build one for your specific dataset if needed.

Step 2: Run the Script in CWMS-Vue

  1. Open the provided DSS_SupInfo_set-location.py script (provided in the DSS_SupInfo_set-location.7z file).
  2. Update the file paths in lines 34 and 35:
    1. Line 34: Path to the configuration CSV file.
    2. Line 35: Path to the target DSS file.
  3. Run the script inside CWMS-Vue.

Open the target DSS file, select your data, and navigate to Display > Supplemental Information. You should now see newly generated location information.

You should also see a new DSS record for each location with a C-Part of Location Info.

Step 3: Create the MetInterp Control File

If you need more information, please refer to Creating an HEC-MetVue Project for instructions on how to create a session before continuing. 

  1. Open HEC-MetVue and load your project,
  2. Select your Map Window and click the MetInterp icon in the main ribbon to open the editor.
  3. Click New to create a control file
    1. (e.g., Tutorial.metinterp)
  4. Input the necessary information on the General Settings tab.
    1. Configure the Time, Parameter, and Unit Settings:
      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
    2. Configure the Spatial Domain:
      1. Coordinate System: Standard Hydrologic Grid (SHG) coordinate system.
      2. Lower Left X: 380
      3. Width: 60
      4. Lower Left Y: 725
      5. Height: 35
      6. Grid Cell Size: 1
    3. Configure the Missing Data Options:
      1. Allowable Missing Data: 20% (Gages missing more than 20% of data during the timeframe are excluded).
      2. Default Value: 0.0 (Replaces missing values for valid gages).
  5. Input the necessary information on the Gage Settings tab.
    1. Click Add Time Series and browse to your updated DSS file.
    2. Select the relevant gages matching your old GageInterp control file and click Add Pathnames.
    3. Use Plot All Time Series to visually validate the data.
  6. Configure the Interpolation and Adjustment Settings tab.
    1. Click Add to create a new interpolator and adjust:
      1. Name: ID2W
      2. Spatial Interpolation Method: InverseDistanceSquared
      3. Vertical Adjustment Method: None
      4. Temporal Sampling Method: None
  7. Configure the Output Settings tab.
    1. Provider: DSS
    2. Save Type: SHG
    3. DSS File: Target output path for the grids.
    4. Path Parts:
      1. A: SHG
      2. B: NASHVILLE
      3. F: INT-ID2W
    5. F-Part Modifier: Replace
    6. Switch the Map Window to be the active Map Window in your session.
  8. Click Apply to save your edits, then Run.

Your results should look like the figure below.

Example MetInterp Control File

Download this file (Nashville.metinterp) if you want the completed MetInterp file for this tutorial.

Step 4: Configure the MetInterp Command Utility

To automate MetInterp runs via script, you need to prepare its command-line wrapper.

  1. Navigate to your /HEC-MetVue/utilities/windows/ folder.
  2. Copy MetInterp.cmd and rename the copy.
  3. Open the copied .cmd file in a text editor and make two edits:
    1. Change line 45 from set usage_help=-? to set usage_help=%*
      1. This change enables argument passing.
    2. Remove the pause command at the end of the file to prevent script execution stalls.

Step 5: Automate in HEC-RTS via Scripting

To execute MetInterp dynamically during an HEC-RTS forecast (handling start/end times and file destinations automatically), use a Python script.

  1. Download and unzip the runMetInterp.7z file.
  2. Open the script and update the two required configuration variables near the top:
    1. MetInterp_Control: Set to your control file name (e.g., Nashville.metinterp) assuming it resides in the HEC-MetVue project directory.
    2. CustomMetInterpInstance: Set to your modified command utility name from Step 4 above.
  3. Open HEC-RTS, load your watershed, and open/create a forecast.
  4. Ensure all required precipitation gage data is extracted.
  5. Execute runMetInterp.py within the HEC-RTS Script Editor.

Once complete, a confirmation dialog will appear, and the generated MetInterp grids will be available within the forecast.dss file.

Additional Resources

Refer to the official HEC-DSS Documentation for more details on location information.

Refer to the official HEC-MetVue Documentation for more details on MetInterp.