AV-THRESHR TUTORIALLast Modified 02/28/2000
1.0 Introduction:This tutorial provides instructions on how to use AV-ThreshR. Readers who want to know more details about AV-ThreshR methods and the accompanying database may want to take a look at the AV-ThreshR documentation. Hyperlinks within this document link to this user documentation to explain certain concepts.The AV-ThreshR system is being developed for implementation at each of the 13 National Weather Service River Forecast Centers (RFCs). As discussed in the user documentation, AV-ThreshR consists of both software and a database. The software consists primarily of Avenue programs that are packaged as an ArcView Extension called threshr.avx. For UNIX users, the AV-ThreshR package is also delivered with a compiled C++ program to provide a more efficient stream tracing algorithm. 2.0 Requirements:
Hardware:
User Knowledge:
3.0 Demo Instructions:3.1 Getting Started- On UNIX systems, copy the extension file threshr.avx to either your Home directory or to the directory /ext under the ArcView3 installation directory. If the file is copied to your Home directory, only you will be able to load threshr.avx. If threshr.avx is copied to the /ext directory, all ArcView users will be able to access the AV-ThreshR extension. [On a PC, copy threshr.avx to the ArcViewext32 directory.]- Start ArcView and load the AV-ThreshR Extension. This can be done by accessing the menu item File --> Extensions when either a Project window or a View window is active. In the Extensions dialog, scroll down the list of available Extensions and place a check mark next to "ThreshR." To see information about the version number of ThreshR in the "About" frame, click the mouse on the "ThreshR" text. Threshr.avx is dependent on the Spatial Analyst so the Spatial Analyst Extension is automatically loaded if the ThreshR extension box is selected. An error will occur if the Spatial Analyst Extension is not available. Click OK. - Open a new View and you will see that two customized Menus, "ThreshR" and "ThreshR-Utility," are added to the default View GUI. In other words, whenever a View is active, these menus will be seen. Customized tools have also been added to the Tool bar. For the simplest and most straightforward implementation of AV-ThreshR, the end-user is only concerned with items under the "ThreshR" menu. The "ThreshR-Utility" menu contains programs used for data preparation and pre-processing; however, these programs are not needed to calculate threshold runoff and are provided for the advanced user only. Only the programs underneath the "ThreshR" menu are described in this document. - Create a directory in which you want output files to be written. Make the Project window active and then select Project --> Properties. In the "Project Properties" window enter the name of your output directory in the "Work Directory" text box. - With your View active, click View --> Properties and set map units to meters and distance units to meters and click OK. 3.2 Program Execution The 9 items in the main "ThreshR" pull-down menu are shown in the figure below. The ThreshR menu items are divided into logical groups that are separated by a horizontal bar. Steps 2, 3, and 4 are pure GIS processing steps and are also the most time consuming (hours). More discussion of computational time is discussed in the User Documentation. It is expected that a user would run steps 2, 3, and 4 only once or perhaps a few times. Steps 5, 6, and 7 are relatively fast (minutes) and users may wish to repeat these steps to study different scenarios. A user will likely wish to examine subbasin threshold runoff results from Step 7 before interpolating results to the HRAP grid in Step 8 (~ 15 minutes). Subbasin and parameter output from steps 2, 3, and 4 have been pre-computed for ABRFC for one possible subbasin size. These subbasin are used later in the ABRFC Analysis section. The instructions here guide a user through the entire AV-ThreshR procedure for a relatively small analysis area. This is done to illustrate all of the processing steps while eliminating long wait times. ThreshR
Step 1. ThreshR --> Setup Click on this menu item and you will be prompted to enter the directory name for the location of the input data. (Note: The programs can read data directly from a CD-ROM drive although the program performance may be slower and an MSEEK error may occur. Therefore, it is recommended that the input data be available on a local or networked hard disk.) Dialog used to specify the input directory:
After clicking OK, the user is asked whether or not to load input data. Typically the answer is yes unless all of the input data is already loaded and you are just running setup to change the identity of the input directory. In either case, the program will not load a second copy of a Theme to the project if there is already a data Theme with that name loaded.
Click yes and the setup program will automatically load the following data Themes into your currently active View window. Shapefiles:
Grids:
Two Table documents are also loaded into your project:
In this tutorial, information about these input data sets will be provided on an as needed basis. Much more information about the input data is provided in User Documentation: Data, and a more detailed description of the parcode.dbf and regequat.dbf tables is provided in User Documentation: Function. The GIS data sources displayed in your view are not all of the data
sources used by the ThreshR programs. Other input data sets required
for USGS Flood Frequency Regression parameter calculations are accessed
directly by Avenue codes using their file system names (without loading
the data as Themes into a View). This is done to avoid cluttering
up the Theme Table of Contents in the View window. Curious users
may wish to look at these data Themes if there is time at the end of this
workshop. The parcode.dbf field lists file and directory names for
these additional data layers.
Step 1.1 Setting the Analysis Properties - With a View active, click Analysis --> Properties and set the Analysis Extent to Same as the flow direction grid (fd). Also set the Analysis Cell Size to Same as fd. Set the Analysis Mask to Mask and click OK. Step 2. ThreshR --> Define Subbasins By default, AV-ThreshR is set up to work on a large analysis area (the entire RFC). However, to facilitate a quick tutorial we will focus on a small area. To analyze only a selected area, a polygon Shapefile of the area to be analyzed is required. This can be created using ArcView delineation tools, but a pre-defined Shapefile is used in this tutorial. Load the Shapefile called "tkshd.shp" from the input data directory ("/yourlocalpath/abrfc") using . This is a basin boundary for the Illinois River draining to the Tenkiller Reservoir in eastern Oklahoma. Now you are ready to define subbasins within this area. Turn this Theme "on" in the View by placing a check next to its name in the Table of Contents and Zoom to the extent of this Theme using . The default method used to define subbasins will be referred to as the "Streamlink" method. This method is explained in detail in User Documentation: Function: Define Subbasins. The basic approach is to (1) define a stream network from the DEM using an area threshold, (2) define local subbasins draining to each stream reach, and (3) calculate threshold runoff at the outlet of each subbasin. Since the final Threshold Runoff values are currently used in a gridded form by the Flash Flood Guidance (FFG) program, the objective of subbasin definition is to create a sampling of outlet points covering a large geographic area where computations can be made and interpolated to a grid. Two alternative subbasin definition methods have recently been added as options to the AV-ThreshR software. For purposes of this workshop, stick with the fully tested "Streamlink" method. Alternative subbasin delineation options will be discussed in the lecture. Click ThreshR --> Define Subbasins and the following dialog will appear.
Five Themes are added to the View by this program: a subbasin theme (shdx.shp), a subbasin outlet theme (outcx.shp), a stream coverage (strcx.shp), a watershed grid (shdgrix), and stream grid (strgx). The "x" in these file names represents an integer that should be equal to 1 on the first run, but will be incremented if you re-run the programs using the same Project Working Directory. You will need to adjust the Theme Legends to see a result similar to that shown here.
Note that the white areas are interbasins for which the cumulative area at the outlet is greater than 2000 km2. The subbasin delineation program can be re-run with no area limit if it is desirable to delineate these "missing" interbasins. The option to specify a maximum subbasin size has been included at this step to reduce the number of subbasins for which calculations are required in the next two steps: stream connectivity and subbasin parameter calculations. This option, to set a maximum subbasin size where calculations actually occur is also offered in subsequent steps. Threshold runoff results will be sensitive to the stream definition threshold. As database development continues and guidelines for software use are refomed (Status, Future Plans), it will be important to consider how subbasin size relates to: (1) threshold runoff, (2) the underlying rainfall-runoff model used for flash-flood guidance, (3) the spatial resolution of the rainfall, and (4) the required spatial resolution in flash-flood forecasts. Step 3. ThreshR --> Determine Connectivity NOTE: When running "Determine Connectivity" for a large area (>10,000) subbasins, I've had problems with the user dialog locking up (and not closing correctly) after the calculations are complete. I don't know what causes this yet but it is a good idea to periodically save your project file in case this occurs. Basin connectivity is determined to facilitate computation of cumulative subbasin parameters for non-headwater subbasins. Click ThreshR --> Determine Connectivity to get the following dialog:
Check to make sure the program has provided the correct subwatershed and stream line theme names (shown above) and click Calculate to run. Click OK when the program is complete. This program identifies headwater and outlet subbasins and also stores upstream connectivity information in three ASCII files. See Function: Determine Connectivity for more information about these files. The program adds the fields "shdishead" and "shdisout" to the subbasin Shapefile (shd1.shp). One way to see this is to make shd1.shp the active theme (by clicking on its Theme name in the Table of Contents), click on , enter the query ( [shdishead] = 1 ), and click on the "New Set" button to select all headwater subbasins. Queries can be entered without typing by double-clicking on a field name, clicking on an operator (e.g. "="), and double clicking on a value in the query window presented.
To close this query window, hold down the left mouse on the tab in the upper left corner and select "Close" from the options presented (or use Alt-F4). The "No C Program" option is provided for users who do not have the executable file "idupstream" (e.g. PC users). For this small example area, running with the No C Program box checked is fairly quick; however, this option becomes inefficient when working with many subbasins; hence, the reason for using an external program. This option will add an "isoutlet" field to the stream Shapefile (strc1.shp) rather than adding the "shdisout" field to the subbasin Shapefile (shd1.shp). Step 4. ThreshR --> Compute Subbasin Parameters Click on ThreshR --> Compute Subbasin Parameters to see the following dialog:
For standard runs, the program will provide the correct names for the input Themes so no typing is required. The option to change the names of inpute themes is only provided for users who want to skip around in the processing sequence. Radio buttons on the right side of the dialog allow the user to choose whether "All Parameters,""Basic Parameters Only," or "USGS Regression Parameters Only" will be computed. For this tutorial, select the "All Parameters" button. More information about the other options is provided in Function: Compute Subbasin Parameters. Do not check the box next to Heads Only (2/28/2000) -- this option has no been fully tested. Click Calculate to start calculations. For this area, these calculations may take several minutes depending on the speed of your computer. Click OK when the calculations are complete. This program computes topographic and climatic parameters required for Snyder unit graph peak flow calculations and USGS Flood Frequency Regression Equations. The parameters required for the Snyder unit graph peak flow calculations are cumulative drainage area (ARM), length of the longest flow path (CHLN), and length to the point on the longest flow path opposite the centroid (CHCN). Since the drainage area of interest intersects both Oklahoma and Arkansas-Flood Region B, the following equations will be used to calculate the 2-year peak flow in the next step: Oklahoma: Q2 = 0.368*ARM^0.59*PRE_OK^1.84 Arkansas Region B: Q2 = 0.120*ARM^0.78*CHSL^0.42*PRE_AR^0.55*ELV^0.75 These equations are taken from USGS WRIR 94-4002.
The input parameters for these equations are:
Take a look at the parameter values that have been computed for each
subbasin by reactivating the View window, making the shd1.shp Theme the
active Theme, and clicking on
to view the attribute table associated with shd1.shp. You may want
to enlarge the table window and scroll to the right. In this table,
you will see that the attributes (fields) ARM, CHSL0, CHLN, CHSL, CHCN,
stateabbr, regions, and reg_fract are computed for all subbasins while
PRE_AR and ELV are only computed for subbasins with their centroid in Arkansas
and PRE_OK is only computed for subbasins which have their centroid in
Oklahoma. The subbasins that are considered to be in Arkansas can
be highlighted on the map by querying the attribute table
with the string ( [stateabbr] = "AR" ) and selecting New Set.
Note that none of the subbasins in this example intersect multiple flood frequency regions within a given State so the "reg_fract" attribute in the shd1.shp attribute table is always 1.0. If a subbasin did overlap more than one region, the area weights for each region would be seen in the reg_fract field. Step 5. ThreshR --> Compute Q2, Q5, etc. With all required parameter values pre-computed, computation of peakflow values for a specified return period is relatively quick. Click ThreshR --> Compute Q2, Q5, etc. to see the following dialog:
For this example, select 2 [years] as the return period. The program should have identified "shd1.shp" as the input Theme and "tkshd.shp" as the "Analysis Area Theme." Leave these inputs as is. Leave the Max. Cum. Area (km2) at its default value of 2000 km2. Enter a 1 to identify this run and click Calculate. Click OK when the completion report appears. The program calculates Q2 for each subbasin. A field called "Q2_1" is added to the shd1.shp attribute table. The output field name will always be "Q" concatenated with the selected return period followed by "_" and the run identifier. The units for Q2 are cfs. Take a look at the output by editing the Theme legend for shd1.shp to map the 2-year peak flows. To do this, double-click on the shd1.shp Theme, select "Graduated Color" as the legend type, choose Q2_1 as the classification field, and then click "Apply." Your result should look similar to the image below. The interbasins with the largest cumulative drainage areas have the highest Q2 values.
Step 6. ThreshR --> UG Peak Flow The last step that occurs before threshold runoff can be calculated is to determine the unit hydrograph peak flow for each subbasin. For the initial release of AV-ThreshR, the only GUI supported unit graph method is the the Snyder method; however, other unit graph approaches could be implemented using standard ArcView table calculations. The programming to include additional synthetic unit graph options (e.g. the geomorphologic unit graph) would be relatively simple; however, the difficulty is that synthetic unit graph parameters (e.g. Snyder coefficients Cp and Ct or cross section parameters for the geomorphological unit graph) cannot be estimated from the GIS database and must be supplied by the user. Note: The possibility of developing a national database to support automatic unit graph estimation for ThreshR has been discussed (See Status and Future Plans). For this example application, we will assume that Cp and Ct are uniform throughout the study area (Cp = 2.7 and Ct = 0.93). Thus variations in Qp (peakflow estimates) will be due to variations in geometric parameters only. These Cp and Ct values were estimated by simulating a 1 hour unit graph for the Illinois River near Watts, OK using modClark parameter values from an HEC-HMS study, and then back calculating Cp and Ct based on geometric characteristics derived using AV-ThreshR. Note: This unit graph and the resulting Cp and Ct values were derived by calibrating data for only a single event and are used for illustration purposes only. Local knowledge of this area should yield better values.
Click ThreshR --> UG Peak Flow and you will see the following dialog:
The program should have identified "shd1.shp" as the Subbain Theme and the run identifier should be the same as that for the peak flow calculations ("1"). Leave these inputs as is. For this tutorial, do not click the check box next to "UG Parameters from A File" because the Snyder coefficients will be entered manually for this case. When this box is selected, the user can specify the name of a polygon Theme that contains spatially distributed Snyder parameter values. Click Calculate Peak Flow and you will be prompted to enter Cp and Ct values. As discussed above, enter Ct = 2.7 and Cp = 0.93. A message will appear when calculations are complete. Click OK. Three new fields have been added to the attribute table of shd1.shp. These fields are named "Qsd1_1," "Qsd3_1," and "Qsd6_1" respectively, which represent the 1 hour, 3 hour, and 6 hour unit hydrograph peak flows respectively in [cfs]. Step 7. ThreshR --> Subbasin Threshold Runoff The function of this step is to simply create a new field (or fields) in the subbasin theme ("shd1.shp") that contains the computed threshold runoff for a selected duration (or durations). The programs run in this step provide an interface for making the necessary tabular calculations (dividing the bankfull flow field (cfs) by the unit graph peak flow field (cfs/in)). If the bankfull flow or unit graph peak values for any of the subbasins are 0, then the value in the output field is flagged as -1. With your View active, Click ThreshR --> Subbasins Threshold Runoff and you will see a dialog similar to the following except that the "Bankfull Flow Field" Combo Box and the "UG Peaks" List Box will initially be blank. Once you select "shd1.shp" as the subbasin Theme, this Combo Box and List Box get populated.
Select Q2_1 as the bankfull flow field and select Qsd1_1 as the unit graph peak flow field. Alternatively, you could select multiple unit graph peak flow fields to calculate threshold runoff for multiple unit graph durations (e.g. 1 hr, 3 hr, and 6 hr) in a single pass. Selecting multiple entries in the "UG Peaks" list box can be achieved by holding down the shift key. Click Calculate and you will be prompted to name the output field that will contain computed threshold runoff values. Type "tr1hr_1" or whatever name you like and click OK. (This prompt will appear multiple times if you have selected multiple fields in the "UG Peaks" list box). Q2_1 in cfs is divided by Qsd1_1 in cfs/inch to derive threshold runoff values. Map the subbasin threshold runoff results in the field Qsd1_1 by modifying the legend of shd1.shp to display the values in the field tr1hr_1. You should get a result that looks similar to the map shown below. The general trend shown that threshold runoff values decrease with cumulative drainage area is expected because Q2 is proportional to A raised to a power less than 1 (0.59 in OK and 0.78 in AR), while the unit graph peak values are proportional to A raised to the power of 1.
Compute statistics for the tr1hr_1 field by making shd1.shp the
active Theme, clicking on ,
selecting the field tr1hr_1 with the mouse, and then choosing the
menu item Field --> Statistics. You will see that the
statistics for 1 hour threshold runoff values in the 68 subbasins are:
mean = 2.3
In this case, when the Oklahoma regression equation is applied to the
entire area, the 1 hr threshold runoff statistics for the 68 subbasins
are significantly different:
mean = 1.4Notes: This example was included only to illustrate that flood frequency equations for neighboring states may produce significantly different results near state boundaries. The method used to apply Oklahoma regression equations in Arkansas was to change the database, not the software. The ThreshR software is still under evaluation. Predicted Q2 values should be compared with some of the original data sources for verification. Step 8. ThreshR --> Interpolate to HRAP This step adds threshold runoff values to the Hrappts.shp (center points of the HRAP cells) Theme. There is an option to interpolate values only from the headwater outlets and an option to interpolate values from all subbasin outlets (including cumulative subbasins). In the Avenue program, interpolation to the hrappts.shp locations is actually accomplished in 3 steps: (1) hrappts.shp points that lie within subbasins with known threshold runoff values are assigned the corresponding subbasin values, (2) a grid of interpolated threshold runoff is created using the hrappts.shp points with known values as input (this grid covers all areas including the blank interbasin areas that drain more than 2000 km2), and (3) values from the interpolated grid are mapped back to hrappts.shp to provide a complete set of values for all HRAP cells within the analysis area. Click ThreshR --> Interpolate to HRAP
The program should have identified "shd1.shp" as the Subbasin Polygons, "hrappts.shp" as the HRAP Points, "shdgri1" as the Subbasin Grid, and "tkshd.shp" as the analysis polygon Theme. You may choose to interpolate values from headwaters only or from all subbasins in this example. Click Calculate on the "Interpolate to HRAP" dialog and you will be prompted to identify the name of the field in shd1.shp that contains Threshold Runoff values. In this example, the field name is tr1hr_1. Click OK. Two outputs are created. One is a grid called Trgrid1 which is created for display purposes only. The second is an attribute field called tr1hr_1 that is added to hrappts.shp. If a field named "tr1hr_1" already exists, then the user is prompted to enter an alternate name. Note: hrappts.shp is stored as a point file rather than a grid because the HRAP cells are not regular square cells in the Albers Equal-Area projection used for threshold runoff analysis. Step 9. ThreshR --> Write FFG ASCII File This program reads values from hrappts.shp and writes an ASCII file that can be read by the FFG program. Upon selecting ThreshR --> Write FFG ASCII File the user is prompted with several questions. Select hrapptst.shp as the HRAP Theme. Select tr1hr_1 as the field with threshold runoff values, select tkshd.shp as the analysis polygon Theme, enter "1" as the unit graph duration, and enter any text string as the output file name. An ASCII file with this name is written to the ArcView Project Working directory. ----------------------------------------------------------------------
4.0 Analysis for all of ABRFCGiven pre-computed subbasin parameter values, this section is included to demonstrate that it is relatively quick and easy to calculate threshold runoff values for an entire RFC, that is, if reasonable estimates of Snyder unit graph coefficients are available. Because there is currently no spatial database of synthetic unit hydrograph coefficients (e.g. Snyder's Cp and Ct) or regression equations to estimate these coefficients in the AV-ThreshR database, ABRFC wide computations are illustrated by assuming constant Cp and Ct values -- most likely a poor assumption.-- Open a new View.
-- Click ThreshR --> UG Peak Flow Calculations. In the corresponding dialog, make sure there is no check mark next to "UG Parameters From A File," and the run identifier is the same as what was entered in the last step. Click Calculate Peak Flow. When prompted to enter the Snyder parameter values, enter the same values that were used in the example above (Ct=2.7 and Cp=0.93) and click OK. These calculations should only take a minute or so. Click OK when the completion report appears and the input dialog should close automatically. The fields "Qsd1_1," "Qsd3_1," and "Qsd6_1" are added to shd1.shp. -- Click ThreshR --> Subbasin Threshold Runoff. Select "shd1.shp" as the Subbasin Theme, select "Q2_1" as the bankfull flow field, and select "Qsd1_1," as the unit graph peak flow field. Click Calculate and enter a name for the output field. Suggested name: "tr1hr_1." The 1 hour threshold runoff field is added to shd1.shp. -- Display subbasin results by editing the legend of shd1.shp to display tr1hr_1 using the Graduated Color legend type. The value -1 has been assigned to subbasins in Colorado where Q2 is not known. Unknown areas will be filled in by the interpolation procedures. Although not critical for this tutorial, once satisfied with the subbasin threshold runoff results, a user can interpolate the results to the HRAP grid (~10-15 minutes) and Write the FFG ASCII File (several minutes?). If you want to run the interpolation program for this example, you need to add the subbasin Grid shdgri1 from the input directory to your View. In an end-to-end run, this grid would already be loaded in your project. |
Main Link Categories: Home | OHD | NWS |