r.watershed(1grass) GRASS GIS User's Manual r.watershed(1grass)
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] [thresh-
old=integer] [max_slope_length=float] [accumulation=name]
[tci=name] [spi=name] [drainage=name] [basin=name]
[stream=name] [half_basin=name] [length_slope=name] [slope_steep-
ness=name] [convergence=integer] [memory=memory in MB] [--over-
write] [--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 block-
ing 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=memory in MB
Maximum memory to be used (in MB)
Cache size for raster rows
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 de-
fault surface flow (allows horizontal, vertical, and diagonal flow of
water). This flag will also make the drainage basins look more homoge-
neous.
When -a flag is specified the module will use positive flow accumula-
tion 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 sur-
face runoff from a storm event. All cells that are not NULL and not
zero indicate depressions. Water will flow into but not out of depres-
sions.
Raster flow map specifies amount of overland flow per cell. This map
indicates the amount of overland flow units that each cell will con-
tribute to the watershed basin model. Overland flow units represent the
amount of overland flow each cell contributes to surface flow. If omit-
ted, 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 as-
sumes 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 re-
gion.
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 indi-
cates 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 ar-
ticle entitled Revised Slope Steepness Factor for the Universal Soil
Loss Equation (McCool et al. 1987). Since the S factor is a small num-
ber (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 sec-
tion) 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 re-
sults 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 re-
sults. 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.ter-
raflow. 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, us-
ing slope towards neighbouring cells as a weighing factor for propor-
tional 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 ac-
cumulation 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 re-
gions 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 com-
mand 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.water-
shed 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 parame-
ter, 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 seg-
ments 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 eleva-
tion 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 re-
duce processing time if the watersheds of interest occupy a small per-
centage 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.map-
calc) 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 replace-
ments:
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 vec-
tor 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 con-
vert 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 De-
velop Hydrologic Models from Digital Elevation Data, Proceed-
ings 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 Pro-
file 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 bio-
logical 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 Pro-
cesses Vol 5(1), p.59-79.
DOI: 10.1002/hyp.3360050106
• Weltz M. A., Renard K.G., Simanton J. R. (1987). Revised Uni-
versal 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 Engi-
neering Research Laboratory
Faster sorting algorithm and MFD support: Markus Metz <markus.metz.gis-
work at gmail.com>
Retention for flow distribution by Andreas Gericke (IGB Berlin)
SOURCE CODE
Available at: r.watershed source code (history)
Accessed: unknown
Main index | Raster index | Topics index | Keywords index | Graphical
index | Full index
© 2003-2022 GRASS Development Team, GRASS GIS 7.8.7 Reference Manual
GRASS 7.8.7 r.watershed(1grass)
Generated by dwww version 1.14 on Mon Feb 3 07:39:38 CET 2025.