NAG Library Routine Document
g13aff (uni_arima_estim_easy)
1
Purpose
g13aff is an easytouse 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 nagmk26.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) 

3
Description
The time series
${x}_{1},{x}_{2},\dots ,{x}_{n}$ supplied to the routine is assumed to follow a seasonal autoregressive integrated moving average (ARIMA) model defined as follows:
where
${\nabla}^{d}{\nabla}_{s}^{D}{x}_{t}$ is the result of applying nonseasonal differencing of order
$d$ and seasonal differencing of seasonality
$s$ and order
$D$ to the series
${x}_{t}$, as outlined in the description of
g13aaf. The differenced series is then of length
$N=n{d}^{\prime}$, where
${d}^{\prime}=d+\left(D\times s\right)$ 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 zeromean 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:
The second equation describes the nonseasonal structure. If the model is purely nonseasonal the first equation is redundant and
${e}_{t}$ above is equated with
${w}_{t}$:
Estimates of the model parameters defined by
and (optionally)
$c$ are obtained by minimizing a quadratic form in the vector
$w={\left({w}_{1},{w}_{2},\dots ,{w}_{N}\right)}^{\prime}$.
The minimization process is iterative, iterations being performed until convergence is achieved (see
Section 3 in
g13aef for full details), or until the userspecified 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: $\mathbf{mr}\left(7\right)$ – Integer arrayInput

On entry: the orders vector $\left(p,d,q,P,D,Q,s\right)$ of the ARIMA model whose parameters are to be estimated. $p$, $q$, $P$ and $Q$ refer respectively to the number of autoregressive $\left(\varphi \right)$, moving average $\left(\theta \right)$, seasonal autoregressive $\left(\Phi \right)$ and seasonal moving average $\left(\Theta \right)$ parameters. $d$, $D$ and $s$ refer respectively to the order of nonseasonal 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 \left(P+D\right)\le n$;
 $p+dq+s\times \left(P+DQ\right)\le n$.
 2: $\mathbf{par}\left({\mathbf{npar}}\right)$ – Real (Kind=nag_wp) arrayInput/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: contains the latest values of the estimates of these parameters.
 3: $\mathbf{npar}$ – IntegerInput

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$.
Therefore, if
c and
kfc are both zero on entry, there is no constant correction.
On exit: if
${\mathbf{kfc}}=0$,
c is unchanged.
If
${\mathbf{kfc}}=1$,
c contains the latest estimate of
$c$.
 5: $\mathbf{kfc}$ – IntegerInput

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) arrayInput

On entry: the $n$ values of the original undifferenced time series.
 7: $\mathbf{nx}$ – IntegerInput

On entry: $n$, the length of the original undifferenced time series.
 8: $\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 argument,
s contains zero.
 9: $\mathbf{ndf}$ – IntegerOutput

On exit: the number of degrees of freedom associated with
s,
${\mathbf{ndf}}=ndD\times spqPQ{\mathbf{kfc}}$.
 10: $\mathbf{sd}\left({\mathbf{nppc}}\right)$ – Real (Kind=nag_wp) arrayOutput

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: $\mathbf{nppc}$ – IntegerInput

On entry: the number of $\varphi $, $\theta $, $\Phi $, $\Theta $ and $c$ parameters to be estimated. ${\mathbf{nppc}}=p+q+P+Q+1$ if the constant is being estimated and ${\mathbf{nppc}}=p+q+P+Q$ if not.
Constraint:
${\mathbf{nppc}}={\mathbf{npar}}+{\mathbf{kfc}}$.
 12: $\mathbf{cm}\left({\mathbf{ldcm}},{\mathbf{nppc}}\right)$ – Real (Kind=nag_wp) arrayOutput

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: $\mathbf{ldcm}$ – IntegerInput

On entry: the first dimension of the array
cm as declared in the (sub)program from which
g13aff is called.
Constraint:
${\mathbf{ldcm}}\ge {\mathbf{nppc}}$.
 14: $\mathbf{st}\left({\mathbf{nx}}\right)$ – Real (Kind=nag_wp) arrayOutput

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: $\mathbf{nst}$ – IntegerOutput

On exit: the size of the state set.
${\mathbf{nst}}=P\times s+D\times s+d+q+\mathrm{max}\phantom{\rule{0.125em}{0ex}}\left(p,Q\times s\right)$.
nst should be used subsequently in
g13agf and
g13ahf as the dimension of
st.
 16: $\mathbf{kpiv}$ – IntegerInput

On entry: must be nonzero if the progress of the optimization is to be monitored using the builtin printing facility. Otherwise
kpiv must contain zero. If selected, monitoring output will be sent to the current advisory message unit 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: $\mathbf{nit}$ – IntegerInput

On entry: the maximum number of iterations to be performed.
Constraint:
${\mathbf{nit}}\ge 0$.
 18: $\mathbf{itc}$ – IntegerOutput

On exit: the number of iterations performed.
 19: $\mathbf{isf}\left(4\right)$ – Integer arrayOutput

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. 
$\phantom{}0$ 
No parameter of this type is in the model. 
$\phantom{}1$ 
Valid final estimates for parameters of this type have been obtained. 
 20: $\mathbf{res}\left({\mathbf{ires}}\right)$ – Real (Kind=nag_wp) arrayOutput

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: $\mathbf{ires}$ – IntegerInput

On entry: the dimension of the array
res as declared in the (sub)program from which
g13aff is called.
Constraint:
${\mathbf{ires}}\ge 15\times {Q}^{\prime}+11n+13\times {\mathbf{nppc}}+8\times {P}^{\prime}+12+2\times {\left({Q}^{\prime}+{\mathbf{nppc}}\right)}^{2}$,
where ${P}^{\prime}=p+\left(P\times s\right)$ and ${Q}^{\prime}=q+\left(Q\times s\right)$.
 22: $\mathbf{nres}$ – IntegerOutput

On exit: the number of model residuals returned in
res.
 23: $\mathbf{ifail}$ – IntegerInput/Output

On entry:
ifail must be set to
$0$,
$1\text{ or}1$. If you are unfamiliar with this argument you should refer to
Section 3.4 in How to Use the NAG Library and its Documentation for details.
For environments where it might be inappropriate to halt program execution when an error is detected, the value
$1\text{ or}1$ is recommended. If the output of error messages is undesirable, then the value
$1$ is recommended. Otherwise, because for this routine the values of the output arguments may be useful even if
${\mathbf{ifail}}\ne {\mathbf{0}}$ on exit, the recommended value is
$1$.
When the value $\mathbf{1}\text{ or}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
If on entry
${\mathbf{ifail}}=0$ or
$1$, explanatory error messages are output on the current error message unit (as defined by
x04aaf).
Note: g13aff may return useful information for one or more of the following detected errors or warnings.
Errors or warnings detected by the routine:
 ${\mathbf{ifail}}=1$

On entry,  ${\mathbf{npar}}\ne p+q+P+Q$, 
or  the orders vector mr is invalid (check the constraints in Section 5), 
or  ${\mathbf{kfc}}\ne 0$ or $1$, 
or  ${\mathbf{nppc}}\ne {\mathbf{npar}}+{\mathbf{kfc}}$. 
 ${\mathbf{ifail}}=2$

On entry, ${\mathbf{nx}}dD\times s\le {\mathbf{npar}}+{\mathbf{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 overparameterised.
 ${\mathbf{ifail}}=3$

On entry,  ${\mathbf{nit}}<0$. 
 ${\mathbf{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 with
st dimensioned at least (
nst), where
nst is the value returned by
g13aff, or computed using the formula in
Section 5 of this document.
 ${\mathbf{ifail}}=5$

On entry, the workspace array
res is too small. Check the value of
ires against the constraints in
Section 5.
 ${\mathbf{ifail}}=6$

On entry,  ${\mathbf{ldcm}}<{\mathbf{nppc}}$. 
 ${\mathbf{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 with a less strict convergence criterion.
Some output arguments may contain meaningful values; see
Section 5 for details.
 ${\mathbf{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; see
Section 5 for details.
 ${\mathbf{ifail}}=9$

This indicates a failure when solving the equations giving the latest estimates of the backforecasts.
Some output arguments may contain meaningful values; see
Section 5 for details.
 ${\mathbf{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.
 ${\mathbf{ifail}}=11$

An internal error has arisen in partitioning
res for use by
g13aef. This error should not occur; report it to NAG via your site representative.
 ${\mathbf{ifail}}=99$
An unexpected error has been triggered by this routine. Please
contact
NAG.
See
Section 3.9 in How to Use the NAG Library and its Documentation for further information.
 ${\mathbf{ifail}}=399$
Your licence key may have expired or may not have been installed correctly.
See
Section 3.8 in How to Use the NAG Library and its Documentation for further information.
 ${\mathbf{ifail}}=999$
Dynamic memory allocation failed.
See
Section 3.7 in How to Use the NAG Library and its Documentation for further information.
7
Accuracy
The computations are believed to be stable.
8
Parallelism and Performance
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 implementationspecific information.
The time taken by g13aff is approximately proportional to ${\mathbf{nx}}\times {\mathbf{itc}}\times {\left(q+Q\times s+{\mathbf{nppc}}\right)}^{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 nonseasonal parameters is $3$, one autoregressive ($\varphi $) and two moving average ($\theta $). No seasonal effects are taken into account.
The constant is estimated. Up to $50$ iterations are allowed.
The initial estimates of ${\varphi}_{1}$, ${\theta}_{1}$, ${\theta}_{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)