Econometrics
Toolbox™ VAR model functions require a `varm`

model
object as an input before they simulate, estimate, forecast, or perform
other calculations. `varm`

model objects specify
the structure of the VAR model, that is, the number of response series,
number of lags, whether there are constants or time trends in the
response equations, etc. `varm`

model can serve as
a model template for estimation, or you can specify known values for
some or all parameters either during model creation or after using
dot notation.

By default, `varm`

sets unknown parameter values
to `NaN`

based on its specified structure. `NaN`

values
in model properties indicate that the parameter is present, but the
value is unknown and needs fitting to data. Although, time series
data motivates model creation, it is not required to create a model.
If you have data, you can fit models to the data as described in VAR Model Estimation. If you do not have data,
you can create a fully-specified model, that is, you provide all parameter
values, as described in Model Objects with Known Parameters.

Create an Econometrics
Toolbox VAR model object using `varm`

. Use
this object for estimating, simulating, forecasting, and analyzing
multiple time series.

There are two syntaxes for `varm`

model object creation: shorthand and
longhand. The shorthand syntax is suited for the quick creation of a model that has
all unknown parameters. Using the shorthand syntax, you create a model template for
estimation that specifies the dimension of the response variable
(`numseries`

), the degree of the VAR model
(`p`

), and that the AR polynomial has nonzero lags 1 through
`p`

. After creating a model this way, you can change some
parameter values by adjusting property values using dot notation (see Displaying and Changing Model Objects). For an example, see Create and Adjust VAR Model Using Shorthand Syntax.

The longhand syntax allows for more flexibility in parameter
specification than the shorthand syntax. For example, you can specify
values of autoregressive coefficient matrices or which lags have nonzero
coefficient matrices. Whereas `varm`

requires the
dimensionality of the response variable and degree of the VAR model
when you use the shorthand syntax, `varm`

infers
these structural characteristics from the arguments you supply when
you use the longhand syntax. For an example, see Create and Adjust VAR Model Using Longhand Syntax.

Independent of syntax preference, there are several ways to
create model objects using `varm`

, and they depend
on your analysis goal.

Model Objects with Known Parameters. Use this method when you know the values of all relevant parameters of your model. That is, you do not plan to fit the model to data.

Model Objects with No Parameter Values. Use this method when you know the size, type, and number of lags in your model, but do not know, for example, the values of any of the AR coefficient matrices or the value of the innovations covariance. That is, you know the structure of the VAR model, and you want to fit the model to data using

`estimate`

.Model Objects with Selected Parameter Values. Use this method when you know the size, type, and number of lags in your model, and also know some, but not all, of the parameter values. For example, you know the values of some of the AR coefficient matrices. To estimate any unknown parameter values, you pass the model object and data to

`estimate`

, which applies equality constraints to all known parameters at their values and estimates the rest.

This example shows how to create a three-dimensional VAR(4) model with unknown parameters using `varm`

and the shorthand syntax. Then, this example shows how to adjust parameters of the created model using dot notation.

Create a VAR(4) model for a three-dimensional response series using the shorthand syntax.

numseries = 3; p = 4; Mdl = varm(3,4)

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

`Mdl`

is a `varm`

model object. The properties of the model display at the command line. Observe that:

The default value of some of the parameters are

`NaN`

values, which indicates their presence in the model. In particular, each lag from 1 through 4 has an unknown, nonzero autoregressive coefficient matrix.You created the model without using response data. That is,

`Mdl`

is agnostic about data.

Suppose that you want lags 1 and 4 in the model to be unknown and nonzero, but all other lags are zero. Using dot notation, remove the other lags from the model object by placing 3-by-3 matrices of zeros the corresponding cells.

Mdl.AR{2} = zeros(3); Mdl.AR{3} = zeros(3)

Mdl = varm with properties: Description: "3-Dimensional VAR(4) Model" SeriesNames: "Y1" "Y2" "Y3" NumSeries: 3 P: 4 Constant: [3×1 vector of NaNs] AR: {3×3 matrices} at lags [1 4] Trend: [3×1 vector of zeros] Beta: [3×0 matrix] Covariance: [3×3 matrix of NaNs]

Observe that the model degree `p`

is still `4`

, but there are unknown, nonzero coefficients at lags 1 and 4 only.

This example shows how to create a three-dimensional VAR(4) model with unknown parameters using `varm`

and the longhand syntax. Then, this example shows how to adjust parameters of the created model using dot notation.

Create a VAR(4) model for a three-dimensional response series. Specify that there are unknown coefficient matrices at lags 1 and 4 only.

numseries = 3; p = 4; ar = {nan(3) nan(3)}; lags = [1 p]; Mdl = varm('AR',ar,'Lags',lags)

Mdl = varm with properties: Description: "3-Dimensional VAR(4) Model" SeriesNames: "Y1" "Y2" "Y3" NumSeries: 3 P: 4 Constant: [3×1 vector of NaNs] AR: {3×3 matrices} at lags [1 4] Trend: [3×1 vector of zeros] Beta: [3×0 matrix] Covariance: [3×3 matrix of NaNs]

`Mdl`

is a `varm`

model object. The properties of the model display at the command line. Observe that:

The default value of some of the parameters are

`NaN`

values, which indicates their presence in the model.You created the model without using response data. That is,

`Mdl`

is agnostic about data.

Suppose that you want to add a linear time trend to the model to be estimated. By default, the linear time trend is zero. To make an unknown time trend present in the model, set the `Trend`

property to a 3-by-1 vector of `NaN`

values using dot notation.

Mdl.Trend = nan(3,1)

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

If you know the values of model parameters, create a model object
with the parameter values using longhand syntax. The following are
the name-value pair arguments you can pass to `varm`

for
known parameter values in a `numseries`

-dimensional
VAR(`p`

) model:

**Model Parameters**

Name | Value |
---|---|

`Constant` | A |

`Lags` | A numeric vector of autoregressive polynomial lags. The
largest lag determines |

`AR` | A cell vector of |

`Trend` | A |

`Beta` | A |

`Covariance` | A |

Alternatively, you can create a model object using shorthand
syntax, and then adjust corresponding property values using dot notation
(with the exception of `Lags`

).

The `Lags`

vector allows you to specify which
lags you want to include. For example, to specify AR lags 1 and 3
without lag 2, set `Lag`

to `[1 3]`

.
Although there are only two lags, `p`

is `3`

.

The following example shows how to create a model object when you have known parameters. Consider the VAR(1) model

$${y}_{t}=\left[\begin{array}{c}0.05\\ 0\\ -0.05\end{array}\right]+\left[\begin{array}{ccc}0.5& 0& 0\\ 0.1& 0.1& 0.3\\ 0& 0.2& 0.3\end{array}\right]{y}_{t-1}+{\epsilon}_{t}.$$

The independent disturbances *ε _{t}* are
distributed as standard three-dimensional normal random variables.

Create a model object with `varm`

:

c = [0.05; 0; -0.05]; ar = {[.5 0 0;.1 .1 .3;0 .2 .3]}; Covariance = eye(3); Mdl = varm('Constant',c,'AR',ar,'Covariance',Covariance)

Mdl = varm with properties: Description: "AR-Stationary 3-Dimensional VAR(1) Model" SeriesNames: "Y1" "Y2" "Y3" NumSeries: 3 P: 1 Constant: [0.05 0 -0.05]' AR: {3×3 matrix} at lag [1] Trend: [3×1 vector of zeros] Beta: [3×0 matrix] Covariance: [3×3 diagonal matrix]

`varm`

identifies this model as a stationary
VAR(1) model with three dimensions, additive constants, no time trend,
and no regression component.

By default, `estimate`

fits all unspecified
(that is, elements containing `NaN`

values) model
constants, autoregressive coefficient matrices, regression coefficients,
linear time trends, and the innovation covariance matrix. You must
specify pass a `varm`

model object containing unknown
values and the data to `estimate`

to fit the unknown
parameters.

This example shows how to specify the model in Model Objects with Known Parameters, but without explicit parameters.

Mdl = varm(3,1)

Mdl = varm with properties: Description: "3-Dimensional VAR(1) Model" SeriesNames: "Y1" "Y2" "Y3" NumSeries: 3 P: 1 Constant: [3×1 vector of NaNs] AR: {3×3 matrix of NaNs} at lag [1] Trend: [3×1 vector of zeros] Beta: [3×0 matrix] Covariance: [3×3 matrix of NaNs]

You can create a model object with some known parameters, and
have `estimate`

fit the unknown parameters to data. `estimate`

honors
all equality constraints except for those in the innovation covariance
matrix, that is, the innovations covariance must be completely composed
of `NaN`

values for estimation.

This example shows how to specify the model in Model Objects with Known Parameters, but
with requested AR parameters with a diagonal autoregressive structure
and an unknown innovation covariance. `varm`

infers
the dimensionality of the response variable from the parameters `c`

and `AR`

and
the degree of the VAR model from `AR`

.

c = [.05; 0; -.05]; ar = {diag(nan(3,1))}; Mdl = varm('Constant',c,'AR',ar)

Mdl = varm with properties: Description: "3-Dimensional VAR(1) Model" SeriesNames: "Y1" "Y2" "Y3" NumSeries: 3 P: 1 Constant: [0.05 0 -0.05]' AR: {3×3 matrix} at lag [1] Trend: [3×1 vector of zeros] Beta: [3×0 matrix] Covariance: [3×3 matrix of NaNs]

Mdl.AR{:}

`ans = `*3×3*
NaN 0 0
0 NaN 0
0 0 NaN

After you set up a model object, you can examine it in several ways:

Enter

at the MATLAB`Mdl`

^{®}command line, whereis the name of the model structure.`Mdl`

Double-click the object in the MATLAB Workspace browser.

Enter

at the MATLAB command line, where`Mdl.PropertyName`

is the name of the model object, and`Mdl`

is the name of the property you want to examine or reassign.`PropertyName`

You can change any writable part of a model object named, for
example, * Mdl*, using dot notation as follows:

Mdl.PropertyValue=value;

This syntax changes only the * PropertyValue* parts

`Mdl`

There are two Econometrics Toolbox functions that can help you determine an appropriate number of lags for your models:

`lratiotest`

performs likelihood ratio tests to help identify the appropriate number of lags.`aicbic`

calculates the Akaike and Bayesian information criteria (AIC and BIC, respectively) to determine the minimal appropriate number of required lags.

`lratiotest`

requires inputs
of the loglikelihood of an unrestricted model, the loglikelihood of
a restricted model, and the number of degrees of freedom (DoF). DoF
is the difference in the number of active parameters between the unrestricted
and restricted models. `lratiotest`

returns a Boolean: `1`

means
reject the restricted model in favor of the unrestricted model, `0`

means
there is insufficient evidence to reject the restricted model.

In the context of determining an appropriate number of lags, the restricted model has fewer lags, and the unrestricted model has more lags. Otherwise, test models with the same type of fitted parameters.

Obtain the loglikelihood (

`logL`

) of a model as the third output of`estimate`

:[EstMdl,EstSE,logL,E] = estimate(...)

Obtain the number of active parameters in a model (

`numParameters`

) from the`NumEstimatedParameters`

field in the output structure of`summarize`

:results = summarize(EstMdl); numParameters = results.NumEstimatedParameters;

For example, suppose you have four fitted models with varying
lag structures. The models have loglikelihoods `logL1`

, `logL2`

, `logL3`

,
and `logL4`

, and active parameter counts `n1p`

, `n2p`

, `n3p`

,
and `n4p`

. Suppose model 4 has the largest number
of lags. Perform likelihood ratio tests of models 1, 2, and 3 against
model 4, as follows:

reject1 = lratiotest(logL4,logL1,n4p - n1p) reject2 = lratiotest(logL4,logL2,n4p - n2p) reject3 = lratiotest(logL4,logL3,n4p - n3p)

If `reject1`

= `1`

, you reject
model 1 in favor of model 4, and similarly for models 2 and 3. If
any of the models have `rejectI`

= `0`

,
you have an indication that you can use fewer lags than in model 4.

You can obtain the AIC and BIC fit statistics two ways:

Passing an estimated model to

`summarize`

, and extracting the desired fit statistic from the output structure.Using

`aicbic`

.`aicbic`

requires inputs of the loglikelihood of a model and of the number of active parameters in the model.`aicbic`

also accepts vectors of loglikelihoods and vectors of active parameters, which makes it easy to compare multiple model fits.

Lower values of these information criteria indicate better fits to the data.

Obtain the loglikelihood (

`logL`

) of a model as the third output of`estimate`

:[EstMdl,EstSE,logL,E] = estimate(...)

Obtain the number of active parameters in a model (

`numParameters`

) from the`NumEstimatedParameters`

field in the output structure of`summarize`

:results = summarize(EstMdl); numParameters = results.NumEstimatedParameters;

For example, suppose you have four fitted models with varying
lag structures. The models have loglikelihoods `logL1`

, `logL2`

, `logL3`

,
and `logL4`

, and active parameter counts `n1p`

, `n2p`

, `n3p`

,
and `n4p`

. Calculate the Akaike information criteria
as follows:

AIC = aicbic([logL1 logL2 logL3 logL4],[n1p n2p n3p n4p])

The most suitable model has the lowest value of the Akaike information criterion.