Mercurial > octave
diff scripts/statistics/movmax.m @ 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 | |
children | 895f2f609a96 |
line wrap: on
line diff
--- /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)