Using HMS-PrePro

Prepared By: Cynthia V. Castro

HMS-PrePro contains ArcGIS geoprocessing script tools for extracting data from Esri's Living Atlas,
deriving a watershed network, estimating hydrological parameters, and storing results in a .BASIN
output ASCII file that may be used as input for the HEC-HMS watershed modeling software.

Download: https://github.com/cvcastro/HMSPrePro

Installation / Set-Up
1) Copy or unzip the HMS-PREPRO folder to any location on your hard drive

2) Ensure you have 64-bit geoprocessing capabilities by looking for a folder containing ArcGISx64
in C:\Python27. If you do not see this folder, contact your system administrator for installation.
Running HMS-PrePro without the 64-bit background geoprocessing may cause failures or a
notably longer execution time.

Enable background geoprocessing (64-bit) by clicking the Geoprocessing tab from the ArcMap
toolbar and selecting the Enable box under Background Processing. Click OK.
 Using HMS-PrePro

3) Enable the 3D Analyst and Spatial Analyst extensions by selecting the Customize tab from the
ArcMap toolbar and choosing Extensions. Select the box next to 3D Analyst and Spatial Analyst.

4) Ensure ArcHydro is installed. In ArcMap you will see this toolbar:

a. If not, download and install the appropriate version of Arc Hydro tools here:
http://downloads.esri.com/archydro/ArcHydro/Setup/
b. If you have a 64-bit computer, use the “x64” version for faster background processing.

5) The use of Esri Living Atlas landscape layers requires an ArcGIS Online organizational account.
This is different than an ArcGIS Online personal or global account. You may have been invited to
become a member of an ArcGIS organizational account through your university or workplace. If
so, it is recommended to use the login credentials registered with that organization when using
HMS-PrePro. Contact your organization’s administrator for access.

If you have not been invited to join an existing organizational account, you may create a
temporary one by signing up for the developer trial here:
c. https://developers.arcgis.com/sign-up/
d. NOTE: Access to the landscape layers within the Living Atlas is free and does not
consume any of your organizational credits/tokens.

** Prior to running HMS-PrePro, ensure that you are logged into your organizational account in
ArcMap by selecting File >> Sign In…
 Using HMS-PrePro

Open HMS-PrePro

Using ArcCatalog:

Open ArcCatalog within ArcMap

Navigate to the installation directory in ArcCatalog and expand the HMS-PrePro folder.

Double-click on the script tool to run.

Or, using ArcToolbox:

Open ArcToolbox within ArcMap

Right-click the ArcToolbox folder and select Add Toolbox.

Navigate to the HMS-PREPRO directory and select the HMS-PrePro.tbx. Click Open.
 Using HMS-PrePro

Using the HMS-PrePro GetData Tool

1) Double-click on the GetData script

NOTE: If you encounter an error, first try closing out of ArcMap and re-opening a blank project.

2) ArcGIS Username / ArcGIS Password

a. Input your ArcGIS organizational username and password.

3) Output Geodatabase
a. Create an empty geodatabase and navigate to that directory. This is where the output
layers will be saved. (NOTE: It is possible to create an empty geodatabase within the
tool by selecting the New File Geodatabase icon, as shown below.)

After selecting New File Geodatabase, rename the New File Geodatabase.gdb and
select the icon only once to add the .gdb to the Name field. Select Add.
 Using HMS-PrePro

4) Watershed Boundary
a. Navigate to the watershed boundary layer. This layer may be a shapefile (.shp) or a
feature class within a geodatabase.
b. If you do not have a watershed boundary layer, you may create one for an area of
interest using the ArcGIS Watershed service tool (not part of this tutorial).

For more information about using the Watershed tool, visit:

http://www.arcgis.com/home/item.html?id=8e48f6209d5c4be98ebbf90502f41077

c. NOTE: Do not select a watershed that is too large for your computer RAM and/or
internet connectivity speeds.
d. The watershed boundary may not be edited after execution of HMS-PrePro (without
having to re-calculate all sub-catchments, reaches, junctions, and catchment
parameters). Initial selection of the intended watershed boundary is very important.
e. Ensure that your watershed contains a projected coordinate system prior to execution.

5) Output Coordinates
a. Select the desired output coordinate system.
i. For hydrological purposes, ensure the output coordinate system preserves
spatial area. Examples include the Albers Equal Area Conic projection or the
State Plane systems.
ii. For use with the HMS-PrePro processing script, a Projected Coordinate System
must be selected.
iii. NOTE: The projected coordinate system only applies to the Subbasin and Reach
layers. The landscape rasters (soils, land use, impervious, and DEM) will remain
in the North America Albers Equal Area Conic projection for spatial analysis.
 Using HMS-PrePro

6) ArcHydro

Provide a Stream Threshold based on the number of DEM cells that you wish to define the
stream. The default value is 1000. Smaller stream thresholds will produce more drainage units.

After execution of the GetData script, carefully analyze the size of your catchments and reaches.
If these are too large or small, re-run the script and adjust the “Stream Threshold” value.

Manual editing of catchments/reaches/junctions prior to running the next script is technically

possible, however, if any of the Fields are edited (i.e. Name/HydroID, To_Node, From_Node,
NextDownID, NodeID) and the topology does not match perfectly, HMS-PrePro will be unable to
run the parameterization script. Manual editing of the basin catchments after running ArcHydro
is very typical for land-development projects, because the Node of interest typically lies at a
specific location. Care should be executed in updating the Watershed topology connections if
manual edits are desired.

7) DEM

The Esri Living Atlas may be used to obtain a 30-meter DEM, which is standard across the United
States. A high-resolution DEM may be uploaded by the user from local data.
 Using HMS-PrePro

Click OK to run Get Data.

You will see a dialog box describing the current processing steps and a status bar. Do not close
this box until you see “Completed” at the top.

Once the script has completed, you may navigate to the output folder directory to view the
hydrological geodatabase with landscape layers, subbasins, and reaches. Each of these layers
may be added to ArcMap for viewing.
 Using HMS-PrePro

Using the Preprocess Basin Script

Double-click on the Preprocess Basin script

NOTE: If you encounter an error, first try closing out of ArcMap and re-opening a blank project.
Sometimes, background processing will crash if the layer being processed is open.

1) Select version of HEC-HMS.

2) Select the geodatabase created with the Get Data tool.
3) Select an output folder for the .BASIN HEC-HMS file.
4) Choose a name for the .BASIN file.
5) Select a time interval (whole number) for the HEC-HMS simulation.
6) Choose a Curve Number reduction factor (optional) according to observed/calibrated data.
7) You may choose to employ various Methodologies for basin losses and routing.
See HEC-HMS User’s Manual for more information.
8) Read the “Help” dialogue box for information regarding each Methodology and required input.
** This step is particularly important if you wish to execute the TR-55 Lag Time script. Follow
the user-steps listed under the “Help” screen, and then run the Optional “TR-55 Method” script
after fully executing the “Preprocess Basin” script and updating necessary parameters.
9) Select OK.
 Using HMS-PrePro

Opening .BASIN File in HEC-HMS

Now that you have created a .BASIN file from the hydrological geodatabase, you may use this to
initialize a HEC-HMS model. Further calibration and engineering optimization is necessary to accurately
model the watershed response. These results should not be used for design or judgment purposes
without further analysis by a professional engineer.

1) Open HEC-HMS
Download available: http://www.hec.usace.army.mil/software/hec-hms/downloads.aspx

2) Create a New Project (File >> New…). Choose the U.S. Customary units.

3) Import the .BASIN file (File >> Import >> Basin Model).
Navigate to the directory where you saved the .BASIN file in the HMS-PrePro tool.

4) In the legend, open the Basin Models folder and select your basin. You may optimize the view
by selecting View >> Maximum Extents and changing the percentage value.

You may also import background images (i.e. subbasin, longest flowpath) by selecting View >>
Background Maps >> Add. When importing background images to HEC-HMS, the layer cannot
be contained in a geodatabase. You will need to export the data as a shapefile first.

5) To fully execute a HEC-HMS model, you will need to create a meteorological model, control
specifications, and a simulation run. Refer to the HEC-HMS manual for further information.
 Using HMS-PrePro

Questions

For questions regarding this product, please contact:

Cynthia V. Castro
[email protected]
[email protected]

Please note that no requested coding updates will be conducted on this tool by the Author.
The current tool is compatible with ArcMap 10.7.1. If you wish to update the script codes for improved
performance or for future versions of ArcGIS/ArcPro/HEC-HMS/additional software, you must upload
the modified script back into GitHub for public use and contact the Author, per licensing agreement.
 HMS-PrePro
TR-55 Background & User’s Guide
Prepared By: Cynthia V. Castro

A common approach for determining the runoff time over a watershed is the TR-55 method. According
to the Urban Hydrology for Small Watersheds TR-55 Manual, the time of concentration may be calculated
as the sum of travel times along the longest flow path (USDA, 19861). The longest flow path is split into
three segments that are differentiated by sheet flow (tsh), shallow concentrated flow (tsc), and channelized
flow (tch).
𝑡𝑐 = 𝑡𝑠ℎ + 𝑡𝑠𝑐 + 𝑡𝑐ℎ

0.007(𝑛𝑜𝑙𝐿𝑠ℎ)0.8 𝐿𝑠𝑐 𝐿𝑐ℎ

𝑡𝑠ℎ = 𝑡𝑠𝑐 = 𝑡𝑐ℎ =
𝑃20.5 𝑆𝑠ℎ0.4 3600 𝐾 𝑆𝑠𝑐 0.5 1.49 2/3
(3600 𝑛 𝑅 𝑆𝑐ℎ1/2 )

Where:
P2 = 2-yr, 24-hr rainfall depth (in)
nol = overland flow roughness coefficient
L = length of longest flow path (ft)
S = slope of longest flow path (ft/ft)
K = 16.13 for unpaved surfaces, 20.32 for paved surfaces
n = Manning’s roughness coefficient for channel
R = channel hydraulic radius (ft)
tc = time of concentration (hr)
Sheet flow represents the planar flow that occurs at the headwater of a stream near the most
hydraulically-remote point. Typically, sheet flow occurs for 100 feet or less before transitioning into
shallow-concentrated flow. The TR-55 sheet flow approximation is a simplified version of the kinematic
wave Manning’s equation, developed by Welle and Woodward (19862). Shallow-concentrated flow is
then collected in small swales and gullies. Shallow-concentrated flow is considered to be between 0.1
and 0.5 feet in depth. When flow is collected in a well-defined stream, channel flow is assumed to occur.
The transition between shallow-concentrated and channelized flow is typically assumed to begin where
channels are visible on aerial photography or where surveyed cross-sections establish bankfull conditions
(USDA, 20103). Since detailed channel geometry is unlikely from a DEM, GIS-preprocessors require user-
input for certain channel properties. Field observations, as-built drawings, aerial imagery, and survey
datasets are used to specify channel parameters such as the roughness coefficient and the hydraulic
radius (USACE, 20094).

1
USDA (1986). Urban Hydrology for Small Watersheds: TR-55. 210-VI-TR-55, Second Ed., June 1986.
Washington, D.C.
2
Welle, P.J., and D.E. Woodward (1986). Time of concentration. Hydrology, Technical Note No. N4. U.S.
Department of Agriculture, Soil Conservation Service, NENTC, Chester, PA.
3
USACE (2010). Hydrologic Modeling System HEC-HMS: User’s Manual, Version 3.5. August 2010. US
Army Corps of Engineers, Hydrologic Engineering Center.

4
USACE (2009). HEC-GeoHMS Geospatial Hydrologic Modeling Extension: User’s Manual, Version 4.2.
May 2009. US Army Corps of Engineers, Hydrologic Engineering Center.
 TR-55 User’s Guide
The following figure shows the user-defined parameters required in HMS-PrePro for the TR-55 lag
method. These values should be modified by the user according to local observations.

Figure 1: User-Input for TR-55 Script No. 1

Instructions:

In HMS-PrePro, the TR-55 method uses two separate scripts to allow user-input regarding the flowpath
properties. First, run the Preprocess Basin script tool where fields are automatically added to the longest
flowpath layer and populated according to uniform values from the user-input in Figure 1. For a given
location, the 2-year, 24-hour precipitation may be obtained from a depth-duration-frequency atlas. The
length of sheetflow is specified by the user for values up to 300 feet (typically 100 feet). Average
Manning’s roughness coefficients should be provided for channel and overland flow. The surface type
may be chosen as ‘paved’ or ‘unpaved’, used to determine the K value for shallow-concentrated flow.

Segmented flowpaths for sheet flow, shallow-concentrated flow, and channelize flow are estimated from
the longest flowpath layer. A GIS point feature class called “TR55pts” is created from the Preprocess Basin
script to represent the transition locations between sheet flow, shallow-concentrated flow, and channel
flow. After the Preprocess Basin script is run, the “TR55pts” shapefile points should be edited by the user
and moved to reasonable locations along the longest flowpath layer, according to observed data. After
the point locations are updated, the user should modify Manning’s n-values for channelized flow (field
‘n_ch’) and overland flow (field ‘n_ol’) and the channel hydraulic radius (field ‘R’) in the longest flowpath
layer. The hydraulic radius may be estimated using spatial tools such as 3D-Analyst.
 TR-55 User’s Guide
Next, the TR-55 script should be run once the flowpath transition points have been modified and the
longest flowpath layer fields have been optimized. Select the same geodatabase created by Preprocess
Basin that contains the modified TR-55 points and longest flowpath layers. In the TR-55 script, the user-
defined point locations are used to update the flowpath segment lengths and slopes. The flowpath is
interpolated onto the DEM where elevations are extracted for each upstream and downstream endpoint.
The three TR-55 flowpath equations are solved and summed to determine the time of concentration in
each subbasin and appended to the “Subbasin” layer.

The user should take care to select the same basin file options (i.e. Curve Number Method, Canopy
Method, Unit Hydrograph Method, etc.) when running the TR-55 script as when running the initial
Preprocess Basin script. The resulting basin output text file from the TR-55 tool will be importable into
HEC-HMS. If the user selects the TR-55 method in Preprocess Basin and forgets to update the pertinent
data and run the subsequent TR-55 script, the output .BASIN file will result in an error with instructions to
guide the user in next steps.

Figure 2: Longest flowpath and point output, used to define transition from sheet flow to shallow-concentrated flow to channelized
flow. Points are initially created by the Preprocess Basin script and should be modified per the user. The Manning’s roughness and
Hydraulic Radius (R) attribute values should also be manually updated by the user. Then, the TR-55 script is run for updated
calculations and a new .BASIN output file.