g13 Chapter Contents
g13 Chapter Introduction
NAG Library Manual

# NAG Library Function Documentnag_tsa_inhom_ma (g13mgc)

## 1  Purpose

nag_tsa_inhom_ma (g13mgc) provides a moving average, moving norm, moving variance and moving standard deviation operator for an inhomogeneous time series.

## 2  Specification

 #include #include
 void nag_tsa_inhom_ma (Integer nb, double ma[], const double t[], double tau, Integer m1, Integer m2, const double sinit[], const Nag_TS_Interpolation inter[], Nag_TS_Transform ftype, double *p, Integer *pn, double wma[], double rcomm[], NagError *fail)

## 3  Description

nag_tsa_inhom_ma (g13mgc) provides a number of operators for an inhomogeneous time series. The time series is represented by two vectors of length $n$; a vector of times, $t$; and a vector of values, $z$. Each element of the time series is therefore composed of the pair of scalar values $\left({t}_{\mathit{i}},{z}_{i}\right)$, for $\mathit{i}=1,2,\dots ,n$. Time $t$ can be measured in any arbitrary units, as long as all elements of $t$ use the same units.
The main operator available, the moving average (MA), with parameter $\tau$ is defined as
 $MA τ, m1, m2; y ti = 1 m2 - m1 +1 ∑ j=m1 m2 EMA τ~, j; y ti$ (1)
where $\stackrel{~}{\tau }=\frac{2\tau }{{m}_{2}+{m}_{1}}$, ${m}_{1}$ and ${m}_{2}$ are user-supplied integers controlling the amount of lag and smoothing respectively, with ${m}_{2}\ge {m}_{1}$ and $\text{EMA}\left(·\right)$ is the iterated exponential moving average operator.
The iterated exponential moving average, $\text{EMA}\left[\stackrel{~}{\tau },m;y\right]\left({t}_{i}\right)$, is defined using the recursive formula:
 $EMA τ~,m ; y ti = EMA τ~ ; EMA τ~,m-1 ; y ti ti$
with
 $EMA τ~,1;y ti = EMA τ~;y ti$
and
 $EMA τ~ ; y ti = μ ⁢ EMA τ~;y ti-1 + ν-μ ⁢ yi-1 + 1-ν ⁢ yi$
where
 $μ = e-α and α = ti - ti-1 τ~ .$
The value of $\nu$ depends on the method of interpolation chosen and the relationship between $y$ and the input series $z$ depends on the transformation function chosen. nag_tsa_inhom_ma (g13mgc) gives the option of three interpolation methods:
 1 Previous point: $\nu =1$. 2 Linear: $\nu =\left(1-\mu \right)/\alpha$. 3 Next point: $\nu =\mu$.
and three transformation functions:
 1 Identity: ${y}_{i}={{z}_{i}}^{\left[p\right]}$. 2 Absolute value: ${y}_{i}={\left|{z}_{i}\right|}^{p}$. 3 Absolute difference: ${y}_{i}={\left|{z}_{i}-\text{MA}\left[\tau ,{m}_{1},{m}_{2};z\right]\left({t}_{i}\right)\right|}^{p}$.
where the notation $\left[p\right]$ is used to denote the integer nearest to $p$. In addition, if either the absolute value or absolute difference transformation are used then the resulting moving average can be scaled by ${p}^{-1}$.
The various parameter options allow a number of different operators to be applied by nag_tsa_inhom_ma (g13mgc), a few of which are:
(i) Moving Average (MA), as defined in (1) (obtained by setting ${\mathbf{ftype}}=\mathrm{Nag_Identity}$ and ${\mathbf{p}}=1$).
(ii) Moving Norm (MNorm), defined as
 $MNorm τ,m,p;z = MA τ,1,m; z p 1 / p$
(obtained by setting ${\mathbf{ftype}}=\mathrm{Nag_AbsValScaled}$, ${\mathbf{m1}}=1$ and ${\mathbf{m2}}=m$).
(iii) Moving Variance (MVar), defined as
 $MVar τ,m,p;z = MA τ,1,m; z - MA τ,1,m;z p$
(obtained by setting ${\mathbf{ftype}}=\mathrm{Nag_AbsDiff}$, ${\mathbf{m1}}=1$ and ${\mathbf{m2}}=m$).
(iv) Moving Standard Deviation (MSD), defined as
 $MSD τ,m,p;z = MA τ,1,m; z - MA τ,1,m;z p 1 / p$
(obtained by setting ${\mathbf{ftype}}=\mathrm{Nag_AbsDiffScaled}$, ${\mathbf{m1}}=1$ and ${\mathbf{m2}}=m$).
For large datasets or where all the data is not available at the same time, $z$ and $t$ can be split into arbitrary sized blocks and nag_tsa_inhom_ma (g13mgc) called multiple times.

## 4  References

Dacorogna M M, Gencay R, Müller U, Olsen R B and Pictet O V (2001) An Introduction to High-frequency Finance Academic Press
Zumbach G O and Müller U A (2001) Operators on inhomogeneous time series International Journal of Theoretical and Applied Finance 4(1) 147–178

## 5  Arguments

1:     nbIntegerInput
On entry: $b$, the number of observations in the current block of data. At each call the size of the block of data supplied in ma and t can vary; therefore nb can change between calls to nag_tsa_inhom_ma (g13mgc).
Constraint: ${\mathbf{nb}}\ge 0$.
2:     ma[nb]doubleInput/Output
On entry: ${z}_{\mathit{i}}$, the current block of observations, for $\mathit{i}=k+1,\dots ,k+b$, where $k$ is the number of observations processed so far, i.e., the value supplied in pn on entry.
On exit: the moving average:
if ${\mathbf{ftype}}=\mathrm{Nag_AbsValScaled}$ or $\mathrm{Nag_AbsDiffScaled}$
${\mathbf{ma}}\left[i-1\right]={\left\{\text{MA}\left[\tau ,{m}_{1},{m}_{2};y\right]\left({t}_{i}\right)\right\}}^{1/p}$,
otherwise
${\mathbf{ma}}\left[i-1\right]=\text{MA}\left[\tau ,{m}_{1},{m}_{2};y\right]\left({t}_{i}\right)$.
3:     t[nb]const doubleInput
On entry: ${t}_{\mathit{i}}$, the times for the current block of observations, for $\mathit{i}=k+1,\dots ,k+b$, where $k$ is the number of observations processed so far, i.e., the value supplied in pn on entry.
If ${t}_{i}\le {t}_{i-1}$, ${\mathbf{fail}}\mathbf{.}\mathbf{code}=$ NE_NOT_STRICTLY_INCREASING will be returned, but nag_tsa_inhom_ma (g13mgc) will continue as if $t$ was strictly increasing by using the absolute value. The lagged difference, ${t}_{i}-{t}_{i-1}$ must be sufficiently small that ${e}^{-\alpha }$, $\alpha =\left({t}_{i}-{t}_{i-1}\right)/\stackrel{~}{\tau }$ can be calculated without overflowing, for all $i$.
4:     taudoubleInput
On entry: $\tau$, the parameter controlling the rate of decay. $\tau$ must be sufficiently large that ${e}^{-\alpha }$, $\alpha =\left({t}_{i}-{t}_{i-1}\right)/\stackrel{~}{\tau }$ can be calculated without overflowing, for all $i$, where $\stackrel{~}{\tau }=\frac{2\tau }{{m}_{2}+{m}_{1}}$.
Constraint: ${\mathbf{tau}}>0.0$.
5:     m1IntegerInput
On entry: ${m}_{1}$, the iteration of the EMA operator at which the sum is started.
Constraint: ${\mathbf{m1}}\ge 1$.
6:     m2IntegerInput
On entry: ${m}_{2}$, the iteration of the EMA operator at which the sum is ended.
Constraint: ${\mathbf{m2}}\ge {\mathbf{m1}}$.
7:     sinit[$\mathit{dim}$]const doubleInput
Note: the dimension, dim, of the array sinit must be at least
• $2×{\mathbf{m2}}+3$ when ${\mathbf{ftype}}=\mathrm{Nag_AbsDiff}$ or $\mathrm{Nag_AbsDiffScaled}$;
• ${\mathbf{m2}}+2$ when ${\mathbf{ftype}}=\mathrm{Nag_Identity}$, $\mathrm{Nag_AbsVal}$ or $\mathrm{Nag_AbsValScaled}$;
• sinit may be NULL when ${\mathbf{pn}}\ne 0$.
On entry: if ${\mathbf{pn}}=0$, the values used to start the iterative process, with
• ${\mathbf{sinit}}\left[0\right]={t}_{0}$,
• ${\mathbf{sinit}}\left[1\right]={y}_{0}$,
• ${\mathbf{sinit}}\left[\mathit{j}+1\right]=\text{EMA}\left[\tau ,\mathit{j};y\right]\left({t}_{0}\right)$, for $\mathit{i}=1,2,\dots ,{\mathbf{m2}}$.
In addition, if ${\mathbf{ftype}}=\mathrm{Nag_AbsDiff}$ or $\mathrm{Nag_AbsDiffScaled}$ then
• ${\mathbf{sinit}}\left[{\mathbf{m2}}+2\right]={z}_{0}$,
• ${\mathbf{sinit}}\left[{\mathbf{m2}}+\mathit{j}+1\right]=\text{EMA}\left[\tau ,\mathit{j};z\right]\left({t}_{0}\right)$, for $\mathit{j}=1,2,\dots ,{\mathbf{m2}}$.
i.e., initial values based on the original data $z$ as opposed to the transformed data $y$.
If ${\mathbf{pn}}\ne 0$, sinit is not referenced and may be NULL.
Constraint: if ${\mathbf{ftype}}\ne \mathrm{Nag_Identity}$, ${\mathbf{sinit}}\left[\mathit{j}-1\right]\ge 0$, for $\mathit{j}=2,3,\dots ,{\mathbf{m2}}+2$.
8:     inter[$2$]const Nag_TS_InterpolationInput
On entry: the type of interpolation used with ${\mathbf{inter}}\left[0\right]$ indicating the interpolation method to use when calculating $\text{EMA}\left[\tau ,1;z\right]$ and ${\mathbf{inter}}\left[1\right]$ the interpolation method to use when calculating $\text{EMA}\left[\tau ,j;z\right]$, $j>1$.
Three types of interpolation are possible:
${\mathbf{inter}}\left[i\right]=\mathrm{Nag_PreviousPoint}$
Previous point, with $\nu =1$.
${\mathbf{inter}}\left[i\right]=\mathrm{Nag_Linear}$
Linear, with $\nu =\left(1-\mu \right)/\alpha$.
${\mathbf{inter}}\left[i\right]=\mathrm{Nag_NextPoint}$
Next point, $\nu =\mu$.
Zumbach and Müller (2001) recommend that linear interpolation is used in second and subsequent iterations, i.e., ${\mathbf{inter}}\left[1\right]=\mathrm{Nag_Linear}$, irrespective of the interpolation method used at the first iteration, i.e., the value of ${\mathbf{inter}}\left[0\right]$.
Constraint: ${\mathbf{inter}}\left[\mathit{i}-1\right]=\mathrm{Nag_PreviousPoint}$, $\mathrm{Nag_Linear}$ or $\mathrm{Nag_NextPoint}$, for $\mathit{i}=1,2$.
9:     ftypeNag_TS_TransformInput
On entry: the function type used to define the relationship between $y$ and $z$ when calculating $\text{EMA}\left[\tau ,1;y\right]$. Three functions are provided:
${\mathbf{ftype}}=\mathrm{Nag_Identity}$
The identity function, with ${y}_{i}={{z}_{i}}^{\left[p\right]}$.
${\mathbf{ftype}}=\mathrm{Nag_AbsVal}$ or $\mathrm{Nag_AbsValScaled}$
The absolute value, with ${y}_{i}={\left|{z}_{i}\right|}^{p}$.
${\mathbf{ftype}}=\mathrm{Nag_AbsDiff}$ or $\mathrm{Nag_AbsDiffScaled}$
The absolute difference, with ${y}_{i}={\left|{z}_{i}-\text{MA}\left[\tau ,m;y\right]\left({t}_{i}\right)\right|}^{p}$.
If ${\mathbf{ftype}}=\mathrm{Nag_AbsValScaled}$ or $\mathrm{Nag_AbsDiffScaled}$ then the resulting vector of averages is scaled by ${p}^{-1}$ as described in ma.
Constraint: ${\mathbf{ftype}}=\mathrm{Nag_Identity}$, $\mathrm{Nag_AbsVal}$, $\mathrm{Nag_AbsDiff}$, $\mathrm{Nag_AbsValScaled}$ or $\mathrm{Nag_AbsDiffScaled}$.
10:   pdouble *Input/Output
On entry: $p$, the power used in the transformation function.
On exit: if ${\mathbf{ftype}}=\mathrm{Nag_Identity}$, then $\left[p\right]$, the actual power used in the transformation function is returned, otherwise p is unchanged.
Constraint: ${\mathbf{p}}\ne 0$.
11:   pnInteger *Input/Output
On entry: $k$, the number of observations processed so far. On the first call to nag_tsa_inhom_ma (g13mgc), or when starting to summarise a new dataset, pn must be set to $0$. On subsequent calls it must be the same value as returned by the last call to nag_tsa_inhom_ma (g13mgc).
On exit: $k+b$, the updated number of observations processed so far.
Constraint: ${\mathbf{pn}}\ge 0$.
12:   wma[nb]doubleOutput
On exit: either the moving average or exponential moving average, depending on the value of ftype.
if ${\mathbf{ftype}}=\mathrm{Nag_AbsDiff}$ or $\mathrm{Nag_AbsDiffScaled}$
${\mathbf{wma}}\left[i-1\right]=\text{MA}\left[\tau ;y\right]\left({t}_{i}\right)$
otherwise
${\mathbf{wma}}\left[i-1\right]=\text{EMA}\left[\stackrel{~}{\tau };y\right]\left({t}_{i}\right)$.
13:   rcomm[$2×{\mathbf{m2}}+20$]doubleCommunication Array
On entry: communication array, used to store information between calls to nag_tsa_inhom_ma (g13mgc). If ${\mathbf{rcomm}}\phantom{\rule{0.25em}{0ex}}\text{is}\phantom{\rule{0.25em}{0ex}}\mathbf{NULL}$ then pn must be set to zero and all the data must be supplied in one go.
14:   failNagError *Input/Output
The NAG error argument (see Section 3.6 in the Essential Introduction).

## 6  Error Indicators and Warnings

NE_ALLOC_FAIL
Dynamic memory allocation failed.
On entry, argument $⟨\mathit{\text{value}}⟩$ had an illegal value.
NE_ILLEGAL_COMM
rcomm has been corrupted between calls.
NE_INT
On entry, ${\mathbf{m1}}=⟨\mathit{\text{value}}⟩$.
Constraint: ${\mathbf{m1}}\ge 1$.
On entry, ${\mathbf{nb}}=⟨\mathit{\text{value}}⟩$.
Constraint: ${\mathbf{nb}}\ge 0$.
On entry, ${\mathbf{pn}}=⟨\mathit{\text{value}}⟩$.
Constraint: ${\mathbf{pn}}\ge 0$.
NE_INT_2
On entry, ${\mathbf{m1}}=⟨\mathit{\text{value}}⟩$ and ${\mathbf{m2}}=⟨\mathit{\text{value}}⟩$.
Constraint: ${\mathbf{m2}}\ge {\mathbf{m1}}$.
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.
NE_NOT_STRICTLY_INCREASING
On entry, $i=⟨\mathit{\text{value}}⟩$, ${\mathbf{t}}\left[i-2\right]=⟨\mathit{\text{value}}⟩$ and ${\mathbf{t}}\left[i-1\right]=⟨\mathit{\text{value}}⟩$.
Constraint: t should be strictly increasing.
NE_PREV_CALL
If ${\mathbf{pn}}>0$ then ftype must be unchanged since previous call.
If ${\mathbf{pn}}>0$ then inter must be unchanged since previous call.
On entry, ${\mathbf{m1}}=⟨\mathit{\text{value}}⟩$.
On entry at previous call, ${\mathbf{m1}}=⟨\mathit{\text{value}}⟩$.
Constraint: if ${\mathbf{pn}}>0$ then m1 must be unchanged since previous call.
On entry, ${\mathbf{m2}}=⟨\mathit{\text{value}}⟩$.
On entry at previous call, ${\mathbf{m2}}=⟨\mathit{\text{value}}⟩$.
Constraint: if ${\mathbf{pn}}>0$ then m2 must be unchanged since previous call.
On entry, ${\mathbf{p}}=⟨\mathit{\text{value}}⟩$.
On exit from previous call, ${\mathbf{p}}=⟨\mathit{\text{value}}⟩$.
Constraint: if ${\mathbf{pn}}>0$ then p 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$ then pn must be unchanged since previous call.
On entry, ${\mathbf{tau}}=⟨\mathit{\text{value}}⟩$.
On entry at previous call, ${\mathbf{tau}}=⟨\mathit{\text{value}}⟩$.
Constraint: if ${\mathbf{pn}}>0$ then tau must be unchanged since previous call.
NE_REAL
On entry, $i=⟨\mathit{\text{value}}⟩$, ${\mathbf{ma}}\left[i-1\right]=⟨\mathit{\text{value}}⟩$ and ${\mathbf{p}}=⟨\mathit{\text{value}}⟩$.
Constraint: if ${\mathbf{ftype}}=\mathrm{Nag_Identity}$, $\mathrm{Nag_AbsVal}$ or $\mathrm{Nag_AbsValScaled}$ and ${\mathbf{ma}}\left[i-1\right]=0$ for any $i$ then ${\mathbf{p}}>0.0$.
On entry, $i=⟨\mathit{\text{value}}⟩$, ${\mathbf{ma}}\left[i-1\right]=⟨\mathit{\text{value}}⟩$, ${\mathbf{wma}}\left[i-1\right]=⟨\mathit{\text{value}}⟩$ and ${\mathbf{p}}=⟨\mathit{\text{value}}⟩$.
Constraint: if ${\mathbf{p}}<0.0$, ${\mathbf{ma}}\left[i-1\right]-{\mathbf{wma}}\left[i-1\right]\ne 0.0$, for any $i$.
On entry, ${\mathbf{p}}=⟨\mathit{\text{value}}⟩$.
Constraint: absolute value of p must be representable as an integer.
On entry, ${\mathbf{p}}=⟨\mathit{\text{value}}⟩$.
Constraint: if ${\mathbf{ftype}}\ne \mathrm{Nag_Identity}$, ${\mathbf{p}}\ne 0.0$. If ${\mathbf{ftype}}=\mathrm{Nag_Identity}$, the nearest integer to ${\mathbf{p}}$ must not be $0$.
On entry, ${\mathbf{tau}}=⟨\mathit{\text{value}}⟩$.
Constraint: ${\mathbf{tau}}>0.0$.
NE_REAL_ARRAY
On entry, ${\mathbf{ftype}}\ne \mathrm{Nag_Identity}$, $j=⟨\mathit{\text{value}}⟩$ and ${\mathbf{sinit}}\left[j-1\right]=⟨\mathit{\text{value}}⟩$.
Constraint: if ${\mathbf{ftype}}\ne \mathrm{Nag_Identity}$, ${\mathbf{sinit}}\left[\mathit{j}-1\right]\ge 0.0$, for $\mathit{j}=2,3,\dots ,{\mathbf{m2}}+2$.
On entry, $i=⟨\mathit{\text{value}}⟩$, ${\mathbf{t}}\left[i-2\right]=⟨\mathit{\text{value}}⟩$ and ${\mathbf{t}}\left[i-1\right]=⟨\mathit{\text{value}}⟩$.
Constraint: ${\mathbf{t}}\left[i-1\right]\ne {\mathbf{t}}\left[i-2\right]$ if linear interpolation is being used.
NW_OVERFLOW_WARN
Truncation occurred to avoid overflow, check for extreme values in t, ma or for tau. Results are returned using the truncated values.

Not applicable.

## 8  Parallelism and Performance

nag_tsa_inhom_ma (g13mgc) is threaded by NAG for parallel execution in multithreaded implementations of the NAG Library.
nag_tsa_inhom_ma (g13mgc) makes calls to BLAS and/or LAPACK routines, which may be threaded within the vendor library used by this implementation. Consult the documentation for the vendor library for further information.

Approximately $4{m}_{2}$ real elements are internally allocated by nag_tsa_inhom_ma (g13mgc). If ${\mathbf{ftype}}=\mathrm{Nag_AbsDiff}$ or $\mathrm{Nag_AbsDiffScaled}$ then a further nb real elements are also allocated.
The more data you supply to nag_tsa_inhom_ma (g13mgc) in one call, i.e., the larger nb is, the more efficient the function will be.
Checks are made during the calculation of $\alpha$ and ${y}_{i}$ to avoid overflow. If a potential overflow is detected the offending value is replaced with a large positive or negative value, as appropriate, and the calculations performed based on the replacement values. In such cases ${\mathbf{fail}}\mathbf{.}\mathbf{code}=$ NW_OVERFLOW_WARN is returned. This should not occur in standard usage and will only occur if extreme values of ma, t or tau are supplied.

## 10  Example

The example reads in a simulated time series, $\left(t,z\right)$ and calculates the moving average. The data is supplied in three blocks of differing sizes.

### 10.1  Program Text

Program Text (g13mgce.c)

### 10.2  Program Data

Program Data (g13mgce.d)

### 10.3  Program Results

Program Results (g13mgce.r)