r.watershed(1)		      Grass User's Manual		r.watershed(1)



NNAAMMEE
       rr..wwaatteerrsshheedd  - Watershed basin analysis program.
       _(_G_R_A_S_S _R_a_s_t_e_r _P_r_o_g_r_a_m_)

SSYYNNOOPPSSIISS
       rr..wwaatteerrsshheedd
       rr..wwaatteerrsshheedd hheellpp
       rr..wwaatteerrsshheedd  [  --mm44] eelleevvaattiioonn==_n_a_m_e [ddeepprreessssiioonn==_n_a_m_e] [[ffllooww==_n_a_m_e] [ddiiss--
       ttuurrbbeedd..llaanndd==_n_a_m_e_|_v_a_l_u_e]	      [bblloocckkiinngg==_n_a_m_e]	     [tthhrreesshhoolldd==_v_a_l_u_e]
       [mmaaxx..ssllooppee..lleennggtthh==_v_a_l_u_e]       [aaccccuummuullaattiioonn==_n_a_m_e]      [ddrraaiinnaaggee==_n_a_m_e]
       [bbaassiinn==_n_a_m_e]	[ssttrreeaamm==_n_a_m_e]	  [hhaallff..bbaassiinn==_n_a_m_e]	 [vviissuuaall==_n_a_m_e]
       [lleennggtthh..ssllooppee==_n_a_m_e] [ssllooppee..sstteeeeppnneessss==_n_a_m_e]

DDEESSCCRRIIPPTTIIOONN
       _r_._w_a_t_e_r_s_h_e_d  generates  a  set  of  maps indicating: 1) the location of
       watershed basins, and 2) the LS and S factors of the Revised  Universal
       Soil Loss Equation (RUSLE).


       _r_._w_a_t_e_r_s_h_e_d  can  be run either interactively or non-interactively.  If
       the user types


       rr..wwaatteerrsshheedd



       on the command line without program arguments, the program will	prompt
       the user with a verbose description of the input maps.  The interactive
       version of
	can prepare inputs to lumped-parameter	hydrologic  models.   After  a
       verbose	interactive  session,  will query the user for a number of map
       layers.	Each map layer's values will be tabulated by  watershed  basin
       and sent to an output file.  This output file is organized to ease data
       entry into a lumped-parameter hydrologic model program.	The non-inter-
       active version of
	cannot create this file.


       The user can run the program non-interactively, by specifying input map
       names on the command line.  Parameter names may be specified  by  their
       full  names,  or by any initial string that distinguish them from other
       parameter names.  In 's case, the first two letters of each name suffi-
       ciently	distinguishes  parameter  names.  For example, the two expres-
       sions below are equivalent inputs to :


	eell==elev.map tthh==100 sstt==stream.map bbaa==basin.map


	eelleevvaattiioonn==elev.map tthhrreesshhoolldd==100 ssttrreeaamm==stream.map bbaassiinn==basin.map


OOPPTTIIOONNSS
       _-_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 man-
	      age  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.

       _e_l_e_v_a_t_i_o_n
	      Input map: Elevation on which entire analysis is based.

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

       _f_l_o_w   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
	      flowaccumulation.

       _d_i_s_t_u_r_b_e_d_._l_a_n_d
	      Raster  map  input layer or value containing the percent of dis-
	      turbed land (i.e., croplands, and construction sites) where  the
	      raster  or  input value of 17 equals 17%.  If no map or value is
	      given, assumes no disturbed land.  This input is	used  for  the
	      RUSLE calculations.

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

       _t_h_r_e_s_h_o_l_d
	      The minimum size of an exterior watershed  basin	in  cells,  or
	      overland flow units.

       _m_a_x_._s_l_o_p_e_._l_e_n_g_t_h
	      Input  value  indicating	the maximum length of overland surface
	      flow in meters.  If overland flow travels greater than the maxi-
	      mum  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.

       _a_c_c_u_m_u_l_a_t_i_o_n
	      Output  map:  number of cells that drain through each cell.  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.

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

       _b_a_s_i_n  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 water-
	      shed basin in the current geographic region.

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

       _h_a_l_f_._b_a_s_i_n
	      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 watershed basin values.  The
	      left-hand side cells of the watershed basin are given odd values
	      which are one less than the value of the watershed basin.

       _v_i_s_u_a_l 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 basin threshold.

       _l_e_n_g_t_h_._s_l_o_p_e
	      Output  map:  slope  length and steepness (LS) factor.  Contains
	      the LS factor for the  Revised  Universal  Soil  Loss  Equation.
	      Equations  taken	from  _R_e_v_i_s_e_d _U_n_i_v_e_r_s_a_l _S_o_i_l _L_o_s_s _E_q_u_a_t_i_o_n _f_o_r
	      _W_e_s_t_e_r_n _R_a_n_g_e_l_a_n_d_s (see SEE ALSO section).  Since the LS	factor
	      is  a small number, it is multiplied by 100 for the GRASS output
	      map.

       _s_l_o_p_e_._s_t_e_e_p_n_e_s_s
	      Output map: slope steepness (S) factor for RUSLE.  Contains  the
	      revised  S  factor  for the Universal Soil Loss Equation.  Equa-
	      tions taken from article enTITLEd _R_e_v_i_s_e_d _S_l_o_p_e _S_t_e_e_p_n_e_s_s _F_a_c_t_o_r
	      _f_o_r  _t_h_e	_U_n_i_v_e_r_s_a_l  _S_o_i_l  _L_o_s_s _E_q_u_a_t_i_o_n (see SEE ALSO section).
	      Since the S factor is a small number (usually less than one), it
	      is multiplied by 100 for the GRASS output map layer.


NNOOTTEESS
       There  are  two versions of this program: _r_a_m and _s_e_g.  Which is run by
       depends on whether the _-_m flag is set.  _r_a_m uses virtual memory managed
       by  the operating system to store all the data structures and is faster
       than _s_e_g;  _s_e_g uses the GRASS segment library  which  manages  data  in
       disk  files.   _s_e_g  allows  other processes to operate on the same CPU,
       even when the  current  geographic  region  is  huge.   Due  to	memory
       requirements of both programs, it will be quite easy to run out of mem-
       ory.  If _r_a_m 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  _s_e_g	runs out of memory, additional disk space needs to be freed up
       for the program to run.


       _s_e_g uses the AT least-cost search algorithm to determine  the  flow  of
       water  over  the  landscape (see SEE ALSO section).  The algorithm pro-
       duces results similar to those obtained when running _r_._c_o_s_t and _r_._d_r_a_i_n
       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  will 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 cur-
       rent geographic region equal to the elevation map layer, and  2)  Using
       the  _n_e_i_g_h_b_o_r_h_o_o_d 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  will be 90 meters:	use the minimum function for a 3 by  3	neigh-
       borhood.  After going to the resolution at which  will be run,
	will be taking values from the _n_e_i_g_h_b_o_r_h_o_o_d output map layer that rep-
       resents the minimum elevation within the region of the coarser cell.


       The minimum size of drainage basins is only relevant for  those	basins
       that  have  no  basins  draining  into  them  (they are called exterior
       basins).  An interior drainage basin has the area that  flows  into  an
       interior  stream segment.  Thus, interior drainage basins can be of any
       size.


       The  program does not require the user to have the  current  geographic
       region filled with elevation values.  Areas without elevation data MUST
       be masked out using the _r_._m_a_s_k  command.   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
       occupies a small percentage of the overall area.


       Zero data values will be treated as elevation data (not	no_data).   If
       there  are  zero  data along the edges of the current region, that edge
       will not be able to propagate negative accumulation data to the rest of
       the  map.   This  might	give users a false sense of security about the
       quality of their data.  If there are incomplete data in	the  elevation
       map layer, users should mask out those areas.



SSEEEE AALLSSOO
       The  AT	least-cost search algorithm used by  is described in _U_s_i_n_g _t_h_e
       _A_T _S_e_a_r_c_h _A_l_g_o_r_i_t_h_m _t_o _D_e_v_e_l_o_p _H_y_d_r_o_l_o_g_i_c _M_o_d_e_l_s _f_r_o_m _D_i_g_i_t_a_l _E_l_e_v_a_t_i_o_n
       _D_a_t_a,  in  PPrroocceeeeddiinnggss  ooff IInntteerrnnaattiioonnaall GGeeooggrraapphhiicc IInnffoorrmmaattiioonn SSyysstteemmss
       ((IIGGIISS)) SSyymmppoossiiuumm ''8899, pp 275-281 (Baltimore, MD, 18-19 March 1989),  by
       Charles Ehlschlaeger, U.S. Army Construction Engineering Research Labo-
       ratory.


       Length slope and steepness (_l_e_n_g_t_h_._s_l_o_p_e) factor equations  were  taken
       from  _R_e_v_i_s_e_d _U_n_i_v_e_r_s_a_l _S_o_i_l _L_o_s_s _E_q_u_a_t_i_o_n _f_o_r _W_e_s_t_e_r_n _R_a_n_g_e_l_a_n_d_s, pre-
       sented at the 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), by M. A. Weltz, K. G. Renard, and	J.  R.
       Simanton.


       The slope steepness (_s_l_o_p_e_._s_t_e_e_p_n_e_s_s) factor contains the revised slope
       steepness factor for the Universal Soil Loss Equation.  Equations  were
       taken from article enTITLEd _R_e_v_i_s_e_d _S_l_o_p_e _S_t_e_e_p_n_e_s_s _F_a_c_t_o_r _f_o_r _t_h_e _U_n_i_-
       _v_e_r_s_a_l _S_o_i_l _L_o_s_s _E_q_u_a_t_i_o_n, in TTrraannssaaccttiioonnss  ooff  tthhee  AASSAAEE  (Vol	30(5),
       Sept-Oct 1987), by McCool et al.


       Reference:  "Using the AT Search Algorithm to Develop Hydrologic Models
       from Digital Elevation Data," International Geographic Information Sys-
       tem Symposium, Baltimore MD, 1989

       http://geography.hunter.cuny.edu/~chuck/IGIS/paper.html


       _r_._c_o_s_t_,	_r_._d_r_a_i_n_,  _r_._f_l_o_w_,  _r_._f_l_o_w_m_d_,  _r_._m_a_s_k_, _r_._p_a_r_a_m_._s_c_a_l_e_, _r_._t_o_p_i_d_x_,
       _r_._w_a_t_e_r_._o_u_t_l_e_t


AAUUTTHHOORR
       Charles Ehlschlaeger, U.S. Army Construction Engineering Research Labo-
       ratory

       _L_a_s_t _c_h_a_n_g_e_d_: _$_D_a_t_e_: _2_0_0_3_/_0_2_/_0_9 _1_2_:_0_7_:_2_3 _$



GRASS 5.0							r.watershed(1)
