Description of slcov

Home > sltoolbox > stat > slcov.m

slcov

PURPOSE

SLCOV Compute the covariance matrix

SYNOPSIS

function C = slcov(X, w, vmean, hasbeenchecked)

DESCRIPTION

SLCOV Compute the covariance matrix

 $ Syntax $
   - C = slcov(X) 
   - C = slcov(X, w)
   - C = slcov(X, w, vmean)
   - C = slcov(X, w, 0)
   - C = slcov(X, w, vmean, true)

 $ Arguments $
   - X:        the sample matrix
   - w:        the weights of the samples
   - vmean:    the pre-computed mean vector
   - C:        the computed covariance matrix

 $ Description $
   - C = slcov(X) computes the covariance matrix for the samples in X.
     the samples are stored as column vectors. X should be a d x n 2D
     matrix, where d is the vector dimension, and n is the number of
     samples. 

   - C = slcov(X, w) computes the weighted covariance matrix for
     the samples in X. w is a 1 x n row vector of the sample weights.
     If w is empty, the non-weighted covariance matrix is computed.

   - C = slcov(X, w, vmean) computes the (weighted) covariance matrix
     with the mean vector supplied. Thus in the function, vmean will be
     used, instead of re-computing the mean vector. 

   - C = slcov(X, w, 0) computes the (weighted) covariance matrix on 
     the centered vectors. Since the vectors are treated as centered,
     no mean vector would be computed, and X will not be shifted.

   - C = slcov(X, w, vmean, true) indicates that the size consistency
     has been verified by the invoker. In this function, no checking
     will be conducted on the sizes of input arguments. This syntax
     is designed for the sake of efficiency.

 $ Remarks $
   - M should be a 2D matrix (d x n), then w should be a 1 x n row vector,
     vmean should be a d x 1 column vector or 0. Then C would be a 
     d x d matrix.
   - In a non-weighted version, C = X * X' / n; while in a weighed
     version, the weights would be first normalized before the covariance
     is computed.

 $ History $
   - Created by Dahua Lin on Apr 22, 2006
   - Modified by Dahua Lin on Sep 10, 2006
       - replace sladd by sladdvec to increase efficiency
       - replace slmul by slmulvec

CROSS-REFERENCE INFORMATION

This function calls:

• sladdvec SLADDVEC adds a vector to columns or rows of a matrix
• slmulvec SLMULVEC multiplies a vector to columns or rows of a matrix
• slmean SLMEAN Compute the mean vector of samples

This function is called by:

• sldistmean SLDISTMEAN Uses fast method to compute means of pairwise distances
• slcovs SLCOVS Computes the sample covariance matrix
• slgaussest SLGAUSSEST Estimates the Gaussian models from samples
• slscatter SLSCATTER Compute the scatter matrix
• slpartitionpca SLPARTITIONPCA Performs Partition-based PCA and saves the models

SOURCE CODE

0001 function C = slcov(X, w, vmean, hasbeenchecked)
0002 %SLCOV Compute the covariance matrix
0003 %
0004 % $ Syntax $
0005 %   - C = slcov(X)
0006 %   - C = slcov(X, w)
0007 %   - C = slcov(X, w, vmean)
0008 %   - C = slcov(X, w, 0)
0009 %   - C = slcov(X, w, vmean, true)
0010 %
0011 % $ Arguments $
0012 %   - X:        the sample matrix
0013 %   - w:        the weights of the samples
0014 %   - vmean:    the pre-computed mean vector
0015 %   - C:        the computed covariance matrix
0016 %
0017 % $ Description $
0018 %   - C = slcov(X) computes the covariance matrix for the samples in X.
0019 %     the samples are stored as column vectors. X should be a d x n 2D
0020 %     matrix, where d is the vector dimension, and n is the number of
0021 %     samples.
0022 %
0023 %   - C = slcov(X, w) computes the weighted covariance matrix for
0024 %     the samples in X. w is a 1 x n row vector of the sample weights.
0025 %     If w is empty, the non-weighted covariance matrix is computed.
0026 %
0027 %   - C = slcov(X, w, vmean) computes the (weighted) covariance matrix
0028 %     with the mean vector supplied. Thus in the function, vmean will be
0029 %     used, instead of re-computing the mean vector.
0030 %
0031 %   - C = slcov(X, w, 0) computes the (weighted) covariance matrix on
0032 %     the centered vectors. Since the vectors are treated as centered,
0033 %     no mean vector would be computed, and X will not be shifted.
0034 %
0035 %   - C = slcov(X, w, vmean, true) indicates that the size consistency
0036 %     has been verified by the invoker. In this function, no checking
0037 %     will be conducted on the sizes of input arguments. This syntax
0038 %     is designed for the sake of efficiency.
0039 %
0040 % $ Remarks $
0041 %   - M should be a 2D matrix (d x n), then w should be a 1 x n row vector,
0042 %     vmean should be a d x 1 column vector or 0. Then C would be a
0043 %     d x d matrix.
0044 %   - In a non-weighted version, C = X * X' / n; while in a weighed
0045 %     version, the weights would be first normalized before the covariance
0046 %     is computed.
0047 %
0048 % $ History $
0049 %   - Created by Dahua Lin on Apr 22, 2006
0050 %   - Modified by Dahua Lin on Sep 10, 2006
0051 %       - replace sladd by sladdvec to increase efficiency
0052 %       - replace slmul by slmulvec
0053 %
0054 
0055 %% parse and verify input arguments
0056 
0057 if nargin < 4 || ~hasbeenchecked
0058 
0059     % basic
0060     if ndims(X) ~= 2
0061         error('sltoolbox:invaliddims', 'X should be a 2D matrix');
0062     end
0063     [d, n] = size(X);
0064 
0065     % for weights
0066     if nargin < 2
0067         w = [];
0068     end
0069     if ~isempty(w)
0070         if size(w, 1) ~= 1 || size(w, 2) ~= n
0071             error('sltoolbox:sizmismatch', ...
0072                 'w should be an 1 x n row vector');
0073         end
0074     end
0075 
0076     % for mean vector
0077     if nargin >= 3 && ~isempty(vmean) && ~isequal(vmean, 0)
0078         if size(vmean, 1) ~= d || size(vmean, 2) ~= 1
0079             error('sltoolbox:sizmismatch', ...
0080                 'v should be a d x 1 column vector');
0081         end
0082     end
0083     
0084 else
0085     
0086     % simple parse
0087     n = size(X, 2);
0088     if nargin < 2
0089         w = [];
0090     end
0091     
0092 end
0093 
0094 %% centerize the samples
0095 
0096 if nargin < 3 || isempty(vmean)
0097     vmean = slmean(X, w, true);
0098 end
0099 
0100 if ~isequal(vmean, 0) % need centerization
0101     X = sladdvec(X, -vmean, 1);
0102 end
0103 
0104 %% compute the covariance
0105 
0106 if isempty(w)   % not weighted
0107     
0108     C = X * X' / n;
0109     
0110 else            % weighted
0111     
0112     w = w / sum(w);    
0113     C = slmulvec(X, w, 2) * X';
0114         
0115 end
0116     
0117 
0118     
0119 
0120

---

Generated on Wed 20-Sep-2006 12:43:11 by m2html © 2003