r.average

NAME

r.average - Finds the average of values in a cover map within areas assigned the same category value in a user-specified base map.
(GRASS Raster Program)

SYNOPSIS

r.average
r.average help
r.average [-c] base=name cover=name output=name

DESCRIPTION

r.average calculates the average value of data contained in a cover raster map layer for areas assigned the same category value in the user-specified base raster map layer. These averaged values are stored in the category labels file associated with a new output map layer. The values to be averaged are taken from a user-specified cover map. The category values for the cover map will be averaged, unless the -c flag is set. If the -c flag is set, the values that appear in the category labels file for the cover map will be averaged instead (see example below).

The output map is actually a reclass of the base map (see r.reclass), and will have exactly the same category values as the base map. The averaged values computed by r.average are stored in the output map's category labels file.

If the user simply types r.average 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.

Flag:

-c: Take the average of the values found in the category labels for the cover map, rather than the average of the cover map's category values.

Parameters:

base=name: 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 base map, the values assigned these cells in the cover map will be averaged.
cover=name: 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 base map.
output=name: The name of a new map layer to contain program output (a reclass of the base map). Averaged values will be stored in the output map's category labels file under the user's $LOCATION/cats directory.

EXAMPLE

Assume that farms is a map with 7 farms (i.e., 7 categories), and that soils.Kfactor 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

r.average -c base=farms cover=soils.Kfactor output=K.by.farm

will compute the average soil K factor for each farm, and store the result in the output map K.by.farm, which will be a reclass of farms 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

NOTES

The -c option requires that the category label for each category in the cover 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.mapcalc, and the user is encouraged to read the manual entry for r.mapcalc to see how it works there.)

The user should use the results of r.average 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 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.

AUTHOR

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

Last changed: $Date: 2002/01/25 05:45:34 $