g13 Chapter Contents
g13 Chapter Introduction
NAG Library Manual

# NAG Library Function Documentnag_tsa_inhom_iema (g13mec)

## 1  Purpose

nag_tsa_inhom_iema (g13mec) calculates the iterated exponential moving average for an inhomogeneous time series.

## 2  Specification

 #include #include
 void nag_tsa_inhom_iema (Integer nb, double iema[], const double t[], double tau, Integer m, const double sinit[], const Nag_TS_Interpolation inter[], Integer *pn, double rcomm[], NagError *fail)

## 3  Description

nag_tsa_inhom_iema (g13mec) 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}_{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 for the EMA operator (see Zumbach and Müller (2001)):
 $EMA τ;z ti = μ ⁢ EMA τ;z ti-1 + ν-μ ⁢ zi-1 + 1-ν ⁢ zi$
where
 $μ = e-α and α = ti - ti-1 τ .$
The value of $\nu$ depends on the method of interpolation chosen. nag_tsa_inhom_iema (g13mec) 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$.
The $m$-iterated exponential moving average, $\text{EMA}\left[\tau ,m;z\right]\left({t}_{i}\right)$, $m>1$, is defined using the recursive formula:
 $EMA τ,m;z = EMA τ ; EMA τ,m-1 ; z$
with
 $EMA τ,1;z = EMA τ ; z .$
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_iema (g13mec) 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. The size of the block of data supplied in iema and t can vary; therefore nb can change between calls to nag_tsa_inhom_iema (g13mec).
Constraint: ${\mathbf{nb}}\ge 0$.
2:     iema[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 iterated EMA, with ${\mathbf{iema}}\left[i-1\right]=\text{EMA}\left[\tau ,m;z\right]\left({t}_{i}\right)$.
3:     t[nb]const doubleInput
On entry: ${t}_{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 (g13mec) will continue as if $t$ was strictly increasing by using the absolute value.
4:     taudoubleInput
On entry: $\tau$, the argument controlling the rate of decay, which 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$.
5:     mIntegerInput
On entry: $m$, the number of times the EMA operator is to be iterated.
Constraint: ${\mathbf{m}}\ge 1$.
6:     sinit[${\mathbf{m}}+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]={z}_{0}$,
• ${\mathbf{sinit}}\left[\mathit{j}+1\right]=\text{EMA}\left[\tau ,\mathit{j};z\right]\left({t}_{0}\right)$, for $\mathit{j}=1,2,\dots ,{\mathbf{m}}$.
If ${\mathbf{pn}}\ne 0$, sinit is not referenced and may be NULL.
7:     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$.
8:     pnInteger *Input/Output
On entry: $k$, the number of observations processed so far. On the first call to nag_tsa_inhom_iema (g13mec), 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 (g13mec).
On exit: $k+b$, the updated number of observations processed so far.
Constraint: ${\mathbf{pn}}\ge 0$.
9:     rcomm[${\mathbf{m}}+20$]doubleCommunication Array
On entry: communication array, used to store information between calls to nag_tsa_inhom_iema (g13mec). 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.
10:   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{m}}=⟨\mathit{\text{value}}⟩$.
Constraint: ${\mathbf{m}}\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_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 inter 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$ then 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$ 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, ${\mathbf{tau}}=⟨\mathit{\text{value}}⟩$.
Constraint: ${\mathbf{tau}}>0.0$.
NE_REAL_ARRAY
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, iema or for tau. Results are returned using the truncated values.

Not applicable.

## 8  Parallelism and Performance

nag_tsa_inhom_iema (g13mec) is threaded by NAG for parallel execution in multithreaded implementations of the NAG Library.
nag_tsa_inhom_iema (g13mec) 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 $4m$ real elements are internally allocated by nag_tsa_inhom_iema (g13mec).
The more data you supply to nag_tsa_inhom_iema (g13mec) in one call, i.e., the larger nb is, the more efficient the function will be.
Checks are made during the calculation of $\alpha$ 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 iema, t or tau are supplied.

## 10  Example

The example reads in a simulated time series, $\left(t,z\right)$ and calculates the iterated exponential moving average.

### 10.1  Program Text

Program Text (g13mece.c)

### 10.2  Program Data

Program Data (g13mece.d)

### 10.3  Program Results

Program Results (g13mece.r)

This example plot shows the exponential moving average for the same data using three different values of $\tau$ and illustrates the effect on the EMA of altering this argument.