Mercurial > octave

annotate scripts/statistics/zscore.m @ 29359:7854d5752dd2

Find changesets by keywords (author, files, the commit message), revision number or hash, or revset expression.
maint: merge stable to default.
author John W. Eaton <jwe@octave.org>
date Wed, 10 Feb 2021 10:10:40 -0500
parents 90fea9cc9caa 0a5b15007766
children 796f54d4ddbf
Ignore whitespace changes - Everywhere: Within whitespace: At end of lines:
rev   line source
27923
bd51beb6205e update formatting of copyright notices
John W. Eaton <jwe@octave.org>
parents: 27919
diff changeset
1 ########################################################################
bd51beb6205e update formatting of copyright notices
John W. Eaton <jwe@octave.org>
parents: 27919
diff changeset
2 ##
29358
0a5b15007766 update Octave Project Developers copyright for the new year
John W. Eaton <jwe@octave.org>
parents: 27984
diff changeset
3 ## Copyright (C) 1995-2021 The Octave Project Developers
27918
b442ec6dda5c use centralized file for copyright info for individual contributors
John W. Eaton <jwe@octave.org>
parents: 26376
diff changeset
4 ##
27923
bd51beb6205e update formatting of copyright notices
John W. Eaton <jwe@octave.org>
parents: 27919
diff changeset
5 ## See the file COPYRIGHT.md in the top-level directory of this
bd51beb6205e update formatting of copyright notices
John W. Eaton <jwe@octave.org>
parents: 27919
diff changeset
6 ## distribution or <https://octave.org/copyright/>.
3426
f8dde1807dee [project @ 2000-01-13 08:40:00 by jwe]
jwe
parents: 3388
diff changeset
7 ##
3922
38c61cbf086c [project @ 2002-05-01 06:48:35 by jwe]
jwe
parents: 3458
diff changeset
8 ## This file is part of Octave.
38c61cbf086c [project @ 2002-05-01 06:48:35 by jwe]
jwe
parents: 3458
diff changeset
9 ##
24534
194eb4bd202b maint: Update punctuation for GPL v3 license text.
Rik <rik@octave.org>
parents: 23220
diff changeset
10 ## Octave is free software: you can redistribute it and/or modify it
3922
38c61cbf086c [project @ 2002-05-01 06:48:35 by jwe]
jwe
parents: 3458
diff changeset
11 ## under the terms of the GNU General Public License as published by
24534
194eb4bd202b maint: Update punctuation for GPL v3 license text.
Rik <rik@octave.org>
parents: 23220
diff changeset
12 ## the Free Software Foundation, either version 3 of the License, or
22755
3a2b891d0b33 maint: Standardize Copyright formatting.
Rik <rik@octave.org>
parents: 22323
diff changeset
13 ## (at your option) any later version.
3426
f8dde1807dee [project @ 2000-01-13 08:40:00 by jwe]
jwe
parents: 3388
diff changeset
14 ##
3922
38c61cbf086c [project @ 2002-05-01 06:48:35 by jwe]
jwe
parents: 3458
diff changeset
15 ## 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
16 ## WITHOUT ANY WARRANTY; without even the implied warranty of
22755
3a2b891d0b33 maint: Standardize Copyright formatting.
Rik <rik@octave.org>
parents: 22323
diff changeset
17 ## MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the
3a2b891d0b33 maint: Standardize Copyright formatting.
Rik <rik@octave.org>
parents: 22323
diff changeset
18 ## GNU General Public License for more details.
3426
f8dde1807dee [project @ 2000-01-13 08:40:00 by jwe]
jwe
parents: 3388
diff changeset
19 ##
3200
781c930425fd [project @ 1998-10-29 05:23:08 by jwe]
jwe
parents:
diff changeset
20 ## 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: 6046
diff changeset
21 ## along with Octave; see the file COPYING. If not, see
24534
194eb4bd202b maint: Update punctuation for GPL v3 license text.
Rik <rik@octave.org>
parents: 23220
diff changeset
22 ## <https://www.gnu.org/licenses/>.
27923
bd51beb6205e update formatting of copyright notices
John W. Eaton <jwe@octave.org>
parents: 27919
diff changeset
23 ##
bd51beb6205e update formatting of copyright notices
John W. Eaton <jwe@octave.org>
parents: 27919
diff changeset
24 ########################################################################
3200
781c930425fd [project @ 1998-10-29 05:23:08 by jwe]
jwe
parents:
diff changeset
25
3453
71d2e09c15a2 [project @ 2000-01-18 08:32:09 by jwe]
jwe
parents: 3426
diff changeset
26 ## -*- texinfo -*-
20852
516bb87ea72e 2015 Code Sprint: remove class of function from docstring for all m-files.
Rik <rik@octave.org>
parents: 20617
diff changeset
27 ## @deftypefn {} {@var{z} =} zscore (@var{x})
516bb87ea72e 2015 Code Sprint: remove class of function from docstring for all m-files.
Rik <rik@octave.org>
parents: 20617
diff changeset
28 ## @deftypefnx {} {@var{z} =} zscore (@var{x}, @var{opt})
516bb87ea72e 2015 Code Sprint: remove class of function from docstring for all m-files.
Rik <rik@octave.org>
parents: 20617
diff changeset
29 ## @deftypefnx {} {@var{z} =} zscore (@var{x}, @var{opt}, @var{dim})
516bb87ea72e 2015 Code Sprint: remove class of function from docstring for all m-files.
Rik <rik@octave.org>
parents: 20617
diff changeset
30 ## @deftypefnx {} {[@var{z}, @var{mu}, @var{sigma}] =} zscore (@dots{})
24933
75a748cb08a6 doc: end first sentences of doc strings with a period (bug #53388)
Mike Miller <mtmiller@octave.org>
parents: 24547
diff changeset
31 ## Compute the Z score of @var{x}.
20174
d9341b422488 doc: Update more docstrings to have one sentence summary as first line.
Rik <rik@octave.org>
parents: 19833
diff changeset
32 ##
3453
71d2e09c15a2 [project @ 2000-01-18 08:32:09 by jwe]
jwe
parents: 3426
diff changeset
33 ## If @var{x} is a vector, subtract its mean and divide by its standard
14366
b76f0740940e doc: Periodic grammar check of documentation.
Rik <octave@nomad.inbox5.com>
parents: 14363
diff changeset
34 ## deviation. If the standard deviation is zero, divide by 1 instead.
20174
d9341b422488 doc: Update more docstrings to have one sentence summary as first line.
Rik <rik@octave.org>
parents: 19833
diff changeset
35 ##
d9341b422488 doc: Update more docstrings to have one sentence summary as first line.
Rik <rik@octave.org>
parents: 19833
diff changeset
36 ## The optional parameter @var{opt} determines the normalization to use when
d9341b422488 doc: Update more docstrings to have one sentence summary as first line.
Rik <rik@octave.org>
parents: 19833
diff changeset
37 ## computing the standard deviation and has the same definition as the
14234
938a8d792c37 zscore.m: Return mean and std dev for Matlab compatibility. Update docstring.
Jordi Gutiérrez Hermoso <jordigh@octave.org>
parents: 14138
diff changeset
38 ## corresponding parameter for @code{std}.
3200
781c930425fd [project @ 1998-10-29 05:23:08 by jwe]
jwe
parents:
diff changeset
39 ##
20174
d9341b422488 doc: Update more docstrings to have one sentence summary as first line.
Rik <rik@octave.org>
parents: 19833
diff changeset
40 ## If @var{x} is a matrix, calculate along the first non-singleton dimension.
d9341b422488 doc: Update more docstrings to have one sentence summary as first line.
Rik <rik@octave.org>
parents: 19833
diff changeset
41 ## If the third optional argument @var{dim} is given, operate along this
d9341b422488 doc: Update more docstrings to have one sentence summary as first line.
Rik <rik@octave.org>
parents: 19833
diff changeset
42 ## dimension.
14234
938a8d792c37 zscore.m: Return mean and std dev for Matlab compatibility. Update docstring.
Jordi Gutiérrez Hermoso <jordigh@octave.org>
parents: 14138
diff changeset
43 ##
20174
d9341b422488 doc: Update more docstrings to have one sentence summary as first line.
Rik <rik@octave.org>
parents: 19833
diff changeset
44 ## The optional outputs @var{mu} and @var{sigma} contain the mean and standard
d9341b422488 doc: Update more docstrings to have one sentence summary as first line.
Rik <rik@octave.org>
parents: 19833
diff changeset
45 ## deviation.
14234
938a8d792c37 zscore.m: Return mean and std dev for Matlab compatibility. Update docstring.
Jordi Gutiérrez Hermoso <jordigh@octave.org>
parents: 14138
diff changeset
46 ##
938a8d792c37 zscore.m: Return mean and std dev for Matlab compatibility. Update docstring.
Jordi Gutiérrez Hermoso <jordigh@octave.org>
parents: 14138
diff changeset
47 ## @seealso{mean, std, center}
3453
71d2e09c15a2 [project @ 2000-01-18 08:32:09 by jwe]
jwe
parents: 3426
diff changeset
48 ## @end deftypefn
3200
781c930425fd [project @ 1998-10-29 05:23:08 by jwe]
jwe
parents:
diff changeset
49
25817
dc70b480b9c1 zscore.m: Allow an empty OPT argument to mean default (bug #54531).
Rik <rik@octave.org>
parents: 25054
diff changeset
50 function [z, mu, sigma] = zscore (x, opt = 0, dim)
3426
f8dde1807dee [project @ 2000-01-13 08:40:00 by jwe]
jwe
parents: 3388
diff changeset
51
28789
28de41192f3c Eliminate unneeded verification of nargin, nargout in m-files.
Rik <rik@octave.org>
parents: 27984
diff changeset
52 if (nargin < 1)
6046
34f96dd5441b [project @ 2006-10-10 16:10:25 by jwe]
jwe
parents: 5428
diff changeset
53 print_usage ();
3200
781c930425fd [project @ 1998-10-29 05:23:08 by jwe]
jwe
parents:
diff changeset
54 endif
781c930425fd [project @ 1998-10-29 05:23:08 by jwe]
jwe
parents:
diff changeset
55
12656
6b2f14af2360 Overhaul functions in statistics/base directory.
Rik <octave@nomad.inbox5.com>
parents: 12586
diff changeset
56 if (! (isnumeric (x) || islogical (x)))
12586
f9b7aa3b88f8 Deprecate studentize(), replace with zscore().
Rik <octave@nomad.inbox5.com>
parents: 11587
diff changeset
57 error ("zscore: X must be a numeric vector or matrix");
11436
e151e23f73bc Overhaul base statistics functions and documentation of same.
Rik <octave@nomad.inbox5.com>
parents: 11149
diff changeset
58 endif
e151e23f73bc Overhaul base statistics functions and documentation of same.
Rik <octave@nomad.inbox5.com>
parents: 11149
diff changeset
59
25817
dc70b480b9c1 zscore.m: Allow an empty OPT argument to mean default (bug #54531).
Rik <rik@octave.org>
parents: 25054
diff changeset
60 if (isempty (opt))
14234
938a8d792c37 zscore.m: Return mean and std dev for Matlab compatibility. Update docstring.
Jordi Gutiérrez Hermoso <jordigh@octave.org>
parents: 14138
diff changeset
61 opt = 0;
25817
dc70b480b9c1 zscore.m: Allow an empty OPT argument to mean default (bug #54531).
Rik <rik@octave.org>
parents: 25054
diff changeset
62 elseif (! isscalar (opt) || (opt != 0 && opt != 1))
dc70b480b9c1 zscore.m: Allow an empty OPT argument to mean default (bug #54531).
Rik <rik@octave.org>
parents: 25054
diff changeset
63 error ("zscore: normalization OPT must be empty, 0, or 1");
14234
938a8d792c37 zscore.m: Return mean and std dev for Matlab compatibility. Update docstring.
Jordi Gutiérrez Hermoso <jordigh@octave.org>
parents: 14138
diff changeset
64 endif
938a8d792c37 zscore.m: Return mean and std dev for Matlab compatibility. Update docstring.
Jordi Gutiérrez Hermoso <jordigh@octave.org>
parents: 14138
diff changeset
65
4885
28ab079d8f0e [project @ 2004-04-30 04:21:33 by jwe]
jwe
parents: 4030
diff changeset
66 nd = ndims (x);
28ab079d8f0e [project @ 2004-04-30 04:21:33 by jwe]
jwe
parents: 4030
diff changeset
67 sz = size (x);
14234
938a8d792c37 zscore.m: Return mean and std dev for Matlab compatibility. Update docstring.
Jordi Gutiérrez Hermoso <jordigh@octave.org>
parents: 14138
diff changeset
68 if (nargin < 3)
4886
54b076a24718 [project @ 2004-04-30 04:31:51 by jwe]
jwe
parents: 4885
diff changeset
69 ## Find the first non-singleton dimension.
12656
6b2f14af2360 Overhaul functions in statistics/base directory.
Rik <octave@nomad.inbox5.com>
parents: 12586
diff changeset
70 (dim = find (sz > 1, 1)) || (dim = 1);
3200
781c930425fd [project @ 1998-10-29 05:23:08 by jwe]
jwe
parents:
diff changeset
71 else
11436
e151e23f73bc Overhaul base statistics functions and documentation of same.
Rik <octave@nomad.inbox5.com>
parents: 11149
diff changeset
72 if (!(isscalar (dim) && dim == fix (dim))
11149
fe3c3dfc07eb style fix: break lines before && and ||, not after
John W. Eaton <jwe@octave.org>
parents: 10669
diff changeset
73 || !(1 <= dim && dim <= nd))
12586
f9b7aa3b88f8 Deprecate studentize(), replace with zscore().
Rik <octave@nomad.inbox5.com>
parents: 11587
diff changeset
74 error ("zscore: DIM must be an integer and a valid dimension");
4885
28ab079d8f0e [project @ 2004-04-30 04:21:33 by jwe]
jwe
parents: 4030
diff changeset
75 endif
28ab079d8f0e [project @ 2004-04-30 04:21:33 by jwe]
jwe
parents: 4030
diff changeset
76 endif
28ab079d8f0e [project @ 2004-04-30 04:21:33 by jwe]
jwe
parents: 4030
diff changeset
77
12656
6b2f14af2360 Overhaul functions in statistics/base directory.
Rik <octave@nomad.inbox5.com>
parents: 12586
diff changeset
78 n = sz(dim);
6b2f14af2360 Overhaul functions in statistics/base directory.
Rik <octave@nomad.inbox5.com>
parents: 12586
diff changeset
79 if (n == 0)
6b2f14af2360 Overhaul functions in statistics/base directory.
Rik <octave@nomad.inbox5.com>
parents: 12586
diff changeset
80 z = x;
11436
e151e23f73bc Overhaul base statistics functions and documentation of same.
Rik <octave@nomad.inbox5.com>
parents: 11149
diff changeset
81 else
14234
938a8d792c37 zscore.m: Return mean and std dev for Matlab compatibility. Update docstring.
Jordi Gutiérrez Hermoso <jordigh@octave.org>
parents: 14138
diff changeset
82
938a8d792c37 zscore.m: Return mean and std dev for Matlab compatibility. Update docstring.
Jordi Gutiérrez Hermoso <jordigh@octave.org>
parents: 14138
diff changeset
83 if (isinteger (x))
938a8d792c37 zscore.m: Return mean and std dev for Matlab compatibility. Update docstring.
Jordi Gutiérrez Hermoso <jordigh@octave.org>
parents: 14138
diff changeset
84 x = double (x);
938a8d792c37 zscore.m: Return mean and std dev for Matlab compatibility. Update docstring.
Jordi Gutiérrez Hermoso <jordigh@octave.org>
parents: 14138
diff changeset
85 endif
938a8d792c37 zscore.m: Return mean and std dev for Matlab compatibility. Update docstring.
Jordi Gutiérrez Hermoso <jordigh@octave.org>
parents: 14138
diff changeset
86
938a8d792c37 zscore.m: Return mean and std dev for Matlab compatibility. Update docstring.
Jordi Gutiérrez Hermoso <jordigh@octave.org>
parents: 14138
diff changeset
87 mu = mean (x, dim);
938a8d792c37 zscore.m: Return mean and std dev for Matlab compatibility. Update docstring.
Jordi Gutiérrez Hermoso <jordigh@octave.org>
parents: 14138
diff changeset
88 sigma = std (x, opt, dim);
938a8d792c37 zscore.m: Return mean and std dev for Matlab compatibility. Update docstring.
Jordi Gutiérrez Hermoso <jordigh@octave.org>
parents: 14138
diff changeset
89 s = sigma;
12656
6b2f14af2360 Overhaul functions in statistics/base directory.
Rik <octave@nomad.inbox5.com>
parents: 12586
diff changeset
90 s(s==0) = 1;
20617
a3b9ee5c040a Replace bsxfun with broadcasting for performance with complex inputs (bug #38628).
Rik <rik@octave.org>
parents: 20174
diff changeset
91 z = (x - mu) ./ s;
11436
e151e23f73bc Overhaul base statistics functions and documentation of same.
Rik <octave@nomad.inbox5.com>
parents: 11149
diff changeset
92 endif
4885
28ab079d8f0e [project @ 2004-04-30 04:21:33 by jwe]
jwe
parents: 4030
diff changeset
93
28ab079d8f0e [project @ 2004-04-30 04:21:33 by jwe]
jwe
parents: 4030
diff changeset
94 endfunction
11436
e151e23f73bc Overhaul base statistics functions and documentation of same.
Rik <octave@nomad.inbox5.com>
parents: 11149
diff changeset
95
12656
6b2f14af2360 Overhaul functions in statistics/base directory.
Rik <octave@nomad.inbox5.com>
parents: 12586
diff changeset
96
14363
f3d52523cde1 Use Octave coding conventions in all m-file %!test blocks
Rik <octave@nomad.inbox5.com>
parents: 14234
diff changeset
97 %!assert (zscore ([1,2,3]), [-1,0,1])
f3d52523cde1 Use Octave coding conventions in all m-file %!test blocks
Rik <octave@nomad.inbox5.com>
parents: 14234
diff changeset
98 %!assert (zscore (single ([1,2,3])), single ([-1,0,1]))
f3d52523cde1 Use Octave coding conventions in all m-file %!test blocks
Rik <octave@nomad.inbox5.com>
parents: 14234
diff changeset
99 %!assert (zscore (int8 ([1,2,3])), [-1,0,1])
f3d52523cde1 Use Octave coding conventions in all m-file %!test blocks
Rik <octave@nomad.inbox5.com>
parents: 14234
diff changeset
100 %!assert (zscore (ones (3,2,2,2)), zeros (3,2,2,2))
f3d52523cde1 Use Octave coding conventions in all m-file %!test blocks
Rik <octave@nomad.inbox5.com>
parents: 14234
diff changeset
101 %!assert (zscore ([2,0,-2;0,2,0;-2,-2,2]), [1,0,-1;0,1,0;-1,-1,1])
25817
dc70b480b9c1 zscore.m: Allow an empty OPT argument to mean default (bug #54531).
Rik <rik@octave.org>
parents: 25054
diff changeset
102 %!assert <*54531> (zscore ([1,2,3], [], 2), [-1,0,1])
11436
e151e23f73bc Overhaul base statistics functions and documentation of same.
Rik <octave@nomad.inbox5.com>
parents: 11149
diff changeset
103
19833
9fc020886ae9 maint: Clean up m-files to follow Octave coding conventions.
Rik <rik@octave.org>
parents: 19697
diff changeset
104 ## Test input validation
28896
90fea9cc9caa test: Add expected error message <Invalid call> to BIST tests for nargin.
Rik <rik@octave.org>
parents: 28789
diff changeset
105 %!error <Invalid call> zscore ()
12586
f9b7aa3b88f8 Deprecate studentize(), replace with zscore().
Rik <octave@nomad.inbox5.com>
parents: 11587
diff changeset
106 %!error zscore (1, 2, 3)
25817
dc70b480b9c1 zscore.m: Allow an empty OPT argument to mean default (bug #54531).
Rik <rik@octave.org>
parents: 25054
diff changeset
107 %!error <X must be a numeric> zscore (['A'; 'B'])
dc70b480b9c1 zscore.m: Allow an empty OPT argument to mean default (bug #54531).
Rik <rik@octave.org>
parents: 25054
diff changeset
108 %!error <OPT must be empty, 0, or 1> zscore (1, ones (2,2))
dc70b480b9c1 zscore.m: Allow an empty OPT argument to mean default (bug #54531).
Rik <rik@octave.org>
parents: 25054
diff changeset
109 %!error <OPT must be empty, 0, or 1> zscore (1, 1.5)
dc70b480b9c1 zscore.m: Allow an empty OPT argument to mean default (bug #54531).
Rik <rik@octave.org>
parents: 25054
diff changeset
110 %!error <DIM must be an integer> zscore (1, [], ones (2,2))
dc70b480b9c1 zscore.m: Allow an empty OPT argument to mean default (bug #54531).
Rik <rik@octave.org>
parents: 25054
diff changeset
111 %!error <DIM must be an integer> zscore (1, [], 1.5)
dc70b480b9c1 zscore.m: Allow an empty OPT argument to mean default (bug #54531).
Rik <rik@octave.org>
parents: 25054
diff changeset
112 %!error <DIM must be .* a valid dimension> zscore (1, [], 0)