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  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 scaning through pages
       and pages of numerical output in the form of tables.   The
       following  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	 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 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 out-
       put.  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 number map, _f_i_l_e_n_a_m_e___c_e_l_l___n_u_m, 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 VViissuuaall--
       iizzaattiioonn 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  (gener-
		     ated) map

		     Nitrogen  associated with Sediment (leaving)
		     map

		     Nitrogen associated with Runoff  (generated)
		     map

		     Nitrogen  associated  with  Runoff (leaving)
		     map

		     Phosphorus associated with Sediment  (gener-
		     ated) map

		     Phosphorus  associated  with Sediment (leav-
		     ing) map

		     Phosphorus associated  with  Runoff  (gener-
		     ated) 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 VViissuuaalliizzaattiioonn 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 win-
       dow 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 shell-
       tool 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  watershed.   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 mes-
       sage 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 visu-
       alization 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.


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


       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 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 dis-
       play 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  out-
       let cell of the watershed.  The tool provides error check-
       ing 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 feature of the visual-
       ization	tool for analyzing different scenarios simultane-
       ously.


       _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 _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  per-
       form  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 spatially 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 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 _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  win-
       dow,  and  then drag the mouse to the desired location and
       click on the right mouse key to complete the zoom process.
       Always follow the instructions displayed on the ASCII ter-
       minal. 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 _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 dis-
       plays 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 aver-
       age  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 _Z_o_o_m to
       view any particular section of the watershed. After a cou-
       ple  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
       display	a  cell map, overlay a map on another map or dis-
       play 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 manage-
       ment strategies. For example, by overlaying a field bound-
       ary  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  _(_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.


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