# varm

Create vector autoregression (VAR) model

## Description

The varm function returns a varm object specifying the functional form and storing the parameter values of a p-order, stationary, multivariate vector autoregression model (VAR(p)) model.

The key components of a varm object include the number of time series (response-variable dimensionality) and the order of the multivariate autoregressive polynomial (p) because they completely specify the model structure. Other model components include a regression component to associate the same exogenous predictor variables to each response series, and constant and time trend terms. Given the response-variable dimensionality and p, all coefficient matrices and innovation-distribution parameters are unknown and estimable unless you specify their values.

To estimate models containing unknown parameter values, pass the model and data to estimate. To work with an estimated or fully specified varm model object, pass it to an object function.

## Creation

### Description

example

Mdl = varm creates a VAR(0) model composed of one response series.

example

Mdl = varm(numseries,numlags) creates a VAR(numlags) model composed of numseries response series. The maximum nonzero lag is numlags. All lags have numseries-by-numseries coefficient matrices composed of NaN values.

This shorthand syntax allows for easy model template creation. The model template is suited for unrestricted parameter estimation, that is, estimation without parameter equality constraints. After you create a model, you can alter property values using dot notation.

example

Mdl = varm(Name,Value) sets properties or additional options using name-value pair arguments. Enclose each name in quotes. For example, 'Lags',[1 4],'AR',AR specifies the two autoregressive coefficient matrices in AR at lags 1 and 4.

This longhand syntax allows for creating more flexible models. varm infers the number of series (NumSeries) and autoregressive polynomial degree (P) from the properties that you set. Therefore, property values that correspond to the number of series or autoregressive polynomial degree must be consistent with each other.

### Input Arguments

expand all

The shorthand syntax provides an easy way for you to create model templates that are suitable for unrestricted parameter estimation. For example, to create a VAR(2) model composed of three response series, enter:

Mdl = varm(3,2);

Number of time series m, specified as a positive integer. numseries specifies the dimensionality of the multivariate response variable yt and innovation εt.

numseries sets the NumSeries property.

Data Types: double

Number of lagged responses to include in the model, specified as a nonnegative integer. The resulting model is a VAR(numlags) model. All lags have numseries-by-numseries coefficient matrices composed of NaN values.

Data Types: double

#### Name-Value Pair Arguments

Specify optional comma-separated pairs of Name,Value arguments. Name is the argument name and Value is the corresponding value. Name must appear inside quotes. You can specify several name and value pair arguments in any order as Name1,Value1,...,NameN,ValueN.

The longhand syntax enables you to create models in which some or all coefficients are known. During estimation, estimate imposes equality constraints on any known parameters.

Example: 'Lags',[4 8] specifies a VAR(8) model with nonzero autoregressive coefficient matrices at lags 4 and 8.

To set values for writable properties, use Name,Value pair argument syntax. For example, 'Constant',[1; 2],'AR',{[0.1 -0.2; -0.3 0.5]} sets Constant to [1; 2] and AR to {[0.1 -0.2; -0.3 0.5]}.

Autoregressive polynomial lags, specified as the comma-separated pair consisting of 'Lags' and a numeric vector containing at most P elements of unique positive integers.

The lengths of Lags and AR must be equal. Lags(j) is the lag corresponding to the coefficient matrix AR{j}.

Example: 'Lags',[1 4]

Data Types: double

## Properties

expand all

You can set writable property values when you create the model object by using name-value pair argument syntax, or after you create the model object by using dot notation. For example, to create a VAR(1) model composed of two response series, and then specify an unknown time trend term, enter:

Mdl = varm('AR',{NaN(2)});
Mdl.Trend = NaN;

Number of time series m, specified as a positive integer. NumSeries specifies the dimensionality of the multivariate response variable yt and innovation εt.

Data Types: double

Multivariate autoregressive polynomial order, specified as a nonnegative integer. P is the maximum lag that has a nonzero coefficient matrix. Lags that are less than P can have coefficient matrices composed entirely of zeros.

P specifies the number of presample observations required to initialize the model.

Data Types: double

Model intercepts (or constants), specified as a NumSeries-by-1 numeric vector.

Example: 'Constant',[1; 2]

Data Types: double

Autoregressive coefficient matrices associated with the lagged responses, specified as a cell vector of NumSeries-by-NumSeries numeric matrices.

Specify coefficient signs corresponding to those coefficients in the VAR model expressed in difference-equation notation.

• If you set the Lags name-value pair argument to Lags, then the following conditions apply.

• The lengths of AR and Lags are equal.

• AR{j} is the coefficient matrix of lag Lags(j).

• By default, AR is a numel(Lags)-by-1 cell vector of matrices composed of NaN values.

• Otherwise, the following conditions apply.

• The length of AR is P.

• AR{j} is the coefficient matrix of lag j.

• By default, AR is a P-by-1 cell vector of matrices composed of NaN values.

Example: 'AR',{[0.5 -0.1; 0.1 0.2]}

Data Types: cell

Linear time trend term, specified as a NumSeries-by-1 numeric vector. The default value specifies no linear time trend in the model.

Example: 'Trend',[0.1; 0.2]

Data Types: double

Regression coefficient matrix associated with the predictor variables, specified as a NumSeries-by-NumPreds numeric matrix. NumPreds is the number of predictor variables, that is, the number of columns in the predictor data.

Beta(j,:) contains the regression coefficients for each predictor in the equation of response yj,t. Beta(:,k) contains the regression coefficient in each response equation for predictor xk. By default, all predictor variables are in the regression component of all response equations. You can exclude certain predictors from certain equations by specifying equality constraints to 0.

Example: In a model that includes 3 responses and 4 predictor variables, to exclude the second predictor from the third equation and leave the others unrestricted, specify [NaN NaN NaN NaN; NaN NaN NaN NaN; NaN 0 NaN NaN].

The default value specifies no regression coefficient in the model. However, if you specify predictor data when you estimate the model using estimate, then MATLAB® sets Beta to an appropriately sized matrix of NaN values.

Example: 'Beta',[2 3 -1 2; 0.5 -1 -6 0.1]

Data Types: double

Innovations covariance matrix of the NumSeries innovations at each time t = 1,...,T, specified as a NumSeries-by-NumSeries numeric, positive definite matrix.

Example: 'Covariance',eye(2)

Data Types: double

Model description, specified as a string scalar or character vector. varm stores the value as a string scalar. The default value describes the parametric form of the model, for example "2-Dimensional VAR(3) Model".

Example: 'Description','Model 1'

Data Types: string | char

Response series names, specified as a NumSeries length string vector. The default is ['Y1' 'Y2' ... 'YNumSeries'].

Example: 'SeriesNames',{'CPI' 'Unemployment'}

Data Types: string

### Note

NaN-valued elements in properties indicate unknown, estimable parameters. Specified elements indicate equality constraints on parameters in model estimation. The innovations covariance matrix Covariance cannot contain a mix of NaN values and real numbers; you must fully specify the covariance or it must be completely unknown (NaN(NumSeries)).

## Object Functions

 estimate Fit vector autoregression (VAR) model to data fevd Generate vector autoregression (VAR) model forecast error variance decomposition (FEVD) filter Filter disturbances through vector autoregression (VAR) model forecast Forecast vector autoregression (VAR) model responses gctest Granger causality and block exogeneity tests for vector autoregression (VAR) models infer Infer vector autoregression model (VAR) innovations irf Generate vector autoregression (VAR) model impulse responses simulate Monte Carlo simulation of vector autoregression (VAR) model summarize Display estimation results of vector autoregression (VAR) model vecm Convert vector autoregression (VAR) model to vector error-correction (VEC) model

## Examples

collapse all

Create a zero-degree VAR model composed of one response series.

Mdl = varm
Mdl =
varm with properties:

Description: "1-Dimensional VAR(0) Model"
SeriesNames: "Y"
NumSeries: 1
P: 0
Constant: NaN
AR: {}
Trend: 0
Beta: [1×0 matrix]
Covariance: NaN

Mdl is a varm model object. It contains one response series, an unknown constant, and an unknown innovation variance. Properties of the model appear at the command line.

Suppose your problem has an autoregressive coefficient at lag 1. To create such a model, set the autoregressive coefficient property (AR) to a cell containing a NaN value using dot notation.

Mdl.AR = {NaN}
Mdl =
varm with properties:

Description: "1-Dimensional VAR(1) Model"
SeriesNames: "Y"
NumSeries: 1
P: 1
Constant: NaN
AR: {NaN} at lag [1]
Trend: 0
Beta: [1×0 matrix]
Covariance: NaN

If your problem contains multiple response series, then use a different varm syntax for model creation.

Create a VAR(4) model for the consumer price index (CPI) and unemployment rate.

Load the Data_USEconModel data set. Declare variables for the CPI (CPI) and unemployment rate (UNRATE) series.

cpi = DataTable.CPIAUCSL;
unrate = DataTable.UNRATE;

Create a default VAR(4) model using the shorthand syntax.

Mdl = varm(2,4)
Mdl =
varm with properties:

Description: "2-Dimensional VAR(4) Model"
SeriesNames: "Y1"  "Y2"
NumSeries: 2
P: 4
Constant: [2×1 vector of NaNs]
AR: {2×2 matrices of NaNs} at lags [1 2 3 ... and 1 more]
Trend: [2×1 vector of zeros]
Beta: [2×0 matrix]
Covariance: [2×2 matrix of NaNs]

Mdl is a varm model object. It serves as a template for model estimation. MATLAB® considers any NaN values as unknown parameter values to be estimated. For example, the Constant property is a 2-by-1 vector of NaN values. Therefore, model constants are active model parameters to be estimated.

Include an unknown linear time trend term by setting the Trend property to NaN using dot notation.

Mdl.Trend = NaN
Mdl =
varm with properties:

Description: "2-Dimensional VAR(4) Model with Linear Time Trend"
SeriesNames: "Y1"  "Y2"
NumSeries: 2
P: 4
Constant: [2×1 vector of NaNs]
AR: {2×2 matrices of NaNs} at lags [1 2 3 ... and 1 more]
Trend: [2×1 vector of NaNs]
Beta: [2×0 matrix]
Covariance: [2×2 matrix of NaNs]

MATLAB expands NaN to the appropriate length, that is, a 2-by-1 vector of NaN values.

Create a VAR model for three arbitrary response series. Specify the parameter values in this system of equations.

$\begin{array}{l}{y}_{1,t}=1+0.2{y}_{1,t-1}-0.1{y}_{2,t-1}+0.5{y}_{3,t-1}+1.5t+{\epsilon }_{1,t}\\ {y}_{2,t}=1-0.4{y}_{1,t-1}+0.5{y}_{2,t-1}+2t+{\epsilon }_{2,t}\\ {y}_{3,t}=-0.1{y}_{1,t-1}+0.2{y}_{2,t-1}+0.3{y}_{3,t-1}+{\epsilon }_{3,t}.\end{array}$

Assume the innovations are multivariate Gaussian with a mean of 0 and the covariance matrix

$\Sigma =\left[\begin{array}{ccc}0.1& 0.01& 0.3\\ 0.01& 0.5& 0\\ 0.3& 0& 1\end{array}\right].$

Create variables for the parameter values.

c = [1; 1; 0];
Phi1 = {[0.2 -0.1 0.5; -0.4 0.2 0; -0.1 0.2 0.3]};
delta = [1.5; 2; 0];
Sigma = [0.1 0.01 0.3; 0.01 0.5 0; 0.3 0 1];

Create a VAR(1) model object representing the system of dynamic equations using the appropriate name-value pair arguments.

Mdl = varm('Constant',c,'AR',Phi1,'Trend',delta,'Covariance',Sigma)
Mdl =
varm with properties:

Description: "AR-Stationary 3-Dimensional VAR(1) Model with Linear Time Trend"
SeriesNames: "Y1"  "Y2"  "Y3"
NumSeries: 3
P: 1
Constant: [1 1 0]'
AR: {3×3 matrix} at lag [1]
Trend: [1.5 2 0]'
Beta: [3×0 matrix]
Covariance: [3×3 matrix]

Mdl is a fully specified varm model object. By default, varm attributes the autoregressive coefficient to the first lag.

You can adjust model properties using dot notation. For example, consider another VAR model that attributes the autoregressive coefficient matrix Phi1 to the second lag term, specifies a matrix of zeros for the first lag coefficient, and treats all else as being equal to Mdl. Create this VAR(2) model.

Mdl2 = Mdl;
Phi = [zeros(3,3) Phi1];
Mdl2.AR = Phi
Mdl2 =
varm with properties:

Description: "AR-Stationary 3-Dimensional VAR(2) Model with Linear Time Trend"
SeriesNames: "Y1"  "Y2"  "Y3"
NumSeries: 3
P: 2
Constant: [1 1 0]'
AR: {3×3 matrix} at lag [2]
Trend: [1.5 2 0]'
Beta: [3×0 matrix]
Covariance: [3×3 matrix]

Alternatively, you can create another model object using varm and the same syntax as for Mdl, but additionally specify 'Lags',2.

Fit a VAR(4) model to the consumer price index (CPI) and unemployment rate data.

Plot the two series on separate plots.

figure;
plot(DataTable.Time,DataTable.CPIAUCSL);
title('Consumer Price Index');
ylabel('Index');
xlabel('Date');

figure;
plot(DataTable.Time,DataTable.UNRATE);
title('Unemployment Rate');
ylabel('Percent');
xlabel('Date');

Stabilize the CPI by converting it to a series of growth rates. Synchronize the two series by removing the first observation from the unemployment rate series.

rcpi = price2ret(DataTable.CPIAUCSL);
unrate = DataTable.UNRATE(2:end);

Create a default VAR(4) model using the shorthand syntax.

Mdl = varm(2,4)
Mdl =
varm with properties:

Description: "2-Dimensional VAR(4) Model"
SeriesNames: "Y1"  "Y2"
NumSeries: 2
P: 4
Constant: [2×1 vector of NaNs]
AR: {2×2 matrices of NaNs} at lags [1 2 3 ... and 1 more]
Trend: [2×1 vector of zeros]
Beta: [2×0 matrix]
Covariance: [2×2 matrix of NaNs]

Mdl is a varm model object. All properties containing NaN values correspond to parameters to be estimated given data.

Estimate the model using the entire data set.

EstMdl = estimate(Mdl,[rcpi unrate])
EstMdl =
varm with properties:

Description: "AR-Stationary 2-Dimensional VAR(4) Model"
SeriesNames: "Y1"  "Y2"
NumSeries: 2
P: 4
Constant: [0.00171639 0.316255]'
AR: {2×2 matrices} at lags [1 2 3 ... and 1 more]
Trend: [2×1 vector of zeros]
Beta: [2×0 matrix]
Covariance: [2×2 matrix]

EstMdl is an estimated varm model object. It is fully specified because all parameters have known values. The description indicates that the autoregressive polynomial is stationary.

Display summary statistics from the estimation.

summarize(EstMdl)

AR-Stationary 2-Dimensional VAR(4) Model

Effective Sample Size: 241
Number of Estimated Parameters: 18
LogLikelihood: 811.361
AIC: -1586.72
BIC: -1524

Value       StandardError    TStatistic      PValue
___________    _____________    __________    __________

Constant(1)      0.0017164      0.0015988         1.0735        0.28303
Constant(2)        0.31626       0.091961          3.439      0.0005838
AR{1}(1,1)         0.30899       0.063356          4.877     1.0772e-06
AR{1}(2,1)         -4.4834         3.6441        -1.2303        0.21857
AR{1}(1,2)      -0.0031796      0.0011306        -2.8122       0.004921
AR{1}(2,2)          1.3433       0.065032         20.656      8.546e-95
AR{2}(1,1)         0.22433       0.069631         3.2217      0.0012741
AR{2}(2,1)          7.1896          4.005         1.7951       0.072631
AR{2}(1,2)       0.0012375      0.0018631         0.6642        0.50656
AR{2}(2,2)        -0.26817        0.10716        -2.5025       0.012331
AR{3}(1,1)         0.35333       0.068287         5.1742     2.2887e-07
AR{3}(2,1)           1.487         3.9277        0.37858          0.705
AR{3}(1,2)       0.0028594      0.0018621         1.5355        0.12465
AR{3}(2,2)        -0.22709         0.1071        -2.1202       0.033986
AR{4}(1,1)       -0.047563       0.069026       -0.68906        0.49079
AR{4}(2,1)          8.6379         3.9702         2.1757       0.029579
AR{4}(1,2)     -0.00096323      0.0011142       -0.86448        0.38733
AR{4}(2,2)        0.076725       0.064088         1.1972        0.23123

Innovations Covariance Matrix:
0.0000   -0.0002
-0.0002    0.1167

Innovations Correlation Matrix:
1.0000   -0.0925
-0.0925    1.0000

This example follows from Estimate VAR(4) Model.

Create and estimate a VAR(4) model for the CPI growth rate and unemployment rates. Treat the last ten periods as the forecast horizon.

cpi = DataTable.CPIAUCSL;
unrate = DataTable.UNRATE;

rcpi = price2ret(cpi);
unrate = unrate(2:end);
Y = [rcpi unrate];

Mdl = varm(2,4);
EstMdl = estimate(Mdl,Y(1:(end-10),:));

Forecast 10 responses using the estimated model and in-sample data as presample observations.

YF = forecast(EstMdl,10,Y(1:(end-10),:));

Plot the part of the series with their forecasted values on separate plots.

figure;
plot(DataTable.Time(end - 50:end),rcpi(end - 50:end));
hold on
plot(DataTable.Time((end - 9):end),YF(:,1))
h = gca;
fill(DataTable.Time([end - 9 end end end - 9]),h.YLim([1,1,2,2]),'k',...
'FaceAlpha',0.1,'EdgeColor','none');
legend('True CPI growth rate','Forecasted CPI growth rate',...
'Location','NW')
title('Quarterly CPI Growth Rate: 1947 - 2009');
ylabel('CPI growth rate');
xlabel('Year');
hold off

figure;
plot(DataTable.Time(end - 50:end),unrate(end - 50:end));
hold on
plot(DataTable.Time((end - 9):end),YF(:,2))
h = gca;
fill(DataTable.Time([end - 9 end end end - 9]),h.YLim([1,1,2,2]),'k',...
'FaceAlpha',0.1,'EdgeColor','none');
legend('True unemployment rate','Forecasted unemployment rate',...
'Location','NW')
title('Quarterly Unemployment Rate: 1947 - 2009');
ylabel('Unemployment rate');
xlabel('Year');
hold off

expand all