NAG FL Interface
g13aff (uni_​arima_​estim_​easy)

Settings help

FL Name Style:


FL Specification Language:


1 Purpose

g13aff is an easy-to-use version of g13aef. 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 g13agf and g13ahf.
The estimation procedure is iterative, starting with initial parameter values such as may be obtained using g13adf. 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.

2 Specification

Fortran Interface
Subroutine g13aff ( mr, par, npar, c, kfc, x, nx, s, ndf, sd, nppc, cm, ldcm, st, nst, kpiv, nit, itc, isf, res, ires, nres, ifail)
Integer, Intent (In) :: mr(7), npar, kfc, nx, nppc, ldcm, kpiv, nit, ires
Integer, Intent (Inout) :: ifail
Integer, Intent (Out) :: ndf, nst, itc, isf(4), nres
Real (Kind=nag_wp), Intent (In) :: x(nx)
Real (Kind=nag_wp), Intent (Inout) :: par(npar), c, cm(ldcm,nppc)
Real (Kind=nag_wp), Intent (Out) :: s, sd(nppc), st(nx), res(ires)
C Header Interface
#include <nag.h>
void  g13aff_ (const Integer mr[], double par[], const Integer *npar, double *c, const Integer *kfc, const double x[], const Integer *nx, double *s, Integer *ndf, double sd[], const Integer *nppc, double cm[], const Integer *ldcm, double st[], Integer *nst, const Integer *kpiv, const Integer *nit, Integer *itc, Integer isf[], double res[], const Integer *ires, Integer *nres, Integer *ifail)
The routine may be called by the names g13aff or nagf_tsa_uni_arima_estim_easy.

3 Description

The time series x1,x2,,xn supplied to the routine is assumed to follow a seasonal autoregressive integrated moving average (ARIMA) model defined as follows:
dsDxt-c=wt,  
where dsDxt is the result of applying non-seasonal differencing of order d and seasonal differencing of seasonality s and order D to the series xt, as outlined in the description of g13aaf. The differenced series is then of length N=n-d, where d=d+(D×s) is the generalized order of differencing. The scalar c is the expected value of the differenced series, and the series w1,w2,,wN follows a zero-mean stationary autoregressive moving average (ARMA) model defined by a pair of recurrence equations. These express wt in terms of an uncorrelated series at, via an intermediate series et. The first equation describes the seasonal structure:
wt=Φ1wt-s+Φ2wt-2×s++ΦPwt-P×s+et-Θ1et-s-Θ2et-2×s--ΘQet-Q×s.  
The second equation describes the non-seasonal structure. If the model is purely non-seasonal the first equation is redundant and et above is equated with wt:
et=ϕ1et-1+ϕ2et-2++ϕpet-p+at-θ1at-1-θ2at-2--θqat-q.  
Estimates of the model parameters defined by
ϕ1,ϕ2,,ϕp,θ1,θ2,,θq, Φ1,Φ2,,ΦP,Θ1,Θ2,,ΘQ  
and (optionally) c are obtained by minimizing a quadratic form in the vector w=(w1,w2,,wN).
The minimization process is iterative, iterations being performed until convergence is achieved (see Section 3 in g13aef 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 routine, to verify that convergence is adequate for practical purposes.

4 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

5 Arguments

1: mr(7) 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 (ϕ), 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, s0;
  • p+q+P+Q>0;
  • s1;
  • if s=0, P+D+Q=0;
  • if s>1, P+D+Q>0;
  • d+s×(P+D)n;
  • p+d-q+s×(P+D-Q)n.
2: par(npar) Real (Kind=nag_wp) array Input/Output
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.
3: npar Integer Input
On entry: the total number of ϕ, θ, Φ and Θ parameters to be estimated.
Constraint: npar=p+q+P+Q.
4: c Real (Kind=nag_wp) Input/Output
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.
5: 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: kfc=0 or 1.
6: x(nx) Real (Kind=nag_wp) array Input
On entry: the n values of the original undifferenced time series.
7: nx Integer Input
On entry: n, the length of the original undifferenced time series.
8: 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.
9: ndf Integer Output
On exit: the number of degrees of freedom associated with s,
ndf=n-d-D×s-p-q-P-Q-kfc.
10: sd(nppc) Real (Kind=nag_wp) array Output
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 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.
11: nppc Integer Input
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.
12: cm(ldcm,nppc) Real (Kind=nag_wp) array Output
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.
13: ldcm Integer Input
On entry: the first dimension of the array cm as declared in the (sub)program from which g13aff is called.
Constraint: ldcmnppc.
14: st(nx) Real (Kind=nag_wp) array Output
On exit: the value of the state set in its first nst elements. If the routine exits with ifail containing a value other than 0 or 9, the contents of st will be indeterminate.
15: nst Integer Output
On exit: the size of the state set. nst=P×s+D×s+d+q+max(p,Q×s).
nst should be used subsequently in g13agf and g13ahf as the dimension of st.
16: kpiv Integer Input
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 (as defined by x04abf). For each iteration, the heading
G13AFZ MONITORING OUTPUT - ITERATION n
followed by the argument values, and residual sum of squares, are printed.
17: nit Integer Input
On entry: the maximum number of iterations to be performed.
Constraint: nit0.
18: itc Integer Output
On exit: the number of iterations performed.
19: isf(4) Integer array Output
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.
20: res(ires) Real (Kind=nag_wp) array Output
On exit: the first nres elements of res contain the model residuals derived from the differenced series. If the routine 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.
21: ires Integer Input
On entry: the dimension of the array res as declared in the (sub)program from which g13aff is called.
Constraint: ires15×Q+11n+13×nppc+8×P+12+2× (Q+nppc) 2,
where P=p+(P×s) and Q=q+(Q×s).
22: nres Integer Output
On exit: the number of model residuals returned in res.
23: 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 −1 is recommended since useful values can be provided in some output arguments even when ifail0 on exit. 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:
Note: in some cases g13aff may return useful information.
ifail=1
On entry, kfc=value.
Constraint: kfc=0 or 1.
On entry, npar=value.
Constraint: npar=p+q+P+Q.
The orders vector mr is invalid.
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., npar+kfcnx-d-D×s.
ifail=3
On entry, nit=value.
Constraint: nit0.
ifail=4
On entry, nx=value and minimum required size for the state set array=value (the minimum size required is returned in nst).
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 with st dimensioned at least nst.
ifail=5
On entry, ires=value and the minimum size required=value.
Constraint: ires15×Q+11n+13×nppc+8×P+12+2× (Q+nppc) 2, where P=p+(P×s) and Q=q+(Q×s).
ifail=6
On entry, ldcm=value and nppc=value.
Constraint: ldcmnppc.
ifail=7
A failure in the search procedure has occurred. This may be due to a badly conditioned sum of squares function, or the default convergence criterion may be too strict. Use g13aef with a less strict convergence criterion. Some output arguments may contain meaningful values.
ifail=8
The inversion of the Hessian matrix in the calculation of the covariance matrix of the parameter estimates has failed. Some output arguments may contain meaningful values.
ifail=9
Failure whilst calculating backforecasts. Some output arguments may contain meaningful values.
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.
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.
g13aff is threaded by NAG for parallel execution in multithreaded implementations of the NAG Library.
g13aff makes calls to BLAS and/or LAPACK routines, which may be threaded within the vendor library used by this implementation. Consult the documentation for the vendor library for further information.
Please consult the X06 Chapter Introduction for information on how to control and interrogate the OpenMP environment used within this routine. Please also consult the Users' Note for your implementation for any additional implementation-specific information.

9 Further Comments

The time taken by g13aff is approximately proportional to nx×itc× (q+Q×s+nppc) 2.

10 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 has been omitted.

10.1 Program Text

Program Text (g13affe.f90)

10.2 Program Data

Program Data (g13affe.d)

10.3 Program Results

Program Results (g13affe.r)