octave_packages/m/deprecated/studentize.m

   1 ## Copyright (C) 1995-2012 Kurt Hornik
   2 ##
   3 ## This file is part of Octave.
   4 ##
   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.
   9 ##
  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.
  14 ##
  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/>.
  18
  19 ## -*- texinfo -*-
  20 ## @deftypefn  {Function File} {} studentize (@var{x})
  21 ## @deftypefnx {Function File} {} studentize (@var{x}, @var{dim})
  22 ## If @var{x} is a vector, subtract its mean and divide by its standard
  23 ## deviation.
  24 ##
  25 ## If @var{x} is a matrix, do the above along the first non-singleton
  26 ## dimension.
  27 ## If the optional argument @var{dim} is given, operate along this dimension.
  28 ## @seealso{center}
  29 ## @end deftypefn
  30
  31 ## Author: KH <Kurt.Hornik@wu-wien.ac.at>
  32 ## Description: Subtract mean and divide by standard deviation
  33
  34 function t = studentize (x, dim)
  35   persistent warned = false;
  36   if (! warned)
  37     warned = true;
  38     warning ("Octave:deprecated-function",
  39              "studentize is obsolete and will be removed from a future version of Octave; please use zscore instead");
  40   endif
  41
  42   if (nargin != 1 && nargin != 2)
  43     print_usage ();
  44   endif
  45
  46   if (! isnumeric(x))
  47     error ("studentize: X must be a numeric vector or matrix");
  48   endif
  49
  50   if (isinteger (x))
  51     x = double (x);
  52   endif
  53
  54   nd = ndims (x);
  55   sz = size (x);
  56   if (nargin != 2)
  57     ## Find the first non-singleton dimension.
  58     dim = find (sz > 1, 1);
  59     if (isempty (dim))
  60       dim = 1;
  61     endif
  62   else
  63     if (!(isscalar (dim) && dim == fix (dim))
  64         || !(1 <= dim && dim <= nd))
  65       error ("studentize: DIM must be an integer and a valid dimension");
  66     endif
  67   endif
  68
  69   c = sz(dim);
  70   if (c == 0)
  71     t = x;
  72   else
  73     idx = ones (1, nd);
  74     idx(dim) = c;
  75     t = x - repmat (mean (x, dim), idx);
  76     t = t ./ repmat (max (cat (dim, std(t, [], dim), ! any (t, dim)), [], dim), idx);
  77   endif
  78
  79 endfunction
  80
  81 %!assert(studentize ([1,2,3]), [-1,0,1])
  82 %!assert(studentize (int8 ([1,2,3])), [-1,0,1])
  83 #%!assert(studentize (ones (3,2,0,2)), zeros (3,2,0,2))
  84 %!assert(studentize ([2,0,-2;0,2,0;-2,-2,2]), [1,0,-1;0,1,0;-1,-1,1])
  85
  86 %% Test input validation
  87 %!error studentize ()
  88 %!error studentize (1, 2, 3)
  89 %!error studentize ([true true])
  90 %!error studentize (1, ones(2,2))
  91 %!error studentize (1, 1.5)
  92 %!error studentize (1, 0)
  93 %!error studentize (1, 3)
  94