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]  [ddiissttuurrbbeedd..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]   [aaccccuummuullaa--
       ttiioonn==_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-inter-
       actively.  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-interactive version of
	cannot create this file.


       The  user can run the program non-interactively, by speci-
       fying input map names  on  the  command	line.	Parameter
       names may be specified by their full names, or by any ini-
       tial string that distinguish  them  from  other	parameter
       names.	In  's	case,  the first two letters of each name
       sufficiently distinguishes parameter names.  For  example,
       the two expressions 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 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 hori-
	      zontal, 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 per-
	      cent  of	disturbed land (i.e., croplands, and con-
	      struction 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.  Terrain 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 over-
	      land surface flow  in  meters.   If  overland  flow
	      travels  greater	than the maximum length, the pro-
	      gram 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 out-
	      put 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  sedi-
	      mentation yields calculated accurately.

       _d_r_a_i_n_a_g_e
	      Output   map:  drainage  direction.   Provides  the
	      "aspect" for each cell.  Multiplying positive  val-
	      ues  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
	      watershed 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  modi-
	      fied  to	provide  for  easy display.  All negative
	      accumulation values are changed to zero.	All posi-
	      tive 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.  Equations 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  sec-
	      tion).   Since the S factor is a small number (usu-
	      ally 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 memory.  If _r_a_m runs out of memory and
       the resolution size of the current geographic region  can-
       not 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 sec-
       tion).  The algorithm produces 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.  Run-
       ning  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 current 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 res-
       olution.   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 neighborhood.  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 represents 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 qual-
       ity 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)) SSyymmppoo--
       ssiiuumm ''8899, pp 275-281 (Baltimore, MD, 18-19 March 1989), by
       Charles Ehlschlaeger, U.S. Army	Construction  Engineering
       Research Laboratory.


       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, presented at the U.S.A./Mexico Sympo-
       sium of Strategies for Classification  and  Management  of
       Native  Vegetation for Food Production In Arid Zones (Tuc-
       son, 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," Interna-
       tional Geographic Information System 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_._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 Laboratory

       _L_a_s_t _c_h_a_n_g_e_d_: _$_D_a_t_e_: _2_0_0_2_/_0_1_/_2_5 _0_5_:_4_5_:_3_4 _$



GRASS 5.0					   r.watershed(1)
