Integer type:  int32  int64  nag_int  show int32  show int32  show int64  show int64  show nag_int  show nag_int

Chapter Contents
Chapter Introduction
NAG Toolbox

# NAG Toolbox: nag_tsa_multi_diff (g13dl)

## Purpose

nag_tsa_multi_diff (g13dl) differences and/or transforms a multivariate time series. It is intended to be used prior to nag_tsa_multi_varma_estimate (g13dd) to fit a vector autoregressive moving average (VARMA) model to the differenced/transformed series.

## Syntax

[w, nd, ifail] = g13dl(z, tr, id, delta, 'k', k, 'n', n)
[w, nd, ifail] = nag_tsa_multi_diff(z, tr, id, delta, 'k', k, 'n', n)

## Description

For certain time series it may first be necessary to difference the original data to obtain a stationary series before calculating autocorrelations, etc. This function also allows you to apply either a square root or a log transformation to the original time series to stabilize the variance if required.
If the order of differencing required for the $i$th series is ${\mathit{d}}_{i}$, then the differencing operator is defined by ${\delta }_{i}\left(B\right)=1-{\delta }_{i1}B-{\delta }_{i2}{B}^{2}-\cdots -{\delta }_{i{\mathit{d}}_{i}}{B}^{{\mathit{d}}_{i}}$, where $B$ is the backward shift operator; that is, $B{Z}_{t}={Z}_{t-1}$. Let $\mathit{d}$ denote the maximum of the orders of differencing, ${\mathit{d}}_{i}$, over the $k$ series. The function computes values of the differenced/transformed series ${W}_{\mathit{t}}={\left({w}_{1\mathit{t}},{w}_{2\mathit{t}},\dots ,{w}_{\mathit{k}\mathit{t}}\right)}^{\mathrm{T}}$, for $\mathit{t}=\mathit{d}+1,\dots ,n$, as follows:
 $wit=δiBzit*, i=1,2,…,k$
where ${z}_{it}^{*}$ are the transformed values of the original $k$-dimensional time series ${Z}_{t}={\left({z}_{1t},{z}_{2t},\dots ,{z}_{kt}\right)}^{\mathrm{T}}$.
The differencing parameters ${\delta }_{ij}$, for $i=1,2,\dots ,k$ and $j=1,2,\dots ,{\mathit{d}}_{i}$, must be supplied by you. If the $i$th series does not require differencing, then ${\mathit{d}}_{i}=0$.

## References

Box G E P and Jenkins G M (1976) Time Series Analysis: Forecasting and Control (Revised Edition) Holden–Day
Wei W W S (1990) Time Series Analysis: Univariate and Multivariate Methods Addison–Wesley

## 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 $\mathrm{max}\phantom{\rule{0.125em}{0ex}}\left(1,\mathit{d}\right)$, where $\mathit{d}=\mathrm{max}\phantom{\rule{0.125em}{0ex}}\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}=\mathrm{max}\phantom{\rule{0.125em}{0ex}}\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}=\mathrm{max}\phantom{\rule{0.125em}{0ex}}\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

Errors or warnings detected by the function:
${\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$
${\mathbf{ifail}}=-399$
Your licence key may have expired or may not have been installed correctly.
${\mathbf{ifail}}=-999$
Dynamic memory allocation failed.

## Accuracy

The computations are believed to be stable.

The same differencing operator does not have to be applied to all the series. For example, suppose we have $k=2$, and wish to apply the second-order differencing operator ${\nabla }^{2}$ to the first series and the first-order differencing operator $\nabla$ to the second series:
 $w1t =∇2z1t= 1-B 2z1t=1-2B+B2z1t, and w2t =∇z2t=1-Bz2t.$
Then ${\mathit{d}}_{1}=2,{\mathit{d}}_{2}=1$, $\mathit{d}=\mathrm{max}\phantom{\rule{0.125em}{0ex}}\left({\mathit{d}}_{1},{\mathit{d}}_{2}\right)=2$, and
 $delta = δ11 δ12 δ21 = 2 -1 1 .$

## Example

A program to difference (non-seasonally) each of two time series of length $48$. No transformation is to be applied to either of the series.
```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
```