NAG FL Interface
g13aef (uni_​arima_​estim)

1 Purpose

2 Specification

3 Description

4 References

5 Arguments

1: $\mathbf{mr}\left(7\right)$ – Integer array Input

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 ($\varphi$), moving average $\left(\theta \right)$, seasonal autoregressive ($\Phi$) and seasonal moving average ($\Theta$) 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\ge 0$;
• $p+q+P+Q>0$;
• $s\ne 1$;
• if $s=0$, $P+D+Q=0$;
• if $s>1$, $P+D+Q>0$;
• $d+s\times (P+D)\le n$;
• $p+d-q+s\times (P+D-Q)\le n$.

2: $\mathbf{par}\left(\mathbf{npar}\right)$ – Real (Kind=nag_wp) array Input/Output

On entry: the initial estimates of the $p$ values of the $\varphi$ parameters, the $q$ values of the $\theta$ parameters, the $P$ values of the $\Phi$ parameters and the $Q$ values of the $\Theta$ parameters, in that order.

On exit: the latest values of the estimates of these parameters.

3: $\mathbf{npar}$ – Integer Input

On entry: the total number of $\varphi$, $\theta$, $\Phi$ and $\Theta$ parameters to be estimated.

Constraint: $\mathbf{npar}=p+q+P+Q$.

4: $\mathbf{c}$ – Real (Kind=nag_wp) Input/Output

On entry: if $\mathbf{kfc}=0$, c must contain the expected value, $c$, of the differenced series.

If $\mathbf{kfc}=1$, c must contain an initial estimate of $c$.

On exit: if $\mathbf{kfc}=0$, c is unchanged.

If $\mathbf{kfc}=1$, c contains the latest estimate of $c$.

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

5: $\mathbf{kfc}$ – Integer Input

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: $\mathbf{kfc}=0$ or $1$.

6: $\mathbf{x}\left(\mathbf{nx}\right)$ – Real (Kind=nag_wp) array Input

On entry: the $n$ values of the original undifferenced time series.

7: $\mathbf{nx}$ – Integer Input

On entry: $n$, the length of the original undifferenced time series.

8: $\mathbf{icount}\left(6\right)$ – Integer array Output

On exit: size of various output arrays.

$\mathbf{icount}\left(1\right)$

Contains $q+(Q\times s)$, the number of backforecasts.

$\mathbf{icount}\left(2\right)$

Contains $n-d-(D\times s)$, the number of differenced values.

$\mathbf{icount}\left(3\right)$

Contains $d+(D\times s)$, the number of values of reconstitution information.

$\mathbf{icount}\left(4\right)$

Contains $n+q+(Q\times s)$, the number of values held in each of the series ex, exr and al.

$\mathbf{icount}\left(5\right)$

Contains $n-d-(D\times s)-p-q-P-Q-\mathbf{kfc}$, the number of degrees of freedom associated with $S$.

$\mathbf{icount}\left(6\right)$

Contains $\mathbf{icount}\left(1\right)+\mathbf{npar}+\mathbf{kfc}$, the number of parameters being estimated.

These values are always computed regardless of the exit value of ifail.

9: $\mathbf{ex}\left(\mathbf{iex}\right)$ – Real (Kind=nag_wp) array Output

On exit: the extended differenced series which is made up of:

$\mathbf{icount}\left(1\right)$ backforecast values of the differenced series.

$\mathbf{icount}\left(2\right)$ actual values of the differenced series.

$\mathbf{icount}\left(3\right)$ values of reconstitution information.

The total number of these values held in ex is $\mathbf{icount}\left(4\right)$.

If the routine exits because of a faulty input parameter, the contents of ex will be indeterminate.

10: $\mathbf{exr}\left(\mathbf{iex}\right)$ – Real (Kind=nag_wp) array Output

On exit: the values of the model residuals which is made up of:

$\mathbf{icount}\left(1\right)$ residuals corresponding to the backforecasts in the differenced series.

$\mathbf{icount}\left(2\right)$ residuals corresponding to the actual values in the differenced series.

The remaining $\mathbf{icount}\left(3\right)$ values contain zeros.

If the routine exits with ifail holding a value other than $0$ or $9$, the contents of exr will be indeterminate.

11: $\mathbf{al}\left(\mathbf{iex}\right)$ – Real (Kind=nag_wp) array Output

On exit: the intermediate series which is made up of:

$\mathbf{icount}\left(1\right)$ intermediate series values corresponding to the backforecasts in the differenced series.

$\mathbf{icount}\left(2\right)$ intermediate series values corresponding to the actual values in the differenced series.

The remaining $\mathbf{icount}\left(3\right)$ values contain zeros.

If the routine exits with $\mathbf{ifail}\ne \mathbf{0}$, the contents of al will be indeterminate.

12: $\mathbf{iex}$ – Integer Input

On entry: the dimension of the arrays ex, exr and al as declared in the (sub)program from which g13aef is called.

Constraint: $\mathbf{iex}\ge q+(Q\times s)+n$, which is equivalent to the exit value of $\mathbf{icount}\left(4\right)$.

13: $\mathbf{s}$ – Real (Kind=nag_wp) Output

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

14: $\mathbf{g}\left(\mathbf{igh}\right)$ – Real (Kind=nag_wp) array Output

On exit: the latest value of the derivatives of $S$ with respect to each of the parameters being estimated (backforecasts, par parameters, and where relevant the constant – in that order). The contents of g will be indeterminate if the routine exits with a faulty input parameter.

15: $\mathbf{igh}$ – Integer Input

On entry: the dimension of the arrays g and sd and the second dimension of the arrays h and hc as declared in the (sub)program from which g13aef is called.

Constraint: $\mathbf{igh}\ge q+(Q\times s)+\mathbf{npar}+\mathbf{kfc}$ which is equivalent to the exit value of $\mathbf{icount}\left(6\right)$.

16: $\mathbf{sd}\left(\mathbf{igh}\right)$ – Real (Kind=nag_wp) array Output

On exit: the standard deviations corresponding to each of the parameters being estimated (backforecasts, par parameters, and where relevant the constant, in that order).

If the routine 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.

17: $\mathbf{h}(\mathbf{ldh},\mathbf{igh})$ – Real (Kind=nag_wp) array Output

On exit: the second derivative of $S$ and correlation coefficients.

1. (a)the latest values of an approximation to the second derivative of $S$ with respect to each of the $(q+Q\times s+\mathbf{npar}+\mathbf{kfc})$ parameters being estimated (backforecasts, par parameters, and where relevant the constant – in that order), and
2. (b)the correlation coefficients relating to each pair of these parameters.

These are held in a matrix defined by the first $(q+Q\times s+\mathbf{npar}+\mathbf{kfc})$ rows and the first $(q+Q\times s+\mathbf{npar}+\mathbf{kfc})$ columns of h. (Note that $\mathbf{icount}\left(6\right)$ contains the value of this expression.) The values of (a) are contained in the upper triangle, and the values of (b) in the strictly lower triangle.

These correlation coefficients are zero during intermediate printout using piv, and indeterminate if ifail contains on exit a value other than $0$ or $9$.

All the contents of h are indeterminate if the required number of iterations are zero. The $(q+(Q\times s)+\mathbf{npar}+\mathbf{kfc}+1)$th row of h is used internally as workspace.

18: $\mathbf{ldh}$ – Integer Input

On entry: the first dimension of the array h and

Constraint: $\mathbf{ldh}\ge 1+\mathit{q}+(\mathit{Q}\times \mathit{s})+\mathbf{npar}+\mathbf{kfc}$, which is equivalent to the exit value of $\mathbf{icount}\left(6\right)$.

19: $\mathbf{st}\left(\mathbf{ist}\right)$ – Real (Kind=nag_wp) array Output

On exit: the nst values of the state set array. If the routine exits with ifail containing a value other than $0$ or $9$, the contents of st will be indeterminate.

20: $\mathbf{ist}$ – Integer Input

On entry: the dimension of the array st as declared in the (sub)program from which g13aef is called.

Constraint: $\mathbf{ist}\ge (P\times s)+d+(D\times s)+q+\max (p,Q\times s)$.

21: $\mathbf{nst}$ – Integer Output

On exit: the number of values in the state set array st.

22: $\mathbf{piv}$ – Subroutine, supplied by the NAG Library or the user. External Procedure

piv is used to monitor the progress of the optimization.

The specification of piv is:

Fortran Interface copy

Subroutine piv ( mr, par, npar, c, kfc, icount, s, g, h, ldh, igh, itc, zsp) Integer, Intent (In) :: mr(7), npar, kfc, icount(6), ldh, igh, itc Real (Kind=nag_wp), Intent (In) :: par(npar), c, s, g(igh), h(ldh,igh), zsp(4)

C Header Interface copy

void  piv (const Integer mr[], const double par[], const Integer *npar, const double *c, const Integer *kfc, const Integer icount[], const double *s, const double g[], const double h[], const Integer *ldh, const Integer *igh, const Integer *itc, const double zsp[])

C++ Header Interface copy

#include <nag.h> extern "C" { void  piv (const Integer mr[], const double par[], const Integer &npar, const double &c, const Integer &kfc, const Integer icount[], const double &s, const double g[], const double h[], const Integer &ldh, const Integer &igh, const Integer &itc, const double zsp[]) }

piv is called on each iteration by g13aef when the input value of kpiv is nonzero and is bypassed when it is $0$.

The routine g13afz may be used as piv. It prints the heading

G13AFZ MONITORING OUTPUT - ITERATION n

followed by the parameter values and the residual sum of squares. Output is directed to the advisory channel defined by x04abf.

1: $\mathbf{mr}\left(7\right)$ – Integer array Input

2: $\mathbf{par}\left(\mathbf{npar}\right)$ – Real (Kind=nag_wp) array Input

3: $\mathbf{npar}$ – Integer Input

4: $\mathbf{c}$ – Real (Kind=nag_wp) Input

5: $\mathbf{kfc}$ – Integer Input

6: $\mathbf{icount}\left(6\right)$ – Integer array Input

7: $\mathbf{s}$ – Real (Kind=nag_wp) Input

8: $\mathbf{g}\left(\mathbf{igh}\right)$ – Real (Kind=nag_wp) array Input

9: $\mathbf{h}(\mathbf{ldh},\mathbf{igh})$ – Real (Kind=nag_wp) array Input

10: $\mathbf{ldh}$ – Integer Input

11: $\mathbf{igh}$ – Integer Input

12: $\mathbf{itc}$ – Integer Input

13: $\mathbf{zsp}\left(4\right)$ – Real (Kind=nag_wp) array Input

On entry: all the arguments are defined as for g13aef itself.

piv must either be a module subprogram USEd by, or declared as EXTERNAL in, the (sub)program from which g13aef is called. Arguments denoted as Input must not be changed by this procedure.

If $\mathbf{kpiv}=0$ a dummy piv must be supplied.

23: $\mathbf{kpiv}$ – Integer Input

On entry: must be nonzero if the progress of the optimization is to be monitored using piv. Otherwise kpiv must contain $0$.

24: $\mathbf{nit}$ – Integer Input

On entry: the maximum number of iterations to be performed.

Constraint: $\mathbf{nit}\ge 0$.

25: $\mathbf{itc}$ – Integer Output

On exit: the number of iterations performed.

26: $\mathbf{zsp}\left(4\right)$ – Real (Kind=nag_wp) array Input/Output

On entry: when $\mathbf{kzsp}=1$, the first four elements of zsp must contain the four values used to guide the search procedure. These are as follows.

$\mathbf{zsp}\left(1\right)$ contains $\alpha$, the value used to constrain the magnitude of the search procedure steps.

$\mathbf{zsp}\left(2\right)$ contains $\beta$, the multiplier which regulates the value $\alpha$.

$\mathbf{zsp}\left(3\right)$ contains $\delta$, the value of the stationarity and invertibility test tolerance factor.

$\mathbf{zsp}\left(4\right)$ contains $\gamma$, the value of the convergence criterion.

If $\mathbf{kzsp}\ne 1$ on entry, default values for zsp are supplied by the routine.

These are $0.001$, $10.0$, $1000.0$ and $\max (100\times \mathit{machine precision},0.0000001)$ respectively.

On exit: zsp contains the values, default or otherwise, used by the routine.

Constraints:

if $\mathbf{kzsp}=1$,

• $\mathbf{zsp}\left(1\right)>0.0$, ;
• $\mathbf{zsp}\left(2\right)>1.0$, ;
• $\mathbf{zsp}\left(3\right)\ge 1.0$, ;
• $0\le \mathbf{zsp}\left(4\right)<1.0$.

27: $\mathbf{kzsp}$ – Integer Input

On entry: the value $1$ if the routine is to use the input values of zsp, and any other value if the default values of zsp are to be used.

28: $\mathbf{isf}\left(4\right)$ – Integer array Output

On exit: contains 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:

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

29: $\mathbf{wa}\left(\mathbf{iwa}\right)$ – Real (Kind=nag_wp) array Workspace

30: $\mathbf{iwa}$ – Integer Input

On entry: the dimension of the array wa as declared in the (sub)program from which g13aef is called.

Constraint: $\mathbf{iwa}\ge (F_1\times F_2)+(9\times \mathbf{npar})\text{,}$

where	$F_1=\mathbf{nx}+1+p+(P\times s)+q+(Q\times s)$;
and	$F_2=8$ if $\mathbf{kfc}=1$;
	$F_2=7$ if $\mathbf{kfc}=0$, $Q>0$;
	$F_2=6$ if $\mathbf{kfc}=0$, $Q=0$, $P>0$;
	$F_2=5$ if $\mathbf{kfc}=0$, $Q=0$, $P=0$, $q>0$;
	$F_2=4$ otherwise.

31: $\mathbf{hc}(\mathbf{ldh},\mathbf{igh})$ – Real (Kind=nag_wp) array Workspace

32: $\mathbf{ifail}$ – Integer Input/Output

On entry: ifail must be set to $0$, $\mathrm{-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 $\mathrm{-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 $\mathrm{-1}$ or $1$ is recommended. If message printing is undesirable, then the value $1$ is recommended. Otherwise, the value $\mathrm{-1}$ is recommended since useful values can be provided in some output arguments even when $\mathbf{ifail}\ne \mathbf{0}$ on exit. 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).

6 Error Indicators and Warnings

$\mathbf{ifail}=1$

On entry, $\mathbf{kfc}=⟨\mathit{\text{value}}⟩$.
Constraint: $\mathbf{kfc}=0$ or $1$.

On entry, $\mathbf{npar}=⟨\mathit{\text{value}}⟩$.
Constraint: $\mathbf{npar}=p+q+P+Q$.

The orders vector mr is invalid.

$\mathbf{ifail}=2$

The model is over-parameterised. The number of parameters in the model is greater than the number of terms in the differenced series, i.e., $\mathbf{npar}+\mathbf{kfc}\ge \mathbf{nx}-d-D\times s$.

$\mathbf{ifail}=3$

On entry, $\mathbf{nit}=⟨\mathit{\text{value}}⟩$.
Constraint: $\mathbf{nit}\ge 0$.

On entry, $\mathbf{zsp}\left(1\right)=⟨\mathit{\text{value}}⟩$.
Constraint: $\mathbf{zsp}\left(1\right)>0.0$.

On entry, $\mathbf{zsp}\left(2\right)=⟨\mathit{\text{value}}⟩$.
Constraint: $\mathbf{zsp}\left(2\right)>1.0$.

On entry, $\mathbf{zsp}\left(3\right)=⟨\mathit{\text{value}}⟩$.
Constraint: $\mathbf{zsp}\left(3\right)\ge 1.0$.

On entry, $\mathbf{zsp}\left(4\right)=⟨\mathit{\text{value}}⟩$.
Constraint: $0.0\le \mathbf{zsp}\left(4\right)<1.0$.

$\mathbf{ifail}=4$

On entry, $\mathbf{ist}=⟨\mathit{\text{value}}⟩$ and the minimum size $\text{required}=⟨\mathit{\text{value}}⟩$ (the minimum size required is returned in nst).
Constraint: $\mathbf{ist}\ge (P\times s)+d+(D\times s)+q+\max (p,Q\times s)$.

$\mathbf{ifail}=5$

On entry, $\mathbf{iwa}=⟨\mathit{\text{value}}⟩$ and the minimum size $\text{required}=⟨\mathit{\text{value}}⟩$.
Constraint: $\mathbf{iwa}\ge (F_1\times F_2)+(9\times \mathbf{npar})$.

$\mathbf{ifail}=6$

On entry, $\mathbf{iex}=⟨\mathit{\text{value}}⟩$.
Constraint: $\mathbf{iex}\ge q\times (Q\times s)+\mathbf{nx}$.

On entry, $\mathbf{igh}=⟨\mathit{\text{value}}⟩$.
Constraint: $\mathbf{igh}\ge q\times (Q\times s)+\mathbf{npar}+\mathbf{kfc}$.

On entry, $\mathbf{ldh}=⟨\mathit{\text{value}}⟩$.
Constraint: $\mathbf{ldh}\ge q\times (Q\times s)+\mathbf{npar}+\mathbf{kfc}$.

$\mathbf{ifail}=7$

A failure in the search procedure has occurred. Some output arguments may contain meaningful values.

$\mathbf{ifail}=8$

Failure to invert $H$. Some output arguments may contain meaningful values.

$\mathbf{ifail}=9$

Unable to calculate the latest estimates of the backforecasts.

Some output arguments may contain meaningful values.

$\mathbf{ifail}=10$

Satisfactory parameter estimates could not be obtained for all parameter types in the model. Inspect array isf for futher information on the parameter type(s) in error.

$\mathbf{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.

$\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.

7 Accuracy

8 Parallelism and Performance

9 Further Comments

10 Example

10.1 Program Text

10.2 Program Data

10.3 Program Results