NAG C Library Function Document

nag_moving_average (g01wac)

1

Purpose

2

Specification

3

Description

4

References

5

Arguments

1:    $\mathbf{m}$ – IntegerInput

On entry: $m$, the length of the rolling window.

If $\mathbf{pn}\ne 0$, m must be unchanged since the last call to nag_moving_average (g01wac).

Constraint: $\mathbf{m}\ge 1$.

2:    $\mathbf{nb}$ – IntegerInput

On entry: $b$, the number of observations in the current block of data. The size of the block of data supplied in x (and when $\mathbf{iwt}=\mathrm{Nag\_WeightObs}$, wt) can vary; therefore nb can change between calls to nag_moving_average (g01wac).

Constraints:

• $\mathbf{nb}\ge 0$;
• if $\mathbf{rcomm}\text{is}\mathbf{NULL}$, $\mathbf{nb}\ge \mathbf{m}$.

3:    $\mathbf{x}\left[\mathbf{nb}\right]$ – const doubleInput

On entry: the current block of observations, corresponding to $x_{\mathit{i}}$, for $\mathit{i}=k+1,\dots ,k+b$, where $k$ is the number of observations processed so far and $b$ is the size of the current block of data.

4:    $\mathbf{iwt}$ – Nag_WeightstypeInput

On entry: the type of weighting to use.

$\mathbf{iwt}=\mathrm{Nag\_NoWeights}$

No weights are used.

$\mathbf{iwt}=\mathrm{Nag\_WeightObs}$

Each observation has its own weight.

$\mathbf{iwt}=\mathrm{Nag\_WeightWindow}$

Each position in the window has its own weight.

$\mathbf{iwt}=\mathrm{Nag\_WeightWindowPos}$

Each position in the window has a weight equal to its position number.

If $\mathbf{pn}\ne 0$, iwt must be unchanged since the last call to nag_moving_average (g01wac).

Constraint: $\mathbf{iwt}=\mathrm{Nag\_NoWeights}$, $\mathrm{Nag\_WeightObs}$, $\mathrm{Nag\_WeightWindow}$ or $\mathrm{Nag\_WeightWindowPos}$.

5:    $\mathbf{wt}\left[\mathit{dim}\right]$ – const doubleInput

Note: the dimension, dim, of the array wt must be at least

• $\mathbf{nb}$, when $\mathbf{iwt}=\mathrm{Nag\_WeightObs}$;
• $\mathbf{m}$, when $\mathbf{iwt}=\mathrm{Nag\_WeightWindow}$;
• otherwise $\mathbf{wt}$ is not referenced and may be NULL.

On entry: the user-supplied weights.

If $\mathbf{iwt}=\mathrm{Nag\_WeightObs}$, $\mathbf{wt}\left[\mathit{i}-1\right]={\nu }_{\mathit{i}+k}$, for $\mathit{i}=1,2,\dots ,b$.

If $\mathbf{iwt}=\mathrm{Nag\_WeightWindow}$, $\mathbf{wt}\left[\mathit{j}-1\right]=w_{\mathit{j}}$, for $\mathit{j}=1,2,\dots ,m$.

Constraints:

• if $\mathbf{iwt}=\mathrm{Nag\_WeightObs}$, $\mathbf{wt}\left[\mathit{i}-1\right]\ge 0$, for $\mathit{i}=1,2,\dots ,\mathbf{nb}$;
• if $\mathbf{iwt}=\mathrm{Nag\_WeightWindow}$, $\mathbf{wt}\left[0\right]\ne 0$ and ${\sum }_{\mathit{j}=1}^m\mathbf{wt}\left[\mathit{j}-1\right]>0$;
• if $\mathbf{iwt}=\mathrm{Nag\_WeightWindow}$ and $\mathbf{rsd}\text{is not}\mathbf{NULL}$, $\mathbf{wt}\left[\mathit{j}-1\right]\ge 0$, for $\mathit{j}=1,2,\dots ,\mathbf{m}$.

6:    $\mathbf{pn}$ – Integer *Input/Output

On entry: $k$, the number of observations processed so far. On the first call to nag_moving_average (g01wac), or when starting to summarise a new dataset, pn must be set to $0$.

If $\mathbf{pn}\ne 0$, it must be the same value as returned by the last call to nag_moving_average (g01wac).

On exit: $k+b$, the updated number of observations processed so far.

Constraint: $\mathbf{pn}\ge 0$.

7:    $\mathbf{rmean}\left[\mathit{dim}\right]$ – doubleOutput

Note: the dimension, dim, of the array rmean must be at least $\max \left(0,\mathbf{nb}+\min \left(0,\mathbf{pn}-\mathbf{m}+1\right)\right)$.

On exit: ${\mu }_{\mathit{l}}$, the (weighted) moving averages, for $\mathit{l}=1,2,\dots ,b+\min \left(0,k-m+1\right)$. Therefore, ${\mu }_l$ is the mean of the data in the window that ends on $\mathbf{x}\left[l+m-\min \left(k,m-1\right)-2\right]$.

If, on entry, $\mathbf{pn}\ge \mathbf{m}-1$, i.e., at least one windows worth of data has been previously processed, then $\mathbf{rmean}\left[l-1\right]$ is the summary corresponding to the window that ends on $\mathbf{x}\left[l-1\right]$. On the other hand, if, on entry, $\mathbf{pn}=0$, i.e., no data has been previously processed, then $\mathbf{rmean}\left[l-1\right]$ is the summary corresponding to the window that ends on $\mathbf{x}\left[\mathbf{m}+l-2\right]$ (or, equivalently, starts on $\mathbf{x}\left[l-1\right]$).

8:    $\mathbf{rsd}\left[\mathit{dim}\right]$ – doubleOutput

Note: the dimension, dim, of the array rsd must be at least

• $\max \left(0,\mathbf{nb}+\min \left(0,\mathbf{pn}-\mathbf{m}+1\right)\right)$, when $\mathbf{rsd}\text{is not}\mathbf{NULL}$.

If standard deviations are not required then rsd must be NULL.

On exit: if $\mathbf{rsd}\text{is not}\mathbf{NULL}$ then ${\sigma }_l$, the (weighted) standard deviation. The ordering of rsd is the same as the ordering of rmean.

9:    $\mathbf{rcomm}\left[\mathit{dim}\right]$ – doubleCommunication Array

Note: the dimension, dim, of the array rcomm must be at least

• $0$, when $\mathbf{rcomm}\text{is}\mathbf{NULL}$;
• $2\mathbf{m}+20$, otherwise.

On entry: communication array, used to store information between calls to nag_moving_average (g01wac). If $\mathbf{rcomm}\text{is}\mathbf{NULL}$ then pn must be set to zero and all the data must be supplied in one go.

10:  $\mathbf{fail}$ – NagError *Input/Output

The NAG error argument (see Section 3.7 in How to Use the NAG Library and its Documentation).

6

Error Indicators and Warnings

NE_ALLOC_FAIL

Dynamic memory allocation failed.
See Section 2.3.1.2 in How to Use the NAG Library and its Documentation for further information.

NE_BAD_PARAM

On entry, argument $〈\mathit{\text{value}}〉$ had an illegal value.

NE_ILLEGAL_COMM

rcomm has been corrupted between calls.

NE_INT

On entry, $\mathbf{m}=〈\mathit{\text{value}}〉$.
Constraint: $\mathbf{m}\ge 1$.

On entry, $\mathbf{nb}=〈\mathit{\text{value}}〉$.
Constraint: $\mathbf{nb}\ge 0$.

On entry, $\mathbf{nb}=〈\mathit{\text{value}}〉$, $\mathbf{m}=〈\mathit{\text{value}}〉$.
Constraint: if $\mathbf{rcomm}\text{is}\mathbf{NULL}$, $\mathbf{nb}\ge \mathbf{m}$.

On entry, $\mathbf{pn}=〈\mathit{\text{value}}〉$.
Constraint: $\mathbf{pn}\ge 0$.

NE_INTERNAL_ERROR

An internal error has occurred in this function. Check the function call and any array sizes. If the call is correct then please contact NAG for assistance.
See Section 2.7.6 in How to Use the NAG Library and its Documentation for further information.

NE_NEG_WEIGHT

On entry, $\mathbf{wt}\left[〈\mathit{\text{value}}〉\right]=〈\mathit{\text{value}}〉$.
Constraint: $\mathbf{wt}\left[i-1\right]\ge 0$.

NE_NO_LICENCE

Your licence key may have expired or may not have been installed correctly.
See Section 2.7.5 in How to Use the NAG Library and its Documentation for further information.

NE_PREV_CALL

if $\mathbf{pn}>0$, iwt must be unchanged since previous call.

On entry, $\mathbf{m}=〈\mathit{\text{value}}〉$.
On entry at previous call, $\mathbf{m}=〈\mathit{\text{value}}〉$.
Constraint: if $\mathbf{pn}>0$, m must be unchanged since previous call.

On entry, $\mathbf{pn}=〈\mathit{\text{value}}〉$.
On exit from previous call, $\mathbf{pn}=〈\mathit{\text{value}}〉$.
Constraint: if $\mathbf{pn}>0$, pn must be unchanged since previous call.

NE_SUM_WEIGHT

On entry, sum of weights supplied in wt is $〈\mathit{\text{value}}〉$.
Constraint: if $\mathbf{iwt}=\mathrm{Nag\_WeightWindow}$, the sum of the weights $>0$.

NE_WEIGHT_ZERO

On entry, $\mathbf{wt}\left[0\right]=〈\mathit{\text{value}}〉$.
Constraint: if $\mathbf{iwt}=\mathrm{Nag\_WeightWindow}$, $\mathbf{wt}\left[0\right]>0$.

NW_POTENTIAL_PROBLEM

On entry, at least one window had all zero weights.

On entry, unable to calculate at least one standard deviation due to the weights supplied.

7

Accuracy

8

Parallelism and Performance

9

Further Comments

10

Example

10.1

Program Text

Program Text (g01wace.c)

10.2

Program Data

Program Data (g01wace.d)

10.3

Program Results

Program Results (g01wace.r)