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-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  speci-
       fied   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):

	    462.876649	   480.411218	  281.758307
	    480.411218	   513.015646	  278.914813
	    281.758307	   278.914813	  336.326645


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 calcula-
	      tions, 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
	      covariance/correlation matrix calculations.



       Alternately, the user can simply type rr..ccoovvaarr on the  com-
       mand  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 values pro-
       duced 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_/_0_1_/_2_5 _0_5_:_4_5_:_3_4 _$



GRASS 5.0					       r.covar(1)
