naginterfaces.library.tsa.inhom_​ma

naginterfaces.library.tsa.inhom_ma(ma, t, tau, m1, m2, inter, ftype, p, sinit=None, pn=0, comm=None)

inhom_ma provides a moving average, moving norm, moving variance and moving standard deviation operator for an inhomogeneous time series.

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

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

Parameters

mafloat, 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$ = 31 will be returned, but inhom_ma 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 =(t_i-t_{i-1})/\tilde{\tau }$ can be calculated without overflowing, for all $i$.

taufloat

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

m1int

$m_1$, the iteration of the EMA operator at which the sum is started.

m2int

$m_2$, the iteration of the EMA operator at which the sum is ended.

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$ or $4$

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

$ftype=3$ or $5$

The absolute difference, with $y_i={|z_i-\text{MA}[\tau ,m;y]\left(t_i\right)|}^p$.

If $ftype=4$ or $5$ then the resulting vector of averages is scaled by $p^{-1}$ as described in $ma$.

pfloat

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

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

Note: the required length for this argument is determined as follows: if $ftype\text{in}(3,5)$: $2\times m2+3$; otherwise: $m2+2$.

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[\text{j}+1]=\text{EMA}[\tau ,\text{j};y]\left(t_0\right)$, for $\text{i}=1,2,\dots ,m2$.

In addition, if $ftype=3$ or $5$ then

$sinit[m2+2]=z_0$,

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

i.e., initial values based on the original data $z$ as opposed to the transformed data $y$.

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

pnint, optional

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

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

Communication structure.

On initial entry: need not be set.

Returns

mafloat, ndarray, shape $\left(\text{nb}\right)$

The moving average:

if $ftype=4$ or $5$

$ma[i-1]={\left\{\text{MA}[\tau ,m_1,m_2;y]\left(t_i\right)\right\}}^{1/p}$,

otherwise

$ma[i-1]=\text{MA}[\tau ,m_1,m_2;y]\left(t_i\right)$.

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.

wmafloat, ndarray, shape $\left(\text{nb}\right)$

Either the moving average or exponential moving average, depending on the value of $ftype$.

if $ftype=3$ or $5$

$wma[i-1]=\text{MA}[\tau ;y]\left(t_i\right)$

otherwise

$wma[i-1]=\text{EMA}[\tilde{\tau };y]\left(t_i\right)$.

Raises

NagValueError

(errno $11$)

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

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

(errno $32$)

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 $41$)

On entry, $tau=⟨value⟩$.

Constraint: $tau>0.0$.

(errno $42$)

On entry, $tau=⟨value⟩$.

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

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

(errno $51$)

On entry, $m1=⟨value⟩$.

Constraint: $m1\ge 1$.

(errno $52$)

On entry, $m1=⟨value⟩$.

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

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

(errno $61$)

On entry, $m1=⟨value⟩$ and $m2=⟨value⟩$.

Constraint: $m2\ge m1$.

(errno $62$)

On entry, $m2=⟨value⟩$.

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

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

(errno $71$)

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 ,m2+2$.

(errno $81$)

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

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

(errno $82$)

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

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

(errno $83$)

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 $91$)

On entry, $ftype=⟨value⟩$.

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

(errno $92$)

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 $101$)

On entry, $p=⟨value⟩$.

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

(errno $102$)

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 $103$)

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

Constraint: if $ftype=1$, $2$ or $4$ and $ma[i-1]=0$ for any $i$ then $p>0.0$.

(errno $104$)

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

Constraint: if $p<0.0$, $ma[i-1]-wma[i-1]\ne 0.0$, for any $i$.

(errno $105$)

On entry, $p=⟨value⟩$.

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

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

(errno $111$)

On entry, $pn=⟨value⟩$.

Constraint: $pn\ge 0$.

(errno $112$)

On entry, $pn=⟨value⟩$.

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

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

(errno $131$)

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

(errno $141$)

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

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

(errno $142$)

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

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

Warns

NagAlgorithmicWarning

(errno $31$)

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$, $ma$ or for $tau$.

Notes

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

$$\text{MA}[\tau ,m_1,m_2;y]\left(t_i\right)=\frac{1}{m_2-m_1+1}\sum _{j=m_1}^{m_2}\text{EMA}[\tilde{\tau },j;y]\left(t_i\right)$$

where $\tilde{\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}[\cdot ]$ is the iterated exponential moving average operator.

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

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

with

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

and

$$\text{EMA}[\tilde{\tau };y]\left(t_i\right)=\mu \text{EMA}[\tilde{\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}}{\tilde{\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_ma 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-\text{MA}[\tau ,m_1,m_2;z]\left(t_i\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 inhom_ma, a few of which are:

1. Moving Average (MA), as defined in [equation] (obtained by setting $ftype=1$ and $p=1$).

2. Moving Norm (MNorm), defined as

   $$\text{MNorm}(\tau ,m,p;z)={\text{MA}[\tau ,1,m;{\left|z\right|}^p]}^{1/p}$$

   (obtained by setting $ftype=4$, $m1=1$ and $m2=m$).

3. Moving Variance (MVar), defined as

   $$\text{MVar}(\tau ,m,p;z)=\text{MA}[\tau ,1,m;{|z-\text{MA}[\tau ,1,m;z]|}^p]$$

   (obtained by setting $ftype=3$, $m1=1$ and $m2=m$).

4. Moving Standard Deviation (MSD), defined as

   $$\text{MSD}(\tau ,m,p;z)={\text{MA}[\tau ,1,m;{|z-\text{MA}[\tau ,1,m;z]|}^p]}^{1/p}$$

   (obtained by setting $ftype=5$, $m1=1$ and $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 inhom_ma 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