1r.watershed(1) Grass User's Manual r.watershed(1)
2
6 r.watershed - Watershed basin analysis program.
7
9 raster
10
12 r.watershed
13 r.watershed help
14 r.watershed [-m4] elevation=string [depression=string] [flow=string]
15 [disturbed.land=string] [blocking=string] [threshold=integer]
16 [max.slope.length=float] [accumulation=string] [drainage=string]
17 [basin=string] [stream=string] [half.basin=string] [vis‐
18 ual=string] [length.slope=string] [slope.steepness=string]
19 [--overwrite]
20 Flags:
22 -m Enable disk swap memory option: Operation is slow
23 -4 Allow only horizontal and vertical flow of water
25 --overwrite
27 Parameters:
29 elevation=string
30 Input map: elevation on which entire analysis is based
31 depression=string
33 Input map: locations of real depressions
34 flow=string
36 Input map: amount of overland flow per cell
37 disturbed.land=string
39 Input map or value: percent of disturbed land, for USLE
40 blocking=string
42 Input map: terrain blocking overland surface flow, for USLE
43 threshold=integer
45 Input value: minimum size of exterior watershed basin
46 max.slope.length=float
48 Input value: maximum length of surface flow, for USLE
49 accumulation=string
51 Output map: number of cells that drain through each cell
52 drainage=string
54 Output map: drainage direction
55 basin=string
57 Output map: unique label for each watershed basin
58 stream=string
60 Output map: stream segments
61 half.basin=string
63 Output map: each half-basin is given a unique value
64 visual=string
66 Output map: useful for visual display of results
67 length.slope=string
69 Output map: slope length and steepness (LS) factor for USLE
70 slope.steepness=string
72 Output map: slope steepness (S) factor for USLE
73
75 r.watershed generates a set of maps indicating: 1) the location of
76 watershed basins, and 2) the LS and S factors of the Revised Universal
77 Soil Loss Equation (RUSLE).
78
80 -m Without this flag set, the entire analysis is run in memory
81 maintained by the operating system. This can be limiting, but
82 is relatively fast. Setting the flag causes the program to man‐
83 age memory on disk which allows larger maps to be processes but
84 is considerably slower.
85 -4 Allow only horizontal and vertical flow of water. Stream and
87 slope lengths are approximately the same as outputs from default
88 surface flow (allows horizontal, vertical, and diagonal flow of
89 water). This flag will also make the drainage basins look more
90 homogeneous.
91 elevation
93 Input map: Elevation on which entire analysis is based.
94 depression
96 Input map: Map layer of actual depressions or sinkholes in the
97 landscape that are large enough to slow and store surface runoff
98 from a storm event. Any non-zero values indicate depressions.
99 flow Input map: amount of overland flow per cell. This map indicates
101 the amount of overland flow units that each cell will contribute
102 to the watershed basin model. Overland flow units represent the
103 amount of overland flow each cell contributes to surface flow.
104 If omitted, a value of one (1) is assumed. The algorithm is D8
105 flow accumulation.
106 disturbed.land
108 Raster map input layer or value containing the percent of dis‐
109 turbed land (i.e., croplands, and construction sites) where the
110 raster or input value of 17 equals 17%. If no map or value is
111 given, r.watershed assumes no disturbed land. This input is
112 used for the RUSLE calculations.
113 blocking
115 Input map: terrain that will block overland surface flow. Ter‐
116 rain that will block overland surface flow and restart the slope
117 length for the RUSLE. Any non-zero values indicate blocking
118 terrain.
119 threshold
121 The minimum size of an exterior watershed basin in cells, if no
122 flow map is input, or overland flow units when a flow map is
123 given. Warning: low threshold values will dramactically
124 increase run time and generate difficult too read basin and
125 half.basin results. This parameter also controls the level of
126 detail in the stream segments map.
127 max.slope.length
129 Input value indicating the maximum length of overland surface
130 flow in meters. If overland flow travels greater than the maxi‐
131 mum length, the program assumes the maximum length (it assumes
132 that landscape characteristics not discernible in the digital
133 elevation model exist that maximize the slope length). This
134 input is used for the RUSLE calculations and is a sensitive
135 parameter.
136 accumulation
138 Output map: The absolute value of each cell in this output map
139 layer is the amount of overland flow that traverses the cell.
140 This value will be the number of upland cells plus one if no
141 overland flow map is given. If the overland flow map is given,
142 the value will be in overland flow units. Negative numbers
143 indicate that those cells possibly have surface runoff from out‐
144 side of the current geographic region. Thus, any cells with neg‐
145 ative values cannot have their surface runoff and sedimentation
146 yields calculated accurately.
147 drainage
149 Output map: drainage direction. Provides the "aspect" for each
150 cell. Multiplying positive values by 45 will give the direction
151 in degrees that the surface runoff will travel from that cell.
152 The value -1 indicates that the cell is a depression area
153 (defined by the depression input map). Other negative values
154 indicate that surface runoff is leaving the boundaries of the
155 current geographic region. The absolute value of these negative
156 cells indicates the direction of flow.
157 basin Output map: Unique label for each watershed basin. Each basin
159 will be given a unique positive even integer. Areas along edges
160 may not be large enough to create an exterior watershed basin.
161 0 values indicate that the cell is not part of a complete water‐
162 shed basin in the current geographic region.
163 stream Output map: stream segments. Values correspond to the watershed
165 basin values.
166 half.basin
168 Output map: each half-basin is given a unique value. Watershed
169 basins are divided into left and right sides. The right-hand
170 side cell of the watershed basin (looking upstream) are given
171 even values corresponding to the values in basin. The left-hand
172 side cells of the watershed basin are given odd values which are
173 one less than the value of the watershed basin.
174 visual Output map: useful for visual display of results. Surface
176 runoff accumulation with the values modified to provide for easy
177 display. All negative accumulation values are changed to zero.
178 All positive values above the basin threshold are given the
179 value of the threshold parameter.
180 length.slope
182 Output map: slope length and steepness (LS) factor. Contains
183 the LS factor for the Revised Universal Soil Loss Equation.
184 Equations taken from Revised Universal Soil Loss Equation for
185 Western Rangelands (Weltz et al. 1987). Since the LS factor is
186 a small number, it is multiplied by 100 for the GRASS output
187 map.
188 slope.steepness
190 Output map: slope steepness (S) factor for RUSLE. Contains the
191 revised S factor for the Universal Soil Loss Equation. Equa‐
192 tions taken from article entitled Revised Slope Steepness Factor
193 for the Universal Soil Loss Equation (McCool et al. 1987).
194 Since the S factor is a small number (usually less than one), it
195 is multiplied by 100 for the GRASS output map layer.
196
198 r.watershed uses an algorithm designed to minimize the impact of DEM
199 data errors. This algorithm works slower than r.terraflow but provides
200 more accurate results in areas of low slope as well as DEMs constructed
201 with techniques that mistake canopy tops as the ground elevation. Kin‐
202 ner et al. (2005), for example, used SRTM and IFSAR DEMs to compare
203 r.watershed against r.terraflow results in Panama. r.terraflow was
204 unable to replicate stream locations in the larger valleys while
205 r.watershed performed much better. Thus, if forest canopy exists in
206 valleys, SRTM, IFSAR, and similar data products will cause major errors
207 in r.terraflow stream output. Under similar conditions, r.watershed
208 will generate better stream and half.basin results. If watershed
209 divides contain flat to low slope, r.watershed will generate better
210 basin results than r.terraflow. (r.terraflow uses the same type of
211 algorithm as ESRI's ArcGIS watershed software which fails under these
212 conditions.) Also, if watershed divides contain forest canopy mixed
213 with uncanopied areas using SRTM, IFSAR, and similar data products,
214 r.watershed will generate better basin results than r.terraflow.
215 There are two versions of this program: ram and seg. Which is version
217 is run depends on whether the -m flag is set.
218 The ram version uses virtual memory managed by the operating system to
219 store all the data structures and is faster than the seg version; seg
220 uses the GRASS segmentation library which manages data in disk files.
221 Thus seg uses much less system memory (RAM) allowing other processes to
222 operate on the same CPU, even when the current geographic region is
223 huge.
224 Due to memory requirements of both programs, it is quite easy to run
225 out of memory when working with huge map regions. If the ram version
226 runs out of memory and the resolution size of the current geographic
227 region cannot be increased, either more memory needs to be added to
228 the computer, or the swap space size needs to be increased. If seg
229 runs out of memory, additional disk space needs to be freed up for the
230 program to run.
231 Both versions use the AT least-cost search algorithm to determine the
233 flow of water over the landscape (see SEE ALSO section). The algorithm
234 produces results similar to those obtained when running r.cost and
235 r.drain on every cell on the map.
236 In many situations, the elevation data will be too finely detailed for
238 the amount of time or memory available. Running r.watershed may
239 require use of a coarser resolution. To make the results more closely
240 resemble the finer terrain data, create a map layer containing the low‐
241 est elevation values at the coarser resolution. This is done by: 1)
242 Setting the current geographic region equal to the elevation map layer
243 with g.region, and 2) Use the r.neighbors or r.resamp.stats command to
244 find the lowest value for an area equal in size to the desired resolu‐
245 tion. For example, if the resolution of the elevation data is 30
246 meters and the resolution of the geographic region for r.watershed will
247 be 90 meters: use the minimum function for a 3 by 3 neighborhood.
248 After changing to the resolution at which r.watershed will be run,
249 r.watershed should be run using the values from the neighborhood output
250 map layer that represents the minimum elevation within the region of
251 the coarser cell.
252 The minimum size of drainage basins, defined by the threshold parame‐
254 ter, is only relevant for those watersheds with a single stream having
255 at least the threshold of cells flowing into it. (These watersheds are
256 called exterior basins.) Interior drainage basins contain stream seg‐
257 ments below multiple tributaries. Interior drainage basins can be of
258 any size because the length of an interior stream segment is determined
259 by the distance between the tributaries flowing into it.
260 The r.watershed program does not require the user to have the current
262 geographic region filled with elevation values. Areas without eleva‐
263 tion data MUST be masked out, by creating a raster map (or raster
264 reclassification) named MASK. Areas masked out will be treated as if
265 they are off the edge of the region. MASKs will reduce the memory nec‐
266 essary to run the program. Masking out unimportant areas can signifi‐
267 cantly reduce processing time if the watersheds of interest occupy a
268 small percentage of the overall area.
269 Zero data values will be treated as elevation data (not no_data).
271
273 Convert r.watershed streams map output to a vector layer.
274 r.watershed elev=elevation.dem stream=rwater.stream
275 r.null map=rwater.stream setnull=0
276 r.to.vect -v in=rwater.stream out=rwater_stream
277 Set a nice color table for the accumulation map:
280 MAP=rwater.accum
281 r.watershed elev=elevation.dem accum=$MAP
282 eval `r.univar -g "$MAP"`
283 stddev_x_2=`echo $stddev | awk '{print $1 * 2}'`
284 stddev_div_2=`echo $stddev | awk '{print $1 / 2}'`
285 r.colors $MAP col=rules << EOF
286 0% red
287 -$stddev_x_2 red
288 -$stddev yellow
289 -$stddev_div_2 cyan
290 -$mean_of_abs blue
291 0 white
292 $mean_of_abs blue
293 $stddev_div_2 cyan
294 $stddev yellow
295 $stddev_x_2 red
296 100% red
297 EOF
298
301 Ehlschlaeger, C. (1989). Using the AT Search Algorithm to Develop
302 Hydrologic Models from Digital Elevation Data, Proceedings of Interna‐
303 tional Geographic Information Systems (IGIS) Symposium '89, pp 275-281
304 (Baltimore, MD, 18-19 March 1989).
305 URL: http://faculty.wiu.edu/CR-Ehlschlaeger2/older/IGIS/paper.html
306 Kinner D., H. Mitasova, R. Harmon, L. Toma, R., Stallard. (2005). GIS-
308 based Stream Network Analysis for The Chagres River Basin, Republic of
309 Panama. The Rio Chagres: A Multidisciplinary Profile of a Tropical
310 Watershed, R. Harmon (Ed.), Springer/Kluwer, p.83-95.
311 URL: http://skagit.meas.ncsu.edu/~helena/measwork/panama/panama.html
312 McCool et al. (1987). Revised Slope Steepness Factor for the Universal
314 Soil Loss Equation, Transactions of the ASAE Vol 30(5).
315 Weltz M. A., K. G. Renard, J. R. Simanton (1987). Revised Universal
317 Soil Loss Equation for Western Rangelands, U.S.A./Mexico Symposium of
318 Strategies for Classification and Management of Native Vegetation for
319 Food Production In Arid Zones (Tucson, AZ, 12-16 Oct. 1987).
320 g.region, r.cost, r.drain, r.flow, r.neighbors, r.param.scale,
322 r.resamp.interp, r.terraflow, r.topidx, r.water.outlet
323
325 Charles Ehlschlaeger, U.S. Army Construction Engineering Research Labo‐
326 ratory
327 Last changed: $Date: 2006/11/20 05:26:57 $
329 Full index
331GRASS 6.2.2 r.watershed(1)