1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
|
########################################################################
##
## Copyright (C) 1996-2024 The Octave Project Developers
##
## See the file COPYRIGHT.md in the top-level directory of this
## distribution or <https://octave.org/copyright/>.
##
## This file is part of Octave.
##
## Octave is free software: you can redistribute it and/or modify it
## under the terms of the GNU General Public License as published by
## the Free Software Foundation, either version 3 of the License, or
## (at your option) any later version.
##
## Octave is distributed in the hope that it will be useful, but
## WITHOUT ANY WARRANTY; without even the implied warranty of
## MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the
## GNU General Public License for more details.
##
## You should have received a copy of the GNU General Public License
## along with Octave; see the file COPYING. If not, see
## <https://www.gnu.org/licenses/>.
##
########################################################################
## -*- texinfo -*-
## @deftypefn {} {@var{s} =} std (@var{x})
## @deftypefnx {} {@var{s} =} std (@var{x}, @var{w})
## @deftypefnx {} {@var{s} =} std (@var{x}, @var{w}, @var{dim})
## @deftypefnx {} {@var{s} =} std (@var{x}, @var{w}, @var{vecdim})
## @deftypefnx {} {@var{s} =} std (@var{x}, @var{w}, @qcode{"ALL"})
## @deftypefnx {} {@var{s} =} std (@dots{}, @var{nanflag})
## @deftypefnx {} {[@var{s}, @var{m}] =} std (@dots{})
## Compute the standard deviation of the elements of the vector @var{x}.
##
## The standard deviation is defined as
## @tex
## $$ {\rm std}(x) = \sqrt{{1\over N-1} \sum_{i=1}^N (x_i - \bar x )^2} $$
## where $\bar{x}$ is the mean value of @var{x} and $N$ is the number of
## elements of @var{x}.
## @end tex
## @ifnottex
##
## @example
## @group
## std (@var{x}) = sqrt ((1 / (N-1)) * SUM_i ((@var{x}(i) - mean(@var{x}))^2))
## @end group
## @end example
##
## @noindent
## where @math{N} is the number of elements of @var{x}.
## @end ifnottex
##
## If @var{x} is an array, compute the standard deviation along the first
## non-singleton dimensions of @var{x}.
##
## The optional argument @var{w} determines the weighting scheme to use. Valid
## values are:
##
## @table @asis
## @item 0 [default]:
## Normalize with @math{N-1} (population standard deviation). This provides
## the square root of the best unbiased estimator of the standard deviation.
##
## @item 1:
## Normalize with @math{N} (sample standard deviation). This provides the
## square root of the second moment around the mean.
##
## @item a vector:
## Compute the weighted standard deviation with non-negative weights.
## The length of @var{w} must equal the size of @var{x} in the operating
## dimension. NaN values are permitted in @var{w}, will be multiplied with the
## associated values in @var{x}, and can be excluded by the @var{nanflag}
## option.
##
## @item an array:
## Similar to vector weights, but @var{w} must be the same size as @var{x}. If
## the operating dimension is supplied as @var{vecdim} or @qcode{"all"} and
## @var{w} is not a scalar, @var{w} must be an same-sized array.
## @end table
##
## Note: @var{w} must always be specified before specifying any of the
## following dimension options. To use the default value for @var{w} you
## may pass an empty input argument [].
##
## The optional variable @var{dim} forces @code{std} to operate over the
## specified dimension, which must be a positive integer-valued number.
## Specifying any singleton dimension in @var{x}, including any dimension
## exceeding @code{ndims (@var{x})}, will result in a standard deviation of 0.
##
## Specifying the dimensions as @var{vecdim}, a vector of non-repeating
## dimensions, will return the standard deviation calculated over the array
## slice defined by @var{vecdim}. If @var{vecdim} indexes all dimensions of
## @var{x}, then it is equivalent to the option @qcode{"all"}. Any
## dimension in @var{vecdim} greater than @code{ndims (@var{x})} is ignored.
##
## Specifying the dimension as @qcode{"all"} will force @code{std} to
## operate on all elements of @var{x}, and is equivalent to
## @code{std (@var{x}(:))}.
##
## The optional variable @var{nanflag} specifies whether to include or exclude
## NaN values from the calculation using any of the previously specified input
## argument combinations. The default value for @var{nanflag} is
## @qcode{"includenan"} which keeps NaN values in the calculation. To
## exclude NaN values set the value of @var{nanflag} to @qcode{"omitnan"}.
## The output will still contain NaN values if @var{x} consists of all NaN
## values in the operating dimension.
##
## The optional second output variable @var{m} contains the mean of the
## elements of @var{x} used to calculate the standard deviation. If @var{v} is
## the weighted standard deviation, then @var{m} is also the weighted mean.
##
## @seealso{var, bounds, mad, range, iqr, mean, median}
## @end deftypefn
function [s, m] = std (varargin)
if (nargin < 1)
print_usage ();
endif
if (nargout < 2)
s = sqrt (var (varargin{:}));
else
[s, m] = var (varargin{:});
s = sqrt (s);
endif
endfunction
%!test
%! x = ones (10, 2);
%! y = [1, 3];
%! assert (std (x), [0, 0]);
%! assert (std (y), sqrt (2), sqrt (eps));
%! assert (std (x, 0, 2), zeros (10, 1));
%!assert (std (ones (3, 1, 2), 0, 2), zeros (3, 1, 2))
%!assert (std ([1 2], 0), sqrt (2)/2, 5*eps)
%!assert (std ([1 2], 1), 0.5, 5*eps)
%!assert (std (1), 0)
%!assert (std (single (1)), single (0))
%!assert (std ([1 2 3], [], 3), [0 0 0])
## Test input validation
%!error <Invalid call> std ()
|
