diff scripts/statistics/base/spearman.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 a1dbe9d80eee
children fd0a3ac60b0e
line wrap: on
line diff
--- a/scripts/statistics/base/spearman.m
+++ b/scripts/statistics/base/spearman.m
@@ -18,48 +18,64 @@
 ## <http://www.gnu.org/licenses/>.
 
 ## -*- texinfo -*-
-## @deftypefn {Function File} {} spearman (@var{x}, @var{y})
-## Compute Spearman's rank correlation coefficient @var{rho} for each of
-## the variables specified by the input arguments.
-##
-## For matrices, each row is an observation and each column a variable;
-## vectors are always observations and may be row or column vectors.
-##
-## @code{spearman (@var{x})} is equivalent to @code{spearman (@var{x},
-## @var{x})}.
+## @deftypefn  {Function File} {} spearman (@var{x})
+## @deftypefnx {Function File} {} spearman (@var{x}, @var{y})
+## @cindex Spearman's Rho
+## Compute Spearman's rank correlation coefficient @var{rho}.
 ##
 ## For two data vectors @var{x} and @var{y}, Spearman's @var{rho} is the
-## correlation of the ranks of @var{x} and @var{y}.
+## correlation coefficient of the ranks of @var{x} and @var{y}.
 ##
 ## If @var{x} and @var{y} are drawn from independent distributions,
 ## @var{rho} has zero mean and variance @code{1 / (n - 1)}, and is
 ## asymptotically normally distributed.
+##
+## @code{spearman (@var{x})} is equivalent to @code{spearman (@var{x},
+## @var{x})}.
+## @seealso{ranks, kendall}
 ## @end deftypefn
 
 ## Author: KH <Kurt.Hornik@wu-wien.ac.at>
 ## Description: Spearman's rank correlation rho
 
-function rho = spearman (x, y)
+function rho = spearman (x, y = [])
 
   if ((nargin < 1) || (nargin > 2))
     print_usage ();
   endif
 
+  if (! (isnumeric (x) && isnumeric (y)))
+    error ("spearman: X and Y must be numeric matrices or vectors");
+  endif
+
+  if (ndims (x) != 2 || ndims (y) != 2)
+    error ("spearman: X and Y must be 2-D matrices or vectors");
+  endif
+
   if (rows (x) == 1)
     x = x';
   endif
   n = rows (x);
 
   if (nargin == 1)
-    rho = cor (ranks (x));
+    rho = corrcoef (ranks (x));
   else
     if (rows (y) == 1)
       y = y';
     endif
     if (rows (y) != n)
-      error ("spearman: x and y must have the same number of observations");
+      error ("spearman: X and Y must have the same number of observations");
     endif
-    rho = cor (ranks (x), ranks (y));
+    rho = corrcoef (ranks (x), ranks (y));
   endif
 
 endfunction
+
+%% Test input validation
+%!error spearman ();
+%!error spearman (1, 2, 3);
+%!error spearman ([true, true]);
+%!error spearman (ones(1,2), [true, true]);
+%!error spearman (ones (2,2,2));
+%!error spearman (ones (2,2), ones (2,2,2));
+%!error spearman (ones (2,2), ones (3,2));