g13af is an easy-to-use version of (G13AEF not in this release). It fits a seasonal autoregressive integrated moving average (ARIMA) model to an observed time series, using a nonlinear least squares procedure incorporating backforecasting. Parameter estimates are obtained, together with appropriate standard errors. The residual series is returned, and information for use in forecasting the time series is produced for use in g13ag and g13ah.

The estimation procedure is iterative, starting with initial parameter values such as may be obtained using g13ad. It continues until a specified convergence criterion is satisfied or until a specified number of iterations have been carried out. The progress of the iteration can be monitored by means of an optional printing facility.

Syntax

C#
public static void g13af( int[] mr, double[] par, ref double c, int kfc, double[] x, int nx, out double s, out int ndf, double[] sd, int nppc, double[,] cm, double[] st, out int nst, int kpiv, int nit, out int itc, int[] isf, double[] res, out int nres, out int ifail )

public static void g13af(
	int[] mr,
	double[] par,
	ref double c,
	int kfc,
	double[] x,
	int nx,
	out double s,
	out int ndf,
	double[] sd,
	int nppc,
	double[,] cm,
	double[] st,
	out int nst,
	int kpiv,
	int nit,
	out int itc,
	int[] isf,
	double[] res,
	out int nres,
	out int ifail
)

Visual Basic
Public Shared Sub g13af ( _ mr As Integer(), _ par As Double(), _ ByRef c As Double, _ kfc As Integer, _ x As Double(), _ nx As Integer, _ <OutAttribute> ByRef s As Double, _ <OutAttribute> ByRef ndf As Integer, _ sd As Double(), _ nppc As Integer, _ cm As Double(,), _ st As Double(), _ <OutAttribute> ByRef nst As Integer, _ kpiv As Integer, _ nit As Integer, _ <OutAttribute> ByRef itc As Integer, _ isf As Integer(), _ res As Double(), _ <OutAttribute> ByRef nres As Integer, _ <OutAttribute> ByRef ifail As Integer _ )

Visual Basic

Public Shared Sub g13af ( _
	mr As Integer(), _
	par As Double(), _
	ByRef c As Double, _
	kfc As Integer, _
	x As Double(), _
	nx As Integer, _
	<OutAttribute> ByRef s As Double, _
	<OutAttribute> ByRef ndf As Integer, _
	sd As Double(), _
	nppc As Integer, _
	cm As Double(,), _
	st As Double(), _
	<OutAttribute> ByRef nst As Integer, _
	kpiv As Integer, _
	nit As Integer, _
	<OutAttribute> ByRef itc As Integer, _
	isf As Integer(), _
	res As Double(), _
	<OutAttribute> ByRef nres As Integer, _
	<OutAttribute> ByRef ifail As Integer _
)

Visual C++
public: static void g13af( array<int>^ mr, array<double>^ par, double% c, int kfc, array<double>^ x, int nx, [OutAttribute] double% s, [OutAttribute] int% ndf, array<double>^ sd, int nppc, array<double,2>^ cm, array<double>^ st, [OutAttribute] int% nst, int kpiv, int nit, [OutAttribute] int% itc, array<int>^ isf, array<double>^ res, [OutAttribute] int% nres, [OutAttribute] int% ifail )

Visual C++

public:
static void g13af(
	array<int>^ mr, 
	array<double>^ par, 
	double% c, 
	int kfc, 
	array<double>^ x, 
	int nx, 
	[OutAttribute] double% s, 
	[OutAttribute] int% ndf, 
	array<double>^ sd, 
	int nppc, 
	array<double,2>^ cm, 
	array<double>^ st, 
	[OutAttribute] int% nst, 
	int kpiv, 
	int nit, 
	[OutAttribute] int% itc, 
	array<int>^ isf, 
	array<double>^ res, 
	[OutAttribute] int% nres, 
	[OutAttribute] int% ifail
)

F#
static member g13af : mr : int[] * par : float[] * c : float byref * kfc : int * x : float[] * nx : int * s : float byref * ndf : int byref * sd : float[] * nppc : int * cm : float[,] * st : float[] * nst : int byref * kpiv : int * nit : int * itc : int byref * isf : int[] * res : float[] * nres : int byref * ifail : int byref -> unit

static member g13af : 
        mr : int[] * 
        par : float[] * 
        c : float byref * 
        kfc : int * 
        x : float[] * 
        nx : int * 
        s : float byref * 
        ndf : int byref * 
        sd : float[] * 
        nppc : int * 
        cm : float[,] * 
        st : float[] * 
        nst : int byref * 
        kpiv : int * 
        nit : int * 
        itc : int byref * 
        isf : int[] * 
        res : float[] * 
        nres : int byref * 
        ifail : int byref -> unit

Parameters

mr

Type: array<System..::..Int32>[]()[][]

An array of size [

7

]

On entry: the orders vector

(p, d, q, P, D, Q, s)

of the ARIMA model whose parameters are to be estimated.

p

q

P

and

Q

refer respectively to the number of autoregressive

(ϕ)

, moving average

(θ)

, seasonal autoregressive

(Φ)

and seasonal moving average

(Θ)

parameters.

d

D

and

s

refer respectively to the order of non-seasonal differencing, the order of seasonal differencing and the seasonal period.

Constraints:

$p$ , $d$ , $q$ , $P$ , $D$ , $Q$ , $s \geq 0$ ;
$p + q + P + Q > 0$ ;
$s \neq 1$ ;
if $s = 0$ , $P + D + Q = 0$ ;
if $s > 1$ , $P + D + Q > 0$ ;
$d + s \times (P + D) \leq n$ ;
$p + d - q + s \times (P + D - Q) \leq n$ .

par: Type: array<System..::..Double>[]()[][]
An array of size [dim1]
Note: dim1 must satisfy the constraint: $_npar = p + q + P + Q$
On entry: the initial estimates of the $p$ values of the $ϕ$ parameters, the $q$ values of the $θ$ parameters, the $P$ values of the $Φ$ parameters and the $Q$ values of the $Θ$ parameters, in that order.
On exit: contains the latest values of the estimates of these parameters.

c: Type: System..::..Double%
On entry: if $kfc = 0$ , c must contain the expected value, $c$ , of the differenced series.
If $kfc = 1$ , c must contain an initial estimate of $c$ .

Therefore, if c and kfc are both zero on entry, there is no constant correction.

On exit: if $kfc = 0$ , c is unchanged.
If $kfc = 1$ , c contains the latest estimate of $c$ .

kfc: Type: System..::..Int32
On entry: must be set to $1$ if the constant, $c$ , is to be estimated and $0$ if it is to be held fixed at its initial value.

Constraint: $kfc = 0$ or $1$ .

x: Type: array<System..::..Double>[]()[][]
An array of size [nx]
On entry: the $n$ values of the original undifferenced time series.

nx: Type: System..::..Int32
On entry: $n$ , the length of the original undifferenced time series.

s: Type: System..::..Double%
On exit: the residual sum of squares after the latest series of parameter estimates has been incorporated into the model. If the method exits with a faulty input parameter, s contains zero.

ndf: Type: System..::..Int32%
On exit: the number of degrees of freedom associated with s, $ndf = n - d - D \times s - p - q - P - Q - kfc$ .

sd: Type: array<System..::..Double>[]()[][]
An array of size [nppc]
On exit: the standard deviations corresponding to the parameters in the model ( $p$ autoregressive, $q$ moving average, $P$ seasonal autoregressive, $Q$ seasonal moving average and $c$ , if estimated, in that order). If the method exits with ifail containing a value other than $0$ or $9$ , or if the required number of iterations is zero, the contents of sd will be indeterminate.

nppc: Type: System..::..Int32
On entry: the number of $ϕ$ , $θ$ , $Φ$ , $Θ$ and $c$ parameters to be estimated. $nppc = p + q + P + Q + 1$ if the constant is being estimated and $nppc = p + q + P + Q$ if not.

Constraint: $nppc =_npar + kfc$ .

cm: Type: array<System..::..Double,2>[,](,)[,][,]
An array of size [dim1, nppc]
Note: dim1 must satisfy the constraint: $dim1 \geq nppc$
On exit: the correlation coefficients associated with each pair of the nppc parameters. These are held in the first nppc rows and the first nppc columns of cm. These correlation coefficients are indeterminate if ifail contains on exit a value other than $0$ or $9$ , or if the required number of iterations is zero.

st: Type: array<System..::..Double>[]()[][]
An array of size [nx]
On exit: the value of the state set in its first nst elements. If the method exits with ifail containing a value other than $0$ or $9$ , the contents of st will be indeterminate.

nst: Type: System..::..Int32%
On exit: the size of the state set. $nst = P \times s + D \times s + d + q + \max (p, Q \times s)$ .
nst should be used subsequently in g13ag and g13ah as the dimension of st.

kpiv

Type: System..::..Int32

On entry: must be nonzero if the progress of the optimization is to be monitored using the built-in printing facility. Otherwise kpiv must contain zero. If selected, monitoring output will be sent to the current advisory message unit defined by (X04ABF not in this release). For each iteration, the heading

 G13AFZ MONITORING OUTPUT - ITERATION n

followed by the parameter values, and residual sum of squares, are printed.

nit: Type: System..::..Int32
On entry: the maximum number of iterations to be performed.

Constraint: $nit \geq 0$ .

itc: Type: System..::..Int32%
On exit: the number of iterations performed.

isf

Type: array<System..::..Int32>[]()[][]

An array of size [

4

]

On exit: the first four elements of isf contain success/failure indicators, one for each of the four types of parameter in the model (autoregressive, moving average, seasonal autoregressive, seasonal moving average), in that order.

Each indicator has the interpretation:

$- 2$	On entry parameters of this type have initial estimates which do not satisfy the stationarity or invertibility test conditions.
$- 1$	The search procedure has failed to converge because the latest set of parameter estimates of this type is invalid.
$0$	No parameter of this type is in the model.
$1$	Valid final estimates for parameters of this type have been obtained.

res: Type: array<System..::..Double>[]()[][]
An array of size [ires]
On exit: the first nres elements of res contain the model residuals derived from the differenced series. If the method exits with ifail holding a value other than $0$ or $9$ , these elements of res will be indeterminate. The rest of the array res is used as workspace.

nres: Type: System..::..Int32%
On exit: the number of model residuals returned in res.

ifail: Type: System..::..Int32%
On exit: $ifail = 0$ unless the method detects an error or a warning has been flagged (see [Error Indicators and Warnings]).

Description

The time series

x_{1}, x_{2}, \dots, x_{n}

supplied to the method is assumed to follow a seasonal autoregressive integrated moving average (ARIMA) model defined as follows:

\nabla^{d} \nabla_{s}^{D} x_{t} - c = w_{t},

where

\nabla^{d} \nabla_{s}^{D} x_{t}

is the result of applying non-seasonal differencing of order

d

and seasonal differencing of seasonality

s

and order

D

to the series

x_{t}

, as outlined in the description of g13aa. The differenced series is then of length

N = n - d^{'}

, where

d^{'} = d + (D \times s)

is the generalized order of differencing. The scalar

c

is the expected value of the differenced series, and the series

w_{1}, w_{2}, \dots, w_{N}

follows a zero-mean stationary autoregressive moving average (ARMA) model defined by a pair of recurrence equations. These express

w_{t}

in terms of an uncorrelated series

a_{t}

, via an intermediate series

e_{t}

. The first equation describes the seasonal structure:

w_{t} = Φ_{1} w_{t - s} + Φ_{2} w_{t - 2 \times s} + \dots + Φ_{P} w_{t - P \times s} + e_{t} - Θ_{1} e_{t - s} - Θ_{2} e_{t - 2 \times s} - \dots - Θ_{Q} e_{t - Q \times s} .

The second equation describes the non-seasonal structure. If the model is purely non-seasonal the first equation is redundant and

e_{t}

above is equated with

w_{t}

e_{t} = ϕ_{1} e_{t - 1} + ϕ_{2} e_{t - 2} + \dots + ϕ_{p} e_{t - p} + a_{t} - θ_{1} a_{t - 1} - θ_{2} a_{t - 2} - \dots - θ_{q} a_{t - q} .

Estimates of the model parameters defined by

\begin{array}{l} ϕ_{1}, ϕ_{2}, \dots, ϕ_{p}, θ_{1}, θ_{2}, \dots, θ_{q}, \\ Φ_{1}, Φ_{2}, \dots, Φ_{P}, Θ_{1}, Θ_{2}, \dots, Θ_{Q} \end{array}

and (optionally)

c

are obtained by minimizing a quadratic form in the vector

w = {(w_{1}, w_{2}, \dots, w_{N})}^{'}

The minimization process is iterative, iterations being performed until convergence is achieved (see [Description] in g13ae for full details), or until the user-specified maximum number of iterations are completed.

The final values of the residual sum of squares and the parameter estimates are used to obtain asymptotic approximations to the standard deviations of the parameters, and the correlation matrix for the parameters. The ‘state set’ array of information required by forecasting is also returned.

Note: if the maximum number of iterations are performed without convergence, these quantities may not be reliable. In this case, the sequence of iterates should be checked, using the optional monitoring method, to verify that convergence is adequate for practical purposes.

References

Box G E P and Jenkins G M (1976) Time Series Analysis: Forecasting and Control (Revised Edition) Holden–Day

Marquardt D W (1963) An algorithm for least squares estimation of nonlinear parameters J. Soc. Indust. Appl. Math. 11 431

Error Indicators and Warnings

Note: g13af may return useful information for one or more of the following detected errors or warnings.

Errors or warnings detected by the method:

Some error messages may refer to parameters that are dropped from this interface (NPAR, LDCM) In these cases, an error in another parameter has usually caused an incorrect value to be inferred.

$ifail = 1$

On entry,	the orders vector mr is invalid (check the constraints in [Parameters]),
or	$kfc \neq 0$ or $1$ ,

$ifail = 2$: On entry, $nx - d - D \times s \leq_npar + kfc$ , i.e., the number of terms in the differenced series is not greater than the number of parameters in the model. The model is over-parameterised.

$ifail = 3$

On entry,

nit < 0

$ifail = 4$: On entry, the required size of the state set array st is greater than nx. This occurs only for very unusual models with long seasonal periods or large numbers of parameters. First check that the orders vector mr has been set up as intended. If it has, change to (G13AEF not in this release) with st dimensioned at least (nst), where nst is the value returned by g13af, or computed using the formula in [Parameters] of this document.

$ifail = 5$: On entry, the workspace array res is too small. Check the value of ires against the constraints in [Parameters].

$ifail = 7$: The search procedure in the algorithm has failed. This may be due to a badly conditioned sum of squares function, or the default convergence criterion may be too strict. Use (G13AEF not in this release) with a less strict convergence criterion.
Some output parameters may contain meaningful values; see [Parameters] for details.

$ifail = 8$: The inversion of the Hessian matrix in the calculation of the covariance matrix of the parameter estimates has failed.
Some output parameters may contain meaningful values; see [Parameters] for details.

$ifail = 9$: This indicates a failure when solving the equations giving the latest estimates of the backforecasts.
Some output parameters may contain meaningful values; see [Parameters] for details.

$ifail = 10$: Satisfactory parameter estimates could not be obtained for all parameter types in the model. Inspect array isf for further information on the parameter type(s) in error.

$ifail = 11$: An internal error has arisen in partitioning res for use by (G13AEF not in this release). This error should not occur; report it to NAG via your site representative.

$ifail = -9000$: An error occured, see message report.
$ifail = -6000$: Invalid Parameters $〈value〉$
$ifail = -4000$: Invalid dimension for array $〈value〉$
$ifail = -8000$: Negative dimension for array $〈value〉$
$ifail = -6000$: Invalid Parameters $〈value〉$

Accuracy

The computations are believed to be stable.

Parallelism and Performance

None.

Further Comments

The time taken by g13af is approximately proportional to

nx \times itc \times {(q + Q \times s + nppc)}^{2}

Example

This example reads

30

observations from a time series relating to the rate of the earth's rotation about its polar axis. Differencing of order

1

is applied, and the number of non-seasonal parameters is

3

, one autoregressive (

ϕ

) and two moving average (

θ

). No seasonal effects are taken into account.

The constant is estimated. Up to

50

iterations are allowed.

The initial estimates of

ϕ_{1}

θ_{1}

θ_{2}

and

c

are zero.

Some intermediate monitoring output from (G13AFZ not in this release) has been omitted.

Example program (C#): g13afe.cs

Example program data: g13afe.d

Example program results: g13afe.r