octave: scripts/statistics/base/mean.m annotate

annotate scripts/statistics/base/mean.m @ 12435:0f21f258aa17

mean: also accept logical values

author	John W. Eaton <jwe@octave.org>
date	Thu, 10 Feb 2011 16:24:15 -0500
parents	5ec6aa05638d
children	9337a5c234da

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

Mercurial > octave

annotate scripts/statistics/base/mean.m @ 12435:0f21f258aa17