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

2 Specification

Fortran Interface

Subroutine g13aaf (

x, nx, nd, nds, ns, xd, nxd, ifail)

Integer, Intent (In)	::	nx, nd, nds, ns
Integer, Intent (Inout)	::	ifail
Integer, Intent (Out)	::	nxd
Real (Kind=nag_wp), Intent (In)	::	x(nx)
Real (Kind=nag_wp), Intent (Out)	::	xd(nx)

C Header Interface

#include <nag.h>

void	g13aaf_ (const double x[], const Integer nx, const Integer nd, const Integer nds, const Integer ns, double xd[], Integer nxd, Integer ifail)

The routine may be called by the names g13aaf or nagf_tsa_uni_diff.

3 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, (n - 1)$
$\nabla^{2} x_{i} = \nabla^{1} x_{i + 1} - \nabla^{1} x_{i}$	for $i = 1, 2, \dots, (n - 2)$
$⋮$
$\nabla^{d} x_{i} = \nabla^{d - 1} x_{i + 1} - \nabla^{d - 1} x_{i}$	for $i = 1, 2, \dots, (n - d)$

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, (n - d - s)$
$\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, (n - d - 2 s)$
$⋮$
$\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, (n - d - D \times s)$

Mathematically, the sequence in which the differencing operations are performed does not affect the final resulting series of

m = n - d - D \times s

values.

4 References

None.

5 Arguments

1: $x (nx)$ – Real (Kind=nag_wp) array Input

On entry: the undifferenced time series,

x_{i}

, for

i = 1, 2, \dots, n

2: $nx$ – Integer Input

On entry:

n

, the number of values in the undifferenced time series.

Constraint:

nx > nd + (nds \times ns)

3: $nd$ – Integer Input

On entry:

d

, the order of non-seasonal differencing.

Constraint:

nd \geq 0

4: $nds$ – Integer Input

On entry:

D

, the order of seasonal differencing.

Constraint:

nds \geq 0

5: $ns$ – Integer Input

On entry:

s

, the seasonality.

Constraints:

if $nds > 0$ , $ns > 0$ ;
if $nds = 0$ , $ns \geq 0$ .

6: $xd (nx)$ – Real (Kind=nag_wp) array Output

On exit: the differenced values in elements

1

nxd

, and reconstitution data in the remainder of the array.

7: $nxd$ – Integer Output

On exit: the number of differenced values in the array xd.

8: $ifail$ – Integer Input/Output

On entry: ifail must be set to

0

−1

1

to set behaviour on detection of an error; these values have no effect when no error is detected.

A value of

0

causes the printing of an error message and program execution will be halted; otherwise program execution continues. A value of

−1

means that an error message is printed while a value of

1

means that it is not.

If halting is not appropriate, the value

−1

1

is recommended. If message printing is undesirable, then the value

1

is recommended. Otherwise, the value

0

is recommended. When the value $- 1$ or $1$ is used it is essential to test the value of ifail on exit.

On exit:

ifail = 0

unless the routine detects an error or a warning has been flagged (see Section 6).

6 Error Indicators and Warnings

If on entry

ifail = 0

−1

, explanatory error messages are output on the current error message unit (as defined by x04aaf).

Errors or warnings detected by the routine:

$ifail = 1$: On entry, $nd = ⟨ value ⟩$ .
Constraint: $nd \geq 0$ .

On entry, $nds = ⟨ value ⟩$ .
Constraint: if $ns = 0$ , $nds \leq 0$ .

On entry, $nds = ⟨ value ⟩$ .
Constraint: $nds \geq 0$ .

On entry, $ns = ⟨ value ⟩$ .
Constraint: $ns \geq 0$ .

$ifail = 2$: On entry, $nx = ⟨ value ⟩$ , $nd = ⟨ value ⟩$ , $nds = ⟨ value ⟩$ and $ns = ⟨ value ⟩$ .
Constraint: $nx > nd + (nds \times ns)$ .

$ifail = - 99$: An unexpected error has been triggered by this routine. Please contact NAG.
See Section 7 in the Introduction to the NAG Library FL Interface for further information.

$ifail = - 399$: Your licence key may have expired or may not have been installed correctly.
See Section 8 in the Introduction to the NAG Library FL Interface for further information.

$ifail = - 999$: Dynamic memory allocation failed.
See Section 9 in the Introduction to the NAG Library FL Interface for further information.

7 Accuracy

The computations are believed to be stable.

8 Parallelism and Performance

Background information to multithreading can be found in the Multithreading documentation.

g13aaf is not threaded in any implementation.

9 Further Comments

The time taken by g13aaf is approximately proportional to

(nd + nds) \times nx

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

g13aa: FL CL CPP AD PY MB

NAG FL Interfaceg13aaf (uni_​diff)

▸▿ Contents

1 Purpose

2 Specification

3 Description

4 References

5 Arguments

6 Error Indicators and Warnings

7 Accuracy

8 Parallelism and Performance

9 Further Comments

10 Example

10.1 Program Text

10.2 Program Data

10.3 Program Results

NAG FL Interface
g13aaf (uni_diff)