r.covar

NAME

r.covar - Outputs a covariance/correlation matrix for user-specified raster map layer(s).
(GRASS Raster Program)

SYNOPSIS

r.covar
r.covar help
r.covar [-mrq] map=name[,name,...]

DESCRIPTION

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,

r.covar map=layer.1,layer.2,layer.3

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

     462.876649     480.411218     281.758307 
     480.411218     513.015646     278.914813 
     281.758307     278.914813     336.326645

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

r.covar [-mrq] map=name[,name,...]

where each name specifies the name of a raster map layer to be used in calculating the correlations, and the (optional) flags -m, -r, and -q have meanings given below. If these flags are not specified on the command line, their answers default to "no".

Flags:

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

Parameters:

map=name[,name,...]: Existing raster map layer(s) to be included in the covariance/correlation matrix calculations.

Alternately, the user can simply type r.covar 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.

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:

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 >

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

r.mapcalc 'pc.1 = 0.691002*layer.1 + 0.720528*layer.2 + 0.480511*layer.3'
r.mapcalc 'pc.2 = 0.711939*layer.1 - 0.635820*layer.2 - 0.070394*layer.3'
r.mapcalc 'pc.3 = 0.226584*layer.1 + 0.347470*layer.2 - 0.846873*layer.3'

Note that based on the relative sizes of the eigen values, pc.1 will contain about 88% of the variance in the data set, pc.2 will contain about 1% of the variance in the data set, and pc.3 will contain about 11% of the variance in the data set. Also, note that the range of values produced in pc.1, pc.2, and pc.3 will not (in general) be the same as those for layer.1, layer.2, and layer.3. It may be necessary to rescale pc.1, pc.2 and pc.3 to the desired range (e.g. 0-255). This can be done with r.rescale.

NOTES

If your system has a FORTRAN compiler, then the program m.eigensystem in src.contrib can be compiled and used to generate the eigen values and vectors.

AUTHOR

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