Provided by: grass-doc_7.8.2-1build3_all bug

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]      [threshold=integer]
       [max_slope_length=float]   [accumulation=name]   [tci=name]   [spi=name]   [drainage=name]
       [basin=name]          [stream=name]          [half_basin=name]         [length_slope=name]
       [slope_steepness=name]      [convergence=integer]      [memory=integer]      [--overwrite]
       [--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 blocking 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=integer
           Maximum memory to be used with -m flag (in MB)
           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  default  surface  flow  (allows
       horizontal,  vertical, and diagonal flow of water).  This flag will also make the drainage
       basins look more homogeneous.

       When -a flag is specified the module will use positive flow accumulation 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 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.

       Raster flow map specifies 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.

       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  assumes  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 region.

       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 indicates 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 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), the GRASS output map is of type DCELL.

   AT least-cost search algorithm
       r.watershed  uses  an  AT least-cost search algorithm (see REFERENCES section) 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  results 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 results. 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.terraflow.  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, using slope towards neighbouring cells as  a  weighing  factor
       for  proportional  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 accumulation 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 regions 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 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.

   Basin threshold
       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.

   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 elevation 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 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
       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.mapcalc)  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 replacements:
       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 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 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. 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 Develop Hydrologic Models
               from Digital Elevation Data, Proceedings 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   Profile   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  biological   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 Processes Vol 5(1), p.59-79.
               DOI: 10.1002/hyp.3360050106

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

        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  Engineering Research
       Laboratory
       Faster sorting algorithm and MFD support: Markus Metz <markus.metz.giswork at gmail.com>
       Retention for flow distribution by Andreas Gericke (IGB Berlin)

SOURCE CODE

       Available at: r.watershed source code (history)

       Main index | Raster index | Topics index | Keywords index | Graphical index | Full index

       © 2003-2019 GRASS Development Team, GRASS GIS 7.8.2 Reference Manual