var_to_autocov

Return autocovariance sequence for a VAR model

Syntax

   [G,info] = var_to_autocov(A,SIG,acmaxlags,acdectol,aitr,maxiters,maxrelerr)

Arguments

See also Common variable names and data structures.

input

   A          VAR coefficients matrix
   SIG        residuals covariance matrix
   acmaxlags  maximum autocovariance lags to calculate or (default) zero for automatic calculation
   acdectol   autocovariance decay tolerance (default: 1e-8)
   aitr       use "accelerated iterative" Lyapunov solver algorithm, else (default) a Schur algorithm (see Description)
   maxiters   maximum iterations if using iterative algorithm; see 'dlyap_aitr' for defaults
   maxrelerr  maximum relative error if using iterative algorithm; see 'dlyap_aitr' for defaults

output

   G          autocovariance sequence
   info       info structure, with fields (some may not be present):
       error      error number (0 if no error)
       errmsg     error message string
       warnings   number of warnings (0 if no warnings)
       warnmsg    warning mesage strings (cell array)
       rho        VAR spectral radius
       iters      number of iterations if using iterative algorithm, else 0
       acrelerr   relative error of associated 1-lag solution
       acminlags  minimum lags required to achieve specified autocovariance decay factor
       aclags     actual number of autocovariance lags calculated

Description

Returns autocovariance sequence G defined as for a VAR model with coefficients A and (positive-definite) residual covariance matrix SIG, by "reverse-solving" the Yule-Walker equations

(where = SIG). The algorithm solves the associated 1-lag problem - a discrete-time Lyapunov equation - and then calculates higher lags recursively [1].

Errors, warnings and diagnostics are returned in the info struct. Use the routine var_info (which should always be called after this function) to display this information. Possible errors are

   info.error     info.errmsg
   ----------------------------------------------------------------------
       0          (no error, no message)
       1          unstable VAR (has unit root)
       2          residuals covariance matrix not positive-definite
       3          Lyapunov equation solver failed for some reason
       4          1-lag residuals covariance matrix not positive-definite
   ----------------------------------------------------------------------

For a stable VAR the the spectral radius info.rho (see var_specrad) must be < 1; this may be considered a unit root test for stationarity [1]. Then the autocovariance sequence decays approximately exponentially, by a factor equal to info.rho. The minimum number of lags required to achieve the specified autocovariance decay tolerance acdectol is calculated as info.acminlags, so that info.rho^info.acminlags < acdectol. The actual number of lags info.aclags to which autocovariance is calculated is then set to the minimum of info.acminlags and the specified maximum number of lags, acmaxlags (if acmaxlags is not supplied - the recommended option - it defaults to info.acminlags). A warning is issued if info.aclags < info.acminlags. In this case there is no guarantee that MVGCs - particularly in the spectral domain - will be accurate. However, if the spectral radius of the VAR model is close to 1, so that info.acminlags is unfeasibly large, there may be no alternative [note that most Granger causality libraries effectively set info.aclags to the model order]. The calculated 1-lag autocovariance matrix is also checked for positive-definitiveness. If this check fails, it may be an indication of an ill-conditioned VAR (possibly because residuals variances are too small, and/or the process is borderline stationary). In short, the info.error field must be checked by the caller: 0 signifies success, > 0 signifies an error with corresponding message in info.errmsg. Attention should also be paid to any warnings in info.WARNINGn.

The aitr flag specifies a fast (but experimental) "accelerated" iterative Lyapunov solver algorithm (see dlyap_aitr). If not set (default), the Control System Toolbox dlyap solver routine is used if available, else a roughly equivalent (but slower) scripted algorithm based on Schur decomposition (see dlyap.m in the utils/control directory).

References

[1] L. Barnett and A. K. Seth, The MVGC Multivariate Granger Causality Toolbox: A New Approach to Granger-causal Inference, J. Neurosci. Methods 223, 2014 [ preprint ].

[2] X. Kitagawa, An algorithm for solving the matrix equation X = F X F'+S, Internat. J. Control 25(5), 1977.

[3] S. Hammarling, "Numerical solution of the stable, non-negative definite Lyapunov equation", IMA J. Numer. Anal. 2, 1982.

See also

var_specrad | var_info | dlyap (ControlSystem Toolbox) | dlyap (scripted Schur algorithm) | dlyap_aitr