Mercurial > octave
annotate scripts/statistics/base/mean.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 |
rev | line source |
---|---|
7017 | 1 ## Copyright (C) 1995, 1996, 1997, 1998, 1999, 2000, 2002, 2003, 2005, |
8920 | 2 ## 2006, 2007, 2008, 2009 Kurt Hornik |
3426 | 3 ## |
3922 | 4 ## This file is part of Octave. |
5 ## | |
6 ## Octave is free software; you can redistribute it and/or modify it | |
7 ## under the terms of the GNU General Public License as published by | |
7016 | 8 ## the Free Software Foundation; either version 3 of the License, or (at |
9 ## your option) any later version. | |
3426 | 10 ## |
3922 | 11 ## Octave is distributed in the hope that it will be useful, but |
3200 | 12 ## WITHOUT ANY WARRANTY; without even the implied warranty of |
13 ## MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU | |
3426 | 14 ## General Public License for more details. |
15 ## | |
3200 | 16 ## You should have received a copy of the GNU General Public License |
7016 | 17 ## along with Octave; see the file COPYING. If not, see |
18 ## <http://www.gnu.org/licenses/>. | |
3200 | 19 |
3367 | 20 ## -*- texinfo -*- |
10687
a8ce6bdecce5
Improve documentation strings.
Rik <octave@nomad.inbox5.com>
parents:
9211
diff
changeset
|
21 ## @deftypefn {Function File} {} mean (@var{x}) |
a8ce6bdecce5
Improve documentation strings.
Rik <octave@nomad.inbox5.com>
parents:
9211
diff
changeset
|
22 ## @deftypefnx {Function File} {} mean (@var{x}, @var{dim}) |
a8ce6bdecce5
Improve documentation strings.
Rik <octave@nomad.inbox5.com>
parents:
9211
diff
changeset
|
23 ## @deftypefnx {Function File} {} mean (@var{x}, @var{opt}) |
a8ce6bdecce5
Improve documentation strings.
Rik <octave@nomad.inbox5.com>
parents:
9211
diff
changeset
|
24 ## @deftypefnx {Function File} {} mean (@var{x}, @var{dim}, @var{opt}) |
11436
e151e23f73bc
Overhaul base statistics functions and documentation of same.
Rik <octave@nomad.inbox5.com>
parents:
10821
diff
changeset
|
25 ## Compute the mean of the elements of the vector @var{x}. |
3367 | 26 ## @tex |
27 ## $$ {\rm mean}(x) = \bar{x} = {1\over N} \sum_{i=1}^N x_i $$ | |
28 ## @end tex | |
8517
81d6ab3ac93c
Allow documentation tobe built for other formats than tex and info
sh@sh-laptop
parents:
7411
diff
changeset
|
29 ## @ifnottex |
3426 | 30 ## |
3367 | 31 ## @example |
32 ## mean (x) = SUM_i x(i) / N | |
33 ## @end example | |
10821
693e22af08ae
Grammarcheck documentation of m-files
Rik <octave@nomad.inbox5.com>
parents:
10687
diff
changeset
|
34 ## |
8517
81d6ab3ac93c
Allow documentation tobe built for other formats than tex and info
sh@sh-laptop
parents:
7411
diff
changeset
|
35 ## @end ifnottex |
3367 | 36 ## If @var{x} is a matrix, compute the mean for each column and return them |
37 ## in a row vector. | |
3200 | 38 ## |
10687
a8ce6bdecce5
Improve documentation strings.
Rik <octave@nomad.inbox5.com>
parents:
9211
diff
changeset
|
39 ## The optional argument @var{opt} selects the type of mean to compute. |
a8ce6bdecce5
Improve documentation strings.
Rik <octave@nomad.inbox5.com>
parents:
9211
diff
changeset
|
40 ## The following options are recognized: |
3367 | 41 ## |
42 ## @table @code | |
43 ## @item "a" | |
10687
a8ce6bdecce5
Improve documentation strings.
Rik <octave@nomad.inbox5.com>
parents:
9211
diff
changeset
|
44 ## Compute the (ordinary) arithmetic mean. [default] |
3367 | 45 ## |
46 ## @item "g" | |
7001 | 47 ## Compute the geometric mean. |
3367 | 48 ## |
49 ## @item "h" | |
50 ## Compute the harmonic mean. | |
51 ## @end table | |
4022 | 52 ## |
11436
e151e23f73bc
Overhaul base statistics functions and documentation of same.
Rik <octave@nomad.inbox5.com>
parents:
10821
diff
changeset
|
53 ## If the optional argument @var{dim} is given, operate along this dimension. |
4022 | 54 ## |
55 ## Both @var{dim} and @var{opt} are optional. If both are supplied, | |
56 ## either may appear first. | |
10687
a8ce6bdecce5
Improve documentation strings.
Rik <octave@nomad.inbox5.com>
parents:
9211
diff
changeset
|
57 ## @seealso{median,mode} |
3367 | 58 ## @end deftypefn |
3426 | 59 |
5428 | 60 ## Author: KH <Kurt.Hornik@wu-wien.ac.at> |
3456 | 61 ## Description: Compute arithmetic, geometric, and harmonic mean |
3200 | 62 |
4022 | 63 function y = mean (x, opt1, opt2) |
64 | |
11436
e151e23f73bc
Overhaul base statistics functions and documentation of same.
Rik <octave@nomad.inbox5.com>
parents:
10821
diff
changeset
|
65 if (nargin < 1 || nargin > 3) |
e151e23f73bc
Overhaul base statistics functions and documentation of same.
Rik <octave@nomad.inbox5.com>
parents:
10821
diff
changeset
|
66 print_usage (); |
e151e23f73bc
Overhaul base statistics functions and documentation of same.
Rik <octave@nomad.inbox5.com>
parents:
10821
diff
changeset
|
67 endif |
e151e23f73bc
Overhaul base statistics functions and documentation of same.
Rik <octave@nomad.inbox5.com>
parents:
10821
diff
changeset
|
68 |
e151e23f73bc
Overhaul base statistics functions and documentation of same.
Rik <octave@nomad.inbox5.com>
parents:
10821
diff
changeset
|
69 if (!isnumeric (x)) |
e151e23f73bc
Overhaul base statistics functions and documentation of same.
Rik <octave@nomad.inbox5.com>
parents:
10821
diff
changeset
|
70 error ("mean: X must be a numeric vector or matrix"); |
e151e23f73bc
Overhaul base statistics functions and documentation of same.
Rik <octave@nomad.inbox5.com>
parents:
10821
diff
changeset
|
71 endif |
e151e23f73bc
Overhaul base statistics functions and documentation of same.
Rik <octave@nomad.inbox5.com>
parents:
10821
diff
changeset
|
72 |
4022 | 73 need_dim = 0; |
3200 | 74 |
4022 | 75 if (nargin == 1) |
76 opt = "a"; | |
77 need_dim = 1; | |
78 elseif (nargin == 2) | |
5443 | 79 if (ischar (opt1)) |
4022 | 80 opt = opt1; |
81 need_dim = 1; | |
82 else | |
4525 | 83 dim = opt1; |
4022 | 84 opt = "a"; |
85 endif | |
86 elseif (nargin == 3) | |
5443 | 87 if (ischar (opt1)) |
4022 | 88 opt = opt1; |
89 dim = opt2; | |
5443 | 90 elseif (ischar (opt2)) |
4022 | 91 opt = opt2; |
92 dim = opt1; | |
93 else | |
11436
e151e23f73bc
Overhaul base statistics functions and documentation of same.
Rik <octave@nomad.inbox5.com>
parents:
10821
diff
changeset
|
94 error ("mean: OPT must be a string"); |
4022 | 95 endif |
96 else | |
6046 | 97 print_usage (); |
3200 | 98 endif |
3426 | 99 |
11436
e151e23f73bc
Overhaul base statistics functions and documentation of same.
Rik <octave@nomad.inbox5.com>
parents:
10821
diff
changeset
|
100 nd = ndims (x); |
e151e23f73bc
Overhaul base statistics functions and documentation of same.
Rik <octave@nomad.inbox5.com>
parents:
10821
diff
changeset
|
101 sz = size (x); |
4022 | 102 if (need_dim) |
11436
e151e23f73bc
Overhaul base statistics functions and documentation of same.
Rik <octave@nomad.inbox5.com>
parents:
10821
diff
changeset
|
103 ## Find the first non-singleton dimension. |
e151e23f73bc
Overhaul base statistics functions and documentation of same.
Rik <octave@nomad.inbox5.com>
parents:
10821
diff
changeset
|
104 dim = find (sz > 1, 1); |
e151e23f73bc
Overhaul base statistics functions and documentation of same.
Rik <octave@nomad.inbox5.com>
parents:
10821
diff
changeset
|
105 if (isempty (dim)) |
4022 | 106 dim = 1; |
107 endif | |
3200 | 108 endif |
109 | |
11436
e151e23f73bc
Overhaul base statistics functions and documentation of same.
Rik <octave@nomad.inbox5.com>
parents:
10821
diff
changeset
|
110 if (!(isscalar (dim) && dim == fix (dim)) |
e151e23f73bc
Overhaul base statistics functions and documentation of same.
Rik <octave@nomad.inbox5.com>
parents:
10821
diff
changeset
|
111 || !(1 <= dim && dim <= nd)) |
e151e23f73bc
Overhaul base statistics functions and documentation of same.
Rik <octave@nomad.inbox5.com>
parents:
10821
diff
changeset
|
112 error ("mean: DIM must be an integer and a valid dimension"); |
e151e23f73bc
Overhaul base statistics functions and documentation of same.
Rik <octave@nomad.inbox5.com>
parents:
10821
diff
changeset
|
113 endif |
e151e23f73bc
Overhaul base statistics functions and documentation of same.
Rik <octave@nomad.inbox5.com>
parents:
10821
diff
changeset
|
114 |
e151e23f73bc
Overhaul base statistics functions and documentation of same.
Rik <octave@nomad.inbox5.com>
parents:
10821
diff
changeset
|
115 if (dim > nd) |
5243 | 116 n = 1; |
11436
e151e23f73bc
Overhaul base statistics functions and documentation of same.
Rik <octave@nomad.inbox5.com>
parents:
10821
diff
changeset
|
117 else |
e151e23f73bc
Overhaul base statistics functions and documentation of same.
Rik <octave@nomad.inbox5.com>
parents:
10821
diff
changeset
|
118 n = sz(dim); |
5243 | 119 endif |
3426 | 120 |
3200 | 121 if (strcmp (opt, "a")) |
4022 | 122 y = sum (x, dim) / n; |
3200 | 123 elseif (strcmp (opt, "g")) |
8976
22a7e4690742
adjust some stats funcs
Jaroslav Hajek <highegg@gmail.com>
parents:
8920
diff
changeset
|
124 y = prod (x, dim) .^ (1/n); |
3200 | 125 elseif (strcmp (opt, "h")) |
4022 | 126 y = n ./ sum (1 ./ x, dim); |
3200 | 127 else |
3456 | 128 error ("mean: option `%s' not recognized", opt); |
3200 | 129 endif |
3426 | 130 |
3200 | 131 endfunction |
7411 | 132 |
133 %!test | |
134 %! x = -10:10; | |
135 %! y = x'; | |
136 %! z = [y, y+10]; | |
11436
e151e23f73bc
Overhaul base statistics functions and documentation of same.
Rik <octave@nomad.inbox5.com>
parents:
10821
diff
changeset
|
137 %! assert(mean (x) == 0); |
e151e23f73bc
Overhaul base statistics functions and documentation of same.
Rik <octave@nomad.inbox5.com>
parents:
10821
diff
changeset
|
138 %! assert(mean (y) == 0); |
e151e23f73bc
Overhaul base statistics functions and documentation of same.
Rik <octave@nomad.inbox5.com>
parents:
10821
diff
changeset
|
139 %! assert(mean (z) == [0, 10]); |
7411 | 140 |
11436
e151e23f73bc
Overhaul base statistics functions and documentation of same.
Rik <octave@nomad.inbox5.com>
parents:
10821
diff
changeset
|
141 %!assert(mean ([2 8], 'g'), 4); |
e151e23f73bc
Overhaul base statistics functions and documentation of same.
Rik <octave@nomad.inbox5.com>
parents:
10821
diff
changeset
|
142 %!assert(mean ([4 4 2], 'h'), 3); |
e151e23f73bc
Overhaul base statistics functions and documentation of same.
Rik <octave@nomad.inbox5.com>
parents:
10821
diff
changeset
|
143 |
e151e23f73bc
Overhaul base statistics functions and documentation of same.
Rik <octave@nomad.inbox5.com>
parents:
10821
diff
changeset
|
144 %% Test input validation |
7411 | 145 %!error mean (); |
11436
e151e23f73bc
Overhaul base statistics functions and documentation of same.
Rik <octave@nomad.inbox5.com>
parents:
10821
diff
changeset
|
146 %!error mean (1, 2, 3, 4); |
e151e23f73bc
Overhaul base statistics functions and documentation of same.
Rik <octave@nomad.inbox5.com>
parents:
10821
diff
changeset
|
147 %!error mean ({1:5}); |
e151e23f73bc
Overhaul base statistics functions and documentation of same.
Rik <octave@nomad.inbox5.com>
parents:
10821
diff
changeset
|
148 %!error mean (true(1, 5)); |
7411 | 149 %!error mean (1, 2, 3); |
11436
e151e23f73bc
Overhaul base statistics functions and documentation of same.
Rik <octave@nomad.inbox5.com>
parents:
10821
diff
changeset
|
150 %!error mean (1, ones(2,2)); |
e151e23f73bc
Overhaul base statistics functions and documentation of same.
Rik <octave@nomad.inbox5.com>
parents:
10821
diff
changeset
|
151 %!error mean (1, 1.5); |
e151e23f73bc
Overhaul base statistics functions and documentation of same.
Rik <octave@nomad.inbox5.com>
parents:
10821
diff
changeset
|
152 %!error mean (1, 0); |
e151e23f73bc
Overhaul base statistics functions and documentation of same.
Rik <octave@nomad.inbox5.com>
parents:
10821
diff
changeset
|
153 %!error mean (1, 3); |
e151e23f73bc
Overhaul base statistics functions and documentation of same.
Rik <octave@nomad.inbox5.com>
parents:
10821
diff
changeset
|
154 %!error mean (1, 'b'); |
7411 | 155 |