octave_packages/m/statistics/base/mean.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} {} mean (@var{x})
  21 ## @deftypefnx {Function File} {} mean (@var{x}, @var{dim})
  22 ## @deftypefnx {Function File} {} mean (@var{x}, @var{opt})
  23 ## @deftypefnx {Function File} {} mean (@var{x}, @var{dim}, @var{opt})
  24 ## Compute the mean of the elements of the vector @var{x}.
  25 ## @tex
  26 ## $$ {\rm mean}(x) = \bar{x} = {1\over N} \sum_{i=1}^N x_i $$
  27 ## @end tex
  28 ## @ifnottex
  29 ##
  30 ## @example
  31 ## mean (x) = SUM_i x(i) / N
  32 ## @end example
  33 ##
  34 ## @end ifnottex
  35 ## If @var{x} is a matrix, compute the mean for each column and return them
  36 ## in a row vector.
  37 ##
  38 ## The optional argument @var{opt} selects the type of mean to compute.
  39 ## The following options are recognized:
  40 ##
  41 ## @table @asis
  42 ## @item "a"
  43 ## Compute the (ordinary) arithmetic mean.  [default]
  44 ##
  45 ## @item "g"
  46 ## Compute the geometric mean.
  47 ##
  48 ## @item "h"
  49 ## Compute the harmonic mean.
  50 ## @end table
  51 ##
  52 ## If the optional argument @var{dim} is given, operate along this dimension.
  53 ##
  54 ## Both @var{dim} and @var{opt} are optional.  If both are supplied,
  55 ## either may appear first.
  56 ## @seealso{median, mode}
  57 ## @end deftypefn
  58
  59 ## Author: KH <Kurt.Hornik@wu-wien.ac.at>
  60 ## Description: Compute arithmetic, geometric, and harmonic mean
  61
  62 function y = mean (x, opt1, opt2)
  63
  64   if (nargin < 1 || nargin > 3)
  65     print_usage ();
  66   endif
  67
  68   if (! (isnumeric (x) || islogical (x)))
  69     error ("mean: X must be a numeric vector or matrix");
  70   endif
  71
  72   need_dim = false;
  73
  74   if (nargin == 1)
  75     opt = "a";
  76     need_dim = true;
  77   elseif (nargin == 2)
  78     if (ischar (opt1))
  79       opt = opt1;
  80       need_dim = true;
  81     else
  82       dim = opt1;
  83       opt = "a";
  84     endif
  85   elseif (nargin == 3)
  86     if (ischar (opt1))
  87       opt = opt1;
  88       dim = opt2;
  89     elseif (ischar (opt2))
  90       opt = opt2;
  91       dim = opt1;
  92     else
  93       error ("mean: OPT must be a string");
  94     endif
  95   else
  96     print_usage ();
  97   endif
  98
  99   nd = ndims (x);
 100   sz = size (x);
 101   if (need_dim)
 102     ## Find the first non-singleton dimension.
 103     (dim = find (sz > 1, 1)) || (dim = 1);
 104   else
 105     if (!(isscalar (dim) && dim == fix (dim))
 106       || !(1 <= dim && dim <= nd))
 107       error ("mean: DIM must be an integer and a valid dimension");
 108     endif
 109   endif
 110
 111   n = sz(dim);
 112
 113   if (strcmp (opt, "a"))
 114     y = sum (x, dim) / n;
 115   elseif (strcmp (opt, "g"))
 116     y = prod (x, dim) .^ (1/n);
 117   elseif (strcmp (opt, "h"))
 118     y = n ./ sum (1 ./ x, dim);
 119   else
 120     error ("mean: option `%s' not recognized", opt);
 121   endif
 122
 123 endfunction
 124
 125
 126 %!test
 127 %! x = -10:10;
 128 %! y = x';
 129 %! z = [y, y+10];
 130 %! assert(mean (x) == 0);
 131 %! assert(mean (y) == 0);
 132 %! assert(mean (z) == [0, 10]);
 133
 134 %!assert(mean (magic(3), 1), [5, 5, 5]);
 135 %!assert(mean (magic(3), 2), [5; 5; 5]);
 136 %!assert(mean ([2 8], 'g'), 4);
 137 %!assert(mean ([4 4 2], 'h'), 3);
 138 %!assert(mean (logical ([1 0 1 1])), 0.75);
 139 %!assert(mean (single ([1 0 1 1])), single (0.75));
 140
 141 %% Test input validation
 142 %!error mean ();
 143 %!error mean (1, 2, 3, 4);
 144 %!error mean ({1:5});
 145 %!error mean (1, 2, 3);
 146 %!error mean (1, ones(2,2));
 147 %!error mean (1, 1.5);
 148 %!error mean (1, 0);
 149 %!error mean (1, 3);
 150 %!error mean (1, 'b');
 151