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  capabil-
       ity  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 follow-
       ing 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 sed-
       iment delivery ratio, sediment enrichment ratio, mean sediment  concen-
       tration,  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
       nutrients, 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 concentration (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) * Concentration  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 principle 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 filename 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 (generated)	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  associated  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 monitor.  The  GRASS  shelltool
       window  should be at the right hand side bottom of the screen.  Execute
       the _v_i_s___t_o_o_l program 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  containing  cell
	      values greater than zero and zero's for cells outside the water-
	      shed 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 extension 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 contin-
       uing the execution, if there is no message then hit Enter after answer-
       ing the question else hit Esc to continue.


       In  the following text, each output screen of the visualization tool is
       discussed. The  visualization  tool  splits  the  screen  into  various
       screens to display the output of the model.  The number of windows cre-
       ated 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 window.  The  watershed  summary  can  be
       accessed from any part of the visualization tool, providing an opportu-
       nity 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  show-
       ing  the color and the numerical value associated with it. The color of
       the output maps range from green-yellow-red, with increasing  intensity
       of  output. The right hand top corner window displays the watershed 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 directions 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 discussed.


       _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 orig-
       inal 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
       visualization 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 displays 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' simu-
       lations. 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  sedi-
       ment,  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 out-
       puts 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 program 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 perform 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 combination with other options.


       _1_.  _Z_o_o_m_:  Allows  users  to  zoom in or zoom out of any section 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 particularly
       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  com-
       plete the zoom process. Always follow the instructions displayed on the
       ASCII terminal.	Failing to do so can cause the program to stop.  Simi-
       larly, 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 chosen 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 choosing one of the top row windows.  The win-
       dow selection process 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 out-
       put 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 useful to correlate cell outputs with those
       of watershed outputs 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 criti-
       cal  areas  easily.   For example, users can use this option to display
       problematic areas that are exceeding the soil tolerance limit  (T  fac-
       tor).   Options are available to save the displayed maps for later ref-
       erence, 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 display 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  dis-
       play  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 simultane-
       ously 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 followed 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 dis-
       tribution 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 maximum and
       minimum of the selected variable.  This option is helpful  to  see  how
       that  particular variable is distributed both cumulatively and the num-
       ber 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 corresponding range.  By choosing this
       option, the program  requests  a  window  to  display  the  statistical
       curves.	Then,  the  program 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  intervals/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 visual-
       ization 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, Temple, 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)
