Mercurial > octave
annotate scripts/statistics/base/mean.m @ 20174:d9341b422488 stable
doc: Update more docstrings to have one sentence summary as first line.
Reviewed statistics/ and @ftp/ in scripts directory.
* scripts/@ftp/ascii.m, scripts/@ftp/binary.m, scripts/@ftp/cd.m,
scripts/@ftp/dir.m, scripts/@ftp/ftp.m, scripts/@ftp/mget.m,
scripts/@ftp/mput.m, scripts/statistics/base/center.m,
scripts/statistics/base/cloglog.m, scripts/statistics/base/cov.m,
scripts/statistics/base/gls.m, scripts/statistics/base/histc.m,
scripts/statistics/base/iqr.m, scripts/statistics/base/kendall.m,
scripts/statistics/base/kurtosis.m, scripts/statistics/base/logit.m,
scripts/statistics/base/lscov.m, scripts/statistics/base/mahalanobis.m,
scripts/statistics/base/mean.m, scripts/statistics/base/meansq.m,
scripts/statistics/base/median.m, scripts/statistics/base/mode.m,
scripts/statistics/base/moment.m, scripts/statistics/base/ols.m,
scripts/statistics/base/ppplot.m, scripts/statistics/base/prctile.m,
scripts/statistics/base/probit.m, scripts/statistics/base/range.m,
scripts/statistics/base/ranks.m, scripts/statistics/base/run_count.m,
scripts/statistics/base/runlength.m, scripts/statistics/base/skewness.m,
scripts/statistics/base/spearman.m, scripts/statistics/base/statistics.m,
scripts/statistics/base/std.m, scripts/statistics/base/table.m,
scripts/statistics/base/var.m, scripts/statistics/base/zscore.m,
scripts/statistics/distributions/betainv.m,
scripts/statistics/distributions/binoinv.m,
scripts/statistics/distributions/binopdf.m,
scripts/statistics/distributions/cauchy_cdf.m,
scripts/statistics/distributions/cauchy_inv.m,
scripts/statistics/distributions/cauchy_pdf.m,
scripts/statistics/distributions/chi2cdf.m,
scripts/statistics/distributions/chi2inv.m,
scripts/statistics/distributions/chi2pdf.m,
scripts/statistics/distributions/discrete_cdf.m,
scripts/statistics/distributions/discrete_inv.m,
scripts/statistics/distributions/discrete_pdf.m,
scripts/statistics/distributions/empirical_cdf.m,
scripts/statistics/distributions/empirical_inv.m,
scripts/statistics/distributions/empirical_pdf.m,
scripts/statistics/distributions/expcdf.m,
scripts/statistics/distributions/expinv.m,
scripts/statistics/distributions/exppdf.m,
scripts/statistics/distributions/finv.m,
scripts/statistics/distributions/fpdf.m,
scripts/statistics/distributions/gamcdf.m,
scripts/statistics/distributions/gaminv.m,
scripts/statistics/distributions/gampdf.m,
scripts/statistics/distributions/geoinv.m,
scripts/statistics/distributions/geopdf.m,
scripts/statistics/distributions/hygecdf.m,
scripts/statistics/distributions/hygeinv.m,
scripts/statistics/distributions/hygepdf.m,
scripts/statistics/distributions/kolmogorov_smirnov_cdf.m,
scripts/statistics/distributions/laplace_cdf.m,
scripts/statistics/distributions/laplace_inv.m,
scripts/statistics/distributions/laplace_pdf.m,
scripts/statistics/distributions/logistic_inv.m,
scripts/statistics/distributions/logncdf.m,
scripts/statistics/distributions/logninv.m,
scripts/statistics/distributions/lognpdf.m,
scripts/statistics/distributions/nbincdf.m,
scripts/statistics/distributions/nbininv.m,
scripts/statistics/distributions/nbinpdf.m,
scripts/statistics/distributions/nbinrnd.m,
scripts/statistics/distributions/normcdf.m,
scripts/statistics/distributions/norminv.m,
scripts/statistics/distributions/normpdf.m,
scripts/statistics/distributions/poisscdf.m,
scripts/statistics/distributions/poissinv.m,
scripts/statistics/distributions/poisspdf.m,
scripts/statistics/distributions/stdnormal_cdf.m,
scripts/statistics/distributions/stdnormal_pdf.m,
scripts/statistics/distributions/tcdf.m,
scripts/statistics/distributions/tinv.m,
scripts/statistics/distributions/tpdf.m,
scripts/statistics/distributions/unidcdf.m,
scripts/statistics/distributions/unidinv.m,
scripts/statistics/distributions/unidpdf.m,
scripts/statistics/distributions/unidrnd.m,
scripts/statistics/distributions/unifcdf.m,
scripts/statistics/distributions/unifinv.m,
scripts/statistics/distributions/wblcdf.m,
scripts/statistics/distributions/wblinv.m,
scripts/statistics/distributions/wblpdf.m,
scripts/statistics/distributions/wienrnd.m,
scripts/statistics/models/private/logistic_regression_derivatives.m,
scripts/statistics/models/private/logistic_regression_likelihood.m,
scripts/statistics/tests/anova.m,
scripts/statistics/tests/chisquare_test_homogeneity.m,
scripts/statistics/tests/chisquare_test_independence.m,
scripts/statistics/tests/cor_test.m,
scripts/statistics/tests/f_test_regression.m,
scripts/statistics/tests/hotelling_test.m,
scripts/statistics/tests/kolmogorov_smirnov_test.m,
scripts/statistics/tests/kolmogorov_smirnov_test_2.m,
scripts/statistics/tests/kruskal_wallis_test.m,
scripts/statistics/tests/manova.m, scripts/statistics/tests/mcnemar_test.m,
scripts/statistics/tests/prop_test_2.m, scripts/statistics/tests/run_test.m,
scripts/statistics/tests/sign_test.m, scripts/statistics/tests/t_test.m,
scripts/statistics/tests/t_test_2.m,
scripts/statistics/tests/t_test_regression.m,
scripts/statistics/tests/u_test.m, scripts/statistics/tests/var_test.m,
scripts/statistics/tests/welch_test.m,
scripts/statistics/tests/wilcoxon_test.m, scripts/statistics/tests/z_test.m,
scripts/statistics/tests/z_test_2.m:
Update more docstrings to have one sentence summary as first line.
author | Rik <rik@octave.org> |
---|---|
date | Sun, 10 May 2015 16:07:41 -0700 |
parents | 9fc020886ae9 |
children | 516bb87ea72e |
rev | line source |
---|---|
19697
4197fc428c7d
maint: Update copyright notices for 2015.
John W. Eaton <jwe@octave.org>
parents:
17744
diff
changeset
|
1 ## Copyright (C) 1995-2015 Kurt Hornik |
3426 | 2 ## |
3922 | 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 | |
7016 | 7 ## the Free Software Foundation; either version 3 of the License, or (at |
8 ## your option) any later version. | |
3426 | 9 ## |
3922 | 10 ## Octave is distributed in the hope that it will be useful, but |
3200 | 11 ## WITHOUT ANY WARRANTY; without even the implied warranty of |
12 ## MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU | |
3426 | 13 ## General Public License for more details. |
14 ## | |
3200 | 15 ## You should have received a copy of the GNU General Public License |
7016 | 16 ## along with Octave; see the file COPYING. If not, see |
17 ## <http://www.gnu.org/licenses/>. | |
3200 | 18 |
3367 | 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}. |
20174
d9341b422488
doc: Update more docstrings to have one sentence summary as first line.
Rik <rik@octave.org>
parents:
19833
diff
changeset
|
25 ## |
d9341b422488
doc: Update more docstrings to have one sentence summary as first line.
Rik <rik@octave.org>
parents:
19833
diff
changeset
|
26 ## The mean is defined as |
d9341b422488
doc: Update more docstrings to have one sentence summary as first line.
Rik <rik@octave.org>
parents:
19833
diff
changeset
|
27 ## |
3367 | 28 ## @tex |
29 ## $$ {\rm mean}(x) = \bar{x} = {1\over N} \sum_{i=1}^N x_i $$ | |
30 ## @end tex | |
8517
81d6ab3ac93c
Allow documentation tobe built for other formats than tex and info
sh@sh-laptop
parents:
7411
diff
changeset
|
31 ## @ifnottex |
3426 | 32 ## |
3367 | 33 ## @example |
34 ## mean (x) = SUM_i x(i) / N | |
35 ## @end example | |
10821
693e22af08ae
Grammarcheck documentation of m-files
Rik <octave@nomad.inbox5.com>
parents:
10687
diff
changeset
|
36 ## |
8517
81d6ab3ac93c
Allow documentation tobe built for other formats than tex and info
sh@sh-laptop
parents:
7411
diff
changeset
|
37 ## @end ifnottex |
3367 | 38 ## If @var{x} is a matrix, compute the mean for each column and return them |
39 ## in a row vector. | |
3200 | 40 ## |
20174
d9341b422488
doc: Update more docstrings to have one sentence summary as first line.
Rik <rik@octave.org>
parents:
19833
diff
changeset
|
41 ## If the optional argument @var{dim} is given, operate along this dimension. |
d9341b422488
doc: Update more docstrings to have one sentence summary as first line.
Rik <rik@octave.org>
parents:
19833
diff
changeset
|
42 ## |
10687
a8ce6bdecce5
Improve documentation strings.
Rik <octave@nomad.inbox5.com>
parents:
9211
diff
changeset
|
43 ## 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
|
44 ## The following options are recognized: |
3367 | 45 ## |
11595
5ec6aa05638d
Prevent doubled quotes around @table items in Info.
Rik <octave@nomad.inbox5.com>
parents:
11587
diff
changeset
|
46 ## @table @asis |
17281
bc924baa2c4e
doc: Add new @qcode macro for code samples which are quoted.
Rik <rik@octave.org>
parents:
15467
diff
changeset
|
47 ## @item @qcode{"a"} |
10687
a8ce6bdecce5
Improve documentation strings.
Rik <octave@nomad.inbox5.com>
parents:
9211
diff
changeset
|
48 ## Compute the (ordinary) arithmetic mean. [default] |
3367 | 49 ## |
17281
bc924baa2c4e
doc: Add new @qcode macro for code samples which are quoted.
Rik <rik@octave.org>
parents:
15467
diff
changeset
|
50 ## @item @qcode{"g"} |
7001 | 51 ## Compute the geometric mean. |
3367 | 52 ## |
17281
bc924baa2c4e
doc: Add new @qcode macro for code samples which are quoted.
Rik <rik@octave.org>
parents:
15467
diff
changeset
|
53 ## @item @qcode{"h"} |
3367 | 54 ## Compute the harmonic mean. |
55 ## @end table | |
4022 | 56 ## |
20174
d9341b422488
doc: Update more docstrings to have one sentence summary as first line.
Rik <rik@octave.org>
parents:
19833
diff
changeset
|
57 ## Both @var{dim} and @var{opt} are optional. If both are supplied, either |
d9341b422488
doc: Update more docstrings to have one sentence summary as first line.
Rik <rik@octave.org>
parents:
19833
diff
changeset
|
58 ## may appear first. |
12575
d0b799dafede
Grammarcheck files for 3.4.1 release.
Rik <octave@nomad.inbox5.com>
parents:
12454
diff
changeset
|
59 ## @seealso{median, mode} |
3367 | 60 ## @end deftypefn |
3426 | 61 |
5428 | 62 ## Author: KH <Kurt.Hornik@wu-wien.ac.at> |
3456 | 63 ## Description: Compute arithmetic, geometric, and harmonic mean |
3200 | 64 |
4022 | 65 function y = mean (x, opt1, opt2) |
66 | |
11436
e151e23f73bc
Overhaul base statistics functions and documentation of same.
Rik <octave@nomad.inbox5.com>
parents:
10821
diff
changeset
|
67 if (nargin < 1 || nargin > 3) |
e151e23f73bc
Overhaul base statistics functions and documentation of same.
Rik <octave@nomad.inbox5.com>
parents:
10821
diff
changeset
|
68 print_usage (); |
e151e23f73bc
Overhaul base statistics functions and documentation of same.
Rik <octave@nomad.inbox5.com>
parents:
10821
diff
changeset
|
69 endif |
e151e23f73bc
Overhaul base statistics functions and documentation of same.
Rik <octave@nomad.inbox5.com>
parents:
10821
diff
changeset
|
70 |
12435
0f21f258aa17
mean: also accept logical values
John W. Eaton <jwe@octave.org>
parents:
11595
diff
changeset
|
71 if (! (isnumeric (x) || islogical (x))) |
11436
e151e23f73bc
Overhaul base statistics functions and documentation of same.
Rik <octave@nomad.inbox5.com>
parents:
10821
diff
changeset
|
72 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
|
73 endif |
e151e23f73bc
Overhaul base statistics functions and documentation of same.
Rik <octave@nomad.inbox5.com>
parents:
10821
diff
changeset
|
74 |
12656
6b2f14af2360
Overhaul functions in statistics/base directory.
Rik <octave@nomad.inbox5.com>
parents:
12575
diff
changeset
|
75 need_dim = false; |
3200 | 76 |
4022 | 77 if (nargin == 1) |
78 opt = "a"; | |
12656
6b2f14af2360
Overhaul functions in statistics/base directory.
Rik <octave@nomad.inbox5.com>
parents:
12575
diff
changeset
|
79 need_dim = true; |
4022 | 80 elseif (nargin == 2) |
5443 | 81 if (ischar (opt1)) |
4022 | 82 opt = opt1; |
12656
6b2f14af2360
Overhaul functions in statistics/base directory.
Rik <octave@nomad.inbox5.com>
parents:
12575
diff
changeset
|
83 need_dim = true; |
4022 | 84 else |
4525 | 85 dim = opt1; |
4022 | 86 opt = "a"; |
87 endif | |
88 elseif (nargin == 3) | |
5443 | 89 if (ischar (opt1)) |
4022 | 90 opt = opt1; |
91 dim = opt2; | |
5443 | 92 elseif (ischar (opt2)) |
4022 | 93 opt = opt2; |
94 dim = opt1; | |
95 else | |
11436
e151e23f73bc
Overhaul base statistics functions and documentation of same.
Rik <octave@nomad.inbox5.com>
parents:
10821
diff
changeset
|
96 error ("mean: OPT must be a string"); |
4022 | 97 endif |
98 else | |
6046 | 99 print_usage (); |
3200 | 100 endif |
3426 | 101 |
11436
e151e23f73bc
Overhaul base statistics functions and documentation of same.
Rik <octave@nomad.inbox5.com>
parents:
10821
diff
changeset
|
102 nd = ndims (x); |
e151e23f73bc
Overhaul base statistics functions and documentation of same.
Rik <octave@nomad.inbox5.com>
parents:
10821
diff
changeset
|
103 sz = size (x); |
4022 | 104 if (need_dim) |
11436
e151e23f73bc
Overhaul base statistics functions and documentation of same.
Rik <octave@nomad.inbox5.com>
parents:
10821
diff
changeset
|
105 ## Find the first non-singleton dimension. |
12656
6b2f14af2360
Overhaul functions in statistics/base directory.
Rik <octave@nomad.inbox5.com>
parents:
12575
diff
changeset
|
106 (dim = find (sz > 1, 1)) || (dim = 1); |
6b2f14af2360
Overhaul functions in statistics/base directory.
Rik <octave@nomad.inbox5.com>
parents:
12575
diff
changeset
|
107 else |
6b2f14af2360
Overhaul functions in statistics/base directory.
Rik <octave@nomad.inbox5.com>
parents:
12575
diff
changeset
|
108 if (!(isscalar (dim) && dim == fix (dim)) |
6b2f14af2360
Overhaul functions in statistics/base directory.
Rik <octave@nomad.inbox5.com>
parents:
12575
diff
changeset
|
109 || !(1 <= dim && dim <= nd)) |
6b2f14af2360
Overhaul functions in statistics/base directory.
Rik <octave@nomad.inbox5.com>
parents:
12575
diff
changeset
|
110 error ("mean: DIM must be an integer and a valid dimension"); |
4022 | 111 endif |
3200 | 112 endif |
113 | |
12656
6b2f14af2360
Overhaul functions in statistics/base directory.
Rik <octave@nomad.inbox5.com>
parents:
12575
diff
changeset
|
114 n = sz(dim); |
3426 | 115 |
3200 | 116 if (strcmp (opt, "a")) |
4022 | 117 y = sum (x, dim) / n; |
3200 | 118 elseif (strcmp (opt, "g")) |
15464
930117c97760
mean.m: improve geometric mean algorithm for small numbers. Add test.
Jordi Gutiérrez Hermoso <jordigh@octave.org>
parents:
14868
diff
changeset
|
119 if (all (x(:) >= 0)) |
930117c97760
mean.m: improve geometric mean algorithm for small numbers. Add test.
Jordi Gutiérrez Hermoso <jordigh@octave.org>
parents:
14868
diff
changeset
|
120 y = exp (sum (log (x), dim) ./ n); |
930117c97760
mean.m: improve geometric mean algorithm for small numbers. Add test.
Jordi Gutiérrez Hermoso <jordigh@octave.org>
parents:
14868
diff
changeset
|
121 else |
930117c97760
mean.m: improve geometric mean algorithm for small numbers. Add test.
Jordi Gutiérrez Hermoso <jordigh@octave.org>
parents:
14868
diff
changeset
|
122 error ("mean: X must not contain any negative values"); |
930117c97760
mean.m: improve geometric mean algorithm for small numbers. Add test.
Jordi Gutiérrez Hermoso <jordigh@octave.org>
parents:
14868
diff
changeset
|
123 endif |
3200 | 124 elseif (strcmp (opt, "h")) |
4022 | 125 y = n ./ sum (1 ./ x, dim); |
3200 | 126 else |
15466
d174210ce1ec
use ' instead of ` in error messages, warnings and most comments
John W. Eaton <jwe@octave.org>
parents:
14138
diff
changeset
|
127 error ("mean: option '%s' not recognized", opt); |
3200 | 128 endif |
3426 | 129 |
3200 | 130 endfunction |
7411 | 131 |
12656
6b2f14af2360
Overhaul functions in statistics/base directory.
Rik <octave@nomad.inbox5.com>
parents:
12575
diff
changeset
|
132 |
7411 | 133 %!test |
134 %! x = -10:10; | |
135 %! y = x'; | |
136 %! z = [y, y+10]; | |
14363
f3d52523cde1
Use Octave coding conventions in all m-file %!test blocks
Rik <octave@nomad.inbox5.com>
parents:
14138
diff
changeset
|
137 %! assert (mean (x), 0); |
f3d52523cde1
Use Octave coding conventions in all m-file %!test blocks
Rik <octave@nomad.inbox5.com>
parents:
14138
diff
changeset
|
138 %! assert (mean (y), 0); |
f3d52523cde1
Use Octave coding conventions in all m-file %!test blocks
Rik <octave@nomad.inbox5.com>
parents:
14138
diff
changeset
|
139 %! assert (mean (z), [0, 10]); |
7411 | 140 |
15464
930117c97760
mean.m: improve geometric mean algorithm for small numbers. Add test.
Jordi Gutiérrez Hermoso <jordigh@octave.org>
parents:
14868
diff
changeset
|
141 ## Test small numbers |
930117c97760
mean.m: improve geometric mean algorithm for small numbers. Add test.
Jordi Gutiérrez Hermoso <jordigh@octave.org>
parents:
14868
diff
changeset
|
142 %!assert (mean (repmat (0.1,1,1000), "g"), 0.1, 20*eps) |
7411 | 143 |
14363
f3d52523cde1
Use Octave coding conventions in all m-file %!test blocks
Rik <octave@nomad.inbox5.com>
parents:
14138
diff
changeset
|
144 %!assert (mean (magic (3), 1), [5, 5, 5]) |
f3d52523cde1
Use Octave coding conventions in all m-file %!test blocks
Rik <octave@nomad.inbox5.com>
parents:
14138
diff
changeset
|
145 %!assert (mean (magic (3), 2), [5; 5; 5]) |
f3d52523cde1
Use Octave coding conventions in all m-file %!test blocks
Rik <octave@nomad.inbox5.com>
parents:
14138
diff
changeset
|
146 %!assert (mean ([2 8], "g"), 4) |
f3d52523cde1
Use Octave coding conventions in all m-file %!test blocks
Rik <octave@nomad.inbox5.com>
parents:
14138
diff
changeset
|
147 %!assert (mean ([4 4 2], "h"), 3) |
f3d52523cde1
Use Octave coding conventions in all m-file %!test blocks
Rik <octave@nomad.inbox5.com>
parents:
14138
diff
changeset
|
148 %!assert (mean (logical ([1 0 1 1])), 0.75) |
f3d52523cde1
Use Octave coding conventions in all m-file %!test blocks
Rik <octave@nomad.inbox5.com>
parents:
14138
diff
changeset
|
149 %!assert (mean (single ([1 0 1 1])), single (0.75)) |
11436
e151e23f73bc
Overhaul base statistics functions and documentation of same.
Rik <octave@nomad.inbox5.com>
parents:
10821
diff
changeset
|
150 |
19833
9fc020886ae9
maint: Clean up m-files to follow Octave coding conventions.
Rik <rik@octave.org>
parents:
19697
diff
changeset
|
151 ## Test input validation |
14363
f3d52523cde1
Use Octave coding conventions in all m-file %!test blocks
Rik <octave@nomad.inbox5.com>
parents:
14138
diff
changeset
|
152 %!error mean () |
f3d52523cde1
Use Octave coding conventions in all m-file %!test blocks
Rik <octave@nomad.inbox5.com>
parents:
14138
diff
changeset
|
153 %!error mean (1, 2, 3, 4) |
f3d52523cde1
Use Octave coding conventions in all m-file %!test blocks
Rik <octave@nomad.inbox5.com>
parents:
14138
diff
changeset
|
154 %!error mean ({1:5}) |
f3d52523cde1
Use Octave coding conventions in all m-file %!test blocks
Rik <octave@nomad.inbox5.com>
parents:
14138
diff
changeset
|
155 %!error mean (1, 2, 3) |
14868
5d3a684236b0
maint: Use Octave coding conventions for cuddling parentheses in scripts directory
Rik <octave@nomad.inbox5.com>
parents:
14363
diff
changeset
|
156 %!error mean (1, ones (2,2)) |
14363
f3d52523cde1
Use Octave coding conventions in all m-file %!test blocks
Rik <octave@nomad.inbox5.com>
parents:
14138
diff
changeset
|
157 %!error mean (1, 1.5) |
f3d52523cde1
Use Octave coding conventions in all m-file %!test blocks
Rik <octave@nomad.inbox5.com>
parents:
14138
diff
changeset
|
158 %!error mean (1, 0) |
f3d52523cde1
Use Octave coding conventions in all m-file %!test blocks
Rik <octave@nomad.inbox5.com>
parents:
14138
diff
changeset
|
159 %!error mean (1, 3) |
f3d52523cde1
Use Octave coding conventions in all m-file %!test blocks
Rik <octave@nomad.inbox5.com>
parents:
14138
diff
changeset
|
160 %!error mean (1, "b") |
7411 | 161 |