NAG Library Routine Document

g13dkf (multi_varma_update)


g13dkf accepts a sequence of new observations in a multivariate time series and updates both the forecasts and the standard deviations of the forecast errors. A call to g13djf must be made prior to calling this routine in order to calculate the elements of a reference vector together with a set of forecasts and their standard errors. On a successful exit from g13dkf the reference vector is updated so that should future series values become available these forecasts may be updated by recalling g13dkf.


Fortran Interface
Subroutine g13dkf ( k, lmax, m, mlast, z, kmax, ref, lref, v, predz, sefz, work, ifail)
Integer, Intent (In):: k, lmax, m, kmax, lref
Integer, Intent (Inout):: mlast, ifail
Real (Kind=nag_wp), Intent (In):: z(kmax,m)
Real (Kind=nag_wp), Intent (Inout):: ref(lref), v(kmax,m), predz(kmax,lmax), sefz(kmax,lmax)
Real (Kind=nag_wp), Intent (Out):: work(k*m)
C Header Interface
#include <nagmk26.h>
void  g13dkf_ (const Integer *k, const Integer *lmax, const Integer *m, Integer *mlast, const double z[], const Integer *kmax, double ref[], const Integer *lref, double v[], double predz[], double sefz[], double work[], Integer *ifail)


Let Zt = z1t,z2t,,zktT , for t=1,2,,n, denote a k-dimensional time series for which forecasts of Z^n+1,Z^n+2,, Z^n+lmax have been computed using g13djf. Given m further observations Zn+1,Zn+2,,Zn+m, where m<lmax, g13dkf updates the forecasts of Zn+m+1,Zn+m+2,,Zn+lmax and their corresponding standard errors.
g13dkf uses a multivariate version of the procedure described in Box and Jenkins (1976). The forecasts are updated using the ψ weights, computed in g13djf. If Zt* denotes the transformed value of Zt and Z^t*l denotes the forecast of Zt+l* from time t with a lead of l (that is the forecast of Zt+l* given observations Zt*,Zt-1*,), then
Z^t*l+ 1=τ+ψl+ 1εt+ψl+ 2εt- 1+  
where τ is a constant vector of length k involving the differencing parameters and the mean vector μ. By subtraction we obtain
Estimates of the residuals corresponding to the new observations are also computed as εn+l=Zn+l*-Z^n*l, for l=1,2,,m. These may be of use in checking that the new observations conform to the previously fitted model.
On a successful exit, the reference array is updated so that g13dkf may be called again should future series values become available, see Section 9.
When a transformation has been used the forecasts and their standard errors are suitably modified to give results in terms of the original series Zt; see Granger and Newbold (1976).


Box G E P and Jenkins G M (1976) Time Series Analysis: Forecasting and Control (Revised Edition) Holden–Day
Granger C W J and Newbold P (1976) Forecasting transformed series J. Roy. Statist. Soc. Ser. B 38 189–203
Wei W W S (1990) Time Series Analysis: Univariate and Multivariate Methods Addison–Wesley


The quantities k, lmax, kmax, ref and lref from g13djf are suitable for input to g13dkf.
1:     k – IntegerInput
On entry: k, the dimension of the multivariate time series.
Constraint: k1.
2:     lmax – IntegerInput
On entry: the number, lmax, of forecasts requested in the call to g13djf.
Constraint: lmax2.
3:     m – IntegerInput
On entry: m, the number of new observations available since the last call to either g13djf or g13dkf. The number of new observations since the last call to g13djf is then m+mlast.
Constraint: 0<m<lmax-mlast.
4:     mlast – IntegerInput/Output
On entry: on the first call to g13dkf, since calling g13djf, mlast must be set to 0 to indicate that no new observations have yet been used to update the forecasts; on subsequent calls mlast must contain the value of mlast as output on the previous call to g13dkf.
On exit: is incremented by m to indicate that mlast+m observations have now been used to update the forecasts since the last call to g13djf.
mlast must not be changed between calls to g13dkf, unless a call to g13djf has been made between the calls in which case mlast should be reset to 0.
Constraint: 0mlast<lmax-m.
5:     zkmaxm – Real (Kind=nag_wp) arrayInput
On entry: zij must contain the value of zi,n+mlast+j, for i=1,2,,k and j=1,2,,m, and where n is the number of observations in the time series in the last call made to g13djf.
Constraint: if the transformation defined in tr in g13djf for the ith series is the log transformation, then zij>0.0, and if it is the square-root transformation, then zij0.0, for j=1,2,,m and i=1,2,,k.
6:     kmax – IntegerInput
On entry: the first dimension of the arrays z, predz, sefz and v as declared in the (sub)program from which g13dkf is called.
Constraint: kmaxk.
7:     reflref – Real (Kind=nag_wp) arrayInput/Output
On entry: must contain the first lmax-1×k×k+2×k×lmax+k elements of the reference vector as returned on a successful exit from g13djf (or a previous call to g13dkf).
On exit: the elements of ref are updated. The first lmax-1×k×k elements store the ψ weights ψ1,ψ2,,ψlmax-1. The next k×lmax elements contain the forecasts of the transformed series and the next k×lmax elements contain the variances of the forecasts of the transformed variables; see g13djf. The last k elements are not updated.
8:     lref – IntegerInput
On entry: the dimension of the array ref as declared in the (sub)program from which g13dkf is called.
Constraint: lreflmax-1×k×k+2×k×lmax+k.
9:     vkmaxm – Real (Kind=nag_wp) arrayOutput
On exit: vij contains an estimate of the ith component of εn+mlast+j, for i=1,2,,k and j=1,2,,m.
10:   predzkmaxlmax – Real (Kind=nag_wp) arrayInput/Output
On entry: nonupdated values are kept intact.
On exit: predzij contains the updated forecast of zi,n+j, for i=1,2,,k and j=mlast+m+1,,lmax.
The columns of predz corresponding to the new observations since the last call to either g13djf or g13dkf are set equal to the corresponding columns of z.
11:   sefzkmaxlmax – Real (Kind=nag_wp) arrayInput/Output
On entry: nonupdated values are kept intact.
On exit: sefzij contains an estimate of the standard error of the corresponding element of predz, for i=1,2,,k and j=mlast+m+1,,lmax.
The columns of sefz corresponding to the new observations since the last call to either g13djf or g13dkf are set equal to zero.
12:   workk×m – Real (Kind=nag_wp) arrayWorkspace
13:   ifail – IntegerInput/Output
On entry: ifail must be set to 0, -1 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 or 1 is recommended. If the output of error messages is undesirable, then the value 1 is recommended. Otherwise, if you are not familiar with this argument, the recommended value is 0. 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).

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:
On entry, k=value.
Constraint: k1.
On entry, kmax=value and k=value.
Constraint: kmaxk.
On entry, lmax=value.
Constraint: lmax2.
On entry, lref=value and the minimum size required=value.
Constraint: lreflmax-1×k×k+2×k×lmax+k.
On entry, m=value, lmax=value and mlast=value.
Constraint: m<lmax-mlast.
On entry, m=value.
Constraint: m>0.
On entry, mlast=value.
Constraint: mlast0.
On entry, some of the elements of the array ref have been corrupted.
On entry, one (or more) of the transformations requested is invalid. Check that you are not trying to log or square-root a series, some of whose values are negative.
The updated forecasts will overflow if computed.
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.
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.
Dynamic memory allocation failed.
See Section 3.7 in How to Use the NAG Library and its Documentation for further information.


The matrix computations are believed to be stable.

Parallelism and Performance

g13dkf 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.

Further Comments

If a further m* observations, Zn+mlast+1,Zn+mlast+2,, Zn+mlast+m*, become available, then forecasts of Zn+mlast+m*+1,Zn+mlast+m*+2,, Zn+lmax may be updated by recalling g13dkf with m=m*. Note that m and the contents of the array z are the only quantities which need updating; mlast is updated on exit from the previous call. On a successful exit, v contains estimates of εn+mlast+1,εn+mlast+2,, εn+mlast+m*; columns mlast+1,mlast+2,,mlast+m* of predz contain the new observed values Zn+mlast+1,Zn+mlast+2,, Zn+mlast+m* and columns mlast+1,mlast+2,,mlast+m* of sefz are set to zero.


This example shows how to update the forecasts of two series each of length 48. No transformation has been used and no differencing applied to either of the series. g13ddf is first called to fit an AR(1) model to the series. μ is to be estimated and ϕ12,1 constrained to be zero. A call to g13djf is then made in order to compute forecasts of the next five series values. After one new observation becomes available the four forecasts are updated. A further observation becomes available and the three forecasts are updated.

Program Text

Program Text (g13dkfe.f90)

Program Data

Program Data (g13dkfe.d)

Program Results

Program Results (g13dkfe.r)