Engee documentation

movmad

The moving average is the absolute deviation.

Library

EngeeDSP

Syntax

Function call

  • M = movmad(A,k) — returns the local average Absolute Deviation (MAD) by k points where each average (absolute) deviation is calculated in a sliding window of length k, which moves through the neighboring elements of the array A. M has the same size as A.

    If k odd, the window is centered relative to the element in the current position. If k even, the window is centered relative to the current and previous elements. The window size is automatically truncated at the endpoints when there are not enough elements to fill it. When the window is truncated, the average deviation is taken only for the elements filling the window.

    • If A — vector, then movmad it acts on the length of the vector A.

    • If A — a multidimensional array, then movmad it operates on the first dimension A, the size of which is not equal to 1.

  • M = movmad(A,[kb kf]) — calculates the average deviation with a length window kb+kf+1, which includes the element in the current position, kb elements back and kf Let’s go ahead.

  • M = movmad(___,dim) — defines the dimension of the matrix A, which is used to perform the operation for any of the previous syntax options. For example, movmad(A,k,2) for the matrix A performs an operation on the columns of the matrix A, calculating the moving average deviation by k elements for each row.

  • M = movmad(___,nanflag) — determines whether to include or exclude values NaN to the array A. For example, movmad(A,k,"omitnan") ignores values NaN when calculating each average deviation. By default movmad includes values NaN.

  • M = movmad(___,Name,Value) — sets additional parameters for the moving average deviation using one or more name-value arguments.

Arguments

Input arguments

# A — input data

+ vector | the matrix | multidimensional array

Details

Input data specified as a vector, matrix, or multidimensional array.

Data types

Float32, Float64, Int8, Int16, Int32, Int64, UInt8, UInt16, UInt32, UInt64, Bool

# k — window length

+ scalar

Details

The length of the window, set as a scalar. If k — a positive integer, the centered absolute average value includes the element in the current position and its neighbors.

For example, movmad(A,3) calculates an array of values for the local three-point average deviation.

movmad 1

# [kb kf] is the length of the directional window

+ A two-element vector is a string

Details

The length of the directional window, set as a string vector containing two elements. If kb and kf — positive integers, the calculation is performed by kb+kf+1 the elements. The calculation includes an element in the current position, kb elements up to the current position and kf items after the current position.

For example, movmad(A,[2 1]) calculates an array of values for the local four-point average deviation.

movmad 2

# dim — the dimension along which the operation is performed

+ a positive integer scalar

Details

The dimension along which the operation is performed is specified as a positive integer scalar. If no dimension is specified, the first dimension of the array is used by default, the size of which is not equal to 1.

Consider the input matrix A size m on n:

  • movmad(A,k,1) calculates the moving average deviation by k elements for each column A and returns a matrix of size m on n.

    movmad 3

  • movmad(A,k,2) calculates the moving average deviation by k elements for each row of the matrix A and returns a matrix of size m on n.

    movmad 4

# nanflag — condition for missing value

+ "includemissing" (default) | "includenan" | "omitmissing" | "omitnan"

Details

The condition for processing a missing value, set by one of the following values:

  • "includemissing" or "includenan" — enable values NaN in A when calculating each average deviation. If any element is in the window — NaN, then the corresponding element in M — NaN. Values "includemissing" and "includenan" they behave the same way.

  • "omitmissing" or "omitnan" — ignore all values NaN in A and calculate each average deviation for fewer points. If all the elements are in the window — NaN, then the corresponding element in M — NaN. Values "omitmissing" and "omitnan" they behave the same way.

Name-value input arguments

Specify optional argument pairs in the format Name, Value, where Name — the name of the argument, and Value — the appropriate value. Name-value arguments should be placed after other arguments, but the order of the pairs does not matter.

Use commas to separate the name and value, and Name put it in quotation marks.

Example: M = movmad(A,k,"Endpoints","fill").

# Endpoints — a method for processing windows near endpoints

+ "shrink" (by default) | "discard" | "fill" | scalar

Details

The method of processing windows near endpoints, specified by one of the following options:

Meaning Description

"shrink"

Reduce the window size near the endpoints of the input data to include only existing elements.

"discard"

Do not display any values of the average absolute deviation if the window does not completely overlap the existing elements.

"fill"

Replace non-existent elements with NaN.

scalar

Replace non-existent elements with the specified numeric or logical value.

Output arguments

# M — output data

+ vector | the matrix | multidimensional array

Details

The output data returned as a vector, matrix, or multidimensional array.

Examples

Centered moving average deviation of the vector

Details

Calculate the three-point centered moving average deviation of the row vector. If there are less than three elements in the window at the ends of the array, the calculation is performed on the available elements.

import EngeeDSP.Functions: movmad

A = [1 2 4 -1 -2 -3 -1 3 2 1]
M = movmad(A, 3)
1×10 Matrix{Float64}:
 0.5  1.0  2.0  1.0  1.0  1.0  2.0  1.0  1.0  0.5

The moving average deviation of the matrix

Details

Calculate the three-point centered moving average deviation for each row of the matrix. The dimension argument is two, which allows you to slide through the columns of the matrix A. The window starts from the first line, slides horizontally to the end of the line, then moves to the second line, and so on.

A = [1 2 1; -1 -2 -3; -1 3 4]
3×3 Matrix{Int64}:
  1   2   1
 -1  -2  -3
 -1   3   4
import EngeeDSP.Functions: movmad

M = movmad(A, 3, 2)
3×3 Matrix{Float64}:
 0.5  0.0  0.5
 0.5  1.0  0.5
 2.0  1.0  0.5

Moving average deviation without missing values

Details

Creating a vector string containing the values NaN.

A = [4 8 NaN -1 -2 -3 NaN 3 4 5];

Calculate the three-point centered moving average deviation of the vector, excluding the values NaN. For windows containing any value NaN, function movmad calculates the value taking into account all elements except NaN.

import EngeeDSP.Functions: movmad

M = movmad(A, 3, "omitnan")
1×10 Matrix{Float64}:
 2.0  2.0  4.5  0.5  1.0  0.5  3.0  0.5  1.0  0.5

Returning only the average deviations of the full window

Details

Let’s calculate the three-point centered moving average deviation of the row vector, but discard all calculations using less than three points from the output data. In other words, we will return only the average deviations calculated for the full three-element window, discarding calculations at the endpoints.

import EngeeDSP.Functions: movmad

A = [1 2 1 -1 -2 -3 -1 3 4 1];
M = movmad(A, 3, "Endpoints", "discard")
1×8 Matrix{Float64}:
 0.0  1.0  1.0  1.0  1.0  2.0  1.0  1.0

Additional Info

Average absolute deviation

Details

For the vector of finite length, consisting of for scalar observations, the mean absolute deviation is defined as

by .