Main Content

Convert from vgx Functions to Model Objects

In R2017a, the functions varm, arma2ar, arma2ma, and isStable replaced vgxar, vgxcount, vgxdisp, vgxget, vgxinfer, vgxloglik, vgxma, vgxplot, vgxpred, vgxproc, vgxqual, vgxset, vgxsim, and vgxvarx. If you use the older vgx multivariate data analysis functions in releases after R2017b, MATLAB® issues an error. This topic shows you how to convert common tasks that use the vgx functions to the newer functionality.

Assume these conditions:

  • You want to model three response variables simultaneously by using a VARX(4) model. The model contains a regression component for two predictor variables, a constant vector, and a linear time-trend term.

  • The presample response data is in the 4-by-3 matrix Y0.

  • The estimation sample response data is in the 100-by-3 matrix Y.

  • The exogenous data is in the 100-by-2 matrix X.

This table compares the old and new ways to complete common tasks, based on the stated conditions.

TaskOld Functionality or BehaviorNew Functionality or Behavior
Create a VAR(4) model template for estimation.

Mdl = vgxset('n',3,'nAR',4,'Constant',true);

Mdl = varm(3,4);
Mdl.Trend = nan(3,1);

Retrieve model properties, such as, the innovations covariance matrix. 
vgxget(Mdl,'Q')
 
Mdl.Covariance
Set equality constraints for estimation; for example, set the model constant to a vector of ones. 
Mdl = vgxset(Mdl,'a',ones(3,1),'asolve',false(3,1));
 
Mdl.Constant = ones(3,1);
Fit an unrestricted model with a time trend to the data. All exogenous predictors occur in each response equation and do not share coefficients.

Xk = [(1:100)' X];    % Include linear trend
Xk = kron(Xk,eye(3)); % Create design matrix
Xk = mat2cell(Xk,3*ones(100,1),size(Xk,2)); % Pack into 100-by-1 cell vector

Mdl.nX = size(Xk{1},2); % vgxvarx must know the number ...
                        % of exogenous variables
EstMdl = vgxvarx(Mdl,Y,Xk,Y0);
vgxvarx requires a design matrix rather than a matrix of data. A linear trend and two exogenous variables yield nine columns in the design matrix.

 
EstMdl = estimate(Mdl,Y,'Y0',Y0,'X',X);
Fit the model to the data. X(:,1) appears in all equations, but X(:,2) appears in the first equation only. 
Xk = [(1:100)' X];
Xk = [kron(Xk(:,1:2),eye(3)) kron(Xk(:,3),[1; 0; 0])];
Xk = mat2cell(Xk,3*ones(100,1),size(Xk,2));
EstMdl = vgxvarx(Mdl,Y,Xk,Y0);
 
Mdl.Beta = nan(3,2);
Mdl.Beta(2:3,2) = 0;
EstMdl = estimate(Mdl,Y,'Y0',Y0,'X',X);
Obtain estimated regression coefficients.

EstMdl.b, a 9-by-1 vector in which:

  • EstMdl.b(1:3) are the estimated time trends for equations 1–3, respectively.

  • EstMdl.b(4:6) are the estimated regression coefficients of exogenous variable X(:,1) for equations 1–3, respectively.

  • EstMdl.b(7:9) are the estimated regression coefficients of exogenous variable X(:,2) for equations 1–3, respectively.

EstMdl.Beta, a 3-by-2 matrix with rows corresponding to equations (columns of Y) and columns corresponding to exogenous variables (columns of X)

Display the estimated model. 
vgxdisp(EstMdl)
 
summarize(EstMdl)
Obtain the number of unrestricted or estimated parameters in the model.

[~,numactive] = vgxcount(EstMdl);
numactive includes estimated elements in the innovations covariance matrix.

results = summarize(EstMdl);
numactive = results.NumEstimatedParameters;
numactive does not include estimated elements of the innovations covariance matrix.

Infer residuals. 
[EstMdl,~,~,E] = vgxvarx(Mdl,Y,Xk,Y0); % Method 1
E = vgxinfer(EstMdl,Y,X,Y0);           % Method 2
 
[EstMdl,~,~,E] = estimate(Mdl,Y,'Y0',Y0,'X',X);
E = infer(EstMdl,Y,'Y0',Y0,'X',X);
Obtain fit statistics. 
logl = vgxloglik(EstMdl,E);
[aic,bic] = aicbic(logl,numactive - 6,100) ...
            % Remove count of estimated covariance elements

logl = results.LogLikelihood;
aic = results.AIC;
bic = results.BIC;
Determine model stability. 
isstable = vgxqual(EstMdl);
 
ARLagOp = LagOp([{eye(3)} EstMdl.AR]);
isstable = isStable(ARLagOp);
Simulate 1000 paths of responses during the estimation period. 
YSim = vgxproc(EstMdl,100,X,Y0,[],1000);
 
YSim = simulate(EstMdl,100,'Y0',Y0,...
    'X',X,'NumPaths',1000);
Forecast the model into an 8-period horizon with 8-by-2 matrix XF containing the future exogenous data. 
XFk = [(101:108)' XF];
XFk = kron(XFk,eye(3));  % Create design matrix
XFk = mat2cell(XFk,3*ones(8,1),size(XFk,2)); 
YF = vgxpred(EstMdl,8,XFk,Y);
 
YF = forecast(EstMdl,8,Y,'X',XF);

Some notable differences between the vgx and varm functionalities are:

  • varm does not support the creation of models with structural or MA components. However, you can perform some tasks using an implicit SVARMA model. See arma2ar, arma2ma, armairf, and armafevd.

  • estimate does not support the specification of a diagonal covariance matrix for estimation.

  • varm does not allow the same regression coefficient in multiple equations. Each exogenous variable is associated with a unique regression coefficient across equations.

  • Functions in the varm framework do not accommodate multiple paths of exogenous data. Instead, when a function operates on multiple paths of responses or innovations, the function applies the same exogenous data to all paths.

See Also

Objects

Functions

Related Topics