vecm
Create vector errorcorrection (VEC) model
Description
The vecm
function returns a vecm
object specifying the functional form and storing the parameter values of a (p – 1)order, cointegrated, multivariate vector errorcorrection model (VEC((p – 1)) model.
The key components of a vecm
object include the number of time series (responsevariable dimensionality), the number of cointegrating relations among the response variables (cointegrating rank), and the degree of the multivariate autoregressive polynomial composed of first differences of the response series (shortrun polynomial), which is p – 1. That is, p – 1 is the maximum lag with a nonzero coefficient matrix, and p is the order of the vector autoregression (VAR) model representation of the VEC model. Other model components include a regression component to associate the same exogenous predictor variables to each response series, and constant and time trend terms.
Another important component of a VEC model is its Johansen form because it dictates how MATLAB^{®} includes deterministic terms in the model. This specification has implications on the estimation procedure and allowable equality constraints. For more details, see Johansen Form and [2].
Given the responsevariable dimensionality, cointegrating rank, and shortrun
polynomial degree, all coefficient matrices and innovationdistribution parameters are
unknown and estimable unless you specify their values by using namevalue pair argument
syntax. To choose which Johansen form is suitable for your data, then estimate a model
containing all or partially unknown parameter values given the data, use estimate
. To
work with an estimated or fully specified vecm
model object, pass it to
an object function.
Alternatively, you can create and work with vecm
model objects
interactively by using Econometric
Modeler.
Creation
Description
creates a VEC(Mdl
= vecm(numseries
,rank
,numlags
)numlags
) model composed of numseries
time series containing rank
cointegrating relations. The maximum nonzero lag in the shortrun polynomial is numlags
. All lags and the errorcorrection term have numseries
bynumseries
coefficient matrices composed of NaN
values.
This shorthand syntax allows for easy model template creation in which you specify the model dimensions explicitly. The model template is suited for unrestricted parameter estimation, that is, estimation without any parameter equality constraints. After you create a model, you can alter property values using dot notation.
sets properties or additional options using namevalue pair arguments. Enclose each name in quotes. For example, Mdl
= vecm(Name,Value
)'Lags',[1 4],'ShortRun',ShortRun
specifies the two shortrun coefficient matrices in ShortRun
at lags 1
and 4
.
This longhand syntax allows for creating more flexible models. However, vecm
must be able to infer the number of series (NumSeries
) and cointegrating rank (Rank
) from the specified namevalue pair arguments. Namevalue pair arguments and property values that correspond to the number of time series and cointegrating rank must be consistent with each other.
Input Arguments
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 VEC(2) model composed of three response series containing one cointegrating relation and unknown parameter values, enter:
Mdl = vecm(3,1,2);
numseries
— Number of time series m
1
(default)  positive integer
Number of time series m, specified as a positive integer. numseries
specifies the dimensionality of the multivariate response variable y_{t} and innovation ε_{t}.
numseries
sets the NumSeries
property.
Data Types: double
rank
— Number of cointegrating relations
nonnegative integer
Number of cointegrating relations, specified as a nonnegative integer. The adjustment and cointegration matrices in the model have rank
linearly independent columns, and are numseries
byrank
matrices composed of NaN
values.
Data Types: double
numlags
— Number of first differences of responses
nonnegative integer
Number of first differences of responses to include in the shortrun polynomial of the VEC(p – 1) model, specified as a nonnegative integer. That is, numlags
= p – 1. Consequently, numlags
specifies the number of shortrun terms associated with the corresponding VAR(p) model.
All lags have numseries
bynumseries
shortrun coefficient matrices composed of NaN
values.
Data Types: double
Specify optional pairs of arguments as
Name1=Value1,...,NameN=ValueN
, where Name
is
the argument name and Value
is the corresponding value.
Namevalue arguments must appear after other arguments, but the order of the
pairs does not matter.
Before R2021a, use commas to separate each name and value, and enclose
Name
in quotes.
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. Specify enough information for vecm
to infer
the number of response series and the cointegrating rank.
Example: 'Adjustment',nan(3,2),'Lags',[4 8]
specifies a
threedimensional VEC(8) model with two cointegrating relations and nonzero
shortrun coefficient matrices at lags 4
and
8
.
Lags
— Shortrun polynomial lags
1:(P1)
(default)  numeric vector of unique positive integers
Shortrun polynomial lags, specified as the commaseparated pair
consisting of 'Lags'
and a numeric vector
containing at most P
– 1 elements of unique
positive integers.
The matrix
ShortRun{
is the
coefficient of lag
j
}Lags(
.j
)
Example: 'Lags',[1 4]
Data Types: double
Properties
You can set writable property values when you create the model object by using namevalue pair argument syntax, or after you create the model object by using dot notation. For example, to create a VEC(1) model in the H1 Johansen form suitable for simulation, and composed of two response series of cointegrating rank one and no overall time trend term, enter:
Mdl = vecm('Constant',[0; 0.01],'Adjustment',[0.1; 0.15],... 'Cointegration',[1; 4],'ShortRun',{[0.3 0.15 ; 0.1 0.3]},... 'Covariance',eye(2)); Mdl.Trend = 0;
NumSeries
— Number of time series m
positive integer
This property is readonly.
Number of time series m, specified as a positive integer. NumSeries
specifies the dimensionality of the multivariate response variable y_{t} and innovation ε_{t}.
Data Types: double
Rank
— Number of cointegrating relations
nonnegative integer
This property is readonly.
Number of cointegrating relations, specified as a nonnegative integer. The adjustment and cointegration matrices in the model have Rank
linearly independent columns and are NumSeries
byRank
matrices.
Data Types: double
P
— Corresponding VAR model order
nonnegative integer
This property is readonly.
Corresponding VAR model order, specified as a nonnegative integer. P
– 1 is the maximum lag in the shortrun polynomial that has a nonzero coefficient matrix. Lags in the shortrun polynomial that have degree less than P
– 1 can have coefficient matrices composed entirely of zeros.
P
specifies the number of presample observations required to initialize the model.
Data Types: double
Description
— Model description
string scalar  character vector
Model description, specified as a string scalar or character vector. vecm
stores the value as a string scalar. The default value describes the parametric form of the model, for example
"2Dimensional Rank = 1 VEC(1) Model"
.
Example: 'Description','Model 1'
Data Types: string
 char
SeriesNames
— Response series names
string vector  cell array of character vectors
Response series names, specified as a NumSeries
length string vector. The
default is ['Y1' 'Y2' ...
'Y
.NumSeries
']
Example: 'SeriesNames',{'CPI' 'Unemployment'}
Data Types: string
Constant
— Overall model constant
NaN(NumSeries,1)
(default)  numeric vector
Overall model constant (c), specified as a NumSeries
by1 numeric vector.
The value of Constant
, and whether estimate
supports equality constraints on it during estimation, depend on the Johansen form of the VEC model.
Example: 'Constant',[1; 2]
Data Types: double
Trend
— Overall linear time trend
nan(NumSeries,1)
(default)  numeric vector
Overall linear time trend (d), specified as a NumSeries
by1 numeric vector.
The value of Trend
, and whether estimate
supports equality constraints on it during estimation, depend on the Johansen form of the VEC model.
Example: 'Trend',[0.1; 0.2]
Data Types: double
Adjustment
— Cointegration adjustment speeds
NaN(NumSeries,Rank)
(default)  numeric matrix
Cointegration adjustment speeds (A), specified as a NumSeries
byRank
numeric matrix.
If you specify a matrix of known values, then all columns must be linearly independent (that is, Adjustment
must be a matrix of full column rank).
For estimation, you can impose equality constraints on the cointegration adjustment speeds by supplying a matrix composed entirely of numeric values or a mixture of numeric and missing (NaN
) values.
If Rank
= 0
, then Adjustment
is an empty NumSeries
by0
vector.
For more details on specifying Adjustment
, see Algorithms.
Example: 'Adjustment',NaN(2,1)
Data Types: double
Cointegration
— Cointegration matrix
NaN(NumSeries,Rank)
(default)  numeric matrix
Cointegration matrix (B), specified as a NumSeries
byRank
numeric matrix.
If you specify a matrix of known values, then all columns must be linearly independent (that is, Cointegration
must be a matrix of full column rank).
Cointegration
cannot contain a mixture of missing (NaN
) values and numeric values. Supported equality constraints on the cointegration matrix during estimation depend on the Johansen form of the VEC model.
If Rank
= 0
, then Cointegration
is an empty NumSeries
by0
vector.
For more details on specifying Cointegration
, see Algorithms.
Example: 'Cointegration',NaN(2,1)
Data Types: double
Impact
— Impact matrix
numeric matrix
Impact, or longrun level, matrix (Π), specified as a NumSeries
byNumSeries
numeric matrix. The rank of Impact
must be Rank
.
For estimation of fullrank models (Rank
= NumSeries
), you can impose equality constraints on the impact matrix by supplying a matrix containing a mixture of numeric and missing values (NaN
).
If 1
≤ Rank
≤ NumSeries
– 1
, then the default value is Adjustment*Cointegration'
.
If Rank
= 0, then Impact
is a matrix of zeros. Consequently, the model does not have an errorcorrection term.
For more details on specifying Impact
, see Algorithms.
Example: 'Impact',[0.5 0.25 0; 0.3 0.15 0; 0 0 0.9]
Data Types: double
CointegrationConstant
— Constant in cointegrating relations
NaN(Rank,1)
(default)  numeric vector
Constant (intercept) in the cointegrating relations (c_{0}), specified as a Rank
by1
numeric vector. You can set CointegrationConstant
only by using dot notation after you create the model.
CointegrationConstant
cannot contain a mixture of missing (NaN
) values and numeric values. Supported equality constraints on the cointegration constant vector during estimation depend on the Johansen form of the VEC model.
If Rank
= 0
, then CointegrationConstant
is a 0
by1
vector of zeros.
Example: Mdl.CointegrationConstant = [1; 0]
Data Types: double
CointegrationTrend
— Time trend in cointegrating relations
NaN(Rank,1)
(default)  numeric vector
Time trend in the cointegrating relations (d_{0}), specified as a Rank
by1
numeric vector. You can set CointegrationTrend
only by using dot notation after you create the model.
CointegrationTrend
cannot contain a mixture of missing (NaN
) values and numeric values. Supported equality constraints on the cointegration linear trend vector during estimation depend on the Johansen form of the VEC model.
If Rank
= 0, then CointegrationTrend
is a 0
by1
vector of zeros.
Example: Mdl.CointegrationTrend = [0; 0.5]
Data Types: double
ShortRun
— Shortrun coefficient matrices
cell vector of numeric matrices
Shortrun coefficient matrices associated with the lagged response differences, specified as a cell vector of NumSeries
byNumSeries
numeric matrices.
Specify coefficient signs corresponding to those coefficients in the VEC model expressed in differenceequation notation. The property P
is numel(ShortRun) + 1
.
If you set the
'Lags'
namevalue pair argument toLags
, the following conditions apply.The lengths of
ShortRun
andLags
must be equal.ShortRun{
is the coefficient matrix of lagj
}Lags(
.j
)By default,
ShortRun
is anumel(Lags)
by1 cell vector of matrices composed ofNaN
values.
Otherwise, the following conditions apply.
ShortRun{
is the coefficient matrix of lagj
}j
.By default,
ShortRun
is a (P
– 1)by1 cell vector of matrices composed ofNaN
values.
MATLAB assumes that the coefficient of the current, differenced response (Δy_{t}) is the identity matrix. Therefore, exclude this coefficient from ShortRun
.
Example: 'ShortRun',{[0.5 0.1; 0.1 0.2]}
Data Types: cell
Beta
— Regression coefficient matrix
NumSeries
by0 empty matrix (default)  numeric matrix
Regression coefficient matrix associated with the predictor variables, specified as a NumSeries
byNumPreds
numeric matrix. NumPreds
is the number of predictor variables, that is, the number of columns in the predictor data.
Beta(
contains the regression coefficients
for each predictor in the equation of response
y_{j,t}.
j
,:)Beta(:,
contains the regression
coefficient in each response equation for predictor
x_{k}. 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.k
)
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
Covariance
— Innovations covariance matrix
NaN(NumSeries)
(default)  numeric, positive definite matrix
Innovations covariance matrix of the NumSeries
innovations at each time t = 1,...,T, specified as a NumSeries
byNumSeries
numeric, positive definite matrix.
Example: 'Covariance',eye(2)
Data Types: double
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 errorcorrection (VEC) model to data 
fevd  Generate vector errorcorrection (VEC) model forecast error variance decomposition (FEVD) 
filter  Filter disturbances through vector errorcorrection (VEC) model 
forecast  Forecast vector errorcorrection (VEC) model responses 
infer  Infer vector errorcorrection (VEC) model innovations 
irf  Generate vector errorcorrection (VEC) model impulse responses 
simulate  Monte Carlo simulation of vector errorcorrection (VEC) model 
summarize  Display estimation results of vector errorcorrection (VEC) model 
varm  Convert vector errorcorrection (VEC) model to vector autoregression (VAR) model 
Examples
Prepare VEC Model Template for Parameter Estimation
Suppose that a VEC model with cointegrating rank of 4 and a shortrun polynomial of degree 2 is appropriate for modeling the behavior of seven hypothetical macroeconometric time series.
Create a VEC(7,4,2) model using the shorthand syntax.
Mdl = vecm(7,4,2)
Mdl = vecm with properties: Description: "7Dimensional Rank = 4 VEC(2) Model with Linear Time Trend" SeriesNames: "Y1" "Y2" "Y3" ... and 4 more NumSeries: 7 Rank: 4 P: 3 Constant: [7×1 vector of NaNs] Adjustment: [7×4 matrix of NaNs] Cointegration: [7×4 matrix of NaNs] Impact: [7×7 matrix of NaNs] CointegrationConstant: [4×1 vector of NaNs] CointegrationTrend: [4×1 vector of NaNs] ShortRun: {7×7 matrices of NaNs} at lags [1 2] Trend: [7×1 vector of NaNs] Beta: [7×0 matrix] Covariance: [7×7 matrix of NaNs]
Mdl
is a vecm
model object that serves as a template for parameter estimation. MATLAB® considers the NaN
values as unknown parameter values to be estimated. For example, the Adjustment
property is a 7by4 matrix of NaN
values. Therefore, the adjustment speeds are active model parameters to be estimated.
By default, MATLAB® includes overall and cointegrating linear time trend terms in the model. You can create a VEC model in H1 Johansen form by removing the time trend terms, that is, by setting the Trend
property to 0
using dot notation.
Mdl.Trend = 0
Mdl = vecm with properties: Description: "7Dimensional Rank = 4 VEC(2) Model" SeriesNames: "Y1" "Y2" "Y3" ... and 4 more NumSeries: 7 Rank: 4 P: 3 Constant: [7×1 vector of NaNs] Adjustment: [7×4 matrix of NaNs] Cointegration: [7×4 matrix of NaNs] Impact: [7×7 matrix of NaNs] CointegrationConstant: [4×1 vector of NaNs] CointegrationTrend: [4×1 vector of NaNs] ShortRun: {7×7 matrices of NaNs} at lags [1 2] Trend: [7×1 vector of zeros] Beta: [7×0 matrix] Covariance: [7×7 matrix of NaNs]
MATLAB® expands Trend
to the appropriate length, a 7by1 vector of zeros.
Specify All Parameter Values of VEC Model
Consider this VEC(1) model for three hypothetical response series.
$$\begin{array}{rcl}\Delta {y}_{t}& =& c+A{B}^{\prime}{y}_{t1}+{\Phi}_{1}\Delta {y}_{t1}+{\epsilon}_{t}\\ & & \\ & =& \left[\begin{array}{c}1\\ 3\\ 30\end{array}\right]+\left[\begin{array}{cc}0.3& 0.3\\ 0.2& 0.1\\ 1& 0\end{array}\right]\left[\begin{array}{ccc}0.1& 0.2& 0.2\\ 0.7& 0.5& 0.2\end{array}\right]{y}_{t1}+\left[\begin{array}{ccc}0& 0.1& 0.2\\ 0.2& 0.2& 0\\ 0.7& 0.2& 0.3\end{array}\right]\Delta {y}_{t1}+{\epsilon}_{t}.\end{array}$$
The innovations are multivariate Gaussian with a mean of 0 and the covariance matrix
$$\Sigma =\left[\begin{array}{ccc}1.3& 0.4& 1.6\\ 0.4& 0.6& 0.7\\ 1.6& 0.7& 5\end{array}\right].$$
Create variables for the parameter values.
Adjustment = [0.3 0.3; 0.2 0.1; 1 0]; Cointegration = [0.1 0.7; 0.2 0.5; 0.2 0.2]; ShortRun = {[0. 0.1 0.2; 0.2 0.2 0; 0.7 0.2 0.3]}; Constant = [1; 3; 30]; Trend = [0; 0; 0]; Covariance = [1.3 0.4 1.6; 0.4 0.6 0.7; 1.6 0.7 5];
Create a vecm
model object representing the VEC(1) model using the appropriate namevalue pair arguments.
Mdl = vecm('Adjustment',Adjustment,'Cointegration',Cointegration,... 'Constant',Constant,'ShortRun',ShortRun,'Trend',Trend,... 'Covariance',Covariance)
Mdl = vecm with properties: Description: "3Dimensional Rank = 2 VEC(1) Model" SeriesNames: "Y1" "Y2" "Y3" NumSeries: 3 Rank: 2 P: 2 Constant: [1 3 30]' Adjustment: [3×2 matrix] Cointegration: [3×2 matrix] Impact: [3×3 matrix] CointegrationConstant: [2×1 vector of NaNs] CointegrationTrend: [2×1 vector of NaNs] ShortRun: {3×3 matrix} at lag [1] Trend: [3×1 vector of zeros] Beta: [3×0 matrix] Covariance: [3×3 matrix]
Mdl
is, effectively, a fully specified vecm
model object. That is, the cointegration constant and linear trend are unknown. However, they are not needed for simulating observations or forecasting, given that the overall constant and trend parameters are known.
By default, vecm
attributes the shortrun coefficient to the first lag in the shortrun polynomial. Consider another VEC model that attributes the shortrun coefficient matrix ShortRun
to the fourth lag term, specifies a matrix of zeros for the first lag coefficient, and treats all else as being equal to Mdl
. Create this VEC(4) model.
Mdl.ShortRun(4) = ShortRun; Mdl.ShortRun(1) = {0}
Mdl = vecm with properties: Description: "3Dimensional Rank = 2 VEC(4) Model" SeriesNames: "Y1" "Y2" "Y3" NumSeries: 3 Rank: 2 P: 5 Constant: [1 3 30]' Adjustment: [3×2 matrix] Cointegration: [3×2 matrix] Impact: [3×3 matrix] CointegrationConstant: [2×1 vector of NaNs] CointegrationTrend: [2×1 vector of NaNs] ShortRun: {3×3 matrix} at lag [4] Trend: [3×1 vector of zeros] Beta: [3×0 matrix] Covariance: [3×3 matrix]
Alternatively, you can create another model object using vecm
and the same syntax as for Mdl
, but additionally specify 'Lags',4
.
Fit VEC(1) Model to Matrix of Response Data
Fit a VEC(1) model to seven macroeconomic series. Supply the response data as a numeric matrix.
Consider a VEC model for the following macroeconomic series:
Gross domestic product (GDP)
GDP implicit price deflator
Paid compensation of employees
Nonfarm business sector hours of all persons
Effective federal funds rate
Personal consumption expenditures
Gross private domestic investment
Suppose that a cointegrating rank of 4 and one shortrun term are appropriate, that is, consider a VEC(1) model.
Load the Data_USEconVECModel
data set.
load Data_USEconVECModel
For more information on the data set and variables, enter Description
at the command line.
Determine whether the data needs to be preprocessed by plotting the series on separate plots.
figure tiledlayout(2,2) nexttile plot(FRED.Time,FRED.GDP); title("Gross Domestic Product"); ylabel("Index"); xlabel("Date"); nexttile plot(FRED.Time,FRED.GDPDEF); title("GDP Deflator"); ylabel("Index"); xlabel("Date"); nexttile plot(FRED.Time,FRED.COE); title("Paid Compensation of Employees"); ylabel("Billions of $"); xlabel("Date"); nexttile plot(FRED.Time,FRED.HOANBS); title("Nonfarm Business Sector Hours"); ylabel("Index"); xlabel("Date");
figure tiledlayout(2,2) nexttile plot(FRED.Time,FRED.FEDFUNDS) title("Federal Funds Rate") ylabel("Percent") xlabel("Date") nexttile plot(FRED.Time,FRED.PCEC) title("Consumption Expenditures") ylabel("Billions of $") xlabel("Date") nexttile plot(FRED.Time,FRED.GPDI) title("Gross Private Domestic Investment") ylabel("Billions of $") xlabel("Date")
Stabilize all series, except the federal funds rate, by applying the log transform. Scale the resulting series by 100 so that all series are on the same scale.
FRED.GDP = 100*log(FRED.GDP); FRED.GDPDEF = 100*log(FRED.GDPDEF); FRED.COE = 100*log(FRED.COE); FRED.HOANBS = 100*log(FRED.HOANBS); FRED.PCEC = 100*log(FRED.PCEC); FRED.GPDI = 100*log(FRED.GPDI);
Create a VEC(1) model using the shorthand syntax. Specify the variable names.
Mdl = vecm(7,4,1); Mdl.SeriesNames = FRED.Properties.VariableNames
Mdl = vecm with properties: Description: "7Dimensional Rank = 4 VEC(1) Model with Linear Time Trend" SeriesNames: "GDP" "GDPDEF" "COE" ... and 4 more NumSeries: 7 Rank: 4 P: 2 Constant: [7×1 vector of NaNs] Adjustment: [7×4 matrix of NaNs] Cointegration: [7×4 matrix of NaNs] Impact: [7×7 matrix of NaNs] CointegrationConstant: [4×1 vector of NaNs] CointegrationTrend: [4×1 vector of NaNs] ShortRun: {7×7 matrix of NaNs} at lag [1] Trend: [7×1 vector of NaNs] Beta: [7×0 matrix] Covariance: [7×7 matrix of NaNs]
Mdl
is a vecm
model object. All properties containing NaN
values correspond to parameters to be estimated given data.
Estimate the model using the entire data set and the default options.
EstMdl = estimate(Mdl,FRED.Variables)
EstMdl = vecm with properties: Description: "7Dimensional Rank = 4 VEC(1) Model" SeriesNames: "GDP" "GDPDEF" "COE" ... and 4 more NumSeries: 7 Rank: 4 P: 2 Constant: [14.1329 8.77841 7.20359 ... and 4 more]' Adjustment: [7×4 matrix] Cointegration: [7×4 matrix] Impact: [7×7 matrix] CointegrationConstant: [28.6082 109.555 77.0912 ... and 1 more]' CointegrationTrend: [4×1 vector of zeros] ShortRun: {7×7 matrix} at lag [1] Trend: [7×1 vector of zeros] Beta: [7×0 matrix] Covariance: [7×7 matrix]
EstMdl
is an estimated vecm
model object. It is fully specified because all parameters have known values. By default, estimate
imposes the constraints of the H1 Johansen VEC model form by removing the cointegrating trend and linear trend terms from the model. Parameter exclusion from estimation is equivalent to imposing equality constraints to zero.
Display a short summary from the estimation.
results = summarize(EstMdl)
results = struct with fields:
Description: "7Dimensional Rank = 4 VEC(1) Model"
Model: "H1"
SampleSize: 238
NumEstimatedParameters: 112
LogLikelihood: 1.4939e+03
AIC: 3.2118e+03
BIC: 3.6007e+03
Table: [133x4 table]
Covariance: [7x7 double]
Correlation: [7x7 double]
The Table
field of results
is a table of parameter estimates and corresponding statistics.
Forecast Responses from VEC Model
This example follows from Fit VEC(1) Model to Matrix of Response Data.
Create and estimate the VEC(1) model. Treat the last ten periods as the forecast horizon.
load Data_USEconVECModel
FRED.GDP = 100*log(FRED.GDP);
FRED.GDPDEF = 100*log(FRED.GDPDEF);
FRED.COE = 100*log(FRED.COE);
FRED.HOANBS = 100*log(FRED.HOANBS);
FRED.PCEC = 100*log(FRED.PCEC);
FRED.GPDI = 100*log(FRED.GPDI);
Mdl = vecm(7,4,1)
Mdl = vecm with properties: Description: "7Dimensional Rank = 4 VEC(1) Model with Linear Time Trend" SeriesNames: "Y1" "Y2" "Y3" ... and 4 more NumSeries: 7 Rank: 4 P: 2 Constant: [7×1 vector of NaNs] Adjustment: [7×4 matrix of NaNs] Cointegration: [7×4 matrix of NaNs] Impact: [7×7 matrix of NaNs] CointegrationConstant: [4×1 vector of NaNs] CointegrationTrend: [4×1 vector of NaNs] ShortRun: {7×7 matrix of NaNs} at lag [1] Trend: [7×1 vector of NaNs] Beta: [7×0 matrix] Covariance: [7×7 matrix of NaNs]
Y = FRED{1:(end  10),:}; EstMdl = estimate(Mdl,Y)
EstMdl = vecm with properties: Description: "7Dimensional Rank = 4 VEC(1) Model" SeriesNames: "Y1" "Y2" "Y3" ... and 4 more NumSeries: 7 Rank: 4 P: 2 Constant: [14.5023 8.46791 7.08266 ... and 4 more]' Adjustment: [7×4 matrix] Cointegration: [7×4 matrix] Impact: [7×7 matrix] CointegrationConstant: [32.8433 101.126 84.2373 ... and 1 more]' CointegrationTrend: [4×1 vector of zeros] ShortRun: {7×7 matrix} at lag [1] Trend: [7×1 vector of zeros] Beta: [7×0 matrix] Covariance: [7×7 matrix]
Forecast 10 responses using the estimated model and insample data as presample observations.
YF = forecast(EstMdl,10,Y);
On separate plots, plot part of the GDP
and GPDI
series with their forecasted values.
figure; plot(FRED.Time(end  50:end),FRED.GDP(end  50:end)); hold on plot(FRED.Time((end  9):end),YF(:,1)) h = gca; fill(FRED.Time([end  9 end end end  9]),h.YLim([1,1,2,2]),'k',... 'FaceAlpha',0.1,'EdgeColor','none'); legend('True','Forecasted','Location','NW') title('Quarterly Scaled GDP: 2004  2016'); ylabel('Billions of $ (scaled)'); xlabel('Year'); hold off
figure; plot(FRED.Time(end  50:end),FRED.GPDI(end  50:end)); hold on plot(FRED.Time((end  9):end),YF(:,7)) h = gca; fill(FRED.Time([end  9 end end end  9]),h.YLim([1,1,2,2]),'k',... 'FaceAlpha',0.1,'EdgeColor','none'); legend('True','Forecasted','Location','NW') title('Quarterly Scaled GPDI: 2004  2016'); ylabel('Billions of $ (scaled)'); xlabel('Year'); hold off
More About
Vector ErrorCorrection Model
A vector errorcorrection (VEC) model is a
multivariate, stochastic time series model consisting of a system of m =
numseries
equations of m distinct, differenced
response variables. Equations in the system can include an errorcorrection
term, which is a linear function of the responses in levels used to
stabilize the system. The cointegrating rank
r is the number of cointegrating relations that
exist in the system.
Each response equation can include an autoregressive polynomial composed of first differences of the response series (shortrun polynomial of degree p – 1), a constant, a time trend, exogenous predictor variables, and a constant and time trend in the errorcorrection term.
A VEC(p – 1) model in differenceequation notation and in reduced form can be expressed in two ways:
This equation is the component form of a VEC model, where the cointegration adjustment speeds and cointegration matrix are explicit, whereas the impact matrix is implied.
$$\begin{array}{c}\Delta {y}_{t}=A\left(B\prime {y}_{t1}+{c}_{0}+{d}_{0}t\right)+{c}_{1}+{d}_{1}t+{\Phi}_{1}\Delta {y}_{t1}+\mathrm{...}+{\Phi}_{p1}\Delta {y}_{t(p1)}+\beta {x}_{t}+{\epsilon}_{t}\\ =c+dt+AB\prime {y}_{t1}+{\Phi}_{1}\Delta {y}_{t1}+\mathrm{...}+{\Phi}_{p1}\Delta {y}_{t(p1)}+\beta {x}_{t}+{\epsilon}_{t}.\end{array}$$
The cointegrating relations are B'y_{t – 1} + c_{0} + d_{0}t and the errorcorrection term is A(B'y_{t – 1} + c_{0} + d_{0}t).
This equation is the impact form of a VEC model, where the impact matrix is explicit, whereas the cointegration adjustment speeds and cointegration matrix are implied.
$$\begin{array}{c}\Delta {y}_{t}=\Pi {y}_{t1}+A\left({c}_{0}+{d}_{0}t\right)+{c}_{1}+{d}_{1}t+{\Phi}_{1}\Delta {y}_{t1}+\mathrm{...}+{\Phi}_{p1}\Delta {y}_{t(p1)}+\beta {x}_{t}+{\epsilon}_{t}\\ =c+dt+\Pi {y}_{t1}+{\Phi}_{1}\Delta {y}_{t1}+\mathrm{...}+{\Phi}_{p1}\Delta {y}_{t(p1)}+\beta {x}_{t}+{\epsilon}_{t}.\end{array}$$
In the equations:
y_{t} is an mby1 vector of values corresponding to m response variables at time t, where t = 1,...,T.
Δy_{t} = y_{t} – y_{t – 1}. The structural coefficient is the identity matrix.
r is the number of cointegrating relations and, in general, 0 < r < m.
A is an mbyr matrix of adjustment speeds.
B is an mbyr cointegration matrix.
Π is an mbym impact matrix with a rank of r.
c_{0} is an rby1 vector of constants (intercepts) in the cointegrating relations.
d_{0} is an rby1 vector of linear time trends in the cointegrating relations.
c_{1} is an mby1 vector of constants (deterministic linear trends in y_{t}).
d_{1} is an mby1 vector of linear timetrend values (deterministic quadratic trends in y_{t}).
c = Ac_{0} + c_{1} and is the overall constant.
d = Ad_{0} + d_{1} and is the overall timetrend coefficient.
Φ_{j} is an mbym matrix of shortrun coefficients, where j = 1,...,p – 1 and Φ_{p – 1} is not a matrix containing only zeros.
x_{t} is a kby1 vector of values corresponding to k exogenous predictor variables.
β is an mbyk matrix of regression coefficients.
ε_{t} is an mby1 vector of random Gaussian innovations, each with a mean of 0 and collectively an mbym covariance matrix Σ. For t ≠ s, ε_{t} and ε_{s} are independent.
Condensed and in lag operator notation, the system is
$$\begin{array}{c}\Phi (L)(1L){y}_{t}=A\left(B\prime {y}_{t1}+{c}_{0}+{d}_{0}t\right)+{c}_{1}+{d}_{1}t+\beta {x}_{t}+{\epsilon}_{t}\\ =c+dt+AB\prime {y}_{t1}+\beta {x}_{t}+{\epsilon}_{t}\end{array}$$
where $$\Phi (L)=I{\Phi}_{1}{\Phi}_{2}\mathrm{...}{\Phi}_{p1}$$, I is the mbym identity matrix, and Ly_{t} = y_{t – 1}.
If m = r, then the VEC model is a stable VAR(p) model in the levels of the responses. If r = 0, then the errorcorrection term is a matrix of zeros, and the VEC(p – 1) model is a stable VAR(p – 1) model in the first differences of the responses.
Johansen Form
The Johansen forms of a VEC Model differ with respect to the presence of deterministic terms. As detailed in [2], the estimation procedure differs among the forms. Consequently, allowable equality constraints on the deterministic terms during estimation differ among forms. For more details, see The Role of Deterministic Terms.
This table describes the five Johansen forms and supported equality constraints.
Form  ErrorCorrection Term  Deterministic Coefficients  Equality Constraints 

H2  AB´y_{t − 1}  c = 0 (Constant). d = 0 (Trend). c_{0} = 0 (CointegrationConstant). d_{0} = 0 (CointegrationTrend).  You can fully specify B. All deterministic coefficients are zero. 
H1*  A(B´y_{t−1}+c_{0})  c = Ac_{0}. d = 0. d_{0} = 0.  If you fully specify either B or c_{0}, then you must fully specify the other. MATLAB derives the value of c from c_{0} and A. All deterministic trends are zero. 
H1  A(B´y_{t−1} + c_{0}) + c_{1}  c = Ac_{0} + c_{1}. d = 0. d_{0} = 0.  You can fully specify B. You can specify a mixture of MATLAB derives the value of c_{0} from c and A. All deterministic trends are zero. 
H*  A(B´y_{t−1} + c_{0} + d_{0}t) + c_{1}  c = Ac_{0} + c_{1}. d = Ad_{0}.  If you fully specify either B or d_{0}, then you must fully specify the other. You can specify a mixture of MATLAB derives the value of c_{0} from c and A. MATLAB derives the value of d from A and d_{0}. 
H  A(B´y_{t−1}+c_{0}+d_{0}t)+c_{1}+d_{1}t  c = Ac_{0} + c_{1}. d = A.d_{0} + d_{1}.  You can fully specify B. You can specify a mixture of MATLAB derives the values of c_{0} and d_{0} from c, d, and A. 
Algorithms
VEC Model Forms
VEC models can take one of two forms: component form or impact form.
If you create a
vecm
model object using the shorthand syntax, and then assign a value to at least one of these properties–Adjustment
,Cointegration
,CointegrationConstant
, orCointegrationTrend
–before assigning a value to theImpact
property, then the model takes the component form.If you create a
vecm
model object using the longhand syntax by assigning a value to either theAdjustment
orCointegration
property (or both), but leave theImpact
property unspecified, then the model the component form.If
1
≤Rank
≤NumSeries
–1
, as is the case for most VEC model analyses, then it can be more convenient to work with the model in component form rather than impact form.The Impact property is readonly and depends on the values of the
Cointegration
andAdjustment
properties. Specifically,Impact
=Adjustment*Cointegration'
.During estimation, MATLAB fits the VEC model to the data in two steps. First, it estimates the cointegrating relations. Second, it constructs a VARX model from the differenced responses and shortrun polynomial, includes an exogenous term for the estimated cointegrating relations, and then fits the VARX model to the differenced response data.
If you create a
vecm
model object using the shorthand syntax, and then assign a value to theImpact
property before assigning a value to any of these properties–Adjustment
,Cointegration
,CointegrationConstant
, orCointegrationTrend
–then the model takes the impact form.If you create a
vecm
model object using the longhand syntax by assigning a value to theImpact
property, but leave either theAdjustment
orCointegration
property (or both) unspecified, then the model takes the impact form.If the value of the Impact property is a fullrank matrix (
Rank
=NumSeries
), then it can be more convenient to work with the model in impact form rather than component form. The corresponding VEC model has no unit roots. Therefore, the model is a stable VAR(P
) model. Because each individual response variable is stable, any linear combination of response variables is also stable.Because matrix factorizations are not necessarily unique, the values of the
Cointegration
andAdjustment
properties are unknown. Therefore, after you pass thevecm
model object toestimate
, MATLAB sets theCointegration
property to theNumSeries
byNumSeries
identity matrix and theAdjustment
property to the value ofImpact
in the estimatedvecm
model object.The
Cointegration
andAdjustment
properties are readonly and depend on the value ofImpact
.During estimation, MATLAB fits the model in one step: it fits the equivalent VARX(
P
) model to the differenced responses and includes y_{t – 1} as exogenous predictors in the regression component.
When using the longhand syntax to create a
vecm
model object, if you assign a value to theImpact
property and either theAdjustment
orCointegration
property (or both) simultaneously, then MATLAB uses the cointegration rankRank
to determine the form of thevecm
model object. Specifically, if 1 ≤Rank
≤NumSeries
–1
, then the model object is in component form. Otherwise, the model object is in impact form.If the model is fully specified, then the form of the
vecm
model object is irrelevant.
Deterministic Parameters
MATLAB does not store c_{1} and δ_{1}, but you can compute them using Adjustment, Constant, CointegrationConstant, Trend, CointegrationTrend, and the corresponding Johansen form of the VEC model.
References
[1] Hamilton, James D. Time Series Analysis. Princeton, NJ: Princeton University Press, 1994.
[2] Johansen, S. LikelihoodBased Inference in Cointegrated Vector Autoregressive Models. Oxford: Oxford University Press, 1995.
[3] Juselius, K. The Cointegrated VAR Model. Oxford: Oxford University Press, 2006.
[4] Lütkepohl, H. New Introduction to Multiple Time Series Analysis. Berlin: Springer, 2005.
Version History
Introduced in R2017bR2022b: Table and Timetable Support: Vector autoregression (VAR) and vector errorcorrection (VEC) model functions accept input data in tables and timetables, and return results in tables and timetables
In addition to accepting input data (insample and presample data) in numeric
arrays, the functions of VAR and VEC models, represented by varm
and vecm
objects, listed in the table accept input data in tables or
regular timetables. When you supply data in a table or timetable, the following
conditions apply:
The functions choose the default series on which to operate, but you can use the specified namevalue argument to select variables.
The functions return results and selected options in a table or timetable.
Function  NameValue Arguments for Variable Specification 

estimate (varm ) and estimate (vecm ) 

fevd (varm ) and fevd (vecm ) 

filter (varm ) and filter (vecm ) 

forecast (varm ) and forecast (vecm ) 

infer (varm ) and infer (vecm ) 

irf (varm ) and irf (vecm ) 

simulate (varm ) and simulate (vecm ) 

See Also
Apps
Objects
Functions
Open Example
You have a modified version of this example. Do you want to open this example with your edits?
MATLAB Command
You clicked a link that corresponds to this MATLAB command:
Run the command by entering it in the MATLAB Command Window. Web browsers do not support MATLAB commands.
Select a Web Site
Choose a web site to get translated content where available and see local events and offers. Based on your location, we recommend that you select: .
You can also select a web site from the following list:
How to Get Best Site Performance
Select the China site (in Chinese or English) for best site performance. Other MathWorks country sites are not optimized for visits from your location.
Americas
 América Latina (Español)
 Canada (English)
 United States (English)
Europe
 Belgium (English)
 Denmark (English)
 Deutschland (Deutsch)
 España (Español)
 Finland (English)
 France (Français)
 Ireland (English)
 Italia (Italiano)
 Luxembourg (English)
 Netherlands (English)
 Norway (English)
 Österreich (Deutsch)
 Portugal (English)
 Sweden (English)
 Switzerland
 United Kingdom (English)