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_uni_diff (g13aa)

## Purpose

nag_tsa_uni_diff (g13aa) carries out non-seasonal and seasonal differencing on a time series. Information which allows the original series to be reconstituted from the differenced series is also produced. This information is required in time series forecasting.

## Syntax

[xd, nxd, ifail] = g13aa(x, nd, nds, ns, 'nx', nx)
[xd, nxd, ifail] = nag_tsa_uni_diff(x, nd, nds, ns, 'nx', nx)

## Description

Let ${\nabla }^{d}{\nabla }_{s}^{D}{x}_{i}$ be the $i$th value of a time series ${x}_{i}$, for $i=1,2,\dots ,n$ after non-seasonal differencing of order $d$ and seasonal differencing of order $D$ (with period or seasonality $s$). In general,
 ${\nabla }^{d}{\nabla }_{s}^{D}{x}_{i}$ $=$ ${\nabla }^{d-1}{\nabla }_{s}^{D}{x}_{i+1}-{\nabla }^{d-1}{\nabla }_{s}^{D}{x}_{i}$ $d>0$ ${\nabla }^{d}{\nabla }_{s}^{D}{x}_{i}$ $=$ ${\nabla }^{d}{\nabla }_{s}^{D-1}{x}_{i+s}-{\nabla }^{d}{\nabla }_{s}^{D-1}{x}_{i}$ $D>0$
Non-seasonal differencing up to the required order $d$ is obtained using
 ${\nabla }^{1}{x}_{i}$ $=$ ${x}_{i+1}-{x}_{i}$ for $i=1,2,\dots ,\left(n-1\right)$ ${\nabla }^{2}{x}_{i}$ $=$ ${\nabla }^{1}{x}_{i+1}-{\nabla }^{1}{x}_{i}$ for $i=1,2,\dots ,\left(n-2\right)$ $\text{ }⋮$ ${\nabla }^{d}{x}_{i}$ $=$ ${\nabla }^{d-1}{x}_{i+1}-{\nabla }^{d-1}{x}_{i}$ for $i=1,2,\dots ,\left(n-d\right)$
Seasonal differencing up to the required order $D$ is then obtained using
 ${\nabla }^{d}{\nabla }_{s}^{1}{x}_{i}$ $=$ ${\nabla }^{d}{x}_{i+s}-{\nabla }^{d}{x}_{i}$ for $i=1,2,\dots ,\left(n-d-s\right)$ ${\nabla }^{d}{\nabla }_{s}^{2}{x}_{i}$ $=$ ${\nabla }^{d}{\nabla }_{s}^{1}{x}_{i+s}-{\nabla }^{d}{\nabla }_{s}^{1}{x}_{i}$ for $i=1,2,\dots ,\left(n-d-2s\right)$ $\text{ }⋮$ ${\nabla }^{d}{\nabla }_{s}^{D}{x}_{i}$ $=$ ${\nabla }^{d}{\nabla }_{s}^{D-1}{x}_{i+s}-{\nabla }^{d}{\nabla }_{s}^{D-1}{x}_{i}$ for $i=1,2,\dots ,\left(n-d-D×s\right)$
Mathematically, the sequence in which the differencing operations are performed does not affect the final resulting series of $m=n-d-D×s$ values.

None.

## Parameters

### Compulsory Input Parameters

1:     $\mathrm{x}\left({\mathbf{nx}}\right)$ – double array
The undifferenced time series, ${x}_{\mathit{i}}$, for $\mathit{i}=1,2,\dots ,n$.
2:     $\mathrm{nd}$int64int32nag_int scalar
$d$, the order of non-seasonal differencing.
Constraint: ${\mathbf{nd}}\ge 0$.
3:     $\mathrm{nds}$int64int32nag_int scalar
$D$, the order of seasonal differencing.
Constraint: ${\mathbf{nds}}\ge 0$.
4:     $\mathrm{ns}$int64int32nag_int scalar
$s$, the seasonality.
Constraints:
• if ${\mathbf{nds}}>0$, ${\mathbf{ns}}>0$;
• if ${\mathbf{nds}}=0$, ${\mathbf{ns}}\ge 0$.

### Optional Input Parameters

1:     $\mathrm{nx}$int64int32nag_int scalar
Default: the dimension of the array x.
$n$, the number of values in the undifferenced time series.
Constraint: ${\mathbf{nx}}>{\mathbf{nd}}+\left({\mathbf{nds}}×{\mathbf{ns}}\right)$.

### Output Parameters

1:     $\mathrm{xd}\left({\mathbf{nx}}\right)$ – double array
The differenced values in elements $1$ to ${\mathbf{nxd}}$, and reconstitution data in the remainder of the array.
2:     $\mathrm{nxd}$int64int32nag_int scalar
The number of differenced values in the array xd.
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{nd}}<0$, or ${\mathbf{nds}}<0$, or ${\mathbf{ns}}<0$, or ${\mathbf{ns}}=0$ when ${\mathbf{nds}}>0$.
${\mathbf{ifail}}=2$
 On entry, ${\mathbf{nx}}\le {\mathbf{nd}}+\left({\mathbf{nds}}×{\mathbf{ns}}\right)$.
${\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 time taken by nag_tsa_uni_diff (g13aa) is approximately proportional to $\left({\mathbf{nd}}+{\mathbf{nds}}\right)×{\mathbf{nx}}$.

## Example

This example reads in a set of data consisting of $20$ observations from a time series. Non-seasonal differencing of order $2$ and seasonal differencing of order $1$ (with seasonality of $4$) are applied to the input data, giving an output array holding $14$ differenced values and $6$ values which can be used to reconstitute the output array.
```function g13aa_example

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

x = [120;     108;      98;     118;     135;
131;     118;     125;     121;     100;
82;      82;      89;      88;      86;
96;     108;     110;      99;     105];
nd  = int64(2);
nds = int64(1);
ns  = int64(4);

[xd, nxd, ifail] = g13aa( ...
x, nd, nds, ns);

% Display results
nx = numel(xd);
fprintf(' Non-seasonal differencing of order %4d\n', nd);
fprintf(' and seasonal differencing of order %4d\n', nds);
fprintf('       are applied with seasonality %4d\n\n',ns);
fprintf('The output array holds %4d values,\n',nx);
fprintf('    of which the first %4d are differenced values\n\n',nxd);
for j = 1:7:nxd
fprintf('%7.0f',xd(j:min(j+6,nxd)));
fprintf('\n');
end
fprintf('\n');
for j = nxd+1:7:nx
fprintf('%7.0f',xd(j:min(j+6,nx)));
fprintf('\n');
end

```
```g13aa example results

Non-seasonal differencing of order    2
and seasonal differencing of order    1
are applied with seasonality    4

The output array holds   20 values,
of which the first   14 are differenced values

-11    -10     -8      4     12     -2     18
9     -4     -6     -5     -2    -12      5

2    -10    -13     17      6    105
```