GRASS GIS manual: r.watershed (2024)

Note: A new GRASS GIS stable version has been released: GRASS GIS 7. Go directly to the new manual page here

NAME

KEYWORDS

SYNOPSIS

Flags:

-f

Enable MFD flow (default is SFD (D8))

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

--overwrite

Allow output files to overwrite existing files

--verbose

Verbose module output

--quiet

Quiet module output

Parameters:

elevation=name

Input map: elevation on which entire analysis is based

depression=name

Input map: locations of real depressions

flow=name

Input map: amount of overland flow per cell

disturbed.land=string

Input map or value: percent of disturbed land, for USLE

blocking=name

Name of input raster map blocking overland surface flow

Input map: terrain blocking overland surface flow, for USLE

accumulation=name

Name for output accumulation raster map

Output map: number of cells that drain through each cell

drainage=name

Output map: drainage direction

basin=name

Output map: basins raster map

stream=name

Output map: stream segments

half.basin=name

Output map: half basins raster map

visual=name

Output map: useful for visual display of results

length.slope=name

Name for output slope length raster map

Output map: slope length and steepness (LS) factor for USLE

slope.steepness=name

Name for output slope steepness raster map

Output map: Slope steepness (S) factor for USLE

threshold=integer

Input value: minimum size of exterior watershed basin

max.slope.length=float

Input value: maximum length of surface flow, 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

OPTIONS

-m

Without this flag set, the entire analysis is run in memorymaintained by the operating system. This can be limiting, but isvery fast. Setting the flag causes the program to manage memoryon disk which allows larger maps to be processed but is considerablyslower.

-f

Use multiple flow direction (MFD) instead of single flow direction (SFD, D8).SFD is enabled by default.

-4

Allow only horizontal and vertical flow of water.Stream and slope lengths are approximately the same as outputs from defaultsurface flow (allows horizontal, vertical, and diagonal flow of water).This flag will also make the drainage basins look more hom*ogeneous.

-a

Use positive flow accumulation even for likely underestimates. When thisflag is not set, cells with a flow accumulation value that is likely to bean underestimate are converted to the negative. See below for a detaileddescription of flow accumulation output.

memory

Maximum amount of memory in MB to be used with -m set. More memory speeds up the processes.

convergence

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.

elevation

Input map: Elevation 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.

depression

Input map: Map layer of actual depressions or sinkholes in thelandscape 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.

flow

Input map: amount of overland flow per cell. This map indicates theamount of overland flow units that each cell will contribute to thewatershed basin model. Overland flow units represent the amount ofoverland flow each cell contributes to surface flow. If omitted, avalue of one (1) is assumed.

disturbed.land

Raster map input layer or value containing the percent of disturbedland (i.e., croplands, and construction sites) where the raster or inputvalue of 17 equals 17%. If no map or value is given, r.watershedassumes no disturbed land. This input is used for the RUSLE calculations.

blocking

Input map: terrain that will block overland surface flow. Terrainthat will block overland surface flow and restart the slope lengthfor the RUSLE. All cells that are not NULL and not zero indicate blocking terrain.

threshold

The minimum size of an exterior watershed basin in cells, if no flowmap is input, or overland flow units when a flow map is given.Warning: low threshold values will dramactically increase run time andgenerate difficult to read basin and half_basin results.This parameter also controls the level of detail in the streamsegments map.

max.slope.length

Input value indicating the maximum length of overland surface flowin meters. If overland flow travels greater than the maximum length,the program assumes the maximum length (it assumes that landscapecharacteristics not discernible in the digital elevation model existthat maximize the slope length). This input is used for the RUSLE calculationsand is a sensitive parameter.

accumulation

Output map: The absolute value of each cell in this output map layer isthe amount of overland flow that traverses the cell. This value will bethe number of upland cells plus one if no overland flow map is given. Ifthe overland flow map is given, the value will be in overland flow units.Negative numbers indicate that those cells possibly have surface runofffrom outside of the current geographic region. Thus, any cells withnegative values cannot have their surface runoff and sedimentation yieldscalculated accurately.

drainage

Output map: drainage direction. Provides the "aspect" for eachcell measured CCW from East. 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 thatsurface runoff is leaving the boundaries of the current geographicregion. The absolute value of these negative cells indicates thedirection of flow.

basin

Output map: Unique label for each watershed basin. Each basin willbe given a unique positive even integer. Areas along edges may notbe large enough to create an exterior watershed basin. 0 valuesindicate that the cell is not part of a complete watershed basinin the current geographic region.

stream

Output map: stream segments. Values correspond to the watershedbasin values. Can be vectorized after thinning (r.thin) with r.to.vect.

half.basin

Output map: each half-basin is given a unique value. Watershedbasins are divided into left and right sides. The right-hand sidecell of the watershed basin (looking upstream) are given even valuescorresponding to the values in basin. The left-hand sidecells of the watershed basin are given odd values which are one lessthan the value of the watershed basin.

visual

DEPRECATED A colortable is generated by default for theaccumulation output for easy visual inspection.

length.slope

Output map: 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), it is multiplied by 100.

slope.steepness

Output map: slope steepness (S) factor for the Universal SoilLoss Equation (RUSLE). Equations taken from article entitledRevised Slope Steepness Factor for the Universal SoilLoss Equation (McCool et al. 1987). Since the S factor is a small number (usually less than one), it is multiplied by 100.

NOTES

A^T least-cost search algorithm

Multiple flow direction (MFD)

In-memory mode and disk swap mode

Large regions with many cells

Basin threshold

MASK and no data

The r.watershed program does not require the user to have thecurrent geographic region filled with elevation values. Areas withoutelevation data (masked or NULL cells) are ignored. It is NOT necessary tocreate 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

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.

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.

EXAMPLES

Convert r.watershed streams map output to a vector layer.

If you want a detailed stream network, set the threshold optionsmall to create lots of catchment basins, as only one stream ispresented per catchment. The r.to.vect -v flag preserves thecatchment 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 convertit to a vector output map. The accumulation cut-off, and therefore fractaldimension, is arbitrary; in this example we use the map's mean number ofupstream 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 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 feature=line v.db.dropcol 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 feature=area v.db.dropcol map=rwater_basins column=label v.db.renamecol map=rwater_basins column=value,catchment

Display output in a nice way

 r.shaded.relief map=elevation.dem d.shadedmap rel=elevation.dem.shade drape=rwater.basin bright=40 d.vect rwater_course color=orange

REFERENCES

Holmgren, P. (1994). Multiple flow direction algorithms for runoff modelling in grid based elevation models: An empirical evaluation.Hydrological Processes Vol 8(4), p.327-334.
DOI: 10.1002/hyp.3360080405

Kinner D., H. Mitasova, R. Harmon, L. Toma, R., Stallard. (2005).GIS-based Stream Network Analysis for The Chagres River Basin,Republic of Panama. The Rio Chagres: A Multidisciplinary Profile ofa 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 UniversalSoil Loss Equation, Transactions of the ASAE Vol 30(5).

Weltz M. A., K. G. Renard, J. R. Simanton (1987). Revised Universal SoilLoss Equation for Western Rangelands, U.S.A./Mexico Symposium ofStrategies for Classification and Management of Native Vegetation forFood Production In Arid Zones (Tucson, AZ, 12-16 Oct. 1987).

SEE ALSO

AUTHORS

Last changed: $Date: 2014-03-15 07:28:47 -0700 (Sat, 15 Mar 2014) $

Main index - raster index - Full index

© 2003-2016 GRASS Development Team