Provided by: grass-doc_7.8.2-1build3_all 
NAME
r.watershed - Calculates hydrological parameters and RUSLE factors.
KEYWORDS
raster, hydrology, watershed, accumulation, drainage, stream network, stream power index,
topographic index
SYNOPSIS
r.watershed
r.watershed --help
r.watershed [-s4mab] elevation=name [depression=name] [flow=name]
[disturbed_land=name] [blocking=name] [retention=name] [threshold=integer]
[max_slope_length=float] [accumulation=name] [tci=name] [spi=name] [drainage=name]
[basin=name] [stream=name] [half_basin=name] [length_slope=name]
[slope_steepness=name] [convergence=integer] [memory=integer] [--overwrite]
[--help] [--verbose] [--quiet] [--ui]
Flags:
-s
SFD (D8) flow (default is MFD)
SFD: single flow direction, MFD: multiple flow direction
-4
Allow only horizontal and vertical flow of water
-m
Enable disk swap memory option: Operation is slow
Only needed if memory requirements exceed available RAM; see manual on how to
calculate memory requirements
-a
Use positive flow accumulation even for likely underestimates
See manual for a detailed description of flow accumulation output
-b
Beautify flat areas
Flow direction in flat areas is modified to look prettier
--overwrite
Allow output files to overwrite existing files
--help
Print usage summary
--verbose
Verbose module output
--quiet
Quiet module output
--ui
Force launching GUI dialog
Parameters:
elevation=name [required]
Name of input elevation raster map
depression=name
Name of input depressions raster map
All non-NULL and non-zero cells are considered as real depressions
flow=name
Name of input raster representing amount of overland flow per cell
disturbed_land=name
Name of input raster map percent of disturbed land
For USLE
blocking=name
Name of input raster map blocking overland surface flow
For USLE. All non-NULL and non-zero cells are considered as blocking terrain.
retention=name
Name of input raster map with percentages for flow accumulation.
threshold=integer
Minimum size of exterior watershed basin
max_slope_length=float
Maximum length of surface flow in map units
For USLE
accumulation=name
Name for output accumulation raster map
Number of cells that drain through each cell
tci=name
Name for output topographic index ln(a / tan(b)) map
spi=name
Name for output stream power index a * tan(b)
Name for output raster map
drainage=name
Name for output drainage direction raster map
Directions numbered from 1 to 8
basin=name
Name for output basins raster map
stream=name
Name for output stream segments raster map
half_basin=name
Name for output half basins raster map
Each half-basin is given a unique value
length_slope=name
Name for output slope length raster map
Slope length and steepness (LS) factor for USLE
slope_steepness=name
Name for output slope steepness raster map
Slope steepness (S) factor for USLE
convergence=integer
Convergence factor for MFD (1-10)
1 = most diverging flow, 10 = most converging flow. Recommended: 5
Default: 5
memory=integer
Maximum memory to be used with -m flag (in MB)
Default: 300
DESCRIPTION
r.watershed generates a set of maps indicating: 1) flow accumulation, drainage direction,
the location of streams and watershed basins, and 2) the LS and S factors of the Revised
Universal Soil Loss Equation (RUSLE).
NOTES
Without flag -m set, the entire analysis is run in memory maintained by the operating
system. This can be limiting, but is very fast. Setting this flag causes the program to
manage memory on disk which allows very large maps to be processed but is slower.
Flag -s force the module to use single flow direction (SFD, D8) instead of multiple flow
direction (MFD). MFD is enabled by default.
By -4 flag the user 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.
When -a flag is specified the module will use positive flow accumulation even for likely
underestimates. When this flag is not set, cells with a flow accumulation value that is
likely to be an underestimate are converted to the negative. See below for a detailed
description of flow accumulation output.
Option convergence specifies convergence factor for MFD. Lower values result in higher
divergence, flow is more widely distributed. Higher values result in higher convergence,
flow is less widely distributed, becoming more similar to SFD.
Option elevation specifies the elevation data on which entire analysis is based. NULL
(nodata) cells are ignored, zero and negative values are valid elevation data. Gaps in
the elevation map that are located within the area of interest must be filled beforehand,
e.g. with r.fillnulls, to avoid distortions. The elevation map need not be sink-filled
because the module uses a least-cost algorithm.
Option depression specifies the optional map of actual depressions or sinkholes in the
landscape that are large enough to slow and store surface runoff from a storm event. All
cells that are not NULL and not zero indicate depressions. Water will flow into but not
out of depressions.
Raster flow map specifies 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.
Raster retention map specifies correction factors per cell for flow distribution. This map
indicates the percentage of overland flow units leaving each cell. Values should be
between zero and 100. If omitted, a value of 100 is assumed.
Input Raster map 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, r.watershed assumes no disturbed land. This input is used for the RUSLE
calculations.
Option blocking specifies terrain that will block overland surface flow. Blocking cells
and streams stop the slope length for the RUSLE. All cells that are not NULL and not zero
indicate blocking terrain.
Option threshold specifies the minimum size of an exterior watershed basin in cells, if no
flow map is input, or overland flow units when a flow map is given. Warning: low
threshold values will dramactically increase run time and generate difficult to read basin
and half_basin results. This parameter also controls the level of detail in the stream
segments map.
Value given by max_slope_length option indicates 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.
Output accumulation map contains the absolute value of the amount of overland flow that
traverses each 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.
Output tci raster map contains topographic index TCI, computed as ln(α / tan(β)) where α
is the cumulative upslope area draining through a point per unit contour length and tan(β)
is the local slope angle. The TCI reflects the tendency of water to accumulate at any
point in the catchment and the tendency for gravitational forces to move that water
downslope (Quinn et al. 1991). This value will be negative if α / tan(β) < 1.
Output spi raster map contains stream power index SPI, computed as α * tan(β) where α is
the cumulative upslope area draining through a point per unit contour length and tan(β) is
the local slope angle. The SPI reflects the power of water flow at any point in the
catchment and the tendency for gravitational forces to move that water downslope (Moore et
al. 1991). This value will be negative if α < 0, i.e. for cells with possible surface
runoff from outside of the current geographic region.
Output drainage raster map contains drainage direction. Provides the "aspect" for each
cell measured CCW from East.
Figure: Drainage is 8 directions numbered counter-clockwise starting from 1 in north-east
direction (source) Multiplying positive values by 45 will give the direction in degrees
that the surface runoff will travel from that cell. The value 0 (zero) indicates that the
cell is a depression area (defined by the depression input map). 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. For MFD, drainage
indicates the direction of maximum flow.
The output basin map contains 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. NULL values indicate that the cell is not part of a complete
watershed basin in the current geographic region.
The output stream contains stream segments. Values correspond to the watershed basin
values. Can be vectorized after thinning (r.thin) with r.to.vect.
The output half_basin raster map stores 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 values in basin. The
left-hand side cells of the watershed basin are given odd values which are one less than
the value of the watershed basin.
The output length_slope raster map stores slope length and steepness (LS) factor for the
Revised Universal Soil Loss Equation (RUSLE). Equations taken from Revised Universal Soil
Loss Equation for Western Rangelands (Weltz et al. 1987). Since the LS factor is a small
number (usually less than one), the GRASS output map is of type DCELL.
The output slope_steepness raster map stores slope steepness (S) factor for the Universal
Soil Loss Equation (RUSLE). Equations taken from article entitled Revised Slope Steepness
Factor for the Universal Soil Loss Equation (McCool et al. 1987). Since the S factor is a
small number (usually less than one), the GRASS output map is of type DCELL.
AT least-cost search algorithm
r.watershed uses an AT least-cost search algorithm (see REFERENCES section) designed to
minimize the impact of DEM data errors. Compared to r.terraflow, this algorithm provides
more accurate results in areas of low slope as well as DEMs constructed with techniques
that mistake canopy tops as the ground elevation. Kinner et al. (2005), for example, used
SRTM and IFSAR DEMs to compare r.watershed against r.terraflow results in Panama.
r.terraflow was unable to replicate stream locations in the larger valleys while
r.watershed performed much better. Thus, if forest canopy exists in valleys, SRTM, IFSAR,
and similar data products will cause major errors in r.terraflow stream output. Under
similar conditions, r.watershed will generate better stream and half_basin results. If
watershed divides contain flat to low slope, r.watershed will generate better basin
results than r.terraflow. (r.terraflow uses the same type of algorithm as ESRI’s ArcGIS
watershed software which fails under these conditions.) Also, if watershed divides contain
forest canopy mixed with uncanopied areas using SRTM, IFSAR, and similar data products,
r.watershed will generate better basin results than r.terraflow. The algorithm produces
results similar to those obtained when running r.cost and r.drain on every cell on the
raster map.
Multiple flow direction (MFD)
r.watershed offers two methods to calculate surface flow: single flow direction (SFD, D8)
and multiple flow direction (MFD). With MFD, water flow is distributed to all neighbouring
cells with lower elevation, using slope towards neighbouring cells as a weighing factor
for proportional distribution. The AT least-cost path is always included. As a result,
depressions and obstacles are traversed with a graceful flow convergence before the
overflow. The convergence factor causes flow accumulation to converge more strongly with
higher values. The supported range is 1 to 10, recommended is a convergence factor of 5
(Holmgren, 1994). If many small sliver basins are created with MFD, setting the
convergence factor to a higher value can reduce the amount of small sliver basins.
In-memory mode and disk swap mode
There are two versions of this program: ram and seg. ram is used by default, seg can be
used by setting the -m flag.
The ram version requires a maximum of 31 MB of RAM for 1 million cells. Together with the
amount of system memory (RAM) available, this value can be used to estimate whether the
current region can be processed with the ram version.
The ram version uses virtual memory managed by the operating system to store all the data
structures and is faster than the seg version; seg uses the GRASS segmentation library
which manages data in disk files. seg uses only as much system memory (RAM) as specified
with the memory option, allowing other processes to operate on the same system, even when
the current geographic region is huge.
Due to memory requirements of both programs, it is quite easy to run out of memory when
working with huge map regions. If the ram version 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. The
r.terraflow module was specifically designed with huge regions in mind and may be useful
here as an alternative, although disk space requirements of r.terraflow are several times
higher than of seg.
Large regions with many cells
The upper limit of the ram version is 2 billion (231 - 1) cells, whereas the upper limit
for the seg version is 9 billion-billion (263 - 1 = 9.223372e+18) cells.
In some situations, the region size (number of cells) may be too large for the amount of
time or memory available. Running r.watershed may then 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 with g.region,
and 2) Use the r.neighbors or r.resamp.stats 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 r.watershed will be 90
meters: use the minimum function for a 3 by 3 neighborhood. After changing to the
resolution at which r.watershed will be run, r.watershed should be run using the values
from the neighborhood output map layer that represents the minimum elevation within the
region of the coarser cell.
Basin threshold
The minimum size of drainage basins, defined by the threshold parameter, is only relevant
for those watersheds with a single stream having at least the threshold of cells flowing
into it. (These watersheds are called exterior basins.) Interior drainage basins contain
stream segments below multiple tributaries. Interior drainage basins can be of any size
because the length of an interior stream segment is determined by the distance between the
tributaries flowing into it.
MASK and no data
The r.watershed program does not require the user to have the current geographic region
filled with elevation values. Areas without elevation data (masked or NULL cells) are
ignored. It is NOT necessary to create a raster map (or raster reclassification) named
MASK for NULL cells. Areas without elevation data will be treated as if they are off the
edge of the region. Such areas will reduce the memory necessary to run the program.
Masking out unimportant areas can significantly reduce processing time if the watersheds
of interest occupy a small percentage of the overall area.
Gaps (NULL cells) in the elevation map that are located within the area of interest will
heavily influence the analysis: water will flow into but not out of these gaps. These gaps
must be filled beforehand, e.g. with r.fillnulls.
Zero (0) and negative values will be treated as elevation data (not no_data).
Further processing of output layers
Problem areas, i.e. those parts of a basin with a likely underestimate of flow
accumulation, can be easily identified with e.g.
r.mapcalc "problems = if(flow_acc < 0, basin, null())"
If the region of interest contains such problem areas, and this is not desired, the
computational region must be expanded until the catchment area for the region of interest
is completely included.
To isolate an individual river network using the output of this module, a number of
approaches may be considered.
1 Use a resample of the basins catchment raster map as a MASK.
The equivalent vector map method is similar using v.select or v.overlay.
2 Use the r.cost module with a point in the river as a starting point.
3 Use the v.net.iso module with a node in the river as a starting point.
All individual river networks in the stream segments output can be identified through
their ultimate outlet points. These points are all cells in the stream segments output
with negative drainage direction. These points can be used as start points for
r.water.outlet or v.net.iso.
To create river mile segmentation from a vectorized streams map, try the v.net.iso or
v.lrs.segment modules.
The stream segments output can be easily vectorized after thinning with r.thin. Each
stream segment in the vector map will have the value of the associated basin. To isolate
subbasins and streams for a larger basin, a MASK for the larger basin can be created with
r.water.outlet. The stream segments output serves as a guide where to place the outlet
point used as input to r.water.outlet. The basin threshold must have been sufficiently
small to isolate a stream network and subbasins within the larger basin.
Given that the drainage is 8 directions numbered counter-clockwise starting from 1 in
north-east direction, multiplying the output by 45 (by 45. to get a double precision
floating point raster map in r.mapcalc) gives the directions in degrees. For most
applications, zeros which indicate depressions specified by depression and negative values
which indicate runoff leaving the region should be replaced by NULL (null() in r.mapcalc).
The following command performs these replacements:
r.mapcalc "drainage_degrees = if(drainage > 0, 45. * drainage, null())"
Alternatively, the user can use the -a flag or later the abs() function in r.mapcalc if
the runoff is leaving the region.
EXAMPLES
These examples use the Spearfish sample dataset.
Convert r.watershed streams map output to a vector map
If you want a detailed stream network, set the threshold option small to create lots of
catchment basins, as only one stream is presented per catchment. The r.to.vect -v flag
preserves the catchment ID as the vector category number.
r.watershed elev=elevation.dem stream=rwater.stream
r.to.vect -v in=rwater.stream out=rwater_stream
Set a different color table for the accumulation map:
MAP=rwater.accum
r.watershed elev=elevation.dem accum=$MAP
eval `r.univar -g "$MAP"`
stddev_x_2=`echo $stddev | awk ’{print $1 * 2}’`
stddev_div_2=`echo $stddev | awk ’{print $1 / 2}’`
r.colors $MAP col=rules << EOF
0% red
-$stddev_x_2 red
-$stddev yellow
-$stddev_div_2 cyan
-$mean_of_abs blue
0 white
$mean_of_abs blue
$stddev_div_2 cyan
$stddev yellow
$stddev_x_2 red
100% red
EOF
Create a more detailed stream map using the accumulation map and convert it to a vector
output map. The accumulation cut-off, and therefore fractal dimension, is arbitrary; in
this example we use the map’s mean number of upstream catchment cells (calculated in the
above example by r.univar) as the cut-off value. This only works with SFD, not with MFD.
r.watershed elev=elevation.dem accum=rwater.accum
r.mapcalc ’MASK = if(!isnull(elevation.dem))’
r.mapcalc "rwater.course = \
if( abs(rwater.accum) > $mean_of_abs, \
abs(rwater.accum), \
null() )"
r.colors -g rwater.course col=bcyr
g.remove -f type=raster name=MASK
# Thinning is required before converting raster lines to vector
r.thin in=rwater.course out=rwater.course.Thin
r.colors -gn rwater.course.Thin color=grey
r.to.vect in=rwater.course.Thin out=rwater_course type=line
v.db.dropcolumn map=rwater_course column=label
Create watershed basins map and convert to a vector polygon map
r.watershed elev=elevation.dem basin=rwater.basin thresh=15000
r.to.vect -s in=rwater.basin out=rwater_basins type=area
v.db.dropcolumn map=rwater_basins column=label
v.db.renamecolumn map=rwater_basins column=value,catchment
Display output in a nice way
r.relief map=elevation.dem
d.shade shade=elevation.dem.shade color=rwater.basin bright=40
d.vect rwater_course color=orange
REFERENCES
• Ehlschlaeger C. (1989). Using the AT Search Algorithm to Develop Hydrologic Models
from Digital Elevation Data, Proceedings of International Geographic Information
Systems (IGIS) Symposium ’89, pp 275-281 (Baltimore, MD, 18-19 March 1989).
URL: http://chuck.ehlschlaeger.info/older/IGIS/paper.html
• Holmgren P. (1994). Multiple flow direction algorithms for runoff modelling in
grid based elevation models: An empirical evaluation. Hydrological Processes Vol
8(4), 327-334.
DOI: 10.1002/hyp.3360080405
• Kinner D., Mitasova H., Harmon R., Toma L., Stallard R. (2005). GIS-based Stream
Network Analysis for The Chagres River Basin, Republic of Panama. The Rio Chagres:
A Multidisciplinary Profile of a Tropical Watershed, R. Harmon (Ed.),
Springer/Kluwer, p.83-95.
URL: http://www4.ncsu.edu/~hmitaso/measwork/panama/panama.html
• McCool et al. (1987). Revised Slope Steepness Factor for the Universal Soil Loss
Equation, Transactions of the ASAE Vol 30(5).
• Metz M., Mitasova H., Harmon R. (2011). Efficient extraction of drainage networks
from massive, radar-based elevation models with least cost path search, Hydrol.
Earth Syst. Sci. Vol 15, 667-678.
DOI: 10.5194/hess-15-667-2011
• Moore I.D., Grayson R.B., Ladson A.R. (1991). Digital terrain modelling: a review
of hydrogical, geomorphological, and biological applications, Hydrological
Processes, Vol 5(1), 3-30
DOI: 10.1002/hyp.3360050103
• Quinn P., K. Beven K., Chevallier P., Planchon O. (1991). The prediction of
hillslope flow paths for distributed hydrological modelling using Digital
Elevation Models, Hydrological Processes Vol 5(1), p.59-79.
DOI: 10.1002/hyp.3360050106
• Weltz M. A., Renard K.G., Simanton J. R. (1987). Revised Universal Soil Loss
Equation for Western Rangelands, 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).
SEE ALSO
g.region, r.cost, r.drain, r.fillnulls, r.flow, r.mask, r.neighbors, r.param.scale,
r.resamp.interp, r.terraflow, r.topidx, r.water.outlet, r.stream.extract
AUTHORS
Original version: Charles Ehlschlaeger, U.S. Army Construction Engineering Research
Laboratory
Faster sorting algorithm and MFD support: Markus Metz <markus.metz.giswork at gmail.com>
Retention for flow distribution by Andreas Gericke (IGB Berlin)
SOURCE CODE
Available at: r.watershed source code (history)
Main index | Raster index | Topics index | Keywords index | Graphical index | Full index
© 2003-2019 GRASS Development Team, GRASS GIS 7.8.2 Reference Manual