Select Page

This tutorial assumes that you have already created your own app instance of eRAMS using the instructions from  Namely, will be need to have the following steps completed before starting this tutorial:

  • Create an eRAMS app instance hosted on the cloud
  • Create a user account on the app instance created in the previous step
  • Generate an eRAMS app template called “my_app” and checkout the app template to your local computer

To complete the tutorial, you’ll need:

  • Mercurial source control management program
  • Familiarity with Python
  • 1 – 2 hours to complete the tutorial

In this tutorial we will show you how to create the HTML, JavaScript, and Python code for designing your new app. We will assume the app name is “my_app” for this tutorial.

The app will estimate total runoff volume and peak flow for a watershed and display the results in a table and graph. To calculate this, you’ll generate a geospatial layer of hydrologic response units (HRU) and a climate data table. These inputs will be generated using tools provided by the eRAMS platform based on an initial area of interest and an outflow point.

This tutorial is split into two sections. The first demonstrates how you can use existing tools in eRAMS to generate the required inputs. The second is writing the code that will collect the inputs for the runoff calculation, execute it and display the results.

Login to your eRAMS app instance.  Select the Projects button from the left navigation bar and create a new app using the “my_app” project type that you generated from previous steps.  Once you have created the app, click the GIS/Analysis tab in the header to open the map page.

Section 1: Creating the Inputs

Create or upload an existing watershed layer.

To create the layer, click on the map toolbar icon Map Toolbox on the top of the map and select Hydrology -> Watershed Delineation.

Watershed Creation Dialog

Use the mouse to drag the map to a desired location (such as Fort Collins, CO) or use the Zoom To entry in the upper left corner of the map

Click on Clip DEM in the Automatic section of the dialog and trace out a rectangle on the map. After the DEM has been extracted, choose the outlet point by clicking Create Layer and then Add Outlet. Click on the lowest point in the map (which will be shown in red). Click Calculate to generate the watershed. If no watershed is generated, click Delete Features and try again.

Complete documentation is available at

If you choose instead to upload a watershed layer, go to the Map tab in the left panel of the screen, select the Project Layers accordion, click on Spatial Layers, and select Add Layer -> Add Shapefile from the context menu. Select all the components of your shapefile.

Create the Hydrologic Response Unit (HRU) Layer

To create the HRU layer, click on the map toolbar icon Map Toolbox on the top of the map and select Hydrology -> Hydrologic Response Units.

HRU Creation Dialog

HRU Creation Dialog

To create your hydrological response units:

  • Create a folder: Click “New Folder” next to the “Store Results in Folder” dropdown box.
  • Select a watershed: Select the “watershed” layer (generated from the previous steps) next to the “Watershed Boundary” dropdown box
  • Generate a land use layer: All hydrologic response units will need land use information.  To include this, select “Build” next to the “Land Use” dropdown box.  Two dropdown boxes will appear, which may take a few seconds before they load the necessary land use data for your watershed.  Once the data has loaded, select either “NLCD” or “NASS,” select a year and then click “Create” to add the land use data to your HRU
  • Generate a soils layer: Repeat the previous steps, but this time for the “Soil” dropdown box
  • Generate a slope layer: Repeat the previous steps, but this time for the “Slope” dropdown box

When all the steps above are completed, click on the green “Create” button, followed by the “C Factor” button.  Before closing the tool, be sure to click C factor to calculate the runoff C factor.

Please see for more help on how to use the tool.

Generate Climate Data

Click on the map toolbar icon Map Toolbox on the top of the map and select Extract Data-> Climate -> GHCND to extract climate stations from the Global Historical Climatology Network. Select WIthin Layer Extent and choose the watershed layer and <Entire Extent> in the succeeding drop down lists.

GHCND Climate Extraction Dialog

GHCND Climate Extraction Dialog

Click Next to select the stations within the watershed boundary.  (Note: if no stations appear, try performing a station search using the Draw Rectangle or Draw Polygon option, with a larger extent.  You may have to play with where and how large the extent is drawn to find weather stations)

Click on the station that you want and click Save To Climate Folder. The climate data will be stored in a folder called “Climate Data” in the Tables section of the Project Layers accordion.

Section 2: Writing Your Own Model Code

Now that we know how to generate all the inputs for our new runoff model, we can begin to build the interface and write the model code.

Here’s an example of what the final product might look like:

A general outline of the required steps are listed below:

  • Add interface functionality (such as a dropdown box under the “my_app” tab in the left panel) to select the previously generated HRU layer (see example)
  • Add interface functionality (such as a dropdown box under the “my_app” tab in the left panel) to select the previously generated climate data (see example)
  • Add a backend function to calculate runoff and call it by sending an AJAX request to use the selected HRU and climate data and combine them to calculate runoff from the watershed
    • To do this, you’ll create a function called “calculateRunoff” which calculates the following:
      • The sum of the area of each HRU in the layer
        • The area has been already calculated for you (in square meters, not acres), and has been saved as a database column called “hru_area” in the HRU layer
      • The weighted average of the cover factor of each HRU
        • The cover factor been calculated for you and saved as a database column called “cfactor” in the HRU layer
        • To compute a weighted average of the cover factor, multiply the area of the HRU by the cfactor.  Take the sum of all of these and divide by the total area of the watershed
      • The average rainfall intensity
        • Rainfall has been already calculated for you and saved as a database column called “apcp (in)” in the climate table
        • Calculate the maximum daily rainfall for the period of record in the climate data file, which is provided in in/day
        • Assuming this storm took place over 4 hours, calculate the average rainfall intensity rate (in/hr)
    • The final equation will look like Q = c * A * I where:
      • Q = the discharge in cubic feet per second
      • c  = the cover factor (cfactor)
      • A = the area in acres
      • I = the average rainfall intensity, in inches per hour, for a design storm

To make these changes, edit the code in your local repository and then use a Mercurial command (such as “hg push”) to push your changes to your eRAMS app instance.  The changes will be automatically deployed, and the server restarted.  (Note: it may take a few seconds for the server to restart, and sometimes it’s helpful to manually restart by clicking the “Restart Server” button in the eRAMS Roundtrip Dashboard).

Bonus: Charting Your Results

As a bonus, you can chart your results using the included HighCharts API.  Examples for this can be found here.


We recommend using Google Chrome for developing eRAMS web applications. See here for help with using Chrome developer tools. Project files are located under “static -> map -> projects/<project name>”.

Chrome Debugger

Chrome Debugger