r.covar(1)		      Grass User's Manual		    r.covar(1)



NNAAMMEE
       rr..ccoovvaarr	 -  Outputs a covariance/correlation matrix for user-specified
       raster map layer(s).
       _(_G_R_A_S_S Raster Program)

SSYYNNOOPPSSIISS
       rr..ccoovvaarr
       rr..ccoovvaarr hheellpp
       rr..ccoovvaarr [--mmrrqq] mmaapp==_n_a_m_e[,_n_a_m_e,...]

DDEESSCCRRIIPPTTIIOONN
       _r_._c_o_v_a_r outputs	a  covariance/correlation  matrix  for	user-specified
       raster  map layer(s).  The output can be printed, or (if run non-inter-
       actively) 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, rr..ccoovvaarr map=_l_a_y_e_r_._1,_l_a_y_e_r_._2,_l_a_y_e_r_._3

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

	    1.000000  0.914922	0.889581
	    0.914922  1.000000	0.939452
	    0.889581  0.939452	1.000000


OOPPTTIIOONNSS
       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 rr..ccoovvaarr [--mmrrqq] mmaapp==_n_a_m_e[,_n_a_m_e,...]

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

   FFllaaggss::
       --mm     Include  zero values in the correlation calculations, due to the
	      mask.

       --rr     Print out the correlation matrix.

       --qq     Run quietly (without comments on program progress).




   PPaarraammeetteerrss::
       mmaapp==_n_a_m_e[,_n_a_m_e,...]
	      Existing raster map layer(s)  to	be  included  in  the  covari-
	      ance/correlation matrix calculations.



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

PPRRIINNCCIIPPLLEE CCOOMMPPOONNEENNTTSS
       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_._m_a_p_-
       _c_a_l_c as follows: rr..mmaappccaallcc 'pc.1 = 0.691002*layer.1 +  0.720528*layer.2
       + 0.480511*layer.3'
       rr..mmaappccaallcc    'pc.2    =	  0.711939*layer.1    -   0.635820*layer.2   -
       0.070394*layer.3'
       rr..mmaappccaallcc   '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, _p_c_._1 will
       contain about 88% of the variance in the data set,  _p_c_._2  will  contain
       about  1%  of the variance in the data set, and _p_c_._3 will contain about
       11% of the variance in the data set.  Also, note that the range of val-
       ues  produced in _p_c_._1, _p_c_._2, and _p_c_._3 will not (in general) be the same
       as those for _l_a_y_e_r_._1, _l_a_y_e_r_._2, and _l_a_y_e_r_._3.  It	may  be  necessary  to
       rescale	_p_c_._1,  _p_c_._2  and _p_c_._3 to the desired range (e.g. 0-255).  This
       can be done with _r_._r_e_s_c_a_l_e.

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

SSEEEE AALLSSOO
       _i_._p_c_a

       _m_._e_i_g_e_n_s_y_s_t_e_m

       _r_._m_a_p_c_a_l_c

       _r_._r_e_s_c_a_l_e

       _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_/_1_0_/_1_4 _1_5_:_4_1_:_0_7 _$



GRASS 5.0							    r.covar(1)
