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 exam-
       ple 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.   Alternately,  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 category 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 output (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 categories), 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 cate-
       gory 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 oouuttppuutt==_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  informa-
       tion  (i.e., information at spatial locations other than just the loca-
       tion of the cell itself), the resultant map layer is only valid if  the
       geographic  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)
