# NAG FL Interfaceg13aaf (uni_​diff)

## 1Purpose

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.

## 2Specification

Fortran Interface
 Subroutine g13aaf ( x, nx, nd, nds, ns, xd, nxd,
 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)
#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.

## 3Description

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.

## 5Arguments

1: $\mathbf{x}\left({\mathbf{nx}}\right)$Real (Kind=nag_wp) array Input
On entry: the undifferenced time series, ${x}_{\mathit{i}}$, for $\mathit{i}=1,2,\dots ,n$.
2: $\mathbf{nx}$Integer Input
On entry: $n$, the number of values in the undifferenced time series.
Constraint: ${\mathbf{nx}}>{\mathbf{nd}}+\left({\mathbf{nds}}×{\mathbf{ns}}\right)$.
3: $\mathbf{nd}$Integer Input
On entry: $d$, the order of non-seasonal differencing.
Constraint: ${\mathbf{nd}}\ge 0$.
4: $\mathbf{nds}$Integer Input
On entry: $D$, the order of seasonal differencing.
Constraint: ${\mathbf{nds}}\ge 0$.
5: $\mathbf{ns}$Integer Input
On entry: $s$, the seasonality.
Constraints:
• if ${\mathbf{nds}}>0$, ${\mathbf{ns}}>0$;
• if ${\mathbf{nds}}=0$, ${\mathbf{ns}}\ge 0$.
6: $\mathbf{xd}\left({\mathbf{nx}}\right)$Real (Kind=nag_wp) array Output
On exit: the differenced values in elements $1$ to ${\mathbf{nxd}}$, and reconstitution data in the remainder of the array.
7: $\mathbf{nxd}$Integer Output
On exit: the number of differenced values in the array xd.
8: $\mathbf{ifail}$Integer Input/Output
On entry: ifail must be set to $0$, $-1$ or $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$ or $1$ is recommended. If message printing is undesirable, then the value $1$ is recommended. Otherwise, the value $0$ is recommended. When the value $-\mathbf{1}$ or $\mathbf{1}$ is used it is essential to test the value of ifail on exit.
On exit: ${\mathbf{ifail}}={\mathbf{0}}$ unless the routine detects an error or a warning has been flagged (see Section 6).

## 6Error Indicators and Warnings

If on entry ${\mathbf{ifail}}=0$ or $-1$, explanatory error messages are output on the current error message unit (as defined by x04aaf).
Errors or warnings detected by the routine:
${\mathbf{ifail}}=1$
On entry, ${\mathbf{nd}}=〈\mathit{\text{value}}〉$.
Constraint: ${\mathbf{nd}}\ge 0$.
On entry, ${\mathbf{nds}}=〈\mathit{\text{value}}〉$.
Constraint: if ${\mathbf{ns}}=0$, ${\mathbf{nds}}\le 0$.
On entry, ${\mathbf{nds}}=〈\mathit{\text{value}}〉$.
Constraint: ${\mathbf{nds}}\ge 0$.
On entry, ${\mathbf{ns}}=〈\mathit{\text{value}}〉$.
Constraint: ${\mathbf{ns}}\ge 0$.
${\mathbf{ifail}}=2$
On entry, ${\mathbf{nx}}=〈\mathit{\text{value}}〉$, ${\mathbf{nd}}=〈\mathit{\text{value}}〉$, ${\mathbf{nds}}=〈\mathit{\text{value}}〉$ and ${\mathbf{ns}}=〈\mathit{\text{value}}〉$.
Constraint: ${\mathbf{nx}}>{\mathbf{nd}}+\left({\mathbf{nds}}×{\mathbf{ns}}\right)$.
${\mathbf{ifail}}=-99$
See Section 7 in the Introduction to the NAG Library FL Interface for further information.
${\mathbf{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.
${\mathbf{ifail}}=-999$
Dynamic memory allocation failed.
See Section 9 in the Introduction to the NAG Library FL Interface for further information.

## 7Accuracy

The computations are believed to be stable.

## 8Parallelism and Performance

g13aaf is not threaded in any implementation.

The time taken by g13aaf is approximately proportional to $\left({\mathbf{nd}}+{\mathbf{nds}}\right)×{\mathbf{nx}}$.

## 10Example

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.

### 10.1Program Text

Program Text (g13aafe.f90)

### 10.2Program Data

Program Data (g13aafe.d)

### 10.3Program Results

Program Results (g13aafe.r)