hide long namesshow long names
hide short namesshow short names
Integer type:  int32  int64  nag_int  show int32  show int32  show int64  show int64  show nag_int  show nag_int

PDF version (NAG web site, 64-bit version, 64-bit version)
Chapter Contents
Chapter Introduction
NAG Toolbox

NAG Toolbox: nag_tsa_uni_arima_estim_easy (g13af)

Purpose

nag_tsa_uni_arima_estim_easy (g13af) is an easy-to-use version of nag_tsa_uni_arima_estim (g13ae). 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 nag_tsa_uni_arima_update (g13ag) and nag_tsa_uni_arima_forecast_state (g13ah).
The estimation procedure is iterative, starting with initial parameter values such as may be obtained using nag_tsa_uni_arima_prelim (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

[par, c, s, ndf, sd, cm, st, nst, itc, isf, res, nres, ifail] = g13af(mr, par, c, x, 'npar', npar, 'kfc', kfc, 'nx', nx, 'kpiv', kpiv, 'nit', nit, 'ires', ires)
[par, c, s, ndf, sd, cm, st, nst, itc, isf, res, nres, ifail] = nag_tsa_uni_arima_estim_easy(mr, par, c, x, 'npar', npar, 'kfc', kfc, 'nx', nx, 'kpiv', kpiv, 'nit', nit, 'ires', ires)
Note: the interface to this routine has changed since earlier releases of the toolbox:
Mark 23: ires, nit, kpiv, kfc optional, npcc dropped
.

Description

The time series x1,x2,,xnx1,x2,,xn supplied to the function is assumed to follow a seasonal autoregressive integrated moving average (ARIMA) model defined as follows:
dsDxtc = wt,
dsDxt-c=wt,
where dsDxtdsDxt is the result of applying non-seasonal differencing of order dd and seasonal differencing of seasonality ss and order DD to the series xtxt, as outlined in the description of nag_tsa_uni_diff (g13aa). The differenced series is then of length N = ndN=n-d, where d = d + (D × s)d=d+(D×s) is the generalized order of differencing. The scalar cc is the expected value of the differenced series, and the series w1,w2,,wNw1,w2,,wN follows a zero-mean stationary autoregressive moving average (ARMA) model defined by a pair of recurrence equations. These express wtwt in terms of an uncorrelated series atat, via an intermediate series etet. The first equation describes the seasonal structure:
wt = Φ1wts + Φ2wt2 × s + + ΦPwtP × s + etΘ1etsΘ2et2 × sΘQetQ × s.
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 etet above is equated with wtwt:
et = φ1et1 + φ2et2 + + φpetp + atθ1at1θ2at2θqatq.
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
ϕ1,ϕ2,,ϕp,θ1,θ2,,θq, Φ1,Φ2,,ΦP,Θ1,Θ2,,ΘQ
and (optionally) cc are obtained by minimizing a quadratic form in the vector w = (w1,w2,,wN)w=(w1,w2,,wN).
The minimization process is iterative, iterations being performed until convergence is achieved (see Section [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 function, 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

Parameters

Compulsory Input Parameters

1:     mr(77) – int64int32nag_int array
The orders vector (p,d,q,P,D,Q,s)(p,d,q,P,D,Q,s) of the ARIMA model whose parameters are to be estimated. pp, qq, PP and QQ refer respectively to the number of autoregressive (φ)(ϕ), moving average (θ)(θ), seasonal autoregressive (Φ)(Φ) and seasonal moving average (Θ)(Θ) parameters. dd, DD and ss refer respectively to the order of non-seasonal differencing, the order of seasonal differencing and the seasonal period.
Constraints:
  • pp, dd, qq, PP, DD, QQ, s0s0;
  • p + q + P + Q > 0p+q+P+Q>0;
  • s1s1;
  • if s = 0s=0, P + D + Q = 0P+D+Q=0;
  • if s > 1s>1, P + D + Q > 0P+D+Q>0;
  • d + s × (P + D)nd+s×(P+D)n;
  • p + dq + s × (P + DQ)np+d-q+s×(P+D-Q)n.
2:     par(npar) – double array
npar, the dimension of the array, must satisfy the constraint npar = p + q + P + Qnpar=p+q+P+Q.
The initial estimates of the pp values of the φϕ parameters, the qq values of the θθ parameters, the PP values of the ΦΦ parameters and the QQ values of the ΘΘ parameters, in that order.
3:     c – double scalar
If kfc = 0kfc=0, c must contain the expected value, cc, of the differenced series.
If kfc = 1kfc=1, c must contain an initial estimate of cc.
Therefore, if c and kfc are both zero on entry, there is no constant correction.
4:     x(nx) – double array
The nn values of the original undifferenced time series.

Optional Input Parameters

1:     npar – int64int32nag_int scalar
Default: The dimension of the array par.
The total number of φϕ, θθ, ΦΦ and ΘΘ parameters to be estimated.
Constraint: npar = p + q + P + Qnpar=p+q+P+Q.
2:     kfc – int64int32nag_int scalar
Must be set to 11 if the constant, cc, is to be estimated and 00 if it is to be held fixed at its initial value.
Default: 11 
Constraint: kfc = 0kfc=0 or 11.
3:     nx – int64int32nag_int scalar
Default: The dimension of the array x.
nn, the length of the original undifferenced time series.
4:     kpiv – int64int32nag_int scalar
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 nag_file_set_unit_advisory (x04ab). For each iteration, the heading
 G13AFZ MONITORING OUTPUT - ITERATION n 
followed by the parameter values, and residual sum of squares, are printed.
Default: 00 
5:     nit – int64int32nag_int scalar
The maximum number of iterations to be performed.
Default: 100100 
Constraint: nit0nit0.
6:     ires – int64int32nag_int scalar
The dimension of the array res as declared in the (sub)program from which nag_tsa_uni_arima_estim_easy (g13af) is called.
Default: 15 × (q + q × s) + 11 × nx + 13 × (npar + kfc) + 8 × (p + p × s) + 12 + 2 × (q + q × s + npar + kfc)2 15×(q+q×s)+11×nx+13×(npar+kfc)+8×(p+p×s)+12+2×(q+q×s+npar+kfc)2  
Constraint: ires15 × Q + 11n + 13 × nppc + 8 × P + 12 + 2 × (Q + nppc)2ires15×Q+11n+13×nppc+8×P+12+2× (Q+nppc) 2, where P = p + (P × s)P=p+(P×s) and Q = q + (Q × s)Q=q+(Q×s).

Input Parameters Omitted from the MATLAB Interface

nppc ldcm

Output Parameters

1:     par(npar) – double array
Contains the latest values of the estimates of these parameters.
2:     c – double scalar
If kfc = 0kfc=0, c is unchanged.
If kfc = 1kfc=1, c contains the latest estimate of cc.
3:     s – double scalar
The residual sum of squares after the latest series of parameter estimates has been incorporated into the model. If the function exits with a faulty input parameter, s contains zero.
4:     ndf – int64int32nag_int scalar
The number of degrees of freedom associated with s, ndf = ndD × spqPQkfcndf=n-d-D×s-p-q-P-Q-kfc.
5:     sd(nppc) – double array
nppc = npar + kfcnppc=npar+kfc.
The standard deviations corresponding to the parameters in the model (pp autoregressive, qq moving average, PP seasonal autoregressive, QQ seasonal moving average and cc, if estimated, in that order). If the function exits with ifail containing a value other than 00 or 99, or if the required number of iterations is zero, the contents of sd will be indeterminate.
6:     cm(ldcm,nppc) – double array
nppc = npar + kfcnppc=npar+kfc.
ldcmnppcldcmnppc.
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 00 or 99, or if the required number of iterations is zero.
7:     st(nx) – double array
The value of the state set in its first nst elements. If the function exits with ifail containing a value other than 00 or 99, the contents of st will be indeterminate.
8:     nst – int64int32nag_int scalar
The size of the state set. nst = P × s + D × s + d + q + max (p,Q × s)nst=P×s+D×s+d+q+max(p,Q×s).
nst should be used subsequently in nag_tsa_uni_arima_update (g13ag) and nag_tsa_uni_arima_forecast_state (g13ah) as the dimension of st.
9:     itc – int64int32nag_int scalar
The number of iterations performed.
10:   isf(44) – int64int32nag_int array
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-2 On entry parameters of this type have initial estimates which do not satisfy the stationarity or invertibility test conditions.
1-1 The search procedure has failed to converge because the latest set of parameter estimates of this type is invalid.
0-0 No parameter of this type is in the model.
1-1 Valid final estimates for parameters of this type have been obtained.
11:   res(ires) – double array
The first nres elements of res contain the model residuals derived from the differenced series. If the function exits with ifail holding a value other than 00 or 99, these elements of res will be indeterminate. The rest of the array res is used as workspace.
12:   nres – int64int32nag_int scalar
The number of model residuals returned in res.
13:   ifail – int64int32nag_int scalar
ifail = 0ifail=0 unless the function detects an error (see [Error Indicators and Warnings]).

Error Indicators and Warnings

Note: nag_tsa_uni_arima_estim_easy (g13af) may return useful information for one or more of the following detected errors or warnings.
Errors or warnings detected by the function:

Cases prefixed with W are classified as warnings and do not generate an error of type NAG:error_n. See nag_issue_warnings.

  ifail = 1ifail=1
On entry,nparp + q + P + Qnparp+q+P+Q,
orthe orders vector mr is invalid (check the constraints in Section [Parameters]),
orkfc0kfc0 or 11,
ornppcnpar + kfcnppcnpar+kfc.
  ifail = 2ifail=2
On entry, nxdD × snpar + kfcnx-d-D×snpar+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 = 3ifail=3
On entry,nit < 0nit<0.
  ifail = 4ifail=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 nag_tsa_uni_arima_estim (g13ae) with st dimensioned at least (nst), where nst is the value returned by nag_tsa_uni_arima_estim_easy (g13af), or computed using the formula in Section [Parameters] of this document.
  ifail = 5ifail=5
On entry, the workspace array res is too small. Check the value of ires against the constraints in Section [Parameters].
  ifail = 6ifail=6
On entry,ldcm < nppcldcm<nppc.
W ifail = 7ifail=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 nag_tsa_uni_arima_estim (g13ae) with a less strict convergence criterion.
Some output parameters may contain meaningful values; see Section [Parameters] for details.
W ifail = 8ifail=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 Section [Parameters] for details.
W ifail = 9ifail=9
This indicates a failure when solving the equations giving the latest estimates of the backforecasts.
Some output parameters may contain meaningful values; see Section [Parameters] for details.
W ifail = 10ifail=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 = 11ifail=11
An internal error has arisen in partitioning res for use by nag_tsa_uni_arima_estim (g13ae). This error should not occur; report it to NAG via your site representative.

Accuracy

The computations are believed to be stable.

Further Comments

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

Example

function nag_tsa_uni_arima_estim_easy_example
mr = [int64(1);1;2;0;0;0;0];
par = [0; 0; 0];
c = 0;
x = [-217;
     -177;
     -166;
     -136;
     -110;
     -95;
     -64;
     -37;
     -14;
     -25;
     -51;
     -62;
     -73;
     -88;
     -113;
     -120;
     -83;
     -33;
     -19;
     21;
     17;
     44;
     44;
     78;
     88;
     122;
     126;
     114;
     85;
     64];
[parOut, cOut, s, ndf, sd, cm, st, nst, itc, isf, res, nres, ifail] = ...
    nag_tsa_uni_arima_estim_easy(mr, par, c, x);
 parOut, cOut, s, ndf, sd, cm, st, nst, itc, isf, nres, ifail
 

parOut =

   -0.0543
   -0.5548
   -0.6734


cOut =

    9.9848


s =

   9.3972e+03


ndf =

                   25


sd =

    0.3457
    0.2636
    0.1665
    7.4170


cm =

    1.0000    0.8072    0.3548   -0.0404
    0.8072    1.0000    0.4681   -0.0491
    0.3548    0.4681    1.0000   -0.0376
   -0.0404   -0.0491   -0.0376    1.0000


st =

   64.0000
  -30.9848
  -20.6573
   -2.2555
         0
         0
         0
         0
         0
         0
         0
         0
         0
         0
         0
         0
         0
         0
         0
         0
         0
         0
         0
         0
         0
         0
         0
         0
         0
         0


nst =

                    4


itc =

                   25


isf =

                    1
                    1
                    0
                    0


nres =

                   29


ifail =

                    0


function g13af_example
mr = [int64(1);1;2;0;0;0;0];
par = [0; 0; 0];
c = 0;
x = [-217;
     -177;
     -166;
     -136;
     -110;
     -95;
     -64;
     -37;
     -14;
     -25;
     -51;
     -62;
     -73;
     -88;
     -113;
     -120;
     -83;
     -33;
     -19;
     21;
     17;
     44;
     44;
     78;
     88;
     122;
     126;
     114;
     85;
     64];
[parOut, cOut, s, ndf, sd, cm, st, nst, itc, isf, res, nres, ifail] = ...
    g13af(mr, par, c, x);
 parOut, cOut, s, ndf, sd, cm, st, nst, itc, isf, nres, ifail
 

parOut =

   -0.0543
   -0.5548
   -0.6734


cOut =

    9.9848


s =

   9.3972e+03


ndf =

                   25


sd =

    0.3457
    0.2636
    0.1665
    7.4170


cm =

    1.0000    0.8072    0.3548   -0.0404
    0.8072    1.0000    0.4681   -0.0491
    0.3548    0.4681    1.0000   -0.0376
   -0.0404   -0.0491   -0.0376    1.0000


st =

   64.0000
  -30.9848
  -20.6573
   -2.2555
         0
         0
         0
         0
         0
         0
         0
         0
         0
         0
         0
         0
         0
         0
         0
         0
         0
         0
         0
         0
         0
         0
         0
         0
         0
         0


nst =

                    4


itc =

                   25


isf =

                    1
                    1
                    0
                    0


nres =

                   29


ifail =

                    0



PDF version (NAG web site, 64-bit version, 64-bit version)
Chapter Contents
Chapter Introduction
NAG Toolbox

© The Numerical Algorithms Group Ltd, Oxford, UK. 2009–2013