NAG FL Interface
g13agf (uni_arima_update)
1
Purpose
g13agf accepts a series of new observations of a time series, the model of which is already fully specified, and updates the ‘state set’ information for use in constructing further forecasts. The previous specifications of the time series model should have been obtained by using
g13aef or
g13aff to estimate the relevant parameters. The supplied state set will originally have been produced by
g13aef or
g13aff, but may since have been updated by earlier calls to
g13agf.
A set of residuals corresponding to the new observations is returned. These may be of use in checking that the new observations conform to the previously fitted model.
2
Specification
Fortran Interface
Subroutine g13agf ( 
st, nst, mr, par, npar, c, anx, nuv, anexr, wa, nwa, ifail) 
Integer, Intent (In) 
:: 
nst, mr(7), npar, nuv, nwa 
Integer, Intent (Inout) 
:: 
ifail 
Real (Kind=nag_wp), Intent (In) 
:: 
par(npar), c, anx(nuv) 
Real (Kind=nag_wp), Intent (Inout) 
:: 
st(nst) 
Real (Kind=nag_wp), Intent (Out) 
:: 
anexr(nuv), wa(nwa) 

C Header Interface
#include <nag.h>
void 
g13agf_ (double st[], const Integer *nst, const Integer mr[], const double par[], const Integer *npar, const double *c, const double anx[], const Integer *nuv, double anexr[], double wa[], const Integer *nwa, Integer *ifail) 

C++ Header Interface
#include <nag.h> extern "C" {
void 
g13agf_ (double st[], const Integer &nst, const Integer mr[], const double par[], const Integer &npar, const double &c, const double anx[], const Integer &nuv, double anexr[], double wa[], const Integer &nwa, Integer &ifail) 
}

The routine may be called by the names g13agf or nagf_tsa_uni_arima_update.
3
Description
The time series model is specified as outlined in Section 3 in
g13aef or
g13aff. This also describes how the state set, which contains the minimum amount of time series information needed to construct forecasts, is made up of

(i)the differenced series ${w}_{t}$ (uncorrected for the constant $c$), for $\left(NP\times s\right)<t\le N$,

(ii)the ${d}^{\prime}$ values required to reconstitute the original series ${x}_{t}$ from the differenced series ${w}_{t}$,

(iii)the intermediate series
${e}_{t}$, for
$\left(N\mathrm{max}\phantom{\rule{0.125em}{0ex}}\left(p,Q\times s\right)\right)<t\le N$, and

(iv)the residual series ${a}_{t}$, for $\left(Nq\right)<t\le N$.
If the number of original undifferenced observations was $n$, then ${d}^{\prime}=d+\left(D\times s\right)$ and $N=n{d}^{\prime}$.
To update the state set, given a number of new undifferenced observations ${x}_{t}$, $t=n+1,n+2,\dots ,n+k$, the four series above are first reconstituted.
Differencing and residual calculation operations are then applied to the new observations and $k$ new values of ${w}_{t},{e}_{t}$ and ${a}_{t}$ are derived.
The first $k$ values in these three series are then discarded and a new state set is obtained.
The residuals in the ${a}_{t}$ series corresponding to the $k$ new observations are preserved in an output array. The parameters of the time series model are not changed in this routine.
4
References
None.
5
Arguments

1:
$\mathbf{st}\left({\mathbf{nst}}\right)$ – Real (Kind=nag_wp) array
Input/Output

On entry: the state set derived from
g13aef or
g13aff, or as modified using earlier calls of
g13agf.
On exit: the updated values of the state set.

2:
$\mathbf{nst}$ – Integer
Input

On entry: the number of values in the state set array
st.
Constraint:
${\mathbf{nst}}=P\times s+D\times s+d+q+\mathrm{max}\phantom{\rule{0.125em}{0ex}}\left(p,Q\times s\right)$. (As returned by
g13aef or
g13aff).

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

On entry: the orders vector $\left(p,d,q,P,D,Q,s\right)$ of the ARIMA model, in the usual notation.
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$.

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

On entry: the 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 the model – in that order, using the usual notation.

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

On entry: the number of $\varphi $, $\theta $, $\Phi $ and $\Theta $ parameters in the model.
Constraint:
${\mathbf{npar}}=p+q+P+Q$.

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

On entry: the constant to be subtracted from the differenced data.

7:
$\mathbf{anx}\left({\mathbf{nuv}}\right)$ – Real (Kind=nag_wp) array
Input

On entry: the new undifferenced observations which are to be used to update
st.

8:
$\mathbf{nuv}$ – Integer
Input

On entry:
$k$, the number of new observations in
anx.

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

On exit: the residuals corresponding to the new observations in
anx.

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

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

On entry: the dimension of the array
wa as declared in the (sub)program from which
g13agf is called.
Constraint:
${\mathbf{nwa}}\ge \left(4\times {\mathbf{npar}}+3\times {\mathbf{nst}}\right)$.

12:
$\mathbf{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
$0$ is recommended.
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
If on entry
${\mathbf{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:
 ${\mathbf{ifail}}=1$

On entry, ${\mathbf{npar}}=\u2329\mathit{\text{value}}\u232a$.
Constraint: ${\mathbf{npar}}=p+q+P+Q$.
The orders vector
mr is invalid.
 ${\mathbf{ifail}}=2$

On entry, ${\mathbf{nst}}=\u2329\mathit{\text{value}}\u232a$.
Constraint: ${\mathbf{nst}}=P\times s+D\times s+d+q+\mathrm{max}\phantom{\rule{0.125em}{0ex}}\left(Q\times s,p\right)$.
 ${\mathbf{ifail}}=3$

On entry, ${\mathbf{nuv}}=\u2329\mathit{\text{value}}\u232a$.
Constraint: ${\mathbf{nuv}}>0$.
 ${\mathbf{ifail}}=4$

On entry, ${\mathbf{nwa}}=\u2329\mathit{\text{value}}\u232a$ and the minimum size $\text{required}=\u2329\mathit{\text{value}}\u232a$.
Constraint: ${\mathbf{nwa}}\ge 4\times {\mathbf{npar}}+3\times {\mathbf{nst}}$.
 ${\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
The computations are believed to be stable.
8
Parallelism and Performance
g13agf is not threaded in any implementation.
The time taken by g13agf is approximately proportional to ${\mathbf{nuv}}\times {\mathbf{npar}}$.
10
Example
The following program is based on data derived from a study of monthly airline passenger totals (in thousands) to which a logarithmic transformation had been applied. The time series model was based on seasonal and nonseasonal differencing both of order
$1$, with seasonal period
$12$. The number of parameters estimated was two: a nonseasonal moving average parameter
${\theta}_{1}$ with value
$0.327$ and a seasonal moving average parameter
${\Theta}_{1}$ with value
$0.6270$. There was no constant correction. These, together with the state set array, were obtained using
g13aef.
Twelve new observations are supplied. The routine updates the state set and outputs a set of residuals corresponding to the new observations.
10.1
Program Text
10.2
Program Data
10.3
Program Results