r.out.agnps(1)	       Grass User's Manual	   r.out.agnps(1)



NNAAMMEE
       vviiss__ttooooll  -  AGNPS-GRASS  1.1  non-point  source hydrology
       model output interface.

       _(_G_R_A_S_S _R_a_s_t_e_r _P_r_o_g_r_a_m_)

GGRRAASSSS VVEERRSSIIOONN
       4.x

SSYYNNOOPPSSIISS
       vis_tool

DDEESSCCRRIIPPTTIIOONN
       Current NPS  models  including  AGNPS  have  very  limited
       graphics  capability  for  visualizing  and  analyzing the
       model output.  A distributed parameter model should assist
       in  pinpointing	the critical areas where one needs to pay
       attention for  controlling  NPS	pollution.   Even  though
       AGNPS  gives detailed output, users often can not make use
       of it, due to lack of proper analyzation and visualization
       tools.	Graphical  displays of the results have proven to
       be a more effective and efficient way of interpreting  the
       results	and  in  making  decisions  than scanning through
       pages and pages of numerical output in the form of tables.
       The  following  sections discuss the visualization tool in
       detail.

   AAGGNNPPSS OOuuttppuutt PPaarraammeetteerrss
       Various output options are available with the AGNPS model.
       Primary	 output   given  for  watersheds  being  analyzed
       includes watershed area, cell size,  storm  precipitation,
       rainfall erosivity (EI), estimates of runoff  volume, peak
       flow rate at the watershed outlet, area-weighted  erosion,
       both  upland and channel.  Also given are estimates of the
       sediment delivery ratio, sediment enrichment  ratio,  mean
       sediment  concentration, and total sediment yield for each
       of five sediment particle size classes.	Also available is
       a  nutrient  analysis, which include N, P and COD mass per
       unit area for both soluble and  sediment  adsorbed  nutri-
       ents,  and  N,  P  and  COD  concentrations in the runoff.
       Table 1 lists a summary of output parameters that  can  be
       obtained for each cell or all cells if desired.

   TTaabbllee  11::  AAGGNNPPSS  oouuttppuutt ppaarraammeetteerrss aatt tthhee wwaatteerrsshheedd oouuttlleett oorr
       aannyy cceellll
       Hydrology output * Runoff volume (inches)  *  Peak  runoff
       rate  (cubic  feet/second)  * Fraction of runoff generated
       within the cell

       Sediment output * Sediment yield (tons) * Sediment concen-
       tration	(ppm)  *  Sediment  particle  size distribution *
       Upland erosion (tons/acre) * Amount of  deposition  (%)	*
       Sediment  generated  within  the  cell (tons) * Enrichment
       ratios by particle size * Delivery ratios by particle size

       Chemical   output!Nitrogen   *  Sediment  associated  mass
       (pounds/acre) * Concentration of soluble material (ppm)	*
       Mass of soluble material (pounds/acre)

       Phosphorus * Sediment associated mass (pounds/acre) * Con-
       centration of soluble material (ppm)  *	Mass  of  soluble
       material (pounds/acre)

       Chemical  oxygen demand (COD) * Concentration (ppm) * Mass
       (pounds/acre)

       Initially the visualization interface  generates  17  maps
       (Table  2)  from  the  ASCII output files of an AGNPS run.
       The generated maps can be saved for future  evaluation  of
       output.	 All maps are generated using the reclass princi-
       ple of the GRASS GIS tool, thereby minimum disk	space  is
       required.   The	map  from  which  all  output  maps  were
       reclassed (cell number map, filename_cell_num, where file-
       name  refers  to the AGNPS ASCII input/output file without
       its extension) should not be removed.

   TTaabbllee 22:: LLiisstt ooff AAGGNNPPSS oouuttppuutt mmaappss ccrreeaatteedd uussiinngg VViissuuaalliizzaattiioonn
       ttooooll
       Cell number map


       Hydrology  output  *  Runoff  generated	map * Runoff from
       upstream map * Runoff to downstream map

       Sediment output * Erosion map * Deposition map *  Sediment
       leaving the cell map

       Chemical  output * Nitrogen associated with Sediment (gen-
       erated) map * Nitrogen associated with Sediment	(leaving)
       map  *  Nitrogen  associated with Runoff (generated) map *
       Nitrogen associated with Runoff (leaving) map * Phosphorus
       associated  with  Sediment  (generated)	map  * Phosphorus
       associated with Sediment (leaving) map * Phosphorus  asso-
       ciated with Runoff (generated) map * Phosphorus associated
       with Runoff (leaving) map *  COD  associated  with  Runoff
       (generated) map * COD associated with Runoff (leaving) map

       Resize the graphics monitor to fit the full screen of  the
       workstation  and use the _d_._m_o_n program to select the moni-
       tor.  The GRASS shelltool window should be  at  the  right
       hand side bottom of the screen.	Execute the _v_i_s___t_o_o_l pro-
       gram from the shelltool window where GRASS is running.	A
       Visualization Tool Input menu will appear on the shelltool
       window requesting the following data/information from  the
       user:

   PPaarraammeetteerrss::
       WWaatteerrsshheedd MMaapp nnaammee
	      Enter  the  name of the watershed boundary map con-
	      taining cell values greater than	zero  and  zero's
	      for cells outside the watershed boundary.

       CCeellll SSiizzee
	      The  length  of  the  side  of a cell in meters for
	      which the model was run is entered.

       AAssppeecctt MMaapp nnaammee
	      Enter the name of the aspect map for the watershed.
	      It should have been created for the same resolution
	      as the cell size above.

       AASSCCIIII AAGGNNPPSS ffiillee nnaammee wwiitthhoouutt iittss eexxtteennssiioonn
	      Enter the ASCII AGNPS file name without its  exten-
	      sion  since the program takes the default extension
	      of .dat and .nps for input and output of the model,
	      respectively.  These files should be in the current
	      working directory, else give the full path with the
	      file name.

       Then hit the Esc key to continue.

NNOOTTEESS
       Always  look  for  a  message  at  the bottom of the ASCII
       screen for continuing the execution, if there is  no  mes-
       sage  then hit Enter after answering the question else hit
       Esc to continue.


       In the following text, each output screen of  the  visual-
       ization	tool  is discussed. The visualization tool splits
       the screen into various screens to display the  output  of
       the  model.   The number of windows created depends on the
       type of output displayed.  The  tool  always  reserves  an
       ASCII  terminal	(non  graphics)  for interacting with the
       user.   The  first  screen  (Figure  1)	provides  various
       options	including  a  watershed summary (no graphics) and
       spatially distributed soil  loss,  nutrients,  runoff  and
       feedlot movement (graphics) output of a watershed.

   FFiigguurree 11:: IInniittiiaall ssccrreeeenn ooff tthhee VViissuuaalliizzaattiioonn ttooooll
       Visualization Tool Main Menu

       Output Display Options
       1. Watershed Summary including sediment (no graphics)
       2. Soil Loss (graphics)
       3. Nutrients Movement (graphics)
       4. Feedlot Analysis (graphics)
       5. Runoff Movement (graphics)
       6. Analyze Different Scenarios
       7. Save Output Maps
       8. Exit to GRASS (to come back type 'return')
       9. Quit
       Enter the choice (1-9):


       _O_p_t_i_o_n  _1  (Figure  1)  displays the watershed summary for
       soil loss, runoff and nutrient movement at  the	watershed
       outlet.	This output is displayed in the non-graphics win-
       dow. The watershed summary can be accessed from	any  part
       of  the	visualization  tool, providing an opportunity for
       decision makers/users to compare the detailed cell  output
       with the watershed outlet output for making decisions.


       _O_p_t_i_o_n_s	_2_-_5 (Figure 1) move to the next screen (Figure 2)
       where the appropriate output option  maps  are  displayed.
       This  screen is divided into numerous windows depending on
       the output option chosen. The screen is divided	in  half,
       having  a series of top row windows and bottom row windows
       with an ASCII terminal. The top row  windows  display  the
       output maps (Table 2). A scale for each of the output maps
       is displayed showing the color  and  the  numerical  value
       associated  with  it.  The  color of the output maps range
       from green-yellow-red, with increasing intensity  of  out-
       put.  The right hand top corner window displays the water-
       shed map with cell numbers by laying a grid on top  of  it
       for  reference. Below this cell number map, the aspect map
       of the watershed with arrows pointing in the  flow  direc-
       tions is displayed. In the bottom row, two windows display
       the output and input statistics for  any  cell.	The  left
       window  shows  cell  inputs. The output window shows a bar
       chart and key features of the output option statistics for
       the  same  cell.  The default cell statistics displayed in
       the bottom row windows are the statistics for  the  outlet
       cell  of  the  watershed. The tool provides error checking
       and also explains what to do at each step.


       In the next section, options 6-9  of  Figure  1	are  dis-
       cussed.


       _A_n_a_l_y_z_e	_D_i_f_f_e_r_e_n_t  _S_c_e_n_a_r_i_o_s: This option allows the user
       to visualize and analyze a different  simulation  for  the
       same  resolution of the original run. The user is asked to
       enter the name of the ASCII AGNPS file  name  without  its
       extension. The AGNPS run that was started with the visual-
       ization tool is called the 'current'  and  the  simulation
       that  was  selected  using  this  option  is  referred  as
       'selected' hereafter in this  documentation.  The  program
       checks  the  resolutions  between  the  'current'  and the
       'selected' runs and checks for the same file  names.  Then
       the  program creates the 17 output maps (Table 2) and dis-
       plays the 'current' and the 'selected' output maps on  the
       screen  in  the top row windows. The default output is the
       sediment movement maps. Bottom  row  windows  display  the
       output histograms of the 'current' and the 'selected' sim-
       ulations. The left bottom row window  corresponds  to  the
       'current'  input/output	window	and  the right bottom row
       window corresponds to the 'selected' input/output.


       Under this option the user has the same options (Figure 2)
       discussed  earlier  in this document. In addition to this,
       the user can alter the output visualization/analyzation to
       other  model  outputs such as sediment, nutrients, feedlot
       or runoff movement. While using options 2  and  3  (Figure
       2),  the user is asked to select either input or output to
       view in the bottom row windows.


       For options 5 and 8 (Figure  2),  the  user  is	asked  to
       select  either  the 'current' or the 'selected' simulation
       results to view in a window.  This option is  one  of  the
       strongest features of the visualization tool for analyzing
       different scenarios simultaneously.


       _S_a_v_e _O_u_t_p_u_t _M_a_p_s: This option allows the user to save  the
       maps  created  using  the visualization tool. The user can
       save all or only those outputs of interest, which  include
       sediment, N, P, COD, and runoff. The program asks the user
       to enter a map name for saving the output maps.	The  pro-
       gram  attaches  proper extensions depending on the type of
       outputs (Appendix 1).  Please refer to the appendix 1  for
       the  extensions	of  different map names. It also contains
       reserved map names that should not exist  in  the  current
       mapset. Do not remove the filename_cell_num map, since all
       output  maps  created  in  the  visualization   tool   are
       reclassed from the created cell number map.


       _E_x_i_t  _t_o  _G_R_A_S_S	(to come back type 'return'): This option
       allows the user to exit to the GRASS temporarily  to  per-
       form  normal  operations under the GRASS GIS tool. To come
       back to the same menu  in  the  visualization  tool,  type
       return and hit enter.


       _Q_u_i_t: This option takes the user back the GRASS prompt and
       exits from the visualization tool. The output maps created
       will  be  removed  from	the  current mapset, but will not
       affect those maps that are saved  using	the  _S_a_v_e  _O_u_t_p_u_t
       _M_a_p_s option. If you plan to use output maps at some future
       time, be sure to save them.

   FFiigguurree 22:: GGeenneerriicc ooppttiioonnss ssccrreeeenn ooff tthhee vviissuuaalliizzaattiioonn ttooooll ffoorr
       ssppaattiiaallllyy ddiissttrriibbuutteedd oouuttppuutt
       Cell input and output Display Options

       1. Zoom
       2. View a Cell
       3. View an area output
       4. Toggle between flow direction map/viewing area
       5. Show the watershed summary output
       6. Displayed range of output maps
       7. Display user's choice map
       8. Draw Cumulative and Frequency Distribution Stats
       9. Restore the initial screen
       10. Exit to GRASS (to come back type 'return')
       11. Quit
       Enter the choice (1-11):


       Each  of  the  options in Figure 2 is discussed below: Its
       usage and how this assists users  or  decision  makers  is
       described.  These options can be used alone or in combina-
       tion with other options.


       _1_. _Z_o_o_m_: Allows users to zoom in or zoom out of	any  sec-
       tion  of  the  watershed  by choosing one of the displayed
       windows.  Once the zoom operation is performed,	the  tool
       automatically  adjusts  or  redisplays all the maps in the
       top row windows to the same area, enabling users to take a
       closer look at an area of interest. This option is partic-
       ularly helpful on large watersheds.  Once the Zoom  option
       is  selected,  the  tool  requests for a window to perform
       zoom operations.  The user has to use the left  mouse  key
       to  click  on one of the top row windows and then click on
       the right mouse key to  complete  the  selection  process.
       Then the zoom function asks the user to use the left mouse
       to click on a place to define the  area	in  the  selected
       window,	and  then  drag the mouse to the desired location
       and click on the right mouse key to complete the zoom pro-
       cess.  Always  follow  the  instructions  displayed on the
       ASCII terminal.	Failing to do so can cause the program to
       stop. Similarly, the unzoom operation can be performed.


       _2_.  _V_i_e_w  _a  _c_e_l_l_:  This option allows the user to enter a
       cell number of interest to display the statistics of  that
       cell's  inputs  and  outputs in the bottom row of windows.
       The displayed bar chart depends on the type of option cho-
       sen in the initial screen (Figure 1).  The cell number can
       be either entered directly using the keyboard in the ASCII
       terminal  or  the mouse can be used to point out a cell on
       the graphics monitor using the left mouse key after choos-
       ing one of the top row windows.	The window selection pro-
       cess is detailed in the Zoom  section.	This  feature  is
       helpful	to  visualize  characteristics of both inputs and
       outputs of a critical area.


       _3_. _V_i_e_w _a_n _a_r_e_a _o_u_t_p_u_t_: This option  allows  the  user  to
       select  an  area  from  one  of	the  top  row windows and
       displays the average input and output statistics for  that
       area  in  the  bottom row windows.  Here also, the user is
       asked to select a window from the top  row  windows  using
       the selection procedure explained earlier.  Then using the
       left mouse key, the user selects a corner of  the  desired
       area  and  drags the mouse to build a box. Click the right
       mouse key to complete the process.   This  information  is
       helpful	to study the statistics of the critical areas and
       its neighbors.  Using  this  option,  one  could  estimate
       average inputs and outputs for a field which should assist
       in making further decisions.


       _4_. _T_o_g_g_l_e _b_e_t_w_e_e_n _f_l_o_w _d_i_r_e_c_t_i_o_n _m_a_p  _a_n_d  _v_i_e_w_i_n_g  _w_i_n_d_o_w
       _l_o_c_a_t_i_o_n_:  This	feature is helpful when users use Zoom to
       view any particular section of  the  watershed.	 After	a
       couple  of zoom operations, users may loose track of which
       part of the watershed is displayed.  This  option  toggles
       between the flow direction map and the whole watershed map
       showing a box around the current viewing area.


       _5_. _S_h_o_w _t_h_e _w_a_t_e_r_s_h_e_d _s_u_m_m_a_r_y _o_u_t_p_u_t_: The summary  at  the
       outlet  of  the watershed for all the outputs is displayed
       in the ASCII (non graphics) terminal.  This option is use-
       ful to correlate cell outputs with those of watershed out-
       puts to make decisions.


       _6_. _D_i_s_p_l_a_y _r_a_n_g_e_s _o_f _o_u_t_p_u_t _m_a_p_s_: This option allows users
       to  visualize  output maps (Table 2) for a specified range
       between maximum and minimum values of the  output  (Figure
       1) chosen.  This helps users locate critical areas easily.
       For example, users can use this option to display problem-
       atic  areas that are exceeding the soil tolerance limit (T
       factor).  Options are available to save the displayed maps
       for  later reference, compare various scenarios or overlay
       one map on another in order to make decisions.


       _7_. _D_i_s_p_l_a_y _u_s_e_r_'_s _c_h_o_i_c_e _m_a_p_: Users have an option to dis-
       play a cell map, overlay a map on another map or display a
       vector map.  The chosen map can be displayed on one of the
       existing  windows  or users have an option to create a new
       window anywhere in the graphics	monitor  to  display  the
       map.   Further,	the  map chosen for display can be one of
       the AGNPS output maps (Table 2) generated from  the  AGNPS
       output  files or one of the existing maps in the database.
       From of the users/decision  makers  point  of  view,  this
       option  is  helpful  to reach conclusions about management
       strategies.  For example, by overlaying a  field  boundary
       or  property  boundary  on  an  erosion map, fields within
       critical limits can be located.	Combinations  of  various
       outputs	can  be  viewed  simultaneously  on  the designed
       graphic windows.  On selection of this option, the user is
       prompted for the map to be displayed.  If the user selects
       to display the map in one of the  existing  windows,  then
       the  selection  of  the window operation is performed fol-
       lowed by the selection of the type of display.  This could
       be  to display a cell map, overlay a map on another map or
       display a vector map.  Maps are listed for selection.   If
       the  user  selected  the  option to create a new window to
       display a map, then the program	requests  a  location  to
       start  the  window.   Using  the  left mouse key, drag the
       mouse to create a box of desired size and click the  right
       mouse key to end the process.


       _8_.  _D_r_a_w _C_u_m_u_l_a_t_i_v_e _a_n_d _F_r_e_q_u_e_n_c_y _D_i_s_t_r_i_b_u_t_i_o_n _S_t_a_t_i_s_t_i_c_s_:
       This option allows the user  to	view  the  percentage  of
       cumulative  and frequency distribution area curves for any
       of the output maps (Table 2) or selective input	variables
       for  either  user specified ranges of intervals/classes or
       for 10 equal ranges of intervals/classes between the maxi-
       mum  and minimum of the selected variable.  This option is
       helpful to see how that particular variable is distributed
       both  cumulatively  and	the number of occurrences in that
       interval. It is believed this information  in  combination
       with  spatial  referenced  maps could be of very useful in
       the decision making process.  The steepness of  the  curve
       shows how that variable is increasing within a correspond-
       ing range.  By choosing this option, the program  requests
       a window to display the statistical curves. Then, the pro-
       gram asks the user to select either  an	input  or  output
       variable  for  which to draw the curves. The user then has
       the option  of  keeping	the  previously  selected  X-axis
       intervals/classes  or  can  select  a  new range of inter-
       vals/classes. The selection of new ranges of intervals can
       be  done in one of two ways. Either the user can select 10
       equal intervals between the maximum  and  minimum  of  the
       selected  variable  or he can enter the ranges between the
       maximum and minimum values.  In either case, the number of
       intervals can't exceed 10.


       _9_.  _R_e_s_t_o_r_e  _t_h_e  _i_n_i_t_i_a_l _s_c_r_e_e_n_: This option restores the
       original or initial display screen that was initiated when
       one of the options from Figure 1 was chosen.


       _1_0_.  _E_x_i_t  _t_o  _G_R_A_S_S  (to  come	back type 'return'): This
       option allows the user to exit to the GRASS temporarily to
       perform	normal	operations  under the GRASS GIS tool.  To
       come back to the same menu in the visualization tool, type
       return and hit enter.


       _1_1_.  _Q_u_i_t_:  This option takes the user back to the initial
       screen (Figure 1).  If the user has created any maps using
       option 6, the program asks if these are to be saved before
       quitting.


       Appendix 1: List of AGNPS output  maps  and  reserved  map
       names


       Hydrology output

       Runoff			 generated		      map
       ro_gen	       X.ro_gen
       Runoff		 from		 upstream	      map
       ro_us	       X.ro_us
       Runoff		  to		downstream	      map
       ro_ds	       X.ro_ds


       Sediment output

       Erosion						      map
       Sed_in	       X.Sed_in
       Deposition					      map
       Sed_gen	       X.Sed_gen
       Sediment        leaving	      the	 cell	      map
       Sed_out	       X.Sed_out


       Chemical output

       Nitrogen     associated	  with	  Sediment    (generated)
       map N_sed_in  X.N_sed_in
       Nitrogen    associated	  with	   Sediment	(leaving)
       map   N_sed_out X.N_sed_out
       Nitrogen     associated	   with     Runoff    (generated)
       map   N_ro_in	    X.N_ro_in
       Nitrogen     associated	   with     Runoff	(leaving)
       map	    N_ro_out  X.N_ro_out
       Phosphorus    associated    with    Sediment   (generated)
       map    P_sed_in	X.P_sed_in
       Phosphorus    associated    with    Sediment	(leaving)
       map P_sed_out X.P_sed_out
       Phosphorus     associated    with    Runoff    (generated)
       map P_ro_in	  X.P_ro_in
       Phosphorus    associated     with     Runoff	(leaving)
       map   P_ro_out  X.P_ro_out
       COD	associated	with	  Runoff      (generated)
       map	  COD_ro_in X.COD_ro_in
       COD	associated	with	   Runoff	(leaving)
       map	    COD_ro_out	   X.COD_ro_out


       _f_i_l_e_n_a_m_e:  Refers  to  the  AGNPS  ASCII input/output file
       without its extension


       X: Refers to the name supplied by the user. The	maps  are
       saved with the extension in the current mapset.

AAUUTTHHOORR
       Raghavan  Srinivasan, TAES-Blackland Research Center, Tem-
       ple, Texas.

       _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.out.agnps(1)
