covar - Compute covariance matrix for a set of volumes  

1998 Ulrik Kjems, DSP/IMM, Technical University of Denmark, uk@imm.dtu.dk
Use : 
covar [-i level] [-l scalelist] [-m maskfile] [-s outmeanvol] [-o outputmatrix] 
       [-d]  [-p type] [-e ] [-c] [-u u_base] [-w svalues ] [-v v_base ] [-t svt_base ] file1 file2 ... fileN 

Computes N x N empirical covariance matrix between the specified volumes and
computes a SVD (singular value decomposition) of the input data.

The covariance matrix is not normalized, i.e. if the files 1..N make up the
columns of a data matrix X then the covariance matrix is (X-<x>)'*(X-<x>) where
<x> is the mean across columns of X. 

The SVD decomposition is performed on the data matrix X: X=USV'. If X is m-by-n,
U is m-by-n and S and V are n-by-n square matrices. The SVD computation is
performed using NR svdcmp(). Note that option -e causes the mean vector <x> NOT to
be subtracted prior to the SVD.


Memory demand
-------------
The program is designed to handle large volumes so volumes are read multiple
times if the memory demand exceeds the max allowable (specified using -x
maxmegs). However, to compute the SVD, all volumes have to fit in memory
simultaneously in double format.
NOTE: you can change this in covar.c and recompile

Minimum memory need to compute a covariance matrix is to store 3 volumes, one
in internal rep. (for the mean volume of the x's) and two in input raw format/
I.e. if the volumes are byte format, and the mean is stored as 16 bit, the total
memory requirement is 2 byte volumes plus one 16 bit volume, i.e. four times one
input volume.

Note: Only voxels inside the mask (if a mask is specified) are stored in memory. 


Internal representation
-----------------------
For covariance matrix computation only (no SVD), the internal representation for the mean
is chosen automatically, but you can use the -p option to manually specify the
internal representation for the mean. Note that <x> is stored as the sum of
file1..N i.e. it is integer when the input format is integer data type (except
if scaling is applied, then the output data type will be float by default).
You can override the automated selections using -p and -q.

To perform an SVD, the internal representation has to be double (this is
selected automatically).


  -d         Compute only diagonal entries of covariance matrix.

  -x max     Use no more than 'max' megabytes of memory. If less memory is needed
             volumes are read once. If more is needed, volumes are read multiple 
             times. Default is 100MB.

  -p type    Specifies the datatype that should be used for internal computation
             BYTE=1, USHORT=2, SSHORT=3 , INT32=4, FLOAT32=5, DOUBLE64=6

  -q type    type = 0..6, specifies the data type that should be used for 
             internal storage of data volumes. Default is 0 which is same 
             format as first input file. Note that to use SVD, this should be 
             either float (5) or double (6). Choose 0..6 where
             same_type_as_in_file=0, BYTE=1, USHORT=2, SSHORT=3 , INT32=4, 
             FLOAT32=5, DOUBLE64=6

  -m maskfile  
             The input 'maskfile' tell covar which voxels to use. This
             saves memory because the mean vectors are only stored for
             non-zero mask voxels.

  -u u_base 
             Perform SVD of data matrix X=USV' and save the U (high-dim) basis here.

  -v v_base 
             Perform SVD of data matrix X=USV' and save the orthogonal (low-dim) V basis here.

  -w w_base 
             Perform SVD of data matrix X=USV' and save the singular values here.

  -t sv_base 
             Perform SVD of data matrix X=USV' and save the SV' (low-dim) basis here.

  -s meanvol 
             Where to save the computed mean image. Note that    
	     for integer datatypes, the output is the sum rather than the  
	     mean.  scalelist' is an ASCII string containing 1 float per   
	     volume (sep by spaces).  Each volume in the list is           
	     multiplied with this scaling factor before the mean and       
	     covariance is computed. If -c is specified, the volume is written
             as a 1 dimensional vector with the values inside the mask. 

 -c          Write all volumes inside mask only. Default is full volumes.

 -e          Do NOT subtract mean <x> from all volumes prior to computing the SVD.
             Default is to perform the subtraction.

 -i level    Report level, either 'silent', 'info' or 'std'.

All volumes have to have same size.

covar -h produces above information