NAG Toolbox: nag_tsa_multi_diff (g13dl)

Purpose

Syntax

Description

References

Parameters

Compulsory Input Parameters

1:     $\mathrm{z}\left(\mathit{kmax},\mathbf{n}\right)$ – double array

kmax, the first dimension of the array, must satisfy the constraint $\mathit{kmax}\ge \mathbf{k}$.

$\mathbf{z}\left(\mathit{i},\mathit{t}\right)$ must contain, $z_{\mathit{i}\mathit{t}}$, the $\mathit{i}$th component of $Z_{\mathit{t}}$, for $\mathit{i}=1,2,\dots ,k$ and $\mathit{t}=1,2,\dots ,n$.

Constraints:

• if $\mathbf{tr}\left(i\right)=\text{'L'}$, $\mathbf{z}\left(i,t\right)>0.0$;
• if $\mathbf{tr}\left(i\right)=\text{'S'}$, $\mathbf{z}\left(\mathit{i},\mathit{t}\right)\ge 0.0$, for $\mathit{i}=1,2,\dots ,k$ and $\mathit{t}=1,2,\dots ,n$.

2:     $\mathrm{tr}\left(\mathbf{k}\right)$ – cell array of strings

$\mathbf{tr}\left(\mathit{i}\right)$ indicates whether the $\mathit{i}$th time series is to be transformed, for $\mathit{i}=1,2,\dots ,k$.

$\mathbf{tr}\left(i\right)=\text{'N'}$

No transformation is used.

$\mathbf{tr}\left(i\right)=\text{'L'}$

A log transformation is used.

$\mathbf{tr}\left(i\right)=\text{'S'}$

A square root transformation is used.

Constraint: $\mathbf{tr}\left(\mathit{i}\right)=\text{'N'}$, $\text{'L'}$ or $\text{'S'}$, for $\mathit{i}=1,2,\dots ,k$.

3:     $\mathrm{id}\left(\mathbf{k}\right)$ – int64int32nag_int array

The order of differencing for each series, ${\mathit{d}}_1,{\mathit{d}}_2,\dots ,{\mathit{d}}_k$.

Constraint: $0\le \mathbf{id}\left(\mathit{i}\right)<\mathbf{n}$, for $\mathit{i}=1,2,\dots ,\mathbf{k}$.

4:     $\mathrm{delta}\left(\mathit{kmax},:\right)$ – double array

The second dimension of the array delta must be at least $\max \left(1,\mathit{d}\right)$, where $\mathit{d}=\max \left(\mathbf{id}\left(i\right)\right)$.

If $\mathbf{id}\left(i\right)>0$, then $\mathbf{delta}\left(\mathit{i},\mathit{j}\right)$ must be set equal to ${\delta }_{\mathit{i}\mathit{j}}$, for $\mathit{j}=1,2,\dots ,{\mathit{d}}_i$ and $\mathit{i}=1,2,\dots ,k$.

If $\mathit{d}=0$, then delta is not referenced.

Optional Input Parameters

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

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

$k$, the dimension of the multivariate time series.

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

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

Default: the second dimension of the array z.

$n$, the number of observations in the series, prior to differencing.

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

Output Parameters

1:     $\mathrm{w}\left(\mathit{kmax},:\right)$ – double array

The second dimension of the array w will be $\mathbf{n}-\mathit{d}$, where $\mathit{d}=\max \left(\mathbf{id}\left(i\right)\right)$.

$\mathit{kmax}=\mathbf{k}$.

$\mathbf{w}\left(\mathit{i},\mathit{t}\right)$ contains the value of $w_{\mathit{i},\mathit{t}+\mathit{d}}$, for $\mathit{i}=1,2,\dots ,k$ and $\mathit{t}=1,2,\dots ,n-\mathit{d}$.

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

The number of differenced values, $n-\mathit{d}$, in the series, where $\mathit{d}=\max \left(\mathbf{id}\left(i\right)\right)$.

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

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

Error Indicators and Warnings

   $\mathbf{ifail}=1$

On entry,	$\mathbf{k}<1$,
or	$\mathbf{n}<1$,
or	$\mathit{kmax}<\mathbf{k}$.

   $\mathbf{ifail}=2$

On entry,	$\mathbf{id}\left(i\right)<0$, for some $i=1,2,\dots ,k$,
or	$\mathbf{id}\left(i\right)\ge \mathbf{n}$, for some $i=1,2,\dots ,k$.

   $\mathbf{ifail}=3$

On entry,

at least one of the first $k$ elements of tr is not equal to 'N', 'L' or 'S'.

   $\mathbf{ifail}=4$

On entry, one or more of the elements of z is invalid, for the transformation requested; that is, you may be trying to log or square root a series, some of whose values are negative.

   $\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: g13dl_example

function g13dl_example


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

z = [-1.49, -1.62, 5.20, 6.23, 6.21, 5.86, 4.09, 3.18, 2.62, 1.49, 1.17, ...
      0.85, -0.35, 0.24, 2.44, 2.58, 2.04, 0.40, 2.26, 3.34, 5.09, 5.00, ...
      4.78,  4.11, 3.45, 1.65, 1.29, 4.09, 6.32, 7.50, 3.89, 1.58, 5.21, ...
      5.25,  4.93, 7.38, 5.87, 5.81, 9.68, 9.07, 7.29, 7.84, 7.55, 7.32, ...
      7.97,  7.76, 7.00, 8.35;
      7.34,  6.35, 6.96, 8.54, 6.62, 4.97, 4.55, 4.81, 4.75, 4.76,10.88, ...
     10.01, 11.62,10.36, 6.40, 6.24, 7.93, 4.04, 3.73, 5.60, 5.35, 6.81, ...
      8.27,  7.68, 6.65, 6.08,10.25, 9.14,17.75,13.30, 9.63, 6.80, 4.08, ...
      5.06,  4.94, 6.65, 7.94,10.76,11.89, 5.85, 9.01, 7.50,10.02,10.38, ...
      8.15, 8.37, 10.73, 12.14];
tr    = {'N'; 'N'};
id    = [int64(1);1];
delta = [1;  1];

[w, nd, ifail] = g13dl( ...
			z, tr, id, delta);

fprintf('Transformed/Differenced series\n');
fprintf('------------------------------\n');

for i = 1:2
  fprintf('\nSeries %2d\n',i);
  fprintf('-----------\n\n');
  fprintf('Number of differenced values = %5d\n\n',nd);
  fprintf('%9.3f%9.3f%9.3f%9.3f%9.3f%9.3f%9.3f%9.3f\n',w(i,:));
  fprintf('\n');
end

g13dl example results

Transformed/Differenced series
------------------------------

Series  1
-----------

Number of differenced values =    47

   -0.130    6.820    1.030   -0.020   -0.350   -1.770   -0.910   -0.560
   -1.130   -0.320   -0.320   -1.200    0.590    2.200    0.140   -0.540
   -1.640    1.860    1.080    1.750   -0.090   -0.220   -0.670   -0.660
   -1.800   -0.360    2.800    2.230    1.180   -3.610   -2.310    3.630
    0.040   -0.320    2.450   -1.510   -0.060    3.870   -0.610   -1.780
    0.550   -0.290   -0.230    0.650   -0.210   -0.760    1.350

Series  2
-----------

Number of differenced values =    47

   -0.990    0.610    1.580   -1.920   -1.650   -0.420    0.260   -0.060
    0.010    6.120   -0.870    1.610   -1.260   -3.960   -0.160    1.690
   -3.890   -0.310    1.870   -0.250    1.460    1.460   -0.590   -1.030
   -0.570    4.170   -1.110    8.610   -4.450   -3.670   -2.830   -2.720
    0.980   -0.120    1.710    1.290    2.820    1.130   -6.040    3.160
   -1.510    2.520    0.360   -2.230    0.220    2.360    1.410