octave_packages/nan-2.5.5/cov.m

   1 function CC = cov(X,Y,Mode)
   2 % COV covariance matrix
   3 % X and Y can contain missing values encoded with NaN.
   4 % NaN's are skipped, NaN do not result in a NaN output.
   5 % The output gives NaN only if there are insufficient input data
   6 % The mean is removed from the data.
   7 %
   8 % Remark: for data contains missing values, the resulting
   9 % matrix might not be positiv definite, and its elements have magnitudes
  10 % larger than one. This ill-behavior is more likely for small sample
  11 % sizes, but there is no garantee that the result "behaves well" for larger
  12 % sample sizes. If you want the a "well behaved" result (i.e. positive
  13 % definiteness and magnitude of elements not larger than 1), use CORRCOEF.
  14 % However, COV is faster than CORRCOEF and might be good enough in some cases.
  15 %
  16 % C = COV(X [,Mode]);
  17 %      calculates the (auto-)correlation matrix of X
  18 % C = COV(X,Y [,Mode]);
  19 %      calculates the crosscorrelation between X and Y.
  20 %      C(i,j) is the correlation between the i-th and jth
  21 %      column of X and Y, respectively.
  22 %   NOTE: Octave and Matlab have (in some special cases) incompatible implemenations.
  23 %       This implementation follows Octave. If the result could be ambigous or
  24 %       incompatible, a warning will be presented in Matlab. To avoid this warning use:
  25 %       a) use COV([X(:),Y(:)]) if you want the traditional Matlab result.
  26 %       b) use C = COV([X,Y]), C = C(1:size(X,2),size(X,2)+1:size(C,2)); if you want to be compatible with this software.
  27 %
  28 % Mode = 0 [default] scales C by (N-1)
  29 % Mode = 1 scales C by N.
  30 %
  31 % see also: COVM, COR, CORRCOEF, SUMSKIPNAN
  32 %
  33 % REFERENCES:
  34 % http://mathworld.wolfram.com/Covariance.html
  35
  36 %       $Id: cov.m 9803 2012-03-09 20:03:49Z schloegl $
  37 %       Copyright (C) 2000-2003,2005,2009,2011,2012 by Alois Schloegl <alois.schloegl@ist.ac.at>
  38 %       This function is part of the NaN-toolbox
  39 %       http://pub.ist.ac.at/~schloegl/matlab/NaN/
  40
  41 %    This program is free software; you can redistribute it and/or modify
  42 %    it under the terms of the GNU General Public License as published by
  43 %    the Free Software Foundation; either version 2 of the License, or
  44 %    (at your option) any later version.
  45 %
  46 %    This program is distributed in the hope that it will be useful,
  47 %    but WITHOUT ANY WARRANTY; without even the implied warranty of
  48 %    MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
  49 %    GNU General Public License for more details.
  50 %
  51 %    You should have received a copy of the GNU General Public License
  52 %    along with this program; If not, see <http://www.gnu.org/licenses/>.
  53
  54
  55 if nargin==1
  56         Mode = 0;
  57         Y = [];
  58 elseif nargin==2,
  59         % if all(size(Y)==1) & any(Y==[0,1]);   % This is not compatible with octave
  60         % short-circuit evaluation is required
  61         % but for compatibility to matlab, && is avoided
  62         SW = all(size(Y)==1);
  63         if SW, SW = any(Y==[0,1]); end;
  64         if SW,
  65                 Mode = Y;
  66                 Y = [];
  67         else
  68                 Mode = 0;
  69         end;
  70 elseif nargin==3,
  71
  72 else
  73         fprintf(2,'Error COV: invalid number of arguments\n');
  74 end;
  75
  76 if ~exist('OCTAVE_VERSION','builtin') && ~isempty(Y) && (size(X,2)+size(Y,2)~=2),
  77         % COV in Matlab is differently defined than COV in Octave.
  78         % For compatibility reasons, this branch reflects the difference.
  79         fprintf(2,'Warning NaN/COV: This kind of use of COV is discouraged because it produces different results for Matlab and Octave. \n');
  80         fprintf(2,'  (a) the traditional Matlab result can be obtained with:  C = COV([X(:),Y(:)]).\n');
  81         fprintf(2,'  (b) the traditional Octave result can be obtained with:  C = COV([X,Y]); C = C(1:size(X,2),size(X,2)+1:size(C,2)).\n');
  82
  83         if numel(Y)~=numel(X),
  84                 error('The lengths of X and Y must match.');
  85         end;
  86         X = [X(:),Y(:)];
  87         Y = [];
  88 end;
  89
  90 if isempty(Y)
  91         CC = covm(X,['D',int2str(Mode>0)]);
  92 else
  93         CC = covm(X,Y,['D',int2str(Mode>0)]);
  94 end;
  95