3
<em>r.watershed</em> generates a set of maps indicating: 1) flow
4
accumulation, drainage direction, the location of streams and
5
watershed basins, and 2) the LS and S factors of the Revised Universal
6
Soil Loss Equation (RUSLE).
8
<!-- Interactive mode not activated in GRASS 7.
10
<em>r.watershed</em> can be run either interactively or non-interactively.
11
The interactive version of
12
<em>r.watershed</em> can prepare inputs to lumped-parameter hydrologic models.
13
After a verbose interactive session, <em>r.watershed</em> will query the user
15
map layers. Each map layer's values will be tabulated by watershed basin and sent
16
to an output file. This output file is organized to ease data entry into a
17
lumped-parameter hydrologic model program. The non-interactive version of
18
<em>r.watershed</em> cannot create this file.
23
Without flag <b>-m</b> set, the entire analysis is run in memory
24
maintained by the operating system. This can be limiting, but is very
25
fast. Setting this flag causes the program to manage memory on disk
26
which allows very large maps to be processed but is slower.
29
Flag <b>-s</b> force the module to use single flow direction (SFD, D8)
30
instead of multiple flow direction (MFD). MFD is enabled by default.
33
By <b>-4</b> flag the user allow only horizontal and vertical flow of
34
water. Stream and slope lengths are approximately the same as outputs
35
from default surface flow (allows horizontal, vertical, and diagonal
36
flow of water). This flag will also make the drainage basins look
40
When <b>-a</b> flag is specified the module will use positive flow
41
accumulation even for likely underestimates. When this flag is not
42
set, cells with a flow accumulation value that is likely to be an
43
underestimate are converted to the negative. See below for a detailed
44
description of flow accumulation output.
47
Option <b>convergence</b> specifies convergence factor for MFD. Lower
48
values result in higher divergence, flow is more widely
49
distributed. Higher values result in higher convergence, flow is less
50
widely distributed, becoming more similar to SFD.
53
Option <b>elevation</b> specifies the elevation data on which entire
54
analysis is based. NULL (nodata) cells are ignored, zero and negative
55
values are valid elevation data. Gaps in the elevation map that are
56
located within the area of interest must be filled beforehand,
57
e.g. with <em><a href="r.fillnulls.html">r.fillnulls</a></em>, to
58
avoid distortions. The elevation map need not be sink-filled because
59
the module uses a least-cost algorithm.
62
Map of actual depressions or sinkholes in the landscape that are large
63
enough to slow and store surface runoff from a storm event. All cells
64
that are not NULL and not zero indicate depressions. Water will flow
65
into but not out of depressions.
68
Raster <b>flow</b> map specifies amount of overland flow per cell.
69
This map indicates the amount of overland flow units that each cell
70
will contribute to the watershed basin model. Overland flow units
71
represent the amount of overland flow each cell contributes to surface
72
flow. If omitted, a value of one (1) is assumed.
75
Input Raster map or value containing the percent of disturbed land
76
(i.e., croplands, and construction sites) where the raster or input
77
value of 17 equals 17%. If no map or value is
78
given, <em>r.watershed</em> assumes no disturbed land. This input is
79
used for the RUSLE calculations.
82
Option <b>blocking</b> specifies terrain that will block overland
83
surface flow. errain that will block overland surface flow and
84
restart the slope length for the RUSLE. All cells that are not NULL
85
and not zero indicate blocking terrain.
88
Option <b>threshold</b> specifies the minimum size of an exterior
89
watershed basin in cells, if no flow map is input, or overland flow
90
units when a flow map is given. Warning: low threshold values will
91
dramactically increase run time and generate difficult to read basin
92
and half_basin results. This parameter also controls the level of
93
detail in the <b>stream</b> segments map.
96
Value given by <b>max_slope_length</b> option indicates the maximum
97
length of overland surface flow in meters. If overland flow travels
98
greater than the maximum length, the program assumes the maximum
99
length (it assumes that landscape characteristics not discernible in
100
the digital elevation model exist that maximize the slope length).
101
This input is used for the RUSLE calculations and is a sensitive
105
Output <b>accumulation</b> map contains the absolute value of each
106
cell in this output map is the amount of overland flow that traverses
107
the cell. This value will be the number of upland cells plus one if no
108
overland flow map is given. If the overland flow map is given, the
109
value will be in overland flow units. Negative numbers indicate that
110
those cells possibly have surface runoff from outside of the current
111
geographic region. Thus, any cells with negative values cannot have
112
their surface runoff and sedimentation yields calculated accurately.
115
Output <b>tci</b> raster map contains topographic index TCI is
117
<tt>ln(α / tan(β))</tt> where α is the cumulative
118
upslope area draining through a point per unit contour length and
119
<tt>tan(β)</tt> is the local slope angle. The TCI reflects the
120
tendency of water to accumulate at any point in the catchment and the
121
tendency for gravitaional forces to move that water downslope (Quinn
122
et al. 1991). This value will be negative if <tt>α /
123
tan(β) < 1</tt>.
126
Output <b>drainage</b> raster map contains drainage direction.
127
Provides the "aspect" for each cell measured CCW from East.
128
Multiplying positive values by 45 will give the direction in degrees
129
that the surface runoff will travel from that cell. The value 0
130
(zero) indicates that the cell is a depression area (defined by the
131
depression input map). Negative values indicate that surface runoff
132
is leaving the boundaries of the current geographic region. The
133
absolute value of these negative cells indicates the direction of
137
The output <b>basin</b> map contains unique label for each watershed
138
basin. Each basin will be given a unique positive even integer. Areas
139
along edges may not be large enough to create an exterior watershed
140
basin. 0 values indicate that the cell is not part of a complete
141
watershed basin in the current geographic region.
144
The output <b>stream</b> contains stream segments. Values correspond
145
to the watershed basin values. Can be vectorized after thinning
146
(<em><a href="r.thin.html">r.thin</a></em>) with
147
<em><a href="r.to.vect.html">r.to.vect</a></em>.
150
The output <b>half_basin</b> raster map stores each half-basin is
151
given a unique value. Watershed basins are divided into left and right
152
sides. The right-hand side cell of the watershed basin (looking
153
upstream) are given even values corresponding to the values in basin.
154
The left-hand side cells of the watershed basin are given odd values
155
which are one less than the value of the watershed basin.
158
The output <b>length_slope</b> raster map stores slope length and
159
steepness (LS) factor for the Revised Universal Soil Loss Equation
160
(RUSLE). Equations taken from <em>Revised Universal Soil Loss
161
Equation for Western Rangelands</em> (Weltz et al. 1987). Since the LS
162
factor is a small number (usually less than one), the GRASS output map
166
The output <b>slope_steepness</b> raster map stores slope steepness
167
(S) factor for the Universal Soil Loss Equation (RUSLE). Equations
168
taken from article entitled
169
<em>Revised Slope Steepness Factor for the Universal Soil
170
Loss Equation</em> (McCool et al. 1987). Since the S factor is a small
171
number (usually less than one), the GRASS output map is of type DCELL.
173
<h3>A<sup>T</sup> least-cost search algorithm</h3>
175
<em>r.watershed</em> uses an A<sup>T</sup> least-cost search algorithm
176
(see REFERENCES section) designed to minimize the impact of DEM data
178
to <em><a href="r.terraflow.html">r.terraflow</a></em>, this algorithm
179
provides more accurate results in areas of low slope as well as DEMs
180
constructed with techniques that mistake canopy tops as the ground
181
elevation. Kinner et al. (2005), for example, used SRTM and IFSAR DEMs
182
to compare <em>r.watershed</em>
183
against <em><a href="r.terraflow.html">r.terraflow</a></em> results in
184
Panama. <em><a href="r.terraflow.html">r.terraflow</a></em> was unable
185
to replicate stream locations in the larger valleys
186
while <em>r.watershed</em> performed much better. Thus, if forest
187
canopy exists in valleys, SRTM, IFSAR, and similar data products will
188
cause major errors in <em>r.terraflow</em> stream output. Under
189
similar conditions, <em>r.watershed</em> will generate
190
better <b>stream</b> and <b>half_basin</b> results. If watershed
191
divides contain flat to low slope, <em>r.watershed</em> will generate
193
than <em><a href="r.terraflow.html">r.terraflow</a></em>. (<em><a href="r.terraflow.html">r.terraflow</a></em>
194
uses the same type of algorithm as ESRI's ArcGIS watershed software
195
which fails under these conditions.) Also, if watershed divides
196
contain forest canopy mixed with uncanopied areas using SRTM, IFSAR,
197
and similar data products, <em>r.watershed</em> will generate better
199
than <em><a href="r.terraflow.html">r.terraflow</a></em>. The
200
algorithm produces results similar to those obtained when running
201
<em><a href="r.cost.html">r.cost</a></em> and
202
<em><a href="r.drain.html">r.drain</a></em> on every cell on the raster map.
204
<h3>Multiple flow direction (MFD)</h3>
206
<em>r.watershed</em> offers two methods to calculate surface flow:
207
single flow direction (SFD, D8) and multiple flow direction
208
(MFD). With MFD, water flow is distributed to all neighbouring cells
209
with lower elevation, using slope towards neighbouring cells as a
210
weighing factor for proportional distribution. The A<sup>T</sup>
211
least-cost path is always included. As a result, depressions and
212
obstacles are traversed with a gracefull flow convergence before the
213
overflow. The convergence factor causes flow accumulation to converge
214
more strongly with higher values. The supported range is 1 to 10,
215
recommended is a convergence factor of 5 (Holmgren, 1994). If many
216
small sliver basins are created with MFD, setting the convergence
217
factor to a higher value can reduce the amount of small sliver basins.
219
<h3>In-memory mode and disk swap mode</h3>
221
There are two versions of this program: <em>ram</em> and <em>seg</em>.
222
<em>ram</em> is used by default, <em>seg</em> can be used by setting
226
The <em>ram</em> version requires a maximum of 31 MB of RAM for 1
227
million cells. Together with the amount of system memory (RAM)
228
available, this value can be used to estimate whether the current
229
region can be processed with the <em>ram</em> version.
232
The <em>ram</em> version uses virtual memory managed by the operating
233
system to store all the data structures and is faster than
234
the <em>seg</em> version; <em>seg</em> uses the GRASS segmentation
235
library which manages data in disk files. <em>seg</em> uses only as
236
much system memory (RAM) as specified with the <b>memory</b> option,
237
allowing other processes to operate on the same system, even when the
238
current geographic region is huge.
241
Due to memory requirements of both programs, it is quite easy to run
242
out of memory when working with huge map regions. If the <em>ram</em>
243
version runs out of memory and the resolution size of the current
244
geographic region cannot be increased, either more memory needs to be
245
added to the computer, or the swap space size needs to be
246
increased. If <em>seg</em> runs out of memory, additional disk space
247
needs to be freed up for the program to run.
248
The <em><a href="r.terraflow.html">r.terraflow</a></em> module was
249
specifically designed with huge regions in mind and may be useful here
250
as an alternative, although disk space requirements
251
of <em><a href="r.terraflow.html">r.terraflow</a></em> are several times higher than of <em>seg</em>.
253
<h3>Large regions with many cells</h3>
255
The upper limit of the <em>ram</em> version is 2 billion
256
(2<sup>31</sup> - 1) cells, whereas the upper limit for
257
the <em>seg</em> version is 9 billion billion (2<sup>63</sup> - 1)
258
cells.<br> In some situations, the region size (number of cells) may
259
be too large for the amount of time or memory
260
available. Running <em>r.watershed</em> may then require use of a
261
coarser resolution. To make the results more closely resemble the
262
finer terrain data, create a map layer containing the lowest elevation
263
values at the coarser resolution. This is done by: 1) Setting the
264
current geographic region equal to the elevation map layer
265
with <em><a href="g.region.html">g.region</a></em>, and 2) Use
266
the <em><a href="r.neighbors.html">r.neighbors</a></em> or
267
<em><a href="r.resamp.stats.html">r.resamp.stats</a></em> command to
268
find the lowest value for an area equal in size to the desired
269
resolution. For example, if the resolution of the elevation data is 30
270
meters and the resolution of the geographic region
271
for <em>r.watershed</em> will be 90 meters: use the minimum function
272
for a 3 by 3 neighborhood. After changing to the resolution at
273
which <em>r.watershed</em> will be run, <em>r.watershed</em> should be
274
run using the values from the <b>neighborhood</b> output map layer
275
that represents the minimum elevation within the region of the coarser
278
<h3>Basin threshold</h3>
280
The minimum size of drainage basins, defined by the <b>threshold</b>
281
parameter, is only relevant for those watersheds with a single stream
282
having at least the <b>threshold</b> of cells flowing into it.
283
(These watersheds are called exterior basins.) Interior drainage
284
basins contain stream segments below multiple tributaries. Interior
285
drainage basins can be of any size because the length of an interior
286
stream segment is determined by the distance between the tributaries
289
<h3>MASK and no data</h3>
292
The <em>r.watershed</em> program does not require the user to have the
293
current geographic region filled with elevation values. Areas without
294
elevation data (masked or NULL cells) are ignored. It is NOT necessary
295
to create a raster map (or raster reclassification)
296
named <tt>MASK</tt> for NULL cells. Areas without elevation data will
297
be treated as if they are off the edge of the region. Such areas will
298
reduce the memory necessary to run the program. Masking out
299
unimportant areas can significantly reduce processing time if the
300
watersheds of interest occupy a small percentage of the overall area.
303
Gaps (NULL cells) in the elevation map that are located within the
304
area of interest will heavily influence the analysis: water will flow
305
into but not out of these gaps. These gaps must be filled beforehand,
306
e.g. with <em><a href="r.fillnulls.html">r.fillnulls</a></em>.
309
Zero (0) and negative values will be treated as elevation data (not
312
<h3>Further processing of output layers</h3>
314
Problem areas, i.e. those parts of a basin with a likely underestimate
315
of flow accumulation, can be easily identified with e.g.
317
<div class="code"><pre>
318
r.mapcalc "problems = if(flow_acc < 0, basin, null())"
321
If the region of interest contains such problem areas, and this is not
322
desired, the computational region must be expanded until the catchment
323
area for the region of interest is completely included.
326
To isolate an individual river network using the output of this
327
module, a number of approaches may be considered.
330
<li>Use a resample of the basins catchment raster map as a MASK.<br>
331
The equivalent vector map method is similar
332
using <em><a href="v.select.html">v.select</a></em> or
333
<em><a href="v.overlay.html">v.overlay</a></em>.
334
<li>Use the <em><a href="r.cost.html">r.cost</a></em> module with a
335
point in the river as a starting point.
336
<li>Use the <em><a href="v.net.iso.html">v.net.iso</a></em> module
337
with a node in the river as a starting point.
340
All individual river networks in the stream segments output can be
341
identified through their ultimate outlet points. These points are all
342
cells in the stream segments output with negative drainage direction.
343
These points can be used as start points
344
for <em><a href="r.water.outlet.html">r.water.outlet</a></em> or
345
<em><a href="v.net.iso.html">v.net.iso<a/></em>.
348
To create <i>river mile</i> segmentation from a vectorized streams
350
the <em><a href="v.net.iso.html">v.net.iso<a/></em> or <em><a href="v.lrs.segment.html">v.lrs.segment</a></em>
354
The stream segments output can be easily vectorized after thinning
356
<em><a href="r.thin.html">r.thin</a></em>. Each stream segment in the
357
vector map will have the value of the associated basin. To isolate
358
subbasins and streams for a larger basin, a MASK for the larger basin
360
<em><a href="r.water.outlet.html">r.water.outlet</a></em>. The stream
361
segments output serves as a guide where to place the outlet point used
362
as input to <em><a href="r.water.outlet.html">r.water.outlet</a></em>.
363
The basin threshold must have been sufficiently small to isolate a
364
stream network and subbasins within the larger basin.
368
These examples use the Spearfish sample dataset.
370
<h3>Convert <em>r.watershed</em> streams map output to a vector map</h3>
372
If you want a detailed stream network, set the threshold option small
373
to create lots of catchment basins, as only one stream is presented
374
per catchment. The <tt>r.to.vect -v</tt> flag preserves the catchment
375
ID as the vector category number.
377
<div class="code"><pre>
378
r.watershed elev=elevation.dem stream=rwater.stream
379
r.to.vect -v in=rwater.stream out=rwater_stream
383
Set a different color table for the accumulation map:
385
<div class="code"><pre>
387
r.watershed elev=elevation.dem accum=$MAP
389
eval `r.univar -g "$MAP"`
390
stddev_x_2=`echo $stddev | awk '{print $1 * 2}'`
391
stddev_div_2=`echo $stddev | awk '{print $1 / 2}'`
393
r.colors $MAP col=rules << EOF
409
Create a more detailed stream map using the accumulation map and
410
convert it to a vector output map. The accumulation cut-off, and
411
therefore fractal dimension, is arbitrary; in this example we use the
412
map's mean number of upstream catchment cells (calculated in the above
413
example by <em><a href="r.univar.html">r.univar</a></em>) as the
414
cut-off value. This only works with SFD, not with MFD.
416
<div class="code"><pre>
417
r.watershed elev=elevation.dem accum=rwater.accum
419
r.mapcalc 'MASK = if(!isnull(elevation.dem))'
420
r.mapcalc "rwater.course = \
421
if( abs(rwater.accum) > $mean_of_abs, \
424
r.colors -g rwater.course col=bcyr
425
g.remove -f type=raster name=MASK
427
# <i>Thinning is required before converting raster lines to vector</i>
428
r.thin in=rwater.course out=rwater.course.Thin
429
r.colors -gn rwater.course.Thin color=grey
430
r.to.vect in=rwater.course.Thin out=rwater_course type=line
431
v.db.dropcolumn map=rwater_course column=label
434
<!-- can't set line attribute to catchment it is in as v.what.rast and
435
v.distance only work for point features. Could create endpoint node
436
points map and upload to that ?? -->
437
<!-- Note value column containing accumulation cells in output vector
438
may not necessarily reference the downstream end of the line! drop it? -->
440
<h3>Create watershed basins map and convert to a vector polygon map</h3>
442
<div class="code"><pre>
443
r.watershed elev=elevation.dem basin=rwater.basin thresh=15000
444
r.to.vect -s in=rwater.basin out=rwater_basins type=area
445
v.db.dropcolumn map=rwater_basins column=label
446
v.db.renamecolumn map=rwater_basins column=value,catchment
450
Display output in a nice way
451
<div class="code"><pre>
452
r.relief map=elevation.dem
453
d.shade shade=elevation.dem.shade color=rwater.basin bright=40
454
d.vect rwater_course color=orange
460
<li>Ehlschlaeger C. (1989). <i>Using the A<sup>T</sup> Search Algorithm
461
to Develop Hydrologic Models from Digital Elevation Data</i>,
462
<b>Proceedings of International Geographic Information Systems (IGIS)
463
Symposium '89</b>, pp 275-281 (Baltimore, MD, 18-19 March 1989).<br>
464
URL: <a href="http://chuck.ehlschlaeger.info/older/IGIS/paper.html">
465
http://chuck.ehlschlaeger.info/older/IGIS/paper.html</a>
467
<li>Holmgren P. (1994). <i>Multiple flow direction algorithms for runoff
468
modelling in grid based elevation models: An empirical evaluation.</i>
469
<b>Hydrological Processes</b> Vol 8(4), 327-334.<br>
470
DOI: <a href="http://dx.doi.org/10.1002/hyp.3360080405">10.1002/hyp.3360080405</a>
472
<li>Kinner D., Mitasova H., Harmon R., Toma L., Stallard R. (2005).
473
<i>GIS-based Stream Network Analysis for The Chagres River Basin,
474
Republic of Panama</i>. <b>The Rio Chagres: A Multidisciplinary Profile of
475
a Tropical Watershed</b>, R. Harmon (Ed.), Springer/Kluwer, p.83-95.<br>
476
URL: <a href="http://www4.ncsu.edu/~hmitaso/measwork/panama/panama.html">
477
http://www4.ncsu.edu/~hmitaso/measwork/panama/panama.html</a>
479
<li>McCool et al. (1987). <i>Revised Slope Steepness Factor for the Universal
480
Soil Loss Equation</i>, <b>Transactions of the ASAE</b> Vol 30(5).
482
<li>Metz M., Mitasova H., Harmon R. (2011). <i>Efficient extraction of
483
drainage networks from massive, radar-based elevation models with least
484
cost path search</i>, <b>Hydrol. Earth Syst. Sci.</b> Vol 15, 667-678.<br>
485
DOI: <a href="http://dx.doi.org/10.5194/hess-15-667-2011">10.5194/hess-15-667-2011</a>
487
<li>Quinn P., K. Beven K., Chevallier P., Planchon O. (1991). <i>The
488
prediction of hillslope flow paths for distributed hydrological modelling
489
using Digital Elevation Models</i>, <b>Hydrological Processes</b> Vol 5(1),
491
DOI: <a href="http://dx.doi.org/10.1002/hyp.3360050106">10.1002/hyp.3360050106</a>
493
<li>Weltz M. A., Renard K.G., Simanton J. R. (1987). <i>Revised Universal Soil
494
Loss Equation for Western Rangelands</i>, <b>U.S.A./Mexico Symposium of
495
Strategies for Classification and Management of Native Vegetation for
496
Food Production In Arid Zones</b> (Tucson, AZ, 12-16 Oct. 1987).
503
<a href="g.region.html">g.region</a>,
504
<a href="r.cost.html">r.cost</a>,
505
<a href="r.drain.html">r.drain</a>,
506
<a href="r.fillnulls.html">r.fillnulls</a>,
507
<a href="r.flow.html">r.flow</a>,
508
<!-- <a href="r.flowmd.html">r.flowmd</a>, -->
509
<a href="r.mask.html">r.mask</a>,
510
<a href="r.neighbors.html">r.neighbors</a>,
511
<a href="r.param.scale.html">r.param.scale</a>,
512
<a href="r.resamp.interp.html">r.resamp.interp</a>,
513
<a href="r.terraflow.html">r.terraflow</a>,
514
<a href="r.topidx.html">r.topidx</a>,
515
<a href="r.water.outlet.html">r.water.outlet</a>,
516
<a href="r.stream.extract.html">r.stream.extract</a>
523
Charles Ehlschlaeger, U.S. Army Construction Engineering Research Laboratory
525
Faster sorting algorithm and MFD support:
526
Markus Metz <markus.metz.giswork at gmail.com>
529
<i>Last changed: $Date: 2014-12-27 00:50:11 +0100 (Sat, 27 Dec 2014) $</i>