r.watershed

NAME

r.watershed - Watershed basin analysis program.
(GRASS Raster Program)

SYNOPSIS

r.watershed
r.watershed help
r.watershed [ -m4] elevation=name [depression=name] [flow=name] [disturbed.land=name|value] [blocking=name] [threshold=value] [max.slope.length=value] [accumulation=name] [drainage=name] [basin=name] [stream=name] [half.basin=name] [visual=name] [length.slope=name] [slope.steepness=name]

DESCRIPTION

r.watershed generates a set of maps indicating: 1) the location of watershed basins, and 2) the LS and S factors of the Revised Universal Soil Loss Equation (RUSLE).

r.watershed can be run either interactively or non-interactively. If the user types

r.watershed

on the command line without program arguments, the program will prompt the user with a verbose description of the input maps. The interactive version of can prepare inputs to lumped-parameter hydrologic models. After a verbose interactive session, will query the user for a number of map layers. Each map layer's values will be tabulated by watershed basin and sent to an output file. This output file is organized to ease data entry into a lumped-parameter hydrologic model program. The non-interactive version of cannot create this file.

The user can run the program non-interactively, by specifying input map names on the command line. Parameter names may be specified by their full names, or by any initial string that distinguish them from other parameter names. In 's case, the first two letters of each name sufficiently distinguishes parameter names. For example, the two expressions below are equivalent inputs to :

el=elev.map th=100 st=stream.map ba=basin.map

elevation=elev.map threshold=100 stream=stream.map basin=basin.map

OPTIONS

-m: Without this flag set, the entire analysis is run in memory maintained by the operating system. This can be limiting, but is relatively fast. Setting the flag causes the program to manage memory on disk which allows larger maps to be processes but is considerably slower.
-4: Allow only horizontal and vertical flow of water. Stream and slope lengths are approximately the same as outputs from default surface flow (allows horizontal, vertical, and diagonal flow of water). This flag will also make the drainage basins look more homogeneous.
elevation: Input map: Elevation on which entire analysis is based.
depression: Input map: Map layer of actual depressions in the landscape that are large enough to slow and store surface runoff from a storm event. Any non-zero values indicate depressions.
flow: Input map: amount of overland flow per cell. This map indicates the amount of overland flow units that each cell will contribute to the watershed basin model. Overland flow units represent the amount of overland flow each cell contributes to surface flow. If omitted, a value of one (1) is assumed. The algorithm is D8 flowaccumulation.
disturbed.land: Raster map input layer or value containing the percent of disturbed land (i.e., croplands, and construction sites) where the raster or input value of 17 equals 17%. If no map or value is given, assumes no disturbed land. This input is used for the RUSLE calculations.
blocking: Input map: terrain that will block overland surface flow. Terrain that will block overland surface flow and restart the slope length for the RUSLE. Any non-zero values indicate blocking terrain.
threshold: The minimum size of an exterior watershed basin in cells, or overland flow units.
max.slope.length: Input value indicating the maximum length of overland surface flow in meters. If overland flow travels greater than the maximum length, the program assumes the maximum length (it assumes that landscape characteristics not discernible in the digital elevation model exist that maximize the slope length). This input is used for the RUSLE calculations and is a sensitive parameter.
accumulation: Output map: number of cells that drain through each cell. The absolute value of each cell in this output map layer is the amount of overland flow that traverses the cell. This value will be the number of upland cells plus one if no overland flow map is given. If the overland flow map is given, the value will be in overland flow units. Negative numbers indicate that those cells possibly have surface runoff from outside of the current geographic region. Thus, any cells with negative values cannot have their surface runoff and sedimentation yields calculated accurately.
drainage: Output map: drainage direction. Provides the "aspect" for each cell. Multiplying positive values by 45 will give the direction in degrees that the surface runoff will travel from that cell. The value -1 indicates that the cell is a depression area (defined by the depression input map). Other negative values indicate that surface runoff is leaving the boundaries of the current geographic region. The absolute value of these negative cells indicates the direction of flow.
basin: Output map: Unique label for each watershed basin. Each basin will be given a unique positive even integer. Areas along edges may not be large enough to create an exterior watershed basin. 0 values indicate that the cell is not part of a complete watershed basin in the current geographic region.
stream: Output map: stream segments. Values correspond to the watershed basin values.
half.basin: Output map: each half-basin is given a unique value. Watershed basins are divided into left and right sides. The right-hand side cell of the watershed basin (looking upstream) are given even values corresponding to the watershed basin values. The left-hand side cells of the watershed basin are given odd values which are one less than the value of the watershed basin.
visual: Output map: useful for visual display of results. Surface runoff accumulation with the values modified to provide for easy display. All negative accumulation values are changed to zero. All positive values above the basin threshold are given the value of the basin threshold.
length.slope: Output map: slope length and steepness (LS) factor. Contains the LS factor for the Revised Universal Soil Loss Equation. Equations taken from Revised Universal Soil Loss Equation for Western Rangelands (see SEE ALSO section). Since the LS factor is a small number, it is multiplied by 100 for the GRASS output map.
slope.steepness: Output map: slope steepness (S) factor for RUSLE. Contains the revised S factor for the Universal Soil Loss Equation. Equations taken from article enTITLEd Revised Slope Steepness Factor for the Universal Soil Loss Equation (see SEE ALSO section). Since the S factor is a small number (usually less than one), it is multiplied by 100 for the GRASS output map layer.

NOTES

There are two versions of this program: ram and seg. Which is run by depends on whether the -m flag is set. ram uses virtual memory managed by the operating system to store all the data structures and is faster than seg; seg uses the GRASS segment library which manages data in disk files. seg allows other processes to operate on the same CPU, even when the current geographic region is huge. Due to memory requirements of both programs, it will be quite easy to run out of memory. If ram runs out of memory and the resolution size of the current geographic region cannot be increased, either more memory needs to be added to the computer, or the swap space size needs to be increased. If seg runs out of memory, additional disk space needs to be freed up for the program to run.

seg uses the A\uT\d least-cost search algorithm to determine the flow of water over the landscape (see SEE ALSO section). The algorithm produces results similar to those obtained when running r.cost and r.drain on every cell on the map.

In many situations, the elevation data will be too finely detailed for the amount of time or memory available. Running will require use of a coarser resolution. To make the results more closely resemble the finer terrain data, create a map layer containing the lowest elevation values at the coarser resolution. This is done by: 1) Setting the current geographic region equal to the elevation map layer, and 2) Using the neighborhood command to find the lowest value for an area equal in size to the desired resolution. For example, if the resolution of the elevation data is 30 meters and the resolution of the geographic region for will be 90 meters: use the minimum function for a 3 by 3 neighborhood. After going to the resolution at which will be run, will be taking values from the neighborhood output map layer that represents the minimum elevation within the region of the coarser cell.

The minimum size of drainage basins is only relevant for those basins that have no basins draining into them (they are called exterior basins). An interior drainage basin has the area that flows into an interior stream segment. Thus, interior drainage basins can be of any size.

The program does not require the user to have the current geographic region filled with elevation values. Areas without elevation data MUST be masked out using the r.mask command. Areas masked out will be treated as if they are off the edge of the region. Masks will reduce the memory necessary to run the program. Masking out unimportant areas can significantly reduce processing time if the watersheds of interest occupies a small percentage of the overall area.

Zero data values will be treated as elevation data (not no_data). If there are zero data along the edges of the current region, that edge will not be able to propagate negative accumulation data to the rest of the map. This might give users a false sense of security about the quality of their data. If there are incomplete data in the elevation map layer, users should mask out those areas.

AUTHOR

Charles Ehlschlaeger, U.S. Army Construction Engineering Research Laboratory

Last changed: $Date$