naginterfaces.library.tsa.inhom_​iema_​all

naginterfaces.library.tsa.inhom_iema_all(z, t, tau, m1, inter, ftype, p, sorder=1, sinit=None, x=None, pn=0, comm=None)

inhom_iema_all calculates the iterated exponential moving average for an inhomogeneous time series, returning the intermediate results.

For full information please refer to the NAG Library document for g13mf

https://support.nag.com/numeric/nl/nagdoc_30/flhtml/g13/g13mff.html

Parameters

zfloat, array-like, shape $\left(\text{nb}\right)$

$z_{\text{i}}$, the current block of observations, for $\text{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.

tfloat, array-like, shape $\left(\text{nb}\right)$

$t_{\text{i}}$, the times for the current block of observations, for $\text{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}$, $errno$ = 61 will be returned, but inhom_iema_all will continue as if $t$ was strictly increasing by using the absolute value.

taufloat

$\tau$, the parameter controlling the rate of decay. $\tau$ must be sufficiently large that $e^{-\alpha }$, $\alpha =(t_i-t_{i-1})/\tau$ can be calculated without overflowing, for all $i$.

m1int

The minimum number of times the EMA operator is to be iterated.

interint, array-like, shape $\left(2\right)$

The type of interpolation used with $inter\left[0\right]$ indicating the interpolation method to use when calculating $\text{EMA}[\tau ,1;z]$ and $inter\left[1\right]$ the interpolation method to use when calculating $\text{EMA}[\tau ,j;z]$, $j>1$.

Three types of interpolation are possible:

$inter\left[i\right]=1$

Previous point, with $\nu =1$.

$inter\left[i\right]=2$

Linear, with $\nu =(1-\mu )/\alpha$.

$inter\left[i\right]=3$

Next point, $\nu =\mu$.

Zumbach and Müller (2001) recommend that linear interpolation is used in second and subsequent iterations, i.e., $inter\left[1\right]=2$, irrespective of the interpolation method used at the first iteration, i.e., the value of $inter\left[0\right]$.

ftypeint

The function type used to define the relationship between $y$ and $z$ when calculating $\text{EMA}[\tau ,1;y]$. Three functions are provided:

$ftype=1$

The identity function, with $y_i=z_i^{\left[p\right]}$.

$ftype=2$

The absolute value, with $y_i={\left|z_i\right|}^p$.

$ftype=3$

The absolute difference, with $y_i={|z_i-x_i|}^p$, where the vector $x$ is supplied in $x$.

pfloat

$p$, the power used in the transformation function.

sorderint, optional

Determines the storage order of output returned in $iema$.

sinitNone or float, array-like, shape $(\text{m2}+2)$, optional

If $pn=0$, the values used to start the iterative process, with

$sinit\left[0\right]=t_0$,

$sinit\left[1\right]=y_0$,

$sinit[j+1]=\text{EMA}[\tau ,j;y]\left(t_0\right)$, $j=1,2,\dots ,\text{m2}$.

If $pn\ne 0$ then $sinit$ is not referenced.

xNone or float, array-like, shape $(:)$, optional

Note: the required length for this argument is determined as follows: if $ftype=3$: $\text{nb}$; otherwise: $0$.

If $ftype=3$, $x_i$, the vector used to shift the current block of observations, for $\text{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 $ftype\ne 3$ then $x$ is not referenced.

pnint, optional

$k$, the number of observations processed so far. On the first call to inhom_iema_all, 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 inhom_iema_all.

commNone or dict, communication object, optional, modified in place

Communication structure.

On initial entry: need not be set.

Returns

iemafloat, ndarray, shape $(:,:)$

The iterated exponential moving average.

If $sorder=1$, $iema[i-1,j-1]=\text{EMA}[\tau ,j+m1-1;y]\left(t_{i+k}\right)$.

If $sorder=2$, $iema[j-1,i-1]=\text{EMA}[\tau ,j+m1-1;y]\left(t_{i+k}\right)$.

For $i=1,2,\dots ,\text{nb}$, $j=1,2,\dots ,\text{m2}-m1+1$ and $k$ is the number of observations processed so far, i.e., the value supplied in $pn$ on entry.

pfloat

If $ftype=1$, then $\left[p\right]$, the actual power used in the transformation function is returned, otherwise $p$ is unchanged.

pnint

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

Raises

NagValueError

(errno $11$)

On entry, $sorder=⟨value⟩$.

Constraint: $sorder=1$ or $2$.

(errno $21$)

On entry, $\text{nb}=⟨value⟩$.

Constraint: $\text{nb}\ge 0$.

(errno $51$)

On entry, $sorder=1$, $\text{ldiema}=⟨value⟩$ and $\text{nb}=⟨value⟩$.

Constraint: $\text{ldiema}\ge \text{nb}$.

(errno $51$)

On entry, $sorder=2$, $\text{ldiema}=⟨value⟩$ and $\text{m2}-m1+1=⟨value⟩$.

Constraint: $\text{ldiema}\ge \text{m2}-m1+1$.

(errno $62$)

On entry, $i=⟨value⟩$, $t[i-2]=⟨value⟩$ and $t[i-1]=⟨value⟩$.

Constraint: $t[i-1]\ne t[i-2]$ if linear interpolation is being used.

(errno $71$)

On entry, $tau=⟨value⟩$.

Constraint: $tau>0.0$.

(errno $72$)

On entry, $tau=⟨value⟩$.

On entry at previous call, $tau=⟨value⟩$.

Constraint: if $pn>0$ then $tau$ must be unchanged since previous call.

(errno $81$)

On entry, $m1=⟨value⟩$.

Constraint: $m1\ge 1$.

(errno $82$)

On entry, $m1=⟨value⟩$.

On entry at previous call, $m1=⟨value⟩$.

Constraint: if $pn>0$ then $m1$ must be unchanged since previous call.

(errno $91$)

On entry, $m1=⟨value⟩$ and $\text{m2}=⟨value⟩$.

Constraint: $\text{m2}\ge m1$.

(errno $92$)

On entry, $\text{m2}=⟨value⟩$.

On entry at previous call, $\text{m2}=⟨value⟩$.

Constraint: if $pn>0$ then $\text{m2}$ must be unchanged since previous call.

(errno $101$)

On entry, $ftype\ne 1$, $j=⟨value⟩$ and $sinit[j-1]=⟨value⟩$.

Constraint: if $ftype\ne 1$, $sinit[\text{j}-1]\ge 0.0$, for $\text{j}=2,3,\dots ,\text{m2}+2$.

(errno $111$)

On entry, $inter\left[0\right]=⟨value⟩$.

Constraint: $inter\left[0\right]=1$, $2$ or $3$.

(errno $112$)

On entry, $inter\left[1\right]=⟨value⟩$.

Constraint: $inter\left[1\right]=1$, $2$ or $3$.

(errno $113$)

On entry, $inter\left[0\right]=⟨value⟩$ and $inter\left[1\right]=⟨value⟩$.

On entry at previous call, $inter\left[0\right]=⟨value⟩$, $inter\left[1\right]=⟨value⟩$.

Constraint: if $pn\ne 0$, $inter$ must be unchanged since the last call.

(errno $121$)

On entry, $ftype=⟨value⟩$.

Constraint: $ftype=1$, $2$ or $3$.

(errno $122$)

On entry, $ftype=⟨value⟩$, On entry at previous call, $ftype=⟨value⟩$.

Constraint: if $pn\ne 0$, $ftype$ must be unchanged since the previous call.

(errno $131$)

On entry, $p=⟨value⟩$.

Constraint: absolute value of $p$ must be representable as an integer.

(errno $132$)

On entry, $p=⟨value⟩$.

Constraint: if $ftype\ne 1$, $p\ne 0.0$. If $ftype=1$, the nearest integer to $p$ must not be $0$.

(errno $133$)

On entry, $i=⟨value⟩$, $z[i-1]=⟨value⟩$ and $p=⟨value⟩$.

Constraint: if $ftype=1$ or $2$ and $z\left[i\right]=0$ for any $i$ then $p>0.0$.

(errno $134$)

On entry, $i=⟨value⟩$, $z[i-1]=⟨value⟩$, $x[i-1]=⟨value⟩$ and $p=⟨value⟩$.

Constraint: if $ftype=3$ and $z\left[i\right]=x\left[i\right]$ for any $i$ then $p>0.0$.

(errno $135$)

On entry, $p=⟨value⟩$.

On exit from previous call, $p=⟨value⟩$.

Constraint: if $pn>0$ then $p$ must be unchanged since previous call.

(errno $151$)

On entry, $pn=⟨value⟩$.

Constraint: $pn\ge 0$.

(errno $152$)

On entry, $pn=⟨value⟩$.

On exit from previous call, $pn=⟨value⟩$.

Constraint: if $pn>0$ then $pn$ must be unchanged since previous call.

(errno $161$)

$comm$[‘rcomm’] has been corrupted between calls.

(errno $171$)

On entry, $pn=0$, $\text{lrcomm}=⟨value⟩$ and $\text{m2}=⟨value⟩$.

Constraint: if $pn=0$, $\text{lrcomm}=0$ or $\text{lrcomm}\ge \text{m2}+20$.

(errno $172$)

On entry, $pn\ne 0$, $\text{lrcomm}=⟨value⟩$ and $\text{m2}=⟨value⟩$.

Constraint: if $pn\ne 0$ then $\text{lrcomm}\ge \text{m2}+20$.

Warns

NagAlgorithmicWarning

(errno $61$)

On entry, $i=⟨value⟩$, $t[i-2]=⟨value⟩$ and $t[i-1]=⟨value⟩$.

Constraint: $t$ should be strictly increasing.

(errno $301$)

Truncation occurred to avoid overflow, check for extreme values in $t$, $z$, $x$ or for $tau$.

Notes

inhom_iema_all 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 $(t_{\text{i}},z_{\text{i}})$, for $\text{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

$$\frac{e^{-t_i/\tau }}{\tau }\text{.}$$

The exponential form of this kernel gives rise to the following iterative formula (Zumbach and Müller (2001)) for the EMA operator:

$$\text{EMA}[\tau ;y]\left(t_i\right)=\mu \text{EMA}[\tau ;y]\left(t_{i-1}\right)+(\nu -\mu )y_{i-1}+(1-\nu )y_i$$

where

$$\mu =e^{-\alpha }\text{and}\alpha =\frac{t_i-t_{i-1}}{\tau }\text{.}$$

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. inhom_iema_all gives the option of three interpolation methods:

	Previous point:	$\nu =1$;
	Linear:	$\nu =(1-\mu )/\alpha$;
	Next point:	$\nu =\mu$.

and three transformation functions:

	Identity:	$y_i=z_i^{\left[p\right]}$;
	Absolute value:	$y_i={\left|z_i\right|}^p$;
	Absolute difference:	$y_i={|z_i-x_i|}^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, $(t_i,z_i,x_i)$.

The $m$-iterated exponential moving average, $\text{EMA}[\tau ,m;y]\left(t_i\right)$, is defined using the recursive formula:

$$\text{EMA}[\tau ,m;y]\left(t_i\right)=\text{EMA}[\tau ;\text{EMA}[\tau ,m-1;y]\left(t_i\right)]\left(t_i\right)$$

with

$$\text{EMA}[\tau ,1;y]\left(t_i\right)=\text{EMA}[\tau ;y]\left(t_i\right)\text{.}$$

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 inhom_iema_all called multiple times.

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