1 ## Copyright (C) 1995-2012 Kurt Hornik
3 ## This file is part of Octave.
5 ## Octave is free software; you can redistribute it and/or modify it
6 ## under the terms of the GNU General Public License as published by
7 ## the Free Software Foundation; either version 3 of the License, or (at
8 ## your option) any later version.
10 ## Octave is distributed in the hope that it will be useful, but
11 ## WITHOUT ANY WARRANTY; without even the implied warranty of
12 ## MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU
13 ## General Public License for more details.
15 ## You should have received a copy of the GNU General Public License
16 ## along with Octave; see the file COPYING. If not, see
17 ## <http://www.gnu.org/licenses/>.
20 ## @deftypefn {Function File} {} cov (@var{x})
21 ## @deftypefnx {Function File} {} cov (@var{x}, @var{opt})
22 ## @deftypefnx {Function File} {} cov (@var{x}, @var{y})
23 ## @deftypefnx {Function File} {} cov (@var{x}, @var{y}, @var{opt})
24 ## Compute the covariance matrix.
26 ## If each row of @var{x} and @var{y} is an observation, and each column is
27 ## a variable, then the @w{(@var{i}, @var{j})-th} entry of
28 ## @code{cov (@var{x}, @var{y})} is the covariance between the @var{i}-th
29 ## variable in @var{x} and the @var{j}-th variable in @var{y}.
32 ## \sigma_{ij} = {1 \over N-1} \sum_{i=1}^N (x_i - \bar{x})(y_i - \bar{y})
34 ## where $\bar{x}$ and $\bar{y}$ are the mean values of $x$ and $y$.
39 ## cov (x) = 1/N-1 * SUM_i (x(i) - mean(x)) * (y(i) - mean(y))
44 ## If called with one argument, compute @code{cov (@var{x}, @var{x})}, the
45 ## covariance between the columns of @var{x}.
47 ## The argument @var{opt} determines the type of normalization to use.
52 ## normalize with @math{N-1}, provides the best unbiased estimator of the
53 ## covariance [default]
56 ## normalize with @math{N}, this provides the second moment around the mean
61 ## Author: KH <Kurt.Hornik@wu-wien.ac.at>
62 ## Description: Compute covariances
64 function c = cov (x, y = [], opt = 0)
66 if (nargin < 1 || nargin > 3)
70 if ( ! (isnumeric (x) || islogical (x))
71 || ! (isnumeric (y) || islogical (y)))
72 error ("cov: X and Y must be numeric matrices or vectors");
75 if (ndims (x) != 2 || ndims (y) != 2)
76 error ("cov: X and Y must be 2-D matrices or vectors");
79 if (nargin == 2 && isscalar (y))
83 if (opt != 0 && opt != 1)
84 error ("cov: normalization OPT must be 0 or 1");
87 ## Special case, scalar has zero covariance
89 if (isa (x, 'single'))
102 if (nargin == 1 || isscalar (y))
104 c = conj (x' * x / (n - 1 + opt));
110 error ("cov: X and Y must have the same number of observations");
114 c = conj (x' * y / (n - 1 + opt));
124 %! assert(size (cx1) == [10, 10] && size (cx2) == [10, 10]);
125 %! assert(cx1, cx2, 1e1*eps);
130 %! assert (cov (x,y), -1, 5*eps)
131 %! assert (cov (x,flipud (y)), 1, 5*eps)
132 %! assert (cov ([x, y]), [1 -1; -1 1], 5*eps)
135 %! x = single ([1:3]');
136 %! y = single ([3:-1:1]');
137 %! assert (cov (x,y), single (-1), 5*eps)
138 %! assert (cov (x,flipud (y)), single (1), 5*eps)
139 %! assert (cov ([x, y]), single ([1 -1; -1 1]), 5*eps)
144 %! assert (isscalar (c));
147 %!assert(cov (5), 0);
148 %!assert(cov (single(5)), single(0));
157 %% Test input validation
159 %!error cov (1, 2, 3, 4);
160 %!error cov ([1; 2], ["A", "B"]);
161 %!error cov (ones (2,2,2));
162 %!error cov (ones (2,2), ones (2,2,2));
164 %!error cov (ones (2,2), ones (3,2));