g13 Chapter Contents
g13 Chapter Introduction
NAG Library Manual

# NAG Library Function Documentnag_tsa_inhom_iema_all (g13mfc)

## 1  Purpose

nag_tsa_inhom_iema_all (g13mfc) calculates the iterated exponential moving average for an inhomogeneous time series, returning the intermediate results.

## 2  Specification

 #include #include
 void nag_tsa_inhom_iema_all (Nag_OrderType order, Integer nb, const double z[], double iema[], Integer pdiema, const double t[], double tau, Integer m1, Integer m2, const double sinit[], const Nag_TS_Interpolation inter[], Nag_TS_Transform ftype, double *p, const double x[], Integer *pn, double rcomm[], NagError *fail)

## 3  Description

nag_tsa_inhom_iema_all (g13mfc) calculates the iterated exponential moving average 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}_{\mathit{i}}\right)$, for $\mathit{i}=1,2,\dots ,n$. Time can be measured in any arbitrary units, as long as all elements of $t$ use the same units.
The exponential moving average (EMA), with parameter $\tau$, is an average operator, with the exponentially decaying kernel given by
 $e -ti/τ τ .$
The exponential form of this kernel gives rise to the following iterative formula (Zumbach and Müller (2001)) for the EMA operator:
 $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_iema_all (g13mfc) 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}-{x}_{i}\right|}^{p}$;
where the notation $\left[p\right]$ is used to denote the integer nearest to $p$. In the case of the absolute difference $x$ is a user-supplied vector of length $n$ and therefore each element of the time series is composed of the triplet of scalar values, $\left({t}_{i},{z}_{i},{x}_{i}\right)$.
The $m$-iterated exponential moving average, $\text{EMA}\left[\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 .$
For large datasets or where all the data is not available at the same time, $z,t$ and, where required, $x$ can be split into arbitrary sized blocks and nag_tsa_inhom_iema_all (g13mfc) 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:     orderNag_OrderTypeInput
On entry: the order argument specifies the two-dimensional storage scheme being used, i.e., row-major ordering or column-major ordering. C language defined storage is specified by ${\mathbf{order}}=\mathrm{Nag_RowMajor}$. See Section 3.2.1.3 in the Essential Introduction for a more detailed explanation of the use of this argument.
Constraint: ${\mathbf{order}}=\mathrm{Nag_RowMajor}$ or $\mathrm{Nag_ColMajor}$.
2:     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 z, t and x can vary; therefore nb can change between calls to nag_tsa_inhom_iema_all (g13mfc).
Constraint: ${\mathbf{nb}}\ge 0$.
3:     z[nb]const doubleInput
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.
Constraint: if ${\mathbf{ftype}}=\mathrm{Nag_Identity}$ or $\mathrm{Nag_AbsVal}$ and ${\mathbf{p}}<0.0$, ${\mathbf{z}}\left[\mathit{i}-1\right]\ne 0$, for $\mathit{i}=1,2,\dots ,{\mathbf{nb}}$.
4:     iema[$\mathit{dim}$]doubleOutput
Note: the dimension, dim, of the array iema must be at least ${\mathbf{pdiema}}×$.
Where ${\mathbf{IEMA}}\left(i,j\right)$ appears in this document, it refers to the array element
• ${\mathbf{iema}}\left[\left(j-1\right)×{\mathbf{pdiema}}+i-1\right]$ when ${\mathbf{order}}=\mathrm{Nag_ColMajor}$;
• ${\mathbf{iema}}\left[\left(i-1\right)×{\mathbf{pdiema}}+j-1\right]$ when ${\mathbf{order}}=\mathrm{Nag_RowMajor}$.
On exit: the iterated exponential moving average.
If ${\mathbf{order}}=\mathrm{Nag_ColMajor}$, ${\mathbf{IEMA}}\left(i,j\right)=\text{EMA}\left[\tau ,j+{\mathbf{m1}}-1;y\right]\left({t}_{i+k}\right)$.
If ${\mathbf{order}}=\mathrm{Nag_RowMajor}$, ${\mathbf{IEMA}}\left(j,i\right)=\text{EMA}\left[\tau ,j+{\mathbf{m1}}-1;y\right]\left({t}_{i+k}\right)$.
For $i=1,2,\dots ,{\mathbf{nb}}$, $j=1,2,\dots ,{\mathbf{m2}}-{\mathbf{m1}}+1$ and $k$ is the number of observations processed so far, i.e., the value supplied in pn on entry.
5:     pdiemaIntegerInput
On entry: the stride separating row or column elements (depending on the value of order) in the array iema.
Constraints:
• if ${\mathbf{order}}=\mathrm{Nag_ColMajor}$, ${\mathbf{pdiema}}\ge {\mathbf{nb}}$;
• otherwise ${\mathbf{pdiema}}\ge {\mathbf{m2}}-{\mathbf{m1}}+1$.
6:     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_iema_all (g13mfc) will continue as if $t$ was strictly increasing by using the absolute value.
7:     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)/\tau$ can be calculated without overflowing, for all $i$.
Constraint: ${\mathbf{tau}}>0.0$.
8:     m1IntegerInput
On entry: the minimum number of times the EMA operator is to be iterated.
Constraint: ${\mathbf{m1}}\ge 1$.
9:     m2IntegerInput
On entry: the maximum number of times the EMA operator is to be iterated. Therefore nag_tsa_inhom_iema_all (g13mfc) returns $\text{EMA}\left[\tau ,m;y\right]$, for $m={\mathbf{m1}},{\mathbf{m1}}+1,\dots ,{\mathbf{m2}}$.
Constraint: ${\mathbf{m2}}\ge {\mathbf{m1}}$.
10:   sinit[${\mathbf{m2}}+2$]const doubleInput
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[j+1\right]=\text{EMA}\left[\tau ,j;y\right]\left({t}_{0}\right)$, $j=1,2,\dots ,{\mathbf{m2}}$.
If ${\mathbf{pn}}\ne 0$ then 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$.
11:   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$.
12:   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}$
The absolute value, with ${y}_{i}={\left|{z}_{i}\right|}^{p}$.
${\mathbf{ftype}}=\mathrm{Nag_AbsDiff}$
The absolute difference, with ${y}_{i}={\left|{z}_{i}-{x}_{i}\right|}^{p}$, where the vector $x$ is supplied in x.
Constraint: ${\mathbf{ftype}}=\mathrm{Nag_Identity}$, $\mathrm{Nag_AbsVal}$ or $\mathrm{Nag_AbsDiff}$.
13:   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$.
14:   x[${\mathbf{nb}}$]const doubleInput
On entry: if ${\mathbf{ftype}}=\mathrm{Nag_AbsDiff}$, ${x}_{i}$, the vector used to shift 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 ${\mathbf{ftype}}\ne \mathrm{Nag_AbsDiff}$ then x is not referenced and may be NULL.
Constraint: if ${\mathbf{ftype}}=\mathrm{Nag_AbsDiff}$ and ${\mathbf{p}}<0$, ${\mathbf{x}}\left[\mathit{i}-1\right]\ne {\mathbf{z}}\left[\mathit{i}-1\right]$, for $\mathit{i}=1,2,\dots ,{\mathbf{nb}}$.
15:   pnInteger *Input/Output
On entry: $k$, the number of observations processed so far. On the first call to nag_tsa_inhom_iema_all (g13mfc), 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_iema_all (g13mfc).
On exit: $k+b$, the updated number of observations processed so far.
Constraint: ${\mathbf{pn}}\ge 0$.
16:   rcomm[${\mathbf{m2}}+20$]doubleCommunication Array
On entry: communication array, used to store information between calls to nag_tsa_inhom_iema_all (g13mfc). 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.
17:   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.
NE_ARRAY_SIZE
On entry, ${\mathbf{order}}=\mathrm{Nag_ColMajor}$, ${\mathbf{pdiema}}=⟨\mathit{\text{value}}⟩$ and ${\mathbf{nb}}=⟨\mathit{\text{value}}⟩$.
Constraint: ${\mathbf{pdiema}}\ge {\mathbf{nb}}$.
On entry, ${\mathbf{order}}=\mathrm{Nag_RowMajor}$, ${\mathbf{pdiema}}=⟨\mathit{\text{value}}⟩$ and ${\mathbf{m2}}-{\mathbf{m1}}+1=⟨\mathit{\text{value}}⟩$.
Constraint: ${\mathbf{pdiema}}\ge {\mathbf{m2}}-{\mathbf{m1}}+1$.
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{z}}\left[i-1\right]=⟨\mathit{\text{value}}⟩$ and ${\mathbf{p}}=⟨\mathit{\text{value}}⟩$.
Constraint: if ${\mathbf{ftype}}=\mathrm{Nag_Identity}$ or $\mathrm{Nag_AbsVal}$ and ${\mathbf{z}}\left[i\right]=0$ for any $i$ then ${\mathbf{p}}>0.0$.
On entry, $i=⟨\mathit{\text{value}}⟩$, ${\mathbf{z}}\left[i-1\right]=⟨\mathit{\text{value}}⟩$, ${\mathbf{x}}\left[i-1\right]=⟨\mathit{\text{value}}⟩$ and ${\mathbf{p}}=⟨\mathit{\text{value}}⟩$.
Constraint: if ${\mathbf{ftype}}=\mathrm{Nag_AbsDiff}$ and ${\mathbf{z}}\left[i\right]={\mathbf{x}}\left[i\right]$ for any $i$ then ${\mathbf{p}}>0.0$.
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, z, x or for tau. Results are returned using the truncated values.

Not applicable.

## 8  Parallelism and Performance

nag_tsa_inhom_iema_all (g13mfc) is threaded by NAG for parallel execution in multithreaded implementations of the NAG Library.
nag_tsa_inhom_iema_all (g13mfc) 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×{\mathbf{m2}}$ real elements are internally allocated by nag_tsa_inhom_iema_all (g13mfc).
The more data you supply to nag_tsa_inhom_iema_all (g13mfc) in one call, i.e., the larger nb is, the more efficient the routine 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 z, t, x or tau are supplied.

## 10  Example

This example reads in three blocks of simulated data from an inhomogeneous time series, then calculates and prints the iterated EMA for $m$ between $2$ and $6$.

### 10.1  Program Text

Program Text (g13mfce.c)

### 10.2  Program Data

Program Data (g13mfce.d)

### 10.3  Program Results

Program Results (g13mfce.r)