r.agnps50.view(1)	      Grass User's Manual	     r.agnps50.view(1)



GGuuiiddeelliinneess ffoorr AAGGNNPPSS--GGRRAASSSS OOuuttppuutt IInntteerrffaaccee ((TThhee VViissuuaalliizzaattiioonn TTooooll))
       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  scaning  through
       pages and pages of numerical output in the form of tables.  The follow-
       ing sections discuss the visualization tool in detail.


       r.agnps50.view


       _A_G_N_P_S _O_u_t_p_u_t _P_a_r_a_m_e_t_e_r_s


       Various output options are available with the AGNPS model. Primary out-
       put  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 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
       rreeccllaassss principle of the GRASS GIS tool, thereby minimum disk space  is
       required.  The map from which all output maps were reclassed (cell num-
       ber map, _f_i_l_e_n_a_m_e___c_e_l_l___n_u_m, 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


       NNaammee ooff tthhee AAGGNNPPSS--GGRRAASSSS OOuuttppuutt IInntteerrffaaccee PPrrooggrraamm: _r_._a_g_n_p_s_5_0_._v_i_e_w.


       PPrroocceedduurreess  ttoo ffoollllooww wwhhiillee eexxeeccuuttiinngg tthhee OOuuttppuutt IInntteerrffaaccee ((tthhee VViissuuaall--
       iizzaattiioonn TTooooll)):


       First start GRASS 5.x from a shelltool window with the mapset where the
       data resides.


       Resize  the  graphics monitor to fit the full screen of the workstation
       and use the _D_s_e_l_e_c_t_._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 _r_._a_g_n_p_s_5_0_._v_i_e_w program  from  the  shelltool  window  where
       GRASS is running


       A  _V_i_s_u_a_l_i_z_a_t_i_o_n  _T_o_o_l  _I_n_p_u_t  menu will appear on the shelltool window
       requesting the following data/information from the user:


       Enter Watershed Map name: Enter the name of the watershed boundary  map
       containing  cell  values greater than zero and zero's for cells outside
       the watershed boundary.


       Enter the cell size in meters: The length of the  side  of  a  cell  in
       meters for which the model was run is entered.


       Enter  Aspect Map name: Enter the name of the aspect map for the water-
       shed.  It should have been created for the same resolution as the  cell
       size above.


       Enter  the ASCII AGNPS file name without its extension: Enter the ASCII
       AGNPS file name without its  extension  since  the  program  takes  the
       default	extension  of _._d_a_t and _._n_p_s 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  _E_s_c  key to continue.  Always look for a message at the
       bottom of the ASCII screen for continuing the execution, if there is no
       message	then  hit  _E_n_t_e_r  after answering the question else hit _E_s_c to
       continue.


       In the following sections, 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.


       Figure 1: Initial screen of the Visualization tool





       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):




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


       Options 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 'cur-
       rent' and the 'selected' runs and checks for the same file names.  Then
       the program creates the 17 output maps (Table 2) and displays the 'cur-
       rent' and the 'selected' output maps on the screen in the top row  win-
       dows. The default output is the sediment movement maps. Bottom row win-
       dows display the output histograms of the 'current' and the  'selected'
       simulations.   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 feature 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 _f_i_l_e_n_a_m_e___c_e_l_l___n_u_m
       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 _(_t_o _c_o_m_e _b_a_c_k _t_y_p_e _'_r_e_t_u_r_n_'_): 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 _r_e_t_u_r_n 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.


       Figure 2: Generic options screen of the	visualization  tool  for  spa-
       tially distributed output





       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 oper-
       ation  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 _Z_o_o_m  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 _z_o_o_m 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 _Z_o_o_m 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 deci-
       sions.


       _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 _Z_o_o_m 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 _(_t_o _c_o_m_e _b_a_c_k _t_y_p_e _'_r_e_t_u_r_n_'_): 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 _r_e_t_u_r_n 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 quiting.


       AAppppeennddiixx 11:: LLiisstt ooff AAGGNNPPSS oouuttppuutt mmaappss aanndd rreesseerrvveedd mmaapp nnaammeess






       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.

SSEEEE AALLSSOO
       _r_._a_g_n_p_s_5_0_._i_n_p_u_t

       _r_._a_g_n_p_s_5_0_._r_u_n



       AGNPS Page



       _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.agnps50.view(1)
