NAG Toolbox: nag_tsa_inhom_iema (g13me)

Purpose

Syntax

Description

References

Parameters

Compulsory Input Parameters

1:     $\mathrm{iema}\left(\mathbf{nb}\right)$ – double array

$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.

2:     $\mathrm{t}\left(\mathbf{nb}\right)$ – double array

$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{ifail}=\mathbf{31}$ will be returned, but nag_tsa_inhom_iema (g13me) will continue as if $t$ was strictly increasing by using the absolute value.

3:     $\mathrm{tau}$ – double scalar

$\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$.

4:     $\mathrm{m}$ – int64int32nag_int scalar

$m$, the number of times the EMA operator is to be iterated.

Constraint: $\mathbf{m}\ge 1$.

5:     $\mathrm{sinit}\left(\mathbf{m}+2\right)$ – double array

If $\mathbf{pn}=0$, the values used to start the iterative process, with

• $\mathbf{sinit}\left(1\right)=t_0$,
• $\mathbf{sinit}\left(2\right)=z_0$,
• $\mathbf{sinit}\left(\mathit{j}+2\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.

6:     $\mathrm{inter}\left(2\right)$ – int64int32nag_int array

The type of interpolation used with $\mathbf{inter}\left(1\right)$ indicating the interpolation method to use when calculating $\text{EMA}\left[\tau ,1;z\right]$ and $\mathbf{inter}\left(2\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)=1$

Previous point, with $\nu =1$.

$\mathbf{inter}\left(i\right)=2$

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

$\mathbf{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., $\mathbf{inter}\left(2\right)=2$, irrespective of the interpolation method used at the first iteration, i.e., the value of $\mathbf{inter}\left(1\right)$.

Constraint: $\mathbf{inter}\left(\mathit{i}\right)=1$, $2$ or $3$, for $\mathit{i}=1,2$.

Optional Input Parameters

1:     $\mathrm{nb}$ – int64int32nag_int scalar

Default: the dimension of the arrays iema, t. (An error is raised if these dimensions are not equal.)

$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 (g13me).

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

2:     $\mathrm{pn}$ – int64int32nag_int scalar

Default: $0$

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

Constraint: $\mathbf{pn}\ge 0$.

3:     $\mathrm{rcomm}\left(\mathit{lrcomm}\right)$ – double array

Communication array, used to store information between calls to nag_tsa_inhom_iema (g13me). On the first call to nag_tsa_inhom_iema (g13me), or if all the data is provided in one go, rcomm need not be provided.

Output Parameters

1:     $\mathrm{iema}\left(\mathbf{nb}\right)$ – double array

The iterated EMA, with $\mathbf{iema}\left(i\right)=\text{EMA}\left[\tau ,m;z\right]\left(t_i\right)$.

2:     $\mathrm{pn}$ – int64int32nag_int scalar

Default: $0$

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

3:     $\mathrm{rcomm}\left(\mathit{lrcomm}\right)$ – double array

Communication array, used to store information between calls to nag_tsa_inhom_iema (g13me).

4:     $\mathrm{ifail}$ – int64int32nag_int scalar

$\mathbf{ifail}=\mathbf{0}$ unless the function detects an error (see Error Indicators and Warnings).

Error Indicators and Warnings

Cases prefixed with W are classified as warnings and do not generate an error of type NAG:error_n. See nag_issue_warnings.

   $\mathbf{ifail}=11$

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

W  $\mathbf{ifail}=31$

Constraint: t should be strictly increasing.

   $\mathbf{ifail}=32$

Constraint: $\mathbf{t}\left(i\right)\ne \mathbf{t}\left(i-1\right)$ if linear interpolation is being used.

   $\mathbf{ifail}=41$

Constraint: $\mathbf{tau}>0.0$.

   $\mathbf{ifail}=42$

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

   $\mathbf{ifail}=51$

Constraint: $\mathbf{m}\ge 1$.

   $\mathbf{ifail}=52$

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

   $\mathbf{ifail}=71$

Constraint: $\mathbf{inter}\left(1\right)=1$, $2$ or $3$.

   $\mathbf{ifail}=72$

Constraint: $\mathbf{inter}\left(2\right)=1$, $2$ or $3$.

   $\mathbf{ifail}=73$

Constraint: if $\mathbf{pn}\ne 0$, inter must be unchanged since the previous call.

   $\mathbf{ifail}=81$

Constraint: $\mathbf{pn}\ge 0$.

   $\mathbf{ifail}=82$

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

   $\mathbf{ifail}=91$

rcomm has been corrupted between calls.

   $\mathbf{ifail}=101$

Constraint: if $\mathbf{pn}=0$, $\mathit{lrcomm}=0$ or $\mathit{lrcomm}\ge \mathbf{m}+20$.

   $\mathbf{ifail}=102$

Constraint: if $\mathbf{pn}\ne 0$, $\mathit{lrcomm}\ge \mathbf{m}+20$.

W  $\mathbf{ifail}=301$

Truncation occurred to avoid overflow, check for extreme values in t, iema or for tau. Results are returned using the truncated values.

   $\mathbf{ifail}=-99$

An unexpected error has been triggered by this routine. Please contact NAG.

   $\mathbf{ifail}=-399$

Your licence key may have expired or may not have been installed correctly.

   $\mathbf{ifail}=-999$

Dynamic memory allocation failed.

Accuracy

Further Comments

Example

Open in the MATLAB editor: g13me_example

function g13me_example


fprintf('g13me example results\n\n');

m     = int64(2);
inter = [int64(3); 2];
tau   = [0.5; 2; 8];
sinit = [5; 0.5; 0.5; 0.5];
nb    = [5, 10, 15];
t     = cell(3, 1);
iema  = cell(3, 1);
t{1}    = [ 7.5;  8.2; 18.1; 22.8; 25.8];
iema{1} = [ 0.6;  0.6;  0.8;  0.1;  0.2];
t{2}    = [26.8; 31.1; 38.4; 45.9; 48.2; 48.9; 57.9; 58.5; 63.9; 65.2];
iema{2} = [ 0.2;  0.5;  0.7;  0.1;  0.4;  0.7;  0.8;  0.3;  0.2;  0.5];
t{3}    = [66.6; 67.4; 69.3; 69.9; 73.0; 75.6; 77.0; 84.7; 86.8; 88.0; ...
           88.5; 91.0; 93.0; 93.7; 94.0];
iema{3} = [ 0.2;  0.3;  0.8;  0.6;  0.1;  0.7;  0.9;  0.6;  0.3;  0.1;  ...
            0.1;  0.4;  1.0;  1.0;  0.1];

fprintf('             Time       Iterated EMA\n');

fig1 = figure;
hold on
linecol = {'blue','green','red'};
xlabel('Time');
ylabel('Value');
title({'Simulated inhomogeneous time series and corresponding',
       'EMA(\tau,2;y) for 3 \tau values'});
tm = [t{1}; t{2}; t{3}];
jm = [iema{1}; iema{2}; iema{3}];
plot(tm,jm,'cs');

% Loop over different values of tau
for k = 1:numel(tau);
  % Loop over each block of data.
  for i = 1:numel(nb)
    if i == 1
      % process first block and create pn
      [ema, pn, rcomm, ifail] = ...
      g13me( ...
             iema{i}, t{i}, tau(k), m, sinit, inter, 'rcomm', zeros(22,1));
      jm = ema;
    else
      % Update the iterated EMA for this block of data, overwriting the input
      % data with the iterated EMA.
      [ema, pn, rcomm, ifail] = ...
      g13me( ...
             iema{i}, t{i}, tau(k), m, sinit, inter, 'pn', pn, 'rcomm', rcomm);
      jm = [jm; ema];
    end

    % Display the results for this block of data (tau = 2 only)
    if k==2
      for l=1:nb(i)
        fprintf('%3d    %10.1f    %10.3f\n', pn-nb(i)+l, t{i}(l), ema(l));
      end
      fprintf('\n');
    end
  end
  plot(tm,jm,linecol{k});
end
legend('Original data', '\tau=0.5', '\tau=2', '\tau=8', ...
       'Location', 'northwest');
legend('boxoff');
hold off

g13me example results

             Time       Iterated EMA
  1           7.5         0.531
  2           8.2         0.544
  3          18.1         0.754
  4          22.8         0.406
  5          25.8         0.232

  6          26.8         0.217
  7          31.1         0.357
  8          38.4         0.630
  9          45.9         0.263
 10          48.2         0.241
 11          48.9         0.279
 12          57.9         0.713
 13          58.5         0.717
 14          63.9         0.385
 15          65.2         0.346

 16          66.6         0.330
 17          67.4         0.315
 18          69.3         0.409
 19          69.9         0.459
 20          73.0         0.377
 21          75.6         0.411
 22          77.0         0.536
 23          84.7         0.632
 24          86.8         0.538
 25          88.0         0.444
 26          88.5         0.401
 27          91.0         0.331
 28          93.0         0.495
 29          93.7         0.585
 30          94.0         0.612