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
148
149
150
151
152
153
154
155
156
157
158
159
160
161
|
########################################################################
##
## Copyright (C) 2018-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{y} =} movmean (@var{x}, @var{wlen})
## @deftypefnx {} {@var{y} =} movmean (@var{x}, [@var{nb}, @var{na}])
## @deftypefnx {} {@var{y} =} movmean (@dots{}, @var{dim})
## @deftypefnx {} {@var{y} =} movmean (@dots{}, "@var{nancond}")
## @deftypefnx {} {@var{y} =} movmean (@dots{}, @var{property}, @var{value})
## Calculate the moving average over a sliding window of length @var{wlen} on
## data @var{x}.
##
## If @var{wlen} is a scalar, the function @code{mean} is applied to a
## moving window of length @var{wlen}. When @var{wlen} is an odd number the
## window is symmetric and includes @w{@code{(@var{wlen} - 1) / 2}}@ elements
## on either side of the central element. For example, when calculating the
## output at index 5 with a window length of 3, @code{movmean} uses data
## elements @w{@code{[4, 5, 6]}}. If @var{wlen} is an even number, the window
## is asymmetric and has @w{@code{@var{wlen}/2}}@ elements to the left of the
## central element and @w{@code{@var{wlen}/2 - 1}}@ elements to the right of
## the central element. For example, when calculating the output at index 5
## with a window length of 4, @code{movmean} uses data elements
## @w{@code{[3, 4, 5, 6]}}.
##
## If @var{wlen} is an array with two elements @w{@code{[@var{nb}, @var{na}]}},
## the function is applied to a moving window @code{-@var{nb}:@var{na}}. This
## window includes @var{nb} number of elements @emph{before} the current
## element and @var{na} number of elements @emph{after} the current element.
## The current element is always included. For example, given
## @w{@code{@var{wlen} = [3, 0]}}, the data used to calculate index 5 is
## @w{@code{[2, 3, 4, 5]}}.
##
## If the optional argument @var{dim} is given, operate along this dimension.
##
## The optional string argument @qcode{"@var{nancond}"} controls whether
## @code{NaN} and @code{NA} values should be included (@qcode{"includenan"}),
## or excluded (@qcode{"omitnan"}), from the data passed to @code{mean}. The
## default is @qcode{"includenan"}. Caution: the @qcode{"omitnan"} option is
## not yet implemented.
##
## The calculation can be controlled by specifying @var{property}/@var{value}
## pairs. Valid properties are
##
## @table @asis
##
## @item @qcode{"Endpoints"}
##
## This property controls how results are calculated at the boundaries
## (@w{endpoints}) of the window. Possible values are:
##
## @table @asis
## @item @qcode{"shrink"} (default)
## The window is truncated at the beginning and end of the array to exclude
## elements for which there is no source data. For example, with a window of
## length 3, @code{@var{y}(1) = mean (@var{x}(1:2))}, and
## @code{@var{y}(end) = mean (@var{x}(end-1:end))}.
##
## @item @qcode{"discard"}
## Any @var{y} values that use a window extending beyond the original
## data array are deleted. For example, with a 10-element data vector and a
## window of length 3, the output will contain only 8 elements. The first
## element would require calculating the function over indices
## @w{@code{[0, 1, 2]}}@ and is therefore discarded. The last element would
## require calculating the function over indices @w{@code{[9, 10, 11]}}@ and is
## therefore discarded.
##
## @item @qcode{"fill"}
## Any window elements outside the data array are replaced by @code{NaN}. For
## example, with a window of length 3,
## @code{@var{y}(1) = mean ([NaN, @var{x}(1:2)])}, and
## @code{@var{y}(end) = mean ([@var{x}(end-1:end), NaN])}.
## This option usually results in @var{y} having @code{NaN} values at the
## boundaries, although it is influenced by how @code{mean} handles @code{NaN},
## and also by the property @qcode{"nancond"}.
##
## @item @var{user_value}
## Any window elements outside the data array are replaced by the specified
## value @var{user_value} which must be a numeric scalar. For example, with a
## window of length 3,
## @code{@var{y}(1) = mean ([@var{user_value}, @var{x}(1:2)])}, and
## @code{@var{y}(end) = mean ([@var{x}(end-1:end), @var{user_value}])}.
## A common choice for @var{user_value} is 0.
##
## @item @qcode{"same"}
## Any window elements outside the data array are replaced by the value of
## @var{x} at the boundary. For example, with a window of length 3,
## @code{@var{y}(1) = mean ([@var{x}(1), @var{x}(1:2)])}, and
## @code{@var{y}(end) = mean ([@var{x}(end-1:end), @var{x}(end)])}.
##
## @item @qcode{"periodic"}
## The window is wrapped so that any missing data elements are taken from
## the other side of the data. For example, with a window of length 3,
## @code{@var{y}(1) = mean ([@var{x}(end), @var{x}(1:2)])}, and
## @code{@var{y}(end) = mean ([@var{x}(end-1:end), @var{x}(1)])}.
##
## @end table
##
## @item @qcode{"SamplePoints"}
## Caution: This option is not yet implemented.
##
## @end table
##
## Programming Note: This function is a wrapper which calls @code{movfun}.
## For additional options and documentation, @pxref{XREFmovfun,,@code{movfun}}.
##
## @seealso{movfun, movslice, movmad, movmax, movmedian, movmin, movprod,
## movstd, movsum, movvar}
## @end deftypefn
function y = movmean (x, wlen, varargin)
if (nargin < 2)
print_usage ();
endif
y = movfun (@mean, x, wlen, __parse_movargs__ ("movmean", varargin{:}){:});
endfunction
%!assert (movmean (1:5, 3), [1.5, 2, 3, 4, 4.5], eps)
%!assert (movmean (1:5, [1, 1]), [1.5, 2, 3, 4, 4.5], eps)
%!assert (movmean (1:5, 3, 2), [1.5, 2, 3, 4, 4.5], eps)
%!assert (movmean (magic (4), 3), ...
%! [10.5, 6.5, 6.5, 10.5; 10, 20/3, 19/3, 11; ...
%! 6, 32/3, 31/3, 7; 6.5, 10.5, 10.5, 6.5], eps)
%!assert (movmean (magic (4), 3, 1), ...
%! [10.5, 6.5, 6.5, 10.5; 10, 20/3, 19/3, 11; ...
%! 6, 32/3, 31/3, 7; 6.5, 10.5, 10.5, 6.5], eps)
%!assert (movmean (magic (4), 3, 2), ...
%! [9, 7, 6, 8; 8, 26/3, 29/3, 9; ...
%! 8, 22/3, 25/3, 9; 9, 11, 10, 8], eps)
%!assert <*55241> (movmean ((1:10).', 3), [1.5; (2:9).'; 9.5])
## Test input validation
%!error <Invalid call> movmean ()
%!error <Invalid call> movmean (1)
|
