NAG Library Routine Document
G13DCF
1 Purpose
G13DCF fits a vector autoregressive moving average (VARMA) model to an observed vector of time series using the method of Maximum Likelihood (ML). Standard errors of parameter estimates are computed along with their appropriate correlation matrix. The routine also calculates estimates of the residual series.
2 Specification
| SUBROUTINE G13DCF ( | K, N, IP, IQ, MEAN, PAR, NPAR, QQ, KMAX, W, PARHLD, EXACT, IPRINT, CGETOL, MAXCAL, ISHOW, NITER, RLOGL, V, G, CM, LDCM, WORK, LWORK, IW, LIW, IFAIL) |
| INTEGER | K, N, IP, IQ, NPAR, KMAX, IPRINT, MAXCAL, ISHOW, NITER, LDCM, LWORK, IW(1), LIW, IFAIL |
| double precision | PAR(NPAR), QQ(KMAX,K), W(KMAX,N), CGETOL, RLOGL, V(KMAX,N), G(NPAR), CM(LDCM,NPAR), WORK(1) |
| LOGICAL | MEAN, PARHLD(NPAR), EXACT |
3 Description
Let
Wt
=
w1t,w2t,…,wktT
, for
t=1,2,…,n, denote a vector of
k time series which is assumed to follow a multivariate ARMA model of the form
where
εt
=
ε1t,ε2t,…,εktT
, for
t=1,2,…,n, is a vector of
k residual series assumed to be Normally distributed with zero mean and positive-definite covariance matrix
Σ. The components of
εt are assumed to be uncorrelated at non-simultaneous lags. The
ϕi and
θj are
k by
k matrices of parameters.
ϕi, for
i=1,2,…,p, are called the autoregressive (AR) parameter matrices, and
θi, for
i=1,2,…,q, the moving average (MA) parameter matrices. The parameters in the model are thus the
p (
k by
k)
ϕ-matrices, the
q (
k by
k)
θ-matrices, the mean vector,
μ, and the residual error covariance matrix
Σ. Let
where
I denotes the
k by
k identity matrix.
The ARMA model
(1) is said to be stationary if the eigenvalues of
Aϕ lie inside the unit circle. Similarly, the ARMA model
(1) is said to be invertible if the eigenvalues of
Bθ lie inside the unit circle.
The method of computing the exact likelihood function (using a Kalman filter algorithm) is discussed in
Shea (1987). A quasi-Newton algorithm (see
Gill and Murray (1972)) is then used to search for the maximum of the log-likelihood function. Stationarity and invertibility are enforced on the model using the reparameterisation discussed in
Ansley and Kohn (1986). Conditional on the maximum likelihood estimates being equal to their true values the estimates of the residual series are uncorrelated with zero mean and constant variance
Σ.
You have the option of setting a parameter (
EXACT to .FALSE.) so that G13DCF calculates conditional maximum likelihood estimates (conditional on
W0=W-1=⋯=W1-p=ε0=ε-1=⋯=
ε1-q=0). This may be useful if the exact maximum likelihood estimates are close to the boundary of the invertibility region.
You also have the option (see
Section 5) of requesting G13DCF to constrain elements of the
ϕ and
θ matrices and
μ vector to have pre-specified values.
4 References
Ansley C F and Kohn R (1986) A note on reparameterising a vector autoregressive moving average model to enforce stationarity
J. Statist. Comput. Simulation 24 99–106
Gill P E and Murray W (1972) Quasi-Newton methods for unconstrained optimization
J. Inst. Math. Appl. 9 91–108
Shea B L (1987) Estimation of multivariate time series
J. Time Ser. Anal. 8 95–110
5 Parameters
- 1: K – INTEGERInput
On entry:
k, the number of observed time series.
Constraint:
K≥1.
- 2: N – INTEGERInput
On entry:
n, the number of observations in each time series.
Constraint:
N≥3.
- 3: IP – INTEGERInput
-
On entry: p, the number of AR parameter matrices.
Constraint:
IP≥0.
- 4: IQ – INTEGERInput
On entry: q, the number of MA parameter matrices.
Constraint:
IQ≥0.
IP=IQ=0 is not permitted.
- 5: MEAN – LOGICALInput
On entry: MEAN='M',
if components of μ have been estimated and
MEAN='Z', if all elements of μ are to be taken as zero.
Constraint:
MEAN='M' or 'Z'.
- 6: PAR(NPAR) – double precision arrayInput/Output
On entry: initial parameter estimates read in row by row in the order
ϕ1,ϕ2,…,ϕp,
θ1,θ2,…,θq,μ.
Thus,
- if IP>0, PARl-1×k×k+i-1×k+j must be set equal to an initial estimate of the i,jth element of ϕl, for l=1,2,…,p and i,j=1,2,…,k;
- if IQ>0, PARp×k×k+l-1×k×k+i-1×k+j must be set equal to an initial estimate of the i,jth element of θl, l=1,2,…,q and i,j=1,2,…,k;
- if MEAN=.TRUE., PARp+q×k×k+i should be set equal to an initial estimate of the ith component of μ (μi). (If you set PARp+q×k×k+i to 0.0 then G13DCF will calculate the mean of the ith series and use this as an initial estimate of μi.)
The first
p×k×k elements of
PAR must satisfy the stationarity condition and the next
q×k×k elements of
PAR must satisfy the invertibility condition.
If in doubt set all elements of
PAR to
0.0.
On exit: if
IFAIL=0 or
IFAIL≥4 then all the elements of
PAR will be overwritten by the latest estimates of the corresponding ARMA parameters.
- 7: NPAR – INTEGERInput
-
On entry:
the dimension of the arrays
PAR,
PARHLD and
G and
the second dimension of the array
CM as declared in the (sub)program from which G13DCF is called.
NPAR is the number of initial parameter estimates. The total number of observations
n×k must exceed the total number of parameters in the model (
NPAR+kk+1/2).
Constraints:
- if MEAN=.TRUE., NPAR must be set equal to k6=p+q×k×k;
- if MEAN=.FALSE., NPAR must be set equal to k6=p+q×k×k+k.
- 8: QQ(KMAX,K) – double precision arrayInput/Output
On entry:
QQij must be set equal to an initial estimate of the
i,jth element of
Σ. The lower triangle only is needed.
QQ must be positive-definite. It is strongly recommended that on entry the elements of
QQ are of the same order of magnitude as at the solution point. If you set
QQij=0.0, for
i=1,2,…,k and
j=1,2,…,i, then G13DCF will calculate the covariance matrix between the
k time series and use this as an initial estimate of
Σ.
On exit: if IFAIL=0 or IFAIL≥4 then QQij will contain the latest estimate of the i,jth element of Σ. The lower triangle only is returned.
- 9: KMAX – INTEGERInput
On entry:
the first dimension of the arrays
QQ,
W and
V as declared in the (sub)program from which G13DCF is called.
Constraint:
KMAX≥K.
- 10: W(KMAX,N) – double precision arrayInput
On entry: Wit must be set equal to the ith component of Wt, for i=1,2,…,k and t=1,2,…,n.
- 11: PARHLD(NPAR) – LOGICAL arrayInput
On entry:
PARHLDi must be set to .TRUE., if
PARi is to be held constant at its input value and .FALSE., if
PARi is a free parameter, for
i=1,2,…,NPAR.
If in doubt try setting all elements of
PARHLD to .FALSE..
- 12: EXACT – LOGICALInput
On entry: must be set equal to .TRUE. if you wish G13DCF to compute exact maximum likelihood estimates.
EXACT must be set equal to .FALSE. if only conditional likelihood estimates are required.
- 13: IPRINT – INTEGERInput
On entry: the frequency with which the automatic monitoring routine is to be called.
- IPRINT>0
- The ML search procedure is monitored once every IPRINT iterations and just before exit from the search routine.
- IPRINT=0
- The search routine is monitored once at the final point.
- IPRINT<0
- The search routine is not monitored at all.
- 14: CGETOL – double precisionInput
On entry: the accuracy to which the solution in
PAR and
QQ is required.
If
CGETOL is set to
10-l and on exit
IFAIL=0 or
IFAIL≥6, then all the elements in
PAR and
QQ should be accurate to approximately
l decimal places. For most practical purposes the value
10-4 should suffice. You should be wary of setting
CGETOL too small since the convergence criteria may then have become too strict for the machine to handle.
If
CGETOL has been set to a value which is less than the
machine precision,
ε, then G13DCF will use the value
10.0×ε instead.
- 15: MAXCAL – INTEGERInput
On entry: the maximum number of likelihood evaluations to be permitted by the search procedure.
Constraint:
MAXCAL≥1.
Suggested value:
MAXCAL=40×NPAR×NPAR+5.
- 16: ISHOW – INTEGERInput
On entry: specifies which of the following two quantities are to be printed.
| (i) |
table of maximum likelihood estimates and their standard errors (as returned in the output arrays PAR, QQ and CM); |
| (ii) |
table of residual series (as returned in the output array V). |
- ISHOW=0
- None of the above are printed.
- ISHOW=1
- (i) only is printed.
- ISHOW=2
- (i) and (ii) are printed.
Constraint:
0≤ISHOW≤2.
- 17: NITER – INTEGEROutput
On exit: if
IFAIL=0 or
IFAIL≥4 then
NITER contains the number of iterations performed by the search routine.
- 18: RLOGL – double precisionOutput
On exit: if
IFAIL=0 or
IFAIL≥4 then
RLOGL contains the value of the log-likelihood function corresponding to the final point held in
PAR and
QQ.
- 19: V(KMAX,N) – double precision arrayOutput
On exit: if
IFAIL=0 or
IFAIL≥4 then
Vit will contain an estimate of the
ith component of
εt, for
i=1,2,…,k and
t=1,2,…,n, corresponding to the final point held in
PAR and
QQ.
- 20: G(NPAR) – double precision arrayOutput
On exit: if
IFAIL=0 or
IFAIL≥4 then
Gi will contain the estimated first derivative of the log-likelihood function with respect to the
ith element in the array
PAR. If the gradient cannot be computed then all the elements of
G are returned as zero.
- 21: CM(LDCM,NPAR) – double precision arrayOutput
On exit: if
IFAIL=0 or
IFAIL≥4 then
CMij will contain an estimate of the correlation coefficient between the
ith and
jth elements in the
PAR array for
1≤i≤NPAR,
1≤j≤NPAR. If
i=j, then
CMij will contain the estimated standard error of
PARi. If the
lth component of
PAR has been held constant, i.e.,
PARHLDl was set to .TRUE., then the
lth row and column of
CM will be set to zero. If the second derivative matrix cannot be computed then all the elements of
CM are returned as zero.
- 22: LDCM – INTEGERInput
On entry:
the first dimension of the array
CM as declared in the (sub)program from which G13DCF is called.
Constraint:
LDCM≥NPAR.
- 23: WORK(1) – double precision arrayInput
- 24: LWORK – INTEGERInput
- 25: IW(1) – INTEGER arrayInput
- 26: LIW – INTEGERInput
-
These parameters are no longer accessed by G13DCF. Workspace is provided internally by dynamic allocation instead.
- 27: IFAIL – INTEGERInput/Output
-
On entry:
IFAIL must be set to
0,
-1 or 1. If you are unfamiliar with this parameter you should refer to
Section 3.3 in the Essential Introduction for details.
On exit:
IFAIL=0 unless the routine detects an error (see
Section 6).
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, because for this routine the values of the output parameters may be useful even if
IFAIL≠0 on exit, the recommended value is
-1.
When the value -1 or 1 is used it is essential to test the value of IFAIL on exit.
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).
Note: G13DCF may return useful information for one or more of the following detected errors or warnings.
Errors or warnings detected by the routine:
- IFAIL=1
-
| On entry, | K<1, |
| or | IP<0, |
| or | IQ<0, |
| or | IP=IQ=0, |
| or | NPAR≠IP+IQ×K×K+Δ×K, where Δ=1 if MEAN=.TRUE. or Δ=0 if MEAN=.FALSE., |
| or | N×K≤NPAR+K×K+1/2, |
| or | KMAX<K, |
| or | MAXCAL<1, |
| or | ISHOW<0, |
| or | ISHOW>2, |
| or | LDCM<NPAR. |
- IFAIL=2
-
On entry, either the initial estimate of Σ is not positive-definite, or the initial estimates of the AR parameters are such that the model is non-stationary, or the initial estimates of the MA parameters are such that the model is non-invertible. To proceed, you must try a different starting point.
- IFAIL=3
-
The routine cannot compute a sufficiently accurate estimate of the gradient vector at the user-supplied starting point. This usually occurs if either the initial parameter estimates are very close to the ML parameter estimates, or you have supplied a very poor estimate of Σ or the starting point is very close to the boundary of the stationarity or invertibility region. To proceed, you must try a different starting point.
- IFAIL=4
-
There have been
MAXCAL log-likelihood evaluations made in the routine. If steady increases in the log-likelihood function were monitored up to the point where this exit occurred, then the exit probably simply occurred because
MAXCAL was set too small, so the calculations should be restarted from the final point held in
PAR and
QQ. This type of exit may also indicate that there is no maximum to the likelihood surface. Output quantities (as described in
Section 5) are computed at the final point held in
PAR and
QQ, except that if
G or
CM cannot be computed, in which case they are set to zero.
- IFAIL=5
-
The conditions for a solution have not all been met, but a point at which the log-likelihood took a larger value could not be found.
Provided that the estimated first derivatives are sufficiently small, and that the estimated condition number of the second derivative (Hessian) matrix, as printed when IPRINT≥0, is not too large, this error exit may simply mean that, although it has not been possible to satisfy the specified requirements, the algorithm has in fact found the solution as far as the accuracy of the machine permits.
Such a condition can arise, for instance, if
CGETOL has been set so small that rounding error in evaluating the likelihood function makes attainment of the convergence conditions impossible.
If the estimated condition number at the final point is large, it could be that the final point is a solution but that the smallest eigenvalue of the Hessian matrix is so close to zero at the solution that it is not possible to recognize it as a solution. Output quantities (as described in
Section 5) are computed at the final point held in
PAR and
QQ, except that if
G or
CM cannot be computed, in which case they are set to zero.
- IFAIL=6
-
The ML solution is so close to the boundary of either the stationarity region or the invertibility region that G13DCF cannot evaluate the Hessian matrix. The elements of
CM will then be set to zero on exit. The elements of
G will also be set to zero. All other output quantities will be correct.
- IFAIL=7
-
This is an unlikely exit, which could occur in
E04XAF/E04XAA, which computes an estimate of the second derivative matrix and the gradient vector at the solution point. Either the Hessian matrix was found to be too ill-conditioned to be evaluated accurately or the gradient vector could not be computed to an acceptable degree of accuracy. In this case the elements of
CM will be set to zero on exit as will the elements of
G. All other output quantities will be correct.
- IFAIL=8
-
The second derivative matrix at the solution point is not positive-definite. In this case the elements of
CM will be set to zero on exit. All other output quantities will be correct.
- IFAIL=-999
-
Internal memory allocation failed.
7 Accuracy
On exit from G13DCF, if
IFAIL=0 or
IFAIL≥6 and
CGETOL has been set to
10-l, then all the parameters should be accurate to approximately
l decimal places. If
CGETOL was set equal to a value less than the
machine precision,
ε, then all the parameters should be accurate to approximately
10.0×ε.
If
IFAIL=4 on exit (i.e.,
MAXCAL likelihood evaluations have been made but the convergence conditions of the search routine have not been satisfied), then the elements in
PAR and
QQ may still be good approximations to the ML estimates. You are advised to inspect the elements of
G to see whether this is likely to be so.
8 Further Comments
8.1 Memory Usage
Let
r
=
maxIP,IQ
and
s
=
NPAR+K×
K+1
/
2
. Local workspace arrays of fixed lengths are allocated internally by G13DCF. The total size of these arrays amounts to
s+K×r+52
INTEGER elements and
2
×
s2
+s×
s-1
/2+15×
s+
K2
×
2×IP+IQ+
r+3
2
+K×
2×
r2
+2×
r+3×
N+4
+10
double precision elements.
8.2 Timing
The number of iterations required depends upon the number of parameters in the model and the distance of the user-supplied starting point from the solution.
8.3 Constraining for Stationarity and Invertibility
If the solution lies on the boundary of the admissibility region (stationarity and invertibility region) then G13DCF may get into difficulty and exit with
IFAIL=5. If this exit occurs you are advised to either try a different starting point or a different setting for
EXACT. If this still continues to occur then you are urged to try fitting a more parsimonious model.
8.4 Over-parameterisation
You are advised to try and avoid fitting models with an excessive number of parameters since over-parameterisation can cause the maximization problem to become ill-conditioned.
8.5 Standardizing the Residual Series
The standardized estimates of the residual series
εt (denoted by
e^t) can easily be calculated by forming the Cholesky decomposition of
Σ, e.g.,
GGT and setting
e^t=G-1ε^t.
F07FDF (DPOTRF) may be used to calculate the array
G. The components of
e^t which are now uncorrelated at
all lags can sometimes be more easily interpreted.
8.6 Assessing the Fit of the Model
If your time series model provides a good fit to the data then the residual series should be approximately white noise, i.e., exhibit no serial cross-correlation. An examination of the residual cross-correlation matrices should confirm whether this is likely to be so. You are advised to call
G13DSF to provide information for diagnostic checking.
G13DSF returns the residual cross-correlation matrices along with their asymptotic standard errors.
G13DSF also computes a portmanteau statistic and its asymptotic significance level for testing model adequacy. If
IFAIL=0 or
5≤IFAIL≤8 on exit from G13DCF then the quantities
K,
N,
V,
KMAX,
IP,
IQ,
PAR,
PARHLD, and
QQ will be suitable for input to
G13DSF.
9 Example
This example shows how to fit a bivariate AR(1) model to two series each of length 48. μ will be estimated and ϕ12,1 will be constrained to be zero.
9.1 Program Text
Program Text (g13dcfe.f)
9.2 Program Data
Program Data (g13dcfe.d)
9.3 Program Results
Program Results (g13dcfe.r)