CAP User Manual (ArcView Prototype v. 1.1)

last modified (December 5, 2006)

Summary of CAP Functionality
Software Requirements
Data Description
Changes from v. 1.0
User Instructions
IMPORTANT: Bug fix on Dec. 5, 2006 related to snow cover data
Download ArcView Extension File

SUMMARY of CAP FUNCTIONALITY

1. Derive area-elevation curves
1. Export area-elevation information directly to MCP input deck format
2. Sub-divide basins based on elevation zones
3. Derive elevation-precipitation plots
4. Display defined zones on top of other data layers (e.g. precipitation, elevation)
5. Compute basin mean, max, and min values of: (may also compute for each elevation zone defined within a basin)
• precipitation (monthly, annual, and seasonal)
• potential evaporation (monthly, annual, and seasonal)
• potential evaporation adjustment factors
• percent forest
• percent of each forest type
• soil-based estimates for 11 SAC-SMA parameters
(Note: A user can also display any of the grids that go into these calculations, plus the basic soil grids that went into the SAC-SMA parameter estimation.)
6. Display selected NOHRSC historical snow images from (1990-1995)

ArcView v. 3.1 (ESRI)
Spatial Analyst Extension 1.1 (ESRI)
CAP Extension (NWS-HL) (64 scripts, 4993 lines of code)

DATA DESCRIPTION

Each RFC is provided with the data sets listed in Table 1 for their service area.  These data sets support CAP v. 1.1 functionality.  Upon installation, these data sets should be stored in the same directory as the ThreshR data sets.  The same DEM data are used by both applications. Although not required for CAP, other data sets used in ThreshR may be loaded into the same ArcView View as the CAP data for reference.  A list of the data sets available with ThreshR is provided at http://hsp.nws.noaa.gov/oh/hrl/gis/data.html#section211.

The data provided with CAP were collected from several sources (specified in Table 1).  For many of the data sets, the source of information is listed as the National Operational Hydrologic Remote Sensing Center (NOHRSC).  In some cases NOHRSC is distributing reformatted or modified data from other government organizations (e.g. EPA, U.S. Forest Service).  If so, this is explained on the NOHRSC web pages. CAP data are stored and displayed in the same map projection used for ThreshR (Albers Equal-Area projection).

Potential Evaporation (PE) Grids

The method for deriving these grids is described in unpublished work by V. Koren, J. Schaake, Q. Duan, M. Smith, and S. Cong (August 13, 1998).  Information from seasonal and annual free water surface evaporation maps (PE) in NOAA Technical Report 33 and mean monthly station data from NOAA Technical Report 34 were used to derive an equation that predicts long-term mean daily variability of PE.   This equation was used to derive the monthly PE grids delivered with CAP.  Summing the monthly values yields a consistent result with the annual and seasonal maps in NOAA Technical Report 33.

PE Adjustment Grids

Also described in unpublished work by V. Koren, J. Schaake, Q. Duan, M. Smith, and S. Cong (August 13, 1998), these PE adjustment grids were derived using an empirical function relating PE adjustment factors to green vegetation fraction data.  The empirical relationship was developed using PE adjustment factors derived from calibration of the SAC-SMA model and montly values of green vegetation fraction data from NCEP data sets.

Soil-based SAC-SMA Parameter Grids

A conference paper describes the theory behind these parameter estimates: "Use of Soil Property Data in the Derivation of Conceptual Rainfall-Runoff Model Parameters" (only the abstract is currently available online).  The SAC-SMA parameter grids derived from soil data may be useful in assisting with current manual and automatic calibration procedures, not used in place of current procedures.  Initial tests in applying these soil-based estimates have yielded mixed results for different parts of the country when compared with manually calibrated results.

Note:  In the initial delivery of SAC-SMA grids to River Forecast Centers, some grids were stored as real values.  Parameter grids are now stored as integer values for efficiency (This change applies to parameter grids distributed after 1/1/2002).  The CAP programs have not been modified to account for this change.   This means that if you run the CAP --> Statistics option, the table of statistics with SACSMA parameters will report some parameters multiplied by the following factors:

parameter   multiplied_by

Basic Soil Information

The three basic soil grids used to derive the SAC-SMA Parameter Grids are included with the CAP database for reference.  These grids, created by scientists at Penn State using information in the USDA STATSGO database, were obtained from http://dbwwww.essc.psu.edu/dbndx/tree/amer_n/us_48/data/soilprop/statsgo_albers.html

1.  soil_depth = mean depth to bedrock (cm)

A caution from http://dbwwww.essc.psu.edu/dbndx/tree/amer_n/us_48/data/soilprop/statsgo_albers.html:

"Many STATSGO Component table entries for depth to bedrock used 60 inches (152 cm) to indicate that bedrock was not encountered within this distance of the surface.  As a result, the mean depth to bedrock values in this dataset should be used primarily to identify mapunits in which bedrock may be encountered at depths shallower than 152 cm."

2.  soil_dom = dominant soil texture class -- 11 layers

3.  soil_hsgpct = percentage of soil in a given hydrologic soil group

Data layers defining other soil properties can be downloaded from the web site given above.

Note:  Creating the gridded (~ 1 km) soil property grids from STATSGO required numerous assumptions and approximations.  These assumptions are documented on the Penn State web site.

CHANGES FROM VERSION 1.0

• PE Adjustment values are now computed.

• 11 Soil based SAC-SMA parameters are estimated.  Basic soil grids including texture, hydrologic soil group, and depth to bedrock are also included in the database for reference.

• The menu item  "Pre-compute Statistics" has been added.  Given a Shapefile of basin boundaries, this function pre-computes statistics for all defined basins and all parameters listed under item 5 in "Summary of CAP v 1.1 Major Functionality."  By pre-computing these values, the user can now run the "Statistics" function quickly to view detailed about individual basins.  Prior to this modification, the "Statistics" function was time consuming, as statistics were calculated for an individual basin at run time.  The new function should take less than a minute while the old function might have taken 20 minutes.  If the user sub-divides a basin into zones, "Statistics" will take longer because the pre-computed statistics can no longer be used.  To compute all of the possible statistics when zones are defined, data in 55 different input grids must be accessed and summarized so this may take several minutes but still not as long as v. 1.0.

• The new menu item "Create SubView for Selected Basin" was formerly called "Clip Data for Selected" basin.  The purpose of this Menu item remains the same; however, the underlying processing steps have been changed to improve speed.  In v. 1.0 numerous grids (including elevation, monthly and annual PPT and PE, etc.) were clipped to the area of the selected basin, resampled to the same cell resolution as the DEM, and stored for later use.  All of this clipping and resampling was not necessary so most of it has been eliminated in v. 1.1.  There is now an option to load previously saved data files to reconstruct a formerly created subbasin View.  It is also possible now to create a subbasin View for multiple selected basins; however, if this is done, the "Plot Graph", "Subdivide Basin" options will operate on the entire area selected rather than individual subbasins.  The "Statistics" program has not yet been modified to operate from a subbasin View with multiple basins.

• A new button ( ) will automatically convert legend units from metric to English or from English back to the native Theme units (metric).

• Elevation levels corresponding to 10%, 50%, and 90% percent of basin area are now automatically plotted on area-elevation curves.

• The meaning of the Detailed Forest Percent numbers has been clarified in the instructions below.


• A new sub-menu (Export OFS-MAPX Area Definitin) that helps define MAPX areas for the National Weather Service Forecast System

USER INSTRUCTIONS

When the CAP Extension is loaded into ArcView, the CAP Main Menu is visible when a View Document is active.  The CAP Main Menu contains 9 items as described below.

(1) SETUP

Setup does the following:

• Prompts for the directory name where input data are located.
• Version 1.1.6 and later will ask whether you are an HL user or an RFC user.  All non-HL users should choose the RFC user option.
• Asks the user to select their RFC from a list of  RFCs.
• Checks to make sure that data subdirectories "prism", "pe", "snow", "forest", and "legends", exist. If any of these subdirectories is missing, the setup program cannot continue. Note: If for some reason you are missing one of these subdirectories and still want to continue, you can use file system commands (e.g. mkdir) to create an empty directory with the name of the missing directory. If you do this, you should rerun setup. Many CAP functions will still work. The exceptions would be statistical calculations based on the data you are missing.
• Prompts for the name of a directory where CAP output files will be written. Setup sets the ArcView Project Working Directory based on this user specified directory.
• Renames the active View to "RFC View"
• Loads the following Themes into the RFC View (see Table 1 for more descriptions of these Themes):
• Grids: dem, for_pct, for_type, peann, pptann
• Shapefiles: bsns_xxp.shp, statekey.shp, rfcbound.shp, rf1.shp, windows.shp (xx is the two letter RFC identifier, e.g. "nw" for Northwest)
• Sets default legends for for_type, rf1.shp, rfcbound.shp, regions.shp, bsns_xxp.shp, pptann, dem
• Stores pointers to the loaded Themes in an object tag associated with the View.

Annual precipitation (ppt) and potential evaporation (pe) grids are loaded automatically into your RFCView, but the monthly ppt and pe grids are not loaded. This is done to avoid cluttering up the Table of Contents in your View. If you wish to display the monthly files, you can load them manually from the "prism" or "pe" subdirectories using . Grids of PE adjustment can also be viewed in this way.

Legends are initially hidden so that the names of all available Themes can be seen in the Table of Contents without too much scrolling. Use Theme à Hide/Show Legend to see Legends for the Themes of your choice. Default shading schemes and symbols have been assigned for bsns_xxp.shp, rfcbound.shp, rf1.shp, pptann, and dem.

(2)  Pre-compute statistics ** PRE-COMPUTE STATISTICS SHOULD ONLY BE RUN WHEN "RFCView" (the main view) IS ACTIVE**

Given a Shapefile of basin boundaries, this function pre-computes statistics for all defined basins and all parameters listed under item 5 in "Summary of CAP v 1.1 Major Functionality."  The user is prompted for:

1. the subbasin Theme name
2. a field with a 5 character basin identifier
3. a field with a unique integer identifier

Pre-compute statistics creates a new directory called "stats" underneath the CAP output directory specified during setup.  Several data files are written to this directory:

• elv.dbf -- contains mean, max, and min elevations and mean, max, and min percent forest for each basin
• pe.dbf -- contains mean, max, and min potential evaporation for each month and annual for each basin
• ppt.dbf -- contains mean, max, and min precipitation for each month and annual for each basin
• sacsma.dbf -- contains mean, max, and min of 11 SAC-SMA parameter estimates for each basin

(3) Create Sub View for Selected Basin

This menu item becomes available when two conditions are met:  (1) if one and only one polygon Theme is active and (2) if one or more basins in the active Theme is selected. The active Theme should be your basin boundary Shapefile Theme (e.g. bsns_xxp.shp). The basin of interest can be selected using standard ArcView selection capabilities:

• Visual selection with the mouse using 
• Using to select the basin based on its handbook 5 (ch5_id or shef_id) attribute:

When a basin in bsns_xxp.shp is selected, you can click on "Create SubView for Selected Basin."  If you select your basin by name using , the "Create SubView for Selected Basin" menu item may not become available until you perform an action that will cause the View Update scripts to run.  An easy way to do this is to simply make the Project Window active and then make the View window active again.

The user is prompted to "Select a field with a 5 character basin identifier".  The "shef_id" field or the "ch5_id" field in the NOHRSC basin boundary files is typically suitable.  In a minute or so. . .

• A new View is created.  Typical name: "Selected Basin View: LEDC2" (LEDC2 is the ch5_id -- this will vary).
• Several clipped data sets are added to this View: a polygon shapefile containing the boundary of the selected basin, rf1 streams, and grids of forest type, forest percent, mean annual PE, mean annual PPT, and a DEM.

• A new subdirectory of your user specified output directory is create to store the clipped data sets. The name of this directory is the same as the 5 character basin identifier in lowercase.  If a subdirectory with this name already exists, the user is prompted with the dialog:

• Initially in the output View, only the river line Themes and selected subbasin boundary Theme are turned on.  As with the Main View, legends are initially hidden but can be made visible using Theme à Hide/Show Legend.

(4) PLOT GRAPH

The Plot Graph, Subdivide Basin, Statistics, and Snow Data menu options become available only when the Subbasin View is the active document.  Plot graph dialog:

Graph type options include "Area vs. Elevation" and "PRISM PPT vs. Elevation".  When we get the PRISM temperature data in the CAP database, the "PRISM TMP vs. Elevation" option will become available.

An Area vs. Elevation plot can be used to help to determine whether the basin should be subdivided into zones.  If multiple zones have already been defined (see 4 below), graphs can be made for selected zones rather than the entire basin.  The "Plot" button becomes active when the Graph Type is selected.  Computations of points to plot may take several seconds.  The plotting points are computed by dividing the elevation data into zones based on equal intervals between the minimum and maximum elevation points.  Mean elevation and mean precipitation are computed for each of these zones.  The "# of points" option allows the user to specify the number of zones.  Note that if you are planning to write data cards 3A and 3B for Snow 17, there is a limit of 12 points used to define the area-elevation curve (not including the max and min points).

An example plot for HOTI1 in NWRFC is shown below.  The black points are the mean values for each of 12 elevation zones.  The 10th, 50th, and 90th percentile points are plotted in green.

The graphing functionality in CAP is implemented by drawing graphics in a new type of document called a "CAPGraph" rather than using the default ESRI Chart Document, which has some serious limitations.  The CAPGraph document is a modification of the default ESRI View document.  Using CAPGraph to plot data is somewhat of an experiment but it seems to work o.k. so far, and offers some significant advantages.

When a CAPGraph document is active (e.g. the "Area vs. Elevation for hoti1" shown above), the following buttons and tools are available to the user.  Help for a button or tool will appear at the bottom of the ArcView Window when the mouse is positioned over it.

  Displays a dialog with an x-y coordinate list of the points displayed on the plot.  The "X-Y Coordinates" dialog contains a "Copy" button, which can be used to copy the data to the system Clipboard and subsequently to a text editor like Nedit.  All text displayed in the dialog will be copied to the clipboard, independent of any text selection.  The "OK" button in the "X-Y Coordinates" dialog dismisses the dialog.

    Write Cards 3A and 3B for Snow 17.  Creates an ASCII file.  A message is provided to the user specifying the location of this ASCII file.

  Provide a report on selected statistics for Area-elevation curves.  Reports the elevation values below which 10%, 50%, and 90% of the basin lies.

  These are standard tools borrowed from the ArcView View GUI.  The tools can be used to add text to the CAPGraph window; draw points, lines or polygons; select, move, or delete selected graphic objects (note: everything shown in the CAPGraph window is a graphic object); pan; zoom in; and zoom out.

  Return the graph coordinates (X,Y) of any point in the CAPGraph window clicked by the mouse.  This can be any point -- on or off the plotted line.

Printing:  The graph can be printed using standard ArcView print capabilities.  File --> Print.
WARNING:  If you unload the CAP extension, any CAPGraph plots that you have made will automatically be removed from your project.

(5)  SUBDIVIDE BASIN

Brings up the following dialog:

The minimum and maximum elevations are specified by default.  The user can select number of elevation breaks desired.  1 break means two elevation zones will be created.  2 breaks means 3 zones, etc. The user can select up to 4 elevation breaks.  The user has the opportunity to type in elevation values at which breaks should occur.

The "Equal Interval" can be used to set equal interval breaks.

• Zones1 -- a Grid of zones; in a case with two zones, the grid cell values in this grid will be 1 and 2, etc.
• Zonesp1.shp -- a polygon of the zone boundary

After subdividing a basin, the user can go back and create graphs for individual zones if desired.

(6)  STATISTICS

The basin statistics dialog appears as follows:

This dialog is divided into 3 Sections.

Top Section
If the "Compute All Statistics" option is selected, then all of the check boxes in the middle section ("Only Selected Stats:") become available.  Otherwise, these check boxes are disabled and all different types of statistics are automatically computed.

If you have subdivided your current basin into zones, then you can choose to calculate statistics for zones in addition to basin wide statistics.  Zonal calculations will take considerably longer (several minutes) than non-zonal calculations (less than 1 minute) because non-zonal calculations are all pre-computed.

Middle Section

If you want to display/calculate results for only selected statistics, do not check the "Compute All Statistics" option in the top section and make your selections in the middle section.

Bottom Section

For the PRISM precipitation and potential evaporation data, both monthly and annual statistics are displayed by default.  Seasonal totals can be determined by selecting the box "Define seasons for precip, temp, and PE calculations" and then defining the winter and summer seasons for your area.

Basin and zonal statistics are summarized in a single table.  An example of a table for a basin with two zones is shown below.  This example table does not show PE adjustment statistics or SAC-SMA parameter estimates which are now available.

If the "Detailed Forest Types" option is selected,  a separate table called  "Percent Forested Area covered by Each Forest Type: BasinID" is created.   An example of this table for basin 2914 is shown here:

The "Basin Pct" numbers indicate that 50% of the forested area (not 50% of the total area!) in this basin is covered by Fir-spruce, while only 6.1% of the forested area in Zone1 and 66.8% of the forested area in Zone 2 is covered by Fir-spruce.  These values are derived using two input grids obtained from NOHRSC -- Forest Type and Percent Forest.  Details about the derivation of these data sets is provided in an ASCII file at the NOHRSC web site.  In these grids, a 1 km cell labeled Fir-spruce in the Forest Type ("For_type") grid will likely only be covered by forest in a fraction of its 1 km2 area, the fraction being defined by the Percent Forest ("For_pct") grid.  Therefore, to derive the "Basin Pct" values above, the averages of the for_pct cells corresponding to each forest type in a basin are computed and then divided by the total basin forest percent to get the percentages shown in the table.  Numbers in the "Basin Pct", "Zone1 Pct", and "Zone2 Pct" columns should add up to 100%.

Note:  Statistical calculations may take several minutes if you are making zonal calculations.

(7)  SNOW DATA

NOHRSC has produced a CD of historical snow images derived from remote sensing.  These images indicating one of three pixel states: no snow/no cloud ( gridcode = 50), clouds (gridcode = 100), snow (gridcode = 250).  Snow images are available for selected days from 1990 - 1995.  The data provided by NOHRSC are organized by Windows.  The figure below shows 13 of these windows with the NOHRSC ID numbers as labels.

For each RFC, all of the available snow images for Windows that intersect your RFC are delivered with the CAP database in the "snow" subdirectory.  When a subbasin has been selected, the Cap --> Snow Data menu item will determine which snow images are available which intersect the selected basin and bring up a selection list as shown below.  The user may choose to load a single image or multiple snow images (hold down Shift key to select multiple images).  After clicking OK, selected images will be loaded.  No clipping is done.  A default legend is provided automatically -- no snow/no clouds = white; snow = green; clouds = grey.

The tool could be used with the DEM active to determine elevation values along the snow line, although the coarseness of the snow cover data may make this difficult.

Notes:

*  For RFCs with basins that extend into Canada (e.g. NWRFC), the snow image data may covers these areas, but the PRISM precipitation, PE data, forest percent, and forest type data does not.  The same goes for Mexico.

(8) OFS PPINIT

Selecting this option brings up the dialog box shown below, where the user selects whether to Define, Delete, or Dump one of the PPINIT group types (i.e. basin, area, and stations).

Define OFS MAPX Area

This option helps define mapx areas for the Operational Forecast System (OFS).  The definition of the mapx area, and the basin(s) it references are defined  in CAP, and can be automatically exported to the NWSRFS database (fs5files).  The process uses some of the existing CAP dataset and an HRAPP points theme.

 Input Data:

• Basin(s) polygon shapefile
• HRAPP points shapefile
• DEM (only needed if you want CAP to compute basin mean elevation)

The following steps for using this sub-menu assumes the user already has a  polygon theme in the active view of the basin(s) the mapx area definition will reference.  The figure below shows an example of a basin that has been subdivided into 3 sub-basins using CAP's sub-divide basin option (5).  For the basin below, mapx areas that reference the entire basin or separate mapx areas that reference the upper, middle, or lower sub-basins can be defined

1). Under the CAP menu select the option Define OFS-MAPX Area.  A dialog box like the one below should appear.

2)  In the dialog box enter:

• a new mapx area identifier
• a new mapx area description

4)  Enter the basin identifier, basin description, and basin mean eleavation:¹

• select the basin(s) theme (a polygon theme in the active view)

NOTE: the features (basin(s)) the mapx area will reference should be selected
• select a field from the basin theme's attribute table containing the basin identifier, enter a basin identifier, or use the mapx area identifier
• select a field from the basin theme's attribute table contaiing the basin description, enter a basin description, or use the mapx area description
• select a field from the basin theme's attribute table containing the basin mean elevation, or select the dem grid for computing the basin mean elevation

• select Export MAPX Area Definition or
• View MAPX Area Definition

If Export MAPX Area Definition is clicked, the definiton of the mapx area and its basin(s) it are automatically inserted into the OFS fs5files.  This option uses the geometry of the selected features in the basin input theme and the information entered in the dialog box to create an input file in the ppinit input directory for running ofs.  The input file has the form ofs.input, where mapxid is the mapx area id entered in the dialog box.  This option assumes the Apps_defaults tokens ($ofs_rls, $ofs_input, and $my_output) are already set.

If View MAPX Area Definition is clicked, an editor window appears with the the ppinit input file for defining the mapx area and its basin(s).  NOTE: If you choose this option the mapx area and basin definitions are not automatically added to the fs5files, they can be added later by manually running ofs.

¹ When field names are specified for basin identifier, basin description, and basin mean elevation, the values used for each sub-basin are taken from the basin theme's attribute table.  When a string is entered for the basin identifier and more than one sub-basin is referenced, the basin identifier for each sub-basin is appended with a number from 1 to the number of sub-basins.

Define OFS Basin

This option is similar to the Define OFS MAPX Area option and is used the same way.  As with the Define MAPX Area dialog box, OFS Basins can be directly exported to the fs5files or a ppinit input file can ge created for running ofs later.

Delete OFS MAPX Area

This option brings up the dialog box shown below, where the user can select one or more mapx areas to delete from the ofs database.  After selecting the areas, an ofs job is execute and displayted on the screen.  Next, a dialog box appears asking whether the mapx area was successfuly deleted.

Delete OFS Basin

This option is exactly like the Delete OFS MAPX Area option.

Dump OFS MAPX Area

This option brings up the dialog box shown below, where the user can select one or more mapx areas to import from the ofs database.  Importing an mapx area creates a shapefile in the active view.  Each row in the the shapefile's attribute table represents a basin the area references.  The basin identifier, description, area and mean elevation are given for each basin.

 Dump OFS Basin

This option brings up a dialog box like the one for Dump OFS MAPX Area, where the user can select one or more basins to import from the ofs database.  Importing a basin creates a shapefile in the active view.  The shapefile's attribute table contains the basin's identifier, description, area, and mean elevation.

IMPORTANT: Bug fix on Dec. 5, 2006 related to snow cover data

Bug description (12/5/2006): The menu item Cap --> Snow Data brings up a dialog called "cap.snowview". This dialog allows you to select dates for which you want to display snow grids. The script then loads all selected files as themes into ArcView, sets appropriate legends, and names each Theme. The bug was that the names assigned to each Theme were incorrect in many cases.

A typical Theme name is "1992-2-14 Window 02". The actual grid file corresponding to this date has a name like "a02g92045" where the "02" means Window 2, the "92" means 1992, and the "045" means the image corresponds to the 45th day of the year (February 14). The bug was that the date strings used to construct Theme names were sorted for easy navigation in the selection dialog, but the corresponding file names were not sorted at the same time. Therefore, some Themes were likely to be labeled with incorrect names.

This bug may have gone unnoticed in some situations since the sorting of file names (which include date information) and date strings may not be much different, causing no obvious seasonal differences. However, the fourth character in the file name is not always "g" as in the example above (could be "a", "e", "c"). This can cause some major errors in the naming of Themes (e.g. a grid from April could have been labeled as if it was from January). This is how the bug was detected.

This bug has been corrected and the Extension containing the corrected Avenue script (cap.snowview is the script name) can be downloaded from this page. The raw data grids have always been valid and any users who chose to load these grids manually rather than using the CAP tool Cap --> Snow Data would not have encountered this problem.