NAG FL Interface
g13aaf (uni_​diff)

1 Purpose

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 dsDxi be the ith value of a time series xi, for i=1,2,,n after non-seasonal differencing of order d and seasonal differencing of order D (with period or seasonality s). In general,
dsDxi = d-1sDxi+1-d-1sDxi d>0
dsDxi = dsD-1xi+s-dsD-1xi D>0
Non-seasonal differencing up to the required order d is obtained using
1xi = xi+1-xi for i=1,2,,n-1
2xi = 1xi+1-1xi for i=1,2,,n-2
     
dxi = d-1xi+1-d-1xi for i=1,2,,n-d
Seasonal differencing up to the required order D is then obtained using
ds1xi = dxi+s-dxi for i=1,2,,n-d-s
ds2xi = ds1xi+s-ds1xi for i=1,2,,n-d-2s
     
dsDxi = dsD-1xi+s-dsD-1xi for i=1,2,,n-d-D×s
Mathematically, the sequence in which the differencing operations are performed does not affect the final resulting series of m=n-d-D×s values.

4 References

None.

5 Arguments

1: xnx Real (Kind=nag_wp) array Input
On entry: the undifferenced time series, xi, for i=1,2,,n.
2: nx Integer Input
On entry: n, the number of values in the undifferenced time series.
Constraint: nx>nd+nds×ns.
3: nd Integer Input
On entry: d, the order of non-seasonal differencing.
Constraint: nd0.
4: nds Integer Input
On entry: D, the order of seasonal differencing.
Constraint: nds0.
5: ns Integer Input
On entry: s, the seasonality.
Constraints:
  • if nds>0, ns>0;
  • if nds=0, ns0.
6: xdnx Real (Kind=nag_wp) array Output
On exit: the differenced values in elements 1 to 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 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 -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 or -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: nd0.
On entry, nds=value.
Constraint: if ns=0, nds0.
On entry, nds=value.
Constraint: nds0.
On entry, ns=value.
Constraint: ns0.
ifail=2
On entry, nx=value, nd=value, nds=value and ns=value.
Constraint: nx>nd+nds×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

g13aaf is not threaded in any implementation.

9 Further Comments

The time taken by g13aaf is approximately proportional to nd+nds×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.

10.1 Program Text

Program Text (g13aafe.f90)

10.2 Program Data

Program Data (g13aafe.d)

10.3 Program Results

Program Results (g13aafe.r)