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.
- 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.
SEE ALSO
The A\uT\d least-cost search algorithm used by is described in
Using the A\uT\d Search Algorithm to Develop Hydrologic Models from
Digital Elevation Data, in Proceedings of International Geographic
Information Systems (IGIS) Symposium '89, pp 275-281 (Baltimore, MD,
18-19 March 1989), by Charles Ehlschlaeger, U.S. Army Construction
Engineering Research Laboratory.
Length slope and steepness (length.slope) factor equations
were taken from Revised Universal Soil Loss
Equation for Western Rangelands, presented at the U.S.A./Mexico
Symposium of Strategies for Classification and Management of Native
Vegetation for Food Production In Arid Zones (Tucson, AZ, 12-16 Oct
1987), by M. A. Weltz, K. G. Renard, and J. R. Simanton.
The slope steepness (slope.steepness) factor contains the revised slope
steepness factor for the Universal Soil Loss Equation. Equations were
taken from article entitled Revised Slope Steepness Factor for the
Universal Soil Loss Equation, in Transactions of the ASAE
(Vol 30(5), Sept-Oct 1987), by McCool et al.
r.cost
r.drain
r.mask
AUTHOR
Charles Ehlschlaeger, U.S. Army Construction Engineering Research Laboratory