Mercurial > hg > octave-nkf
diff scripts/statistics/base/var.m @ 11436:e151e23f73bc
Overhaul base statistics functions and documentation of same.
Add or improve input validation.
Add input validation tests.
Add functional tests.
Improve or re-write documentation strings.
author | Rik <octave@nomad.inbox5.com> |
---|---|
date | Mon, 03 Jan 2011 21:23:08 -0800 |
parents | 693e22af08ae |
children | fd0a3ac60b0e |
line wrap: on
line diff
--- a/scripts/statistics/base/var.m +++ b/scripts/statistics/base/var.m @@ -18,78 +18,91 @@ ## <http://www.gnu.org/licenses/>. ## -*- texinfo -*- -## @deftypefn {Function File} {} var (@var{x}) -## For vector arguments, return the (real) variance of the values. -## For matrix arguments, return a row vector containing the variance for -## each column. +## @deftypefn {Function File} {} var (@var{x}) +## @deftypefnx {Function File} {} var (@var{x}, @var{opt}) +## @deftypefnx {Function File} {} var (@var{x}, @var{opt}, @var{dim}) +## Compute the variance of the elements of the vector @var{x}. +## @tex +## $$ +## {\rm std} (x) = \sigma^2 = {\sum_{i=1}^N (x_i - \bar{x})^2 \over N - 1} +## $$ +## where $\bar{x}$ is the mean value of $x$. +## @end tex +## @ifnottex ## +## @example +## @group +## std (x) = 1/(N-1) SUM_i (x(i) - mean(x))^2 +## @end group +## @end example +## +## @end ifnottex +## If @var{x} is a matrix, compute the variance for each column +## and return them in a row vector. +## ## The argument @var{opt} determines the type of normalization to use. ## Valid values are ## ## @table @asis ## @item 0: -## Normalizes with @math{N-1}, provides the best unbiased estimator of the -## variance [default]. +## normalize with @math{N-1}, provides the best unbiased estimator of the +## variance [default] ## ## @item 1: -## Normalizes with @math{N}, this provides the second moment around the mean. +## normalizes with @math{N}, this provides the second moment around the mean ## @end table ## -## The third argument @var{dim} determines the dimension along which the -## variance is calculated. +## If the optional argument @var{dim} is given, operate along this dimension. +## @seealso{cov,std,skewness,kurtosis,moment} ## @end deftypefn ## Author: KH <Kurt.Hornik@wu-wien.ac.at> ## Description: Compute variance -function retval = var (x, opt, dim) +function retval = var (x, opt = 0, dim) if (nargin < 1 || nargin > 3) print_usage (); endif + + if (!isnumeric (x)) + error ("var: X must be a numeric vector or matrix"); + endif + + if (isempty (opt)) + opt = 0; + endif + if (opt != 0 && opt != 1) + error ("var: normalization OPT must be 0 or 1"); + endif + if (nargin < 3) dim = find (size (x) > 1, 1); if (isempty (dim)) dim = 1; endif endif - if (nargin < 2 || isempty (opt)) - opt = 0; - endif - sz = size (x); - n = sz(dim); - if (isempty (x)) - ## FIXME -- is there a way to obtain these results without all the - ## special cases? - if (ndims (x) == 2 && sz(1) == 0 && sz(2) == 0) - retval = NaN; - else - sz(dim) = 1; - if (n == 0) - if (prod (sz) == 0) - retval = zeros (sz); - else - retval = NaN (sz); - endif - else - retval = zeros (sz); - endif - endif - elseif (n == 1) - retval = zeros (sz); + n = size (x, dim); + if (n == 1) + retval = zeros (size (x), class (x)); + elseif (numel (x) > 0) + retval = sumsq (center (x, dim), dim) / (n - 1 + opt); else - retval = sumsq (center (x, dim), dim) / (n + opt - 1); + error ("var: X must not be empty"); endif endfunction %!assert (var (13), 0) -%!assert (var ([]), NaN) -%!assert (var (ones (0, 0, 0), 0, 1), zeros (1, 0, 0)) -%!assert (var (ones (0, 0, 0), 0, 2), zeros (0, 1, 0)) -%!assert (var (ones (0, 0, 0), 0, 3), zeros (0, 0)) -%!assert (var (ones (1, 2, 0)), zeros (1, 1, 0)) -%!assert (var (ones (1, 2, 0, 0), 0, 1), zeros (1, 2, 0, 0)) -%!assert (var (ones (1, 2, 0, 0), 0, 2), zeros (1, 1, 0, 0)) -%!assert (var (ones (1, 2, 0, 0), 0, 3), zeros (1, 2, 1, 0)) +%!assert (var ([1,2,3]), 1) +%!assert (var ([1,2,3], 1), 2/3, eps) +%!assert (var ([1,2,3], [], 1), [0,0,0]) + +%% Test input validation +%!error var () +%!error var (1,2,3,4) +%!error var (true(1,2)) +%!error var (1, -1); +%!error var ([],1) +