.TH r.covar
.SH NAME
\fIr.covar\fR \- Outputs a covariance/correlation matrix
for user-specified raster map layer(s).
.br
\fI(GRASS Raster Program)\fR
.SH SYNOPSIS
\fBr.covar\fR
.br
\fBr.covar help\fR
.br
\fBr.covar\fR [\fB-mrq\fR] \fBmap\*=\fIname\fR[,\fIname\fR,...]
.SH DESCRIPTION
.I r.covar 
outputs a covariance/correlation matrix for user-specified
raster map layer(s).
The output can be printed,
or (if run non-interactively) saved by redirecting output into a file.

The output is an N x N symmetric covariance (correlation) matrix,
where N is the number of raster map layers specified on the command line.
For example,

.RS
\fBr.covar map\*=layer.1,layer.2,layer.3 \fR
.RE

would produce a 3x3 matrix (values are example only):

.RS
.TS
tab(:);
nnnn.
462.876649:480.411218:281.758307
480.411218:513.015646:278.914813
281.758307:278.914813:336.326645
.TE
.RE
.SH OPTIONS
The program will be run non-interactively, if the user specifies
the names of raster map layers and any desired options on the
command line, using the form
.LP
.RS
\fBr.covar\fR [\fB-mrq\fR] \fBmap\*=\fIname\fR[,\fIname\fR,...]
.RE
.LP
where each \fIname\fR specifies the name of a raster map layer to
be used in calculating the correlations, and the (optional) flags
\fI-m\fR, \fI-r\fR, and \fI-q\fR have meanings given below.
If these flags are not specified on the command line, their answers
default to "no".

.LP
\fBFlags:\fR
.IP \fB-m\fR 24
Include zero values in the correlation calculations, due to the mask.
.IP \fB-r\fR 24
Print out the correlation matrix.
.IP \fB-q\fR 24
Run quietly (without comments on program progress).

.LP
\fBParameters:\fR
.IP "\fBmap\*=\fIname\fR[,\fIname\fR,...]" 24
Existing raster map layer(s) to be included in the covariance/correlation
matrix calculations.
.LP
Alternately, the user can simply type \fBr.covar\fR on the command line,
without program arguments.  In this case, the user will be prompted for
flag settings and parameter values using the standard GRASS parser interface
described in the manual entry for \fIparser\fR.
.SH PRINCIPLE COMPONENTS
This module can be used as the first step of a principle components
transformation.
The covariance matrix would be input into a system which determines
eigen values and eigen vectors.  An NxN covariance matrix would result in
N real eigen values and N eigen vectors (each composed of N real numbers).
In the above example, the eigen values and corresponding eigen vectors
for the covariance matrix are:



.TS
center tab(:);
cccssss
nnrnnnl.
component:eigen value:eigen vector
1:1159.745202:<:0.691002:0.720528:0.480511:>
2:5.970541:<:0.711939:-0.635820:-0.070394:>
3:146.503197:<:0.226584:0.347470:-0.846873:>
.TE

The component corresponding to each vector can be produced using
.I r.mapcalc
as follows:

.nf
.ce 3
\fBr.mapcalc\ 'pc.1 \*= 0.691002*layer.1 + 0.720528*layer.2 + 0.480511*layer.3'\fR
\fBr.mapcalc\ 'pc.2 \*= 0.711939*layer.1 \- 0.635820*layer.2 \- 0.070394*layer.3'\fR
\fBr.mapcalc\ 'pc.3 \*= 0.226584*layer.1 + 0.347470*layer.2 \- 0.846873*layer.3'\fR
.fi

Note that based on the relative sizes of the eigen values,
.I pc.1
will contain about 88% of the variance in the data set,
.I pc.2 
will contain about 1% of the variance in the data set, and
.I pc.3
will contain about 11% of the variance in the data set.

Also, note that the range of values produced in
\fIpc.1, pc.2\fR, and \fIpc.3\fR will
not (in general) be the same as those for
\fIlayer.1, layer.2\fR, and \fIlayer.3\fR.
It may be necessary to rescale
\fIpc.1, pc.2\fR and \fIpc.3\fR to the desired range (e.g. 0-255).
This can be done with \fIr.rescale\fR.
.SH NOTES
If your
system has a FORTRAN compiler, then the program
.I m.eigensystem
in src.contrib
can be compiled and used to generate the eigen values and vectors.
.SH SEE ALSO
.I i.pca,
.I m.eigensystem,
.I r.mapcalc,
.I r.rescale,
and
.I parser
.SH AUTHOR
Michael Shapiro, U.S. Army Construction Engineering Research Laboratory