NAME

KEYWORDS

SYNOPSIS

Flags:

-m

Enable disk swap memory option: Operation is slow

-4

Allow only horizontal and vertical flow of water

--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=string

Input map: locations of real depressions

flow=string

Input map: amount of overland flow per cell

disturbed.land=string

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

blocking=string

Input map: terrain blocking overland surface flow, 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

accumulation=string

Output map: number of cells that drain through each cell

drainage=string

Output map: drainage direction

basin=string

Output map: unique label for each watershed basin

stream=string

Output map: stream segments

half.basin=string

Output map: each half-basin is given a unique value

visual=string

Output map: useful for visual display of results

length.slope=string

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

slope.steepness=string

Output map: slope steepness (S) factor for USLE

DESCRIPTION

OPTIONS

-m

Without this flag set, the entire analysis is run in memory maintained by the operating system. This can be limiting, but is relatively fast. Setting the flag causes the program to manage memory on disk which allows larger maps to be processes but is considerably slower.

-4

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.

elevation

Input map: Elevation on which entire analysis is based.

depression

Input map: Map layer of actual depressions or sinkholes in the landscape that are large enough to slow and store surface runoff from a storm event. Any non-zero values indicate depressions.

flow

Input map: 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. The algorithm is D8 flow accumulation.

disturbed.land

Raster map input layer 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.

blocking

Input map: terrain that will block overland surface flow. Terrain that will block overland surface flow and restart the slope length for the RUSLE. Any non-zero values indicate blocking terrain.

threshold

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 too read basin and half.basin results. This parameter also controls the level of detail in the stream segments map.

max.slope.length

Input value indicating 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.

accumulation

Output map: The absolute value of each cell in this output map layer is the amount of overland flow that traverses the 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.

drainage

Output map: drainage direction. Provides the "aspect" for each cell. Multiplying positive values by 45 will give the direction in degrees that the surface runoff will travel from that cell. The value -1 indicates that the cell is a depression area (defined by the depression input map). Other 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.

basin

Output map: 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. 0 values indicate that the cell is not part of a complete watershed basin in the current geographic region.

stream

Output map: stream segments. Values correspond to the watershed basin values.

half.basin

Output map: 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.

visual

Output map: useful for visual display of results. Surface runoff accumulation with the values modified to provide for easy display. All negative accumulation values are changed to zero. All positive values above the basin threshold are given the value of the threshold parameter.

length.slope

Output map: slope length and steepness (LS) factor. Contains the LS factor for the Revised Universal Soil Loss Equation. Equations taken from Revised Universal Soil Loss Equation for Western Rangelands (Weltz et al. 1987). Since the LS factor is a small number, it is multiplied by 100 for the GRASS output map.

slope.steepness

Output map: slope steepness (S) factor for RUSLE. Contains the revised S factor for the Universal Soil Loss Equation. 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), it is multiplied by 100 for the GRASS output map layer.

NOTES

There are two versions of this program: ram and seg. Which is version is run depends on whether the -m flag is set.
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. Thus seg uses much less system memory (RAM) allowing other processes to operate on the same CPU, 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.

Both versions use the A^T least-cost search algorithm to determine the flow of water over the landscape (see SEE ALSO section). The algorithm produces results similar to those obtained when running r.cost and r.drain on every cell on the map.

In many situations, the elevation data will be too finely detailed for the amount of time or memory available. Running r.watershed may 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.

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.

The r.watershed program does not require the user to have the current geographic region filled with elevation values. Areas without elevation data MUST be masked out, by creating a raster map (or raster reclassification) named MASK. Areas masked out will be treated as if they are off the edge of the region. MASKs 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.

Zero data values will be treated as elevation data (not no_data).

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.

EXAMPLES

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

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 nice 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.

  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

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 of a Tropical Watershed, R. Harmon (Ed.), Springer/Kluwer, p.83-95.
URL: http://skagit.meas.ncsu.edu/~helena/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).

Weltz M. A., K. G. Renard, J. R. Simanton (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

AUTHOR

Last changed: $Date: 2008-02-23 10:20:25 -0800 (Sat, 23 Feb 2008) $

Main index - raster index - Full index

© 2003-2008 GRASS Development Team