.TH r.average
.SH NAME
\fIr.average\fR \- Finds the average of values in a cover map within
areas assigned the same category value in a user-specified base map.
.br
.I (GRASS Raster Program)
.SH SYNOPSIS
\fBr.average\fR
.br
\fBr.average help\fR
.br
\fBr.average\fR [\fB-c\fR] \fBbase\*=\fIname \fBcover\*=\fIname \fBoutput\*=\fIname\fR
.SH DESCRIPTION
.I r.average 
calculates the average value of data contained in a \fIcover\fR raster map layer
for areas assigned the same category value in the user-specified \fIbase\fR
raster map layer.
These averaged values are stored in the category labels file associated with a
new \fIoutput\fR map layer.

The values to be averaged are taken from a user-specified \fIcover\fR map.
The \fIcategory values\fR for the \fIcover\fR map will be averaged,
unless the -c flag is set.
If the -c flag is set, the values that appear in the \fIcategory labels\fR file
for the \fIcover\fR map will be averaged instead (see example below).

The \fIoutput\fR map is actually a \fIreclass\fR of the \fIbase\fR map
(see \fIr.reclass\fR), and will have exactly the same \fIcategory values\fR
as the \fIbase\fR map.
The averaged values computed by \fIr.average\fR are stored
in the \fIoutput\fR map's \fIcategory labels\fR file.

If the user simply types \fBr.average\fR on the command line, the
user is prompted for the flag setting and parameter values
through the standard parser interface (see \fIparser\fR manual entry).

Alternately, the user can supply all needed flag settings and parameter values
on the command line.
.LP
\fBFlag:\fR
.IP \fB-c\fR 18
Take the average of the values found in the \fIcategory labels\fR
for the \fIcover\fR map,
rather than the average of the \fIcover\fR map's \fIcategory values\fR.

.LP
\fBParameters:\fR
.IP \fBbase\*=\fIname\fR 18
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 \fIbase\fR
map, the values assigned these cells in the \fIcover\fR map will be averaged.
.IP \fBcover\*=\fIname\fR 18
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 \fIbase\fR map.
.IP \fBoutput\*=\fIname\fR 18
The name of a new map layer to contain program output
(a \fIreclass\fR of the \fIbase\fR map).  Averaged values will be stored
in the \fIoutput\fR map's category labels file under the user's $LOCATION/cats
directory.
.bp
.SH EXAMPLE
Assume that
.I farms
is a map with 7 farms (i.e., 7 categories), and that
.I soils.Kfactor
is a map of soil K factor values with the following category file:

.TS
center tab(|);
cc
cc
nl.
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
.TE

Then
.LP
.RS
\fBr.average  -c  base\*=farms  cover\*=soils.Kfactor  output\*=K.by.farm\fR
.RE
.LP
will compute the average soil K factor for each farm, and store the result
in the output map
.I K.by.farm,
which will be a reclass of
.I farms
with category labels as follows (example only):

.TS
center tab(|);
cc
cc
nl.
cat|cat
value|label
1|.1023
2|.1532
3|.172
4|.3872
5|.003
6|.28
7|.2345
.TE
.SH NOTES
The -c option requires that the category label for each category in the 
\fIcover\fR 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:
.LP
.TS
center tab(|);
ll.
category label|value used by -c
_
   .12|   .12
   .80 KF|   .8
   no data|   0
.TE
.LP
(This flag is very similar to the @ operator in 
.I r.mapcalc,
and the user is encouraged to read the manual entry for 
.I r.mapcalc
to see how it works there.)

The user should use the results of \fIr.average\fR 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.
.SH SEE ALSO
.I g.region,
.I r.cats,
.I r.clump,
.I r.describe,
.I r.mapcalc,
.I r.mask,
.I r.mfilter,
.I r.mode,
.I r.neighbors,
.I r.reclass,
.I r.stats,
and
.I parser
.SH "AUTHOR"
Michael Shapiro, U.S. Army Construction Engineering Research Laboratory