r.average(1)	       Grass User's Manual	     r.average(1)



NNAAMMEE
       rr..aavveerraaggee   -  Finds  the average of values in a cover map
       within areas assigned the same category value in  a  user-
       specified base map.
       _(_G_R_A_S_S _R_a_s_t_e_r _P_r_o_g_r_a_m_)

SSYYNNOOPPSSIISS
       rr..aavveerraaggee
       rr..aavveerraaggee hheellpp
       rr..aavveerraaggee [--cc] bbaassee==_n_a_m_e ccoovveerr==_n_a_m_e oouuttppuutt==_n_a_m_e

DDEESSCCRRIIPPTTIIOONN
       _r_._a_v_e_r_a_g_e  calculates  the average value of data contained
       in a _c_o_v_e_r raster map layer for areas  assigned	the  same
       category  value	in  the  user-specified  _b_a_s_e  raster map
       layer.  These averaged values are stored in  the  category
       labels  file  associated with a new _o_u_t_p_u_t map layer.  The
       values to be averaged  are  taken  from	a  user-specified
       _c_o_v_e_r  map.  The _c_a_t_e_g_o_r_y _v_a_l_u_e_s for the _c_o_v_e_r map will be
       averaged, unless the --cc flag is set.  If the  --cc  flag  is
       set,  the  values  that appear in the _c_a_t_e_g_o_r_y _l_a_b_e_l_s file
       for the _c_o_v_e_r map will be averaged  instead  (see  example
       below).


       The  _o_u_t_p_u_t map is actually a _r_e_c_l_a_s_s of the _b_a_s_e map (see
       _r_._r_e_c_l_a_s_s), and will have exactly the same _c_a_t_e_g_o_r_y _v_a_l_u_e_s
       as  the _b_a_s_e map.  The averaged values computed by _r_._a_v_e_r_-
       _a_g_e are stored in the _o_u_t_p_u_t map's _c_a_t_e_g_o_r_y _l_a_b_e_l_s file.


       If the user simply types rr..aavveerraaggee on  the  command  line,
       the  user  is  prompted for the flag setting and parameter
       values through  the  standard  parser  interface.   Alter-
       nately,	the  user can supply all needed flag settings and
       parameter values on the command line.

   FFllaagg::
       --cc     Take the average of the values found in  the  _c_a_t_e_-
	      _g_o_r_y  _l_a_b_e_l_s  for  the  _c_o_v_e_r  map, rather than the
	      average of the _c_o_v_e_r map's _c_a_t_e_g_o_r_y _v_a_l_u_e_s.




   PPaarraammeetteerrss::
       bbaassee==_n_a_m_e
	      An existing raster map layer in the user's  current
	      mapset  search  path.   For  each  group	of  cells
	      assigned the same category value in the  _b_a_s_e  map,
	      the  values  assigned  these cells in the _c_o_v_e_r map
	      will be averaged.

       ccoovveerr==_n_a_m_e
	      An existing raster map layer containing the  values
	      (in  the form of cell category values or cell cate-
	      gory labels) to be averaged within each category of
	      the _b_a_s_e map.

       oouuttppuutt==_n_a_m_e
	      The name of a new map layer to contain program out-
	      put (a _r_e_c_l_a_s_s of the _b_a_s_e  map).  Averaged  values
	      will  be stored in the _o_u_t_p_u_t map's category labels
	      file under the user's $LOCATION/cats directory.


EEXXAAMMPPLLEE
       Assume that _f_a_r_m_s is a map with 7  farms  (i.e.,  7  cate-
       gories),  and that _s_o_i_l_s_._K_f_a_c_t_o_r is a map of soil K factor
       values with the following category file:

	    cat  cat
	    value     label
	    0	 no soil data
	    1	 .10
	    2	 .15
	    3	 .17
	    4	 .20
	    5	 .24
	    6	 .28
	    7	 .32
	    8	 .37
	    9	 .43

       Then


       rr..aavveerraaggee   --cc	bbaassee==_f_a_r_m_s    ccoovveerr==_s_o_i_l_s_._K_f_a_c_t_o_r    oouutt--
       ppuutt==_K_._b_y_._f_a_r_m

       will  compute the average soil K factor for each farm, and
       store the result in the output map _K_._b_y_._f_a_r_m,  which  will
       be  a  reclass  of  _f_a_r_m_s  with category labels as follows
       (example only):

	    cat  cat
	    value     label
	    1	 .1023
	    2	 .1532
	    3	 .172
	    4	 .3872
	    5	 .003
	    6	 .28
	    7	 .2345


NNOOTTEESS
       The --cc option requires that the category  label	for  each
       category  in  the _c_o_v_e_r map be a valid number, integer, or
       decimal.  To be exact, if the first item in the	label  is
       numeric, then that value is used. Otherwise, zero is used.
       The following table covers all possible cases:



		category    value
		label	    used by -c
		______________________
		 .12	      .12
		 .80 KF        .8
		 no data      0



       (This flag is very similar to the @ operator in _r_._m_a_p_c_a_l_c,
       and  the  user  is encouraged to read the manual entry for
       _r_._m_a_p_c_a_l_c to see how it works there.)


       The user should use the results of  _r_._a_v_e_r_a_g_e  with  care.
       Since  this  utility assigns a value to each cell which is
       based on global information (i.e., information at  spatial
       locations  other  than  just  the  location  of	the  cell
       itself), the resultant map layer is only valid if the geo-
       graphic region and mask settings are the same as they were
       at the time that the result map was created.


       Results are affected by the current  region  settings  and
       mask.

SSEEEE AALLSSOO
       _g_._r_e_g_i_o_n

       _r_._c_a_t_s

       _r_._c_l_u_m_p

       _r_._d_e_s_c_r_i_b_e

       _r_._m_a_p_c_a_l_c

       _r_._m_a_s_k

       _r_._m_f_i_l_t_e_r

       _r_._m_o_d_e

       _r_._n_e_i_g_h_b_o_r_s

       _r_._r_e_c_l_a_s_s

       _r_._s_t_a_t_s

       _p_a_r_s_e_r

AAUUTTHHOORR
       Michael	 Shapiro,   U.S.  Army	Construction  Engineering
       Research Laboratory

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



GRASS 5.0					     r.average(1)
