Mercurial > octave
changeset 26262:f73ca7468864
Add movXXX moving statistical functions bug #48774).
* NEWS: Announce new functions
* scripts/statistics/movmad.m, scripts/statistics/movmax.m,
scripts/statistics/movmean.m, scripts/statistics/movmin.m,
scripts/statistics/movmedian.m, scripts/statistics/movprod.m,
scripts/statistics/movstd.m, scripts/statistics/movsum.m,
scripts/statistics/movvar.m: New m-files.
* scripts/statistics/module.mk: Add new m-files to build system.
* stats.txi: Add new functions to the manual in the statistics chapter.
* __unimplemented__.m: Remove movXXX functions from list of unimplemented.
author | Rik <rik@octave.org> |
---|---|
date | Tue, 18 Dec 2018 16:29:39 -0800 |
parents | eb1903f8bf98 |
children | 50a161ee72e1 |
files | NEWS doc/interpreter/stats.txi scripts/help/__unimplemented__.m scripts/statistics/module.mk scripts/statistics/movmad.m scripts/statistics/movmax.m scripts/statistics/movmean.m scripts/statistics/movmedian.m scripts/statistics/movmin.m scripts/statistics/movprod.m scripts/statistics/movstd.m scripts/statistics/movsum.m scripts/statistics/movvar.m |
diffstat | 13 files changed, 1259 insertions(+), 24 deletions(-) [+] |
line wrap: on
line diff
--- a/NEWS Tue Dec 18 14:33:35 2018 -0800 +++ b/NEWS Tue Dec 18 16:29:39 2018 -0800 @@ -9,13 +9,15 @@ function. ** A new core function movfun will apply a function to a sliding - window of arbitrary size on a full dataset and accumulate the - results. Many common cases have been implemented using the naming + window of arbitrary size on a dataset and accumulate the results. + Many common cases have been implemented using the naming scheme movXXX where "XXX" is the function that will be applied. For example, the moving average over a dataset is movmean. New moving window functions: - - movfun movmin movslice + + movfun movslice + movmad movmax movmean movmedian movmin movprod + movstd movsum movvar ** The functions issymmetric and ishermitian accept an option "nonskew" or "skew" to calculate the symmetric or skew-symmetric property @@ -186,8 +188,16 @@ movegui movfun movie + movmad + movmax + movmean + movmedian movmin + movprod movslice + movstd + movsum + movvar openfig ordeig savefig
--- a/doc/interpreter/stats.txi Tue Dec 18 14:33:35 2018 -0800 +++ b/doc/interpreter/stats.txi Tue Dec 18 16:29:39 2018 -0800 @@ -120,8 +120,24 @@ @DOCSTRING(movslice) +@DOCSTRING(movmad) + +@DOCSTRING(movmax) + +@DOCSTRING(movmean) + +@DOCSTRING(movmedian) + @DOCSTRING(movmin) +@DOCSTRING(movprod) + +@DOCSTRING(movstd) + +@DOCSTRING(movsum) + +@DOCSTRING(movvar) + @node Basic Statistical Functions @section Basic Statistical Functions
--- a/scripts/help/__unimplemented__.m Tue Dec 18 14:33:35 2018 -0800 +++ b/scripts/help/__unimplemented__.m Tue Dec 18 16:29:39 2018 -0800 @@ -995,18 +995,8 @@ "movegui", "movie", "movie2avi", - "movmad", - "movmax", - "movmean", - "movmedian", - "movmin", "movNamHDU", - "movprod", "movRelHDU", - "movstd" - "movstd", - "movsum", - "movvar", "mput", "multibandread", "multibandwrite",
--- a/scripts/statistics/module.mk Tue Dec 18 14:33:35 2018 -0800 +++ b/scripts/statistics/module.mk Tue Dec 18 16:29:39 2018 -0800 @@ -24,7 +24,15 @@ %reldir%/median.m \ %reldir%/mode.m \ %reldir%/moment.m \ + %reldir%/movmad.m \ + %reldir%/movmax.m \ + %reldir%/movmean.m \ + %reldir%/movmedian.m \ %reldir%/movmin.m \ + %reldir%/movprod.m \ + %reldir%/movstd.m \ + %reldir%/movsum.m \ + %reldir%/movvar.m \ %reldir%/prctile.m \ %reldir%/quantile.m \ %reldir%/range.m \
--- /dev/null Thu Jan 01 00:00:00 1970 +0000 +++ b/scripts/statistics/movmad.m Tue Dec 18 16:29:39 2018 -0800 @@ -0,0 +1,139 @@ +## Copyright (C) 2018 Rik Wehbring +## +## 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} =} movmad (@var{x}, @var{wlen}) +## @deftypefnx {} {@var{y} =} movmad (@var{x}, [@var{na}, @var{nb}]) +## @deftypefnx {} {@var{y} =} movmad (@dots{}, @var{dim}) +## @deftypefnx {} {@var{y} =} movmad (@dots{}, "@var{nancond}") +## @deftypefnx {} {@var{y} =} movmad (@dots{}, @var{property}, @var{value}) +## Calculate the moving mean absolute deviation over a sliding window of length +## @var{wlen} on data @var{x}. +## +## If @var{wlen} is a scalar, the function @code{mad} 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{movmad} 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{movmad} 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{mad}. 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) = mad (@var{x}(1:2))}, and +## @code{@var{y}(end) = mad (@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) = mad ([NaN, @var{x}(1:2)])}, and +## @code{@var{y}(end) = mad ([@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{mad} 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) = mad ([@var{user_value}, @var{x}(1:2)])}, and +## @code{@var{y}(end) = mad ([@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) = mad ([@var{x}(1), @var{x}(1:2)])}, and +## @code{@var{y}(end) = mad ([@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) = mad ([@var{x}(end), @var{x}(1:2)])}, and +## @code{@var{y}(end) = mad ([@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, @xref{XREFmovfun,,movfun}. +## +## @seealso{movfun, movslice, movmax, movmean, movmedian, movmin, movprod, movstd, movsum, movvar} +## @end deftypefn + +function y = movmad (x, wlen, varargin) + + if (nargin < 2) + print_usage (); + endif + + y = movmad (@mad, x, wlen, __parse_movargs__ ("movmad", varargin{:}){:}); + +endfunction + + +## FIXME: Need functional BIST tests + +## Test input validation +%!error movmad () +%!error movmad (1)
--- /dev/null Thu Jan 01 00:00:00 1970 +0000 +++ b/scripts/statistics/movmax.m Tue Dec 18 16:29:39 2018 -0800 @@ -0,0 +1,139 @@ +## Copyright (C) 2018 Rik Wehbring +## +## 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} =} movmax (@var{x}, @var{wlen}) +## @deftypefnx {} {@var{y} =} movmax (@var{x}, [@var{na}, @var{nb}]) +## @deftypefnx {} {@var{y} =} movmax (@dots{}, @var{dim}) +## @deftypefnx {} {@var{y} =} movmax (@dots{}, "@var{nancond}") +## @deftypefnx {} {@var{y} =} movmax (@dots{}, @var{property}, @var{value}) +## Calculate the moving maximum over a sliding window of length @var{wlen} on +## data @var{x}. +## +## If @var{wlen} is a scalar, the function @code{max} 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{movmax} 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{movmax} 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{max}. 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) = max (@var{x}(1:2))}, and +## @code{@var{y}(end) = max (@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) = max ([NaN, @var{x}(1:2)])}, and +## @code{@var{y}(end) = max ([@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{max} 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) = max ([@var{user_value}, @var{x}(1:2)])}, and +## @code{@var{y}(end) = max ([@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) = max ([@var{x}(1), @var{x}(1:2)])}, and +## @code{@var{y}(end) = max ([@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) = max ([@var{x}(end), @var{x}(1:2)])}, and +## @code{@var{y}(end) = max ([@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, @xref{XREFmovfun,,movfun}. +## +## @seealso{movfun, movslice, movmad, movmean, movmedian, movmin, movprod, movstd, movsum, movvar} +## @end deftypefn + +function y = movmax (x, wlen, varargin) + + if (nargin < 2) + print_usage (); + endif + + y = movmax (@max, x, wlen, __parse_movargs__ ("movmax", varargin{:}){:}); + +endfunction + + +## FIXME: Need functional BIST tests + +## Test input validation +%!error movmax () +%!error movmax (1)
--- /dev/null Thu Jan 01 00:00:00 1970 +0000 +++ b/scripts/statistics/movmean.m Tue Dec 18 16:29:39 2018 -0800 @@ -0,0 +1,139 @@ +## Copyright (C) 2018 Rik Wehbring +## +## 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{na}, @var{nb}]) +## @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, @xref{XREFmovfun,,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 = movmean (@mean, x, wlen, __parse_movargs__ ("movmean", varargin{:}){:}); + +endfunction + + +## FIXME: Need functional BIST tests + +## Test input validation +%!error movmean () +%!error movmean (1)
--- /dev/null Thu Jan 01 00:00:00 1970 +0000 +++ b/scripts/statistics/movmedian.m Tue Dec 18 16:29:39 2018 -0800 @@ -0,0 +1,139 @@ +## Copyright (C) 2018 Rik Wehbring +## +## 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} =} movmedian (@var{x}, @var{wlen}) +## @deftypefnx {} {@var{y} =} movmedian (@var{x}, [@var{na}, @var{nb}]) +## @deftypefnx {} {@var{y} =} movmedian (@dots{}, @var{dim}) +## @deftypefnx {} {@var{y} =} movmedian (@dots{}, "@var{nancond}") +## @deftypefnx {} {@var{y} =} movmedian (@dots{}, @var{property}, @var{value}) +## Calculate the moving median over a sliding window of length @var{wlen} on +## data @var{x}. +## +## If @var{wlen} is a scalar, the function @code{movmedian} 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{movmedian} 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{movmedian} 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{movmedian}. 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) = movmedian (@var{x}(1:2))}, and +## @code{@var{y}(end) = movmedian (@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) = movmedian ([NaN, @var{x}(1:2)])}, and +## @code{@var{y}(end) = movmedian ([@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{movmedian} 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) = movmedian ([@var{user_value}, @var{x}(1:2)])}, and +## @code{@var{y}(end) = movmedian ([@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) = movmedian ([@var{x}(1), @var{x}(1:2)])}, and +## @code{@var{y}(end) = movmedian ([@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) = movmedian ([@var{x}(end), @var{x}(1:2)])}, and +## @code{@var{y}(end) = movmedian ([@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, @xref{XREFmovfun,,movfun}. +## +## @seealso{movfun, movslice, movmad, movmax, movmean, movmin, movprod, movstd, movsum, movvar} +## @end deftypefn + +function y = movmedian (x, wlen, varargin) + + if (nargin < 2) + print_usage (); + endif + + y = movmedian (@movmedian, x, wlen, __parse_movargs__ ("movmedian", varargin{:}){:}); + +endfunction + + +## FIXME: Need functional BIST tests + +## Test input validation +%!error movmedian () +%!error movmedian (1)
--- a/scripts/statistics/movmin.m Tue Dec 18 14:33:35 2018 -0800 +++ b/scripts/statistics/movmin.m Tue Dec 18 16:29:39 2018 -0800 @@ -1,4 +1,4 @@ -## Copyright (C) 2018 Juan Pablo Carbajal +## Copyright (C) 2018 Rik Wehbring ## ## This file is part of Octave. ## @@ -16,25 +16,124 @@ ## along with Octave; see the file COPYING. If not, see ## <https://www.gnu.org/licenses/>. -## Author: Juan Pablo Carbajal <ajuanpi+dev@gmail.com> -## Created: 2018-08-13 - ## -*- texinfo -*- ## @deftypefn {} {@var{y} =} movmin (@var{x}, @var{wlen}) ## @deftypefnx {} {@var{y} =} movmin (@var{x}, [@var{na}, @var{nb}]) ## @deftypefnx {} {@var{y} =} movmin (@dots{}, @var{dim}) -## @deftypefnx {} {@var{y} =} movmin (@dots{}, @var{nanstr}) +## @deftypefnx {} {@var{y} =} movmin (@dots{}, "@var{nancond}") ## @deftypefnx {} {@var{y} =} movmin (@dots{}, @var{property}, @var{value}) -## Minimum of @var{x} over a sliding window of length @var{wlen}. +## Calculate the moving minimum over a sliding window of length @var{wlen} on +## data @var{x}. +## +## If @var{wlen} is a scalar, the function @code{min} 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{movmin} 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{movmin} 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{min}. 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) = min (@var{x}(1:2))}, and +## @code{@var{y}(end) = min (@var{x}(end-1:end))}. ## -## FIXME: Need explanation of all options. Write once and then replicate. +## @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) = min ([NaN, @var{x}(1:2)])}, and +## @code{@var{y}(end) = min ([@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{min} handles @code{NaN}, +## and also by the property @qcode{"nancond"}. ## -## @seealso{movfun} +## @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) = min ([@var{user_value}, @var{x}(1:2)])}, and +## @code{@var{y}(end) = min ([@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) = min ([@var{x}(1), @var{x}(1:2)])}, and +## @code{@var{y}(end) = min ([@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) = min ([@var{x}(end), @var{x}(1:2)])}, and +## @code{@var{y}(end) = min ([@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, @xref{XREFmovfun,,movfun}. +## +## @seealso{movfun, movslice, movmad, movmax, movmean, movmedian, movprod, movstd, movsum, movvar} ## @end deftypefn function y = movmin (x, wlen, varargin) - y = movfun (@min, x, wlen, __parse_movargs__ ("movmin", varargin{:}){:}); + + if (nargin < 2) + print_usage (); + endif + + y = movmin (@min, x, wlen, __parse_movargs__ ("movmin", varargin{:}){:}); + endfunction -## FIXME: Need BIST tests +## FIXME: Need functional BIST tests + +## Test input validation +%!error movmin () +%!error movmin (1)
--- /dev/null Thu Jan 01 00:00:00 1970 +0000 +++ b/scripts/statistics/movprod.m Tue Dec 18 16:29:39 2018 -0800 @@ -0,0 +1,139 @@ +## Copyright (C) 2018 Rik Wehbring +## +## 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} =} movprod (@var{x}, @var{wlen}) +## @deftypefnx {} {@var{y} =} movprod (@var{x}, [@var{na}, @var{nb}]) +## @deftypefnx {} {@var{y} =} movprod (@dots{}, @var{dim}) +## @deftypefnx {} {@var{y} =} movprod (@dots{}, "@var{nancond}") +## @deftypefnx {} {@var{y} =} movprod (@dots{}, @var{property}, @var{value}) +## Calculate the moving product over a sliding window of length @var{wlen} on +## data @var{x}. +## +## If @var{wlen} is a scalar, the function @code{movprod} 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{movprod} 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{movprod} 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{movprod}. 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) = movprod (@var{x}(1:2))}, and +## @code{@var{y}(end) = movprod (@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) = movprod ([NaN, @var{x}(1:2)])}, and +## @code{@var{y}(end) = movprod ([@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{movprod} 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) = movprod ([@var{user_value}, @var{x}(1:2)])}, and +## @code{@var{y}(end) = movprod ([@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) = movprod ([@var{x}(1), @var{x}(1:2)])}, and +## @code{@var{y}(end) = movprod ([@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) = movprod ([@var{x}(end), @var{x}(1:2)])}, and +## @code{@var{y}(end) = movprod ([@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, @xref{XREFmovfun,,movfun}. +## +## @seealso{movfun, movslice, movmad, movmax, movmean, movmedian, movmin, movstd, movsum, movvar} +## @end deftypefn + +function y = movprod (x, wlen, varargin) + + if (nargin < 2) + print_usage (); + endif + + y = movprod (@movprod, x, wlen, __parse_movargs__ ("movprod", varargin{:}){:}); + +endfunction + + +## FIXME: Need functional BIST tests + +## Test input validation +%!error movprod () +%!error movprod (1)
--- /dev/null Thu Jan 01 00:00:00 1970 +0000 +++ b/scripts/statistics/movstd.m Tue Dec 18 16:29:39 2018 -0800 @@ -0,0 +1,139 @@ +## Copyright (C) 2018 Rik Wehbring +## +## 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} =} movstd (@var{x}, @var{wlen}) +## @deftypefnx {} {@var{y} =} movstd (@var{x}, [@var{na}, @var{nb}]) +## @deftypefnx {} {@var{y} =} movstd (@dots{}, @var{dim}) +## @deftypefnx {} {@var{y} =} movstd (@dots{}, "@var{nancond}") +## @deftypefnx {} {@var{y} =} movstd (@dots{}, @var{property}, @var{value}) +## Calculate the moving standard deviation over a sliding window of length +## @var{wlen} on data @var{x}. +## +## If @var{wlen} is a scalar, the function @code{movstd} 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{movstd} 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{movstd} 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{movstd}. 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) = movstd (@var{x}(1:2))}, and +## @code{@var{y}(end) = movstd (@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) = movstd ([NaN, @var{x}(1:2)])}, and +## @code{@var{y}(end) = movstd ([@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{movstd} 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) = movstd ([@var{user_value}, @var{x}(1:2)])}, and +## @code{@var{y}(end) = movstd ([@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) = movstd ([@var{x}(1), @var{x}(1:2)])}, and +## @code{@var{y}(end) = movstd ([@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) = movstd ([@var{x}(end), @var{x}(1:2)])}, and +## @code{@var{y}(end) = movstd ([@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, @xref{XREFmovfun,,movfun}. +## +## @seealso{movfun, movslice, movmad, movmax, movmean, movmedian, movmin, movprod, movsum, movvar} +## @end deftypefn + +function y = movstd (x, wlen, varargin) + + if (nargin < 2) + print_usage (); + endif + + y = movstd (@movstd, x, wlen, __parse_movargs__ ("movstd", varargin{:}){:}); + +endfunction + + +## FIXME: Need functional BIST tests + +## Test input validation +%!error movstd () +%!error movstd (1)
--- /dev/null Thu Jan 01 00:00:00 1970 +0000 +++ b/scripts/statistics/movsum.m Tue Dec 18 16:29:39 2018 -0800 @@ -0,0 +1,139 @@ +## Copyright (C) 2018 Rik Wehbring +## +## 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} =} movsum (@var{x}, @var{wlen}) +## @deftypefnx {} {@var{y} =} movsum (@var{x}, [@var{na}, @var{nb}]) +## @deftypefnx {} {@var{y} =} movsum (@dots{}, @var{dim}) +## @deftypefnx {} {@var{y} =} movsum (@dots{}, "@var{nancond}") +## @deftypefnx {} {@var{y} =} movsum (@dots{}, @var{property}, @var{value}) +## Calculate the moving sum over a sliding window of length @var{wlen} on +## data @var{x}. +## +## If @var{wlen} is a scalar, the function @code{movsum} 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{movsum} 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{movsum} 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{movsum}. 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) = movsum (@var{x}(1:2))}, and +## @code{@var{y}(end) = movsum (@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) = movsum ([NaN, @var{x}(1:2)])}, and +## @code{@var{y}(end) = movsum ([@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{movsum} 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) = movsum ([@var{user_value}, @var{x}(1:2)])}, and +## @code{@var{y}(end) = movsum ([@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) = movsum ([@var{x}(1), @var{x}(1:2)])}, and +## @code{@var{y}(end) = movsum ([@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) = movsum ([@var{x}(end), @var{x}(1:2)])}, and +## @code{@var{y}(end) = movsum ([@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, @xref{XREFmovfun,,movfun}. +## +## @seealso{movfun, movslice, movmad, movmax, movmean, movmedian, movmin, movprod, movstd, movvar} +## @end deftypefn + +function y = movsum (x, wlen, varargin) + + if (nargin < 2) + print_usage (); + endif + + y = movsum (@movsum, x, wlen, __parse_movargs__ ("movsum", varargin{:}){:}); + +endfunction + + +## FIXME: Need functional BIST tests + +## Test input validation +%!error movsum () +%!error movsum (1)
--- /dev/null Thu Jan 01 00:00:00 1970 +0000 +++ b/scripts/statistics/movvar.m Tue Dec 18 16:29:39 2018 -0800 @@ -0,0 +1,139 @@ +## Copyright (C) 2018 Rik Wehbring +## +## 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} =} movvar (@var{x}, @var{wlen}) +## @deftypefnx {} {@var{y} =} movvar (@var{x}, [@var{na}, @var{nb}]) +## @deftypefnx {} {@var{y} =} movvar (@dots{}, @var{dim}) +## @deftypefnx {} {@var{y} =} movvar (@dots{}, "@var{nancond}") +## @deftypefnx {} {@var{y} =} movvar (@dots{}, @var{property}, @var{value}) +## Calculate the moving variance over a sliding window of length @var{wlen} on +## data @var{x}. +## +## If @var{wlen} is a scalar, the function @code{var} 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{movvar} 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{movvar} 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{var}. 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) = var (@var{x}(1:2))}, and +## @code{@var{y}(end) = var (@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) = var ([NaN, @var{x}(1:2)])}, and +## @code{@var{y}(end) = var ([@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{var} 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) = var ([@var{user_value}, @var{x}(1:2)])}, and +## @code{@var{y}(end) = var ([@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) = var ([@var{x}(1), @var{x}(1:2)])}, and +## @code{@var{y}(end) = var ([@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) = var ([@var{x}(end), @var{x}(1:2)])}, and +## @code{@var{y}(end) = var ([@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, @xref{XREFmovfun,,movfun}. +## +## @seealso{movfun, movslice, movmad, movmax, movmean, movmedian, movmin, movprod, movstd, movsum} +## @end deftypefn + +function y = movvar (x, wlen, varargin) + + if (nargin < 2) + print_usage (); + endif + + y = movvar (@var, x, wlen, __parse_movargs__ ("movvar", varargin{:}){:}); + +endfunction + + +## FIXME: Need functional BIST tests + +## Test input validation +%!error movvar () +%!error movvar (1)