Documentation

estimate

Fit vector autoregression (VAR) model to data

Description

example

EstMdl = estimate(Mdl,Y) returns a fully specified VAR(p) model. This model stores the estimated parameter values resulting from fitting the VAR(p) model Mdl to the observed multivariate response series Y using maximum likelihood.

example

EstMdl = estimate(Mdl,Y,Name,Value) uses additional options specified by one or more name-value pair arguments. For example, you can specify presample responses or exogenous predictor data.

example

[EstMdl,EstSE] = estimate(___) returns the estimated, asymptotic standard errors of the estimated parameters using any of the input arguments in the previous syntaxes.

example

[EstMdl,EstSE,logL,E] = estimate(___) returns the optimized loglikelihood objective function value (logL) and the multivariate residuals (E).

Examples

collapse all

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

Load the Data_USEconModel data set.

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

Fit a VAR(4) model to the consumer price index (CPI) and unemployment rate data. The estimation sample starts at Q1 of 1980.

Load the Data_USEconModel data set.

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);

Identify the index corresponding to the start of the estimation sample.

estIdx = DataTable.Time(2:end) > '1979-12-31';

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

Mdl = varm(2,4);

Estimate the model using the estimation sample. Specify all observations before the estimation sample as presample data. Display a full estimation summary.

Y0 = [rcpi(~estIdx) unrate(~estIdx)];
EstMdl = estimate(Mdl,[rcpi(estIdx) unrate(estIdx)],'Y0',Y0,'Display',"full");

AR-Stationary 2-Dimensional VAR(4) Model

Effective Sample Size: 117
Number of Estimated Parameters: 18
LogLikelihood: 419.837
AIC: -803.674
BIC: -753.955

Value       StandardError    TStatistic      PValue
__________    _____________    __________    __________

Constant(1)      0.003564      0.0024697         1.4431        0.14898
Constant(2)       0.29922        0.11882         2.5182       0.011795
AR{1}(1,1)       0.022379       0.092458        0.24204        0.80875
AR{1}(2,1)        -2.6318         4.4484       -0.59163         0.5541
AR{1}(1,2)     -0.0082357      0.0020373        -4.0425     5.2884e-05
AR{1}(2,2)         1.2567        0.09802          12.82     1.2601e-37
AR{2}(1,1)        0.20954        0.10182         2.0581       0.039584
AR{2}(2,1)         10.106         4.8987          2.063       0.039117
AR{2}(1,2)      0.0058667       0.003194         1.8368       0.066236
AR{2}(2,2)       -0.14226        0.15367       -0.92571        0.35459
AR{3}(1,1)        0.56095       0.098691         5.6839     1.3167e-08
AR{3}(2,1)        0.44406         4.7483       0.093518        0.92549
AR{3}(1,2)      0.0049062       0.003227         1.5204        0.12841
AR{3}(2,2)      -0.040037        0.15526       -0.25787         0.7965
AR{4}(1,1)       0.046125        0.11163        0.41321        0.67945
AR{4}(2,1)          6.758         5.3707         1.2583        0.20827
AR{4}(1,2)     -0.0030032       0.002018        -1.4882         0.1367
AR{4}(2,2)       -0.14412       0.097094        -1.4843        0.13773

Innovations Covariance Matrix:
0.0000   -0.0003
-0.0003    0.0790

Innovations Correlation Matrix:
1.0000   -0.1686
-0.1686    1.0000

Because the VAR model degree p is 4, estimate uses only the last four observations in Y0 as a presample.

Estimate a VAR(4) model of consumer price index (CPI), the unemployment rate, and real gross domestic product (GDP). Include a linear regression component containing the current quarter and the last four quarters of government consumption expenditures and investment (GCE).

Load the Data_USEconModel data set. Compute the real GDP.

DataTable.RGDP = DataTable.GDP./DataTable.GDPDEF*100;

Plot all variables on separate plots.

figure;
subplot(2,2,1)
plot(DataTable.Time,DataTable.CPIAUCSL);
ylabel('Index');
title('Consumer Price Index');
subplot(2,2,2)
plot(DataTable.Time,DataTable.UNRATE);
ylabel('Percent');
title('Unemployment Rate');
subplot(2,2,3)
plot(DataTable.Time,DataTable.RGDP);
ylabel('Output');
title('Real Gross Domestic Product')
subplot(2,2,4)
plot(DataTable.Time,DataTable.GCE);
ylabel('Billions of \$');
title('Government Expenditures') Stabilize the CPI, GDP, and GCE series by converting each to a series of growth rates. Synchronize the unemployment rate series with the others by removing its first observation.

inputVariables = {'CPIAUCSL' 'RGDP' 'GCE'};
Data = varfun(@price2ret,DataTable,'InputVariables',inputVariables);
Data.Properties.VariableNames = inputVariables;
Data.UNRATE = DataTable.UNRATE(2:end);

Expand the GCE rate series to a matrix that includes its current value and up through four lagged values. Remove the GCE variable from Data.

rgcelag4 = lagmatrix(Data.GCE,0:4);
Data.GCE = [];

Create a default VAR(4) model using the shorthand syntax. You do not have to specify the regression component when creating the model.

Mdl = varm(3,4);

Estimate the model using the entire sample. Specify the GCE rate matrix as data for the regression component. Extract standard errors and the loglikelihood value.

[EstMdl,EstSE,logL] = estimate(Mdl,Data.Variables,'X',rgcelag4);

Display the regression coefficient matrix.

EstMdl.Beta
ans = 3×5

0.0777   -0.0892   -0.0685   -0.0181    0.0330
0.1450   -0.0304    0.0579   -0.0559    0.0185
-2.8138   -0.1636    0.3905    1.1799   -2.3328

EstMdl.Beta is a 3-by-5 matrix. Rows correspond to response series, and columns correspond to predictors.

Display the matrix of standard errors corresponding to the coefficient estimates.

EstSE.Beta
ans = 3×5

0.0250    0.0272    0.0275    0.0274    0.0243
0.0368    0.0401    0.0405    0.0403    0.0358
1.4552    1.5841    1.6028    1.5918    1.4145

EstSE.Beta is commensurate with EstMdl.Beta.

Display the loglikelihood value.

logL
logL = 1.7056e+03

Input Arguments

collapse all

VAR model containing unknown parameter values, specified as a varm model object returned by varm.

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

Observed multivariate response series to which estimate fits the model, specified as a numobs-by-numseries numeric matrix.

numobs is the sample size. numseries is the number of response variables (Mdl.NumSeries).

Rows correspond to observations, and the last row contains the latest observation.

Columns correspond to individual response variables.

Y represents the continuation of the presample response series in Y0.

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.

Example: 'Y0',Y0,'X',X uses the matrix Y0 as presample responses required for estimation and includes a linear regression component composed of the predictor data in X.

Presample responses to initiate the model estimation, specified as the comma-separated pair consisting of 'Y0' and a numpreobs-by-numseries numeric matrix.

numpreobs is the number of presample observations.

Rows correspond to presample observations, and the last row contains the latest observation. Y0 must have at least Mdl.P rows. If you supply more rows than necessary, estimate uses the latest Mdl.P observations only.

Columns must correspond to the response series in Y.

By default, estimate uses Y(1:Mdl.P,:) as presample observations, and then fits the model to Y((Mdl.P + 1):end,:). This action reduces the effective sample size.

Data Types: double

Predictor data for the regression component in the model, specified as the comma-separated pair consisting of 'X' and a numeric matrix containing numpreds columns.

numpreds is the number of predictor variables.

Rows correspond to observations, and the last row contains the latest observation. estimate does not use the regression component in the presample period. X must have at least as many observations as are used after the presample period.

• If you specify Y0, then X must have at least numobs rows (see Y).

• Otherwise, X must have at least numobsMdl.P observations to account for the presample removal.

In either case, if you supply more rows than necessary, estimate uses the latest observations only.

Columns correspond to individual predictor variables. All predictor variables are present in the regression component of each response equation.

By default, estimate excludes the regression component, regardless of its presence in Mdl.

Data Types: double

Estimation information display type, specified as the comma-separated pair consisting of 'Display' and a value in this table.

ValueDescription
"off"estimate does not display estimation information at the command line.
"table"estimate displays a table of estimation information. Rows correspond to parameters, and columns correspond to estimates, standard errors, t statistics, and p values.
"full"In addition to a table of summary statistics, estimate displays the estimated innovations covariance and correlation matrices, loglikelihood value, Akaike Information Criterion (AIC), Bayesian Information Criterion (BIC), and other estimation information.

Example: 'Display',"full"

Data Types: string | char

Maximum number of solver iterations allowed, specified as the comma-separated pair consisting of 'MaxIterations' and a positive numeric scalar.

estimate dispatches MaxIterations to mvregress.

Data Types: double

Note

NaN values in Y, Y0, and X indicate missing values. estimate removes missing values from the data by list-wise deletion.

• For the presample, estimate removes any row containing at least one NaN.

• For the estimation sample, estimate removes any row of the concatenated data matrix [Y X] containing at least one NaN.

This type of data reduction reduces the effective sample size.

Output Arguments

collapse all

Estimated VAR(p) model, returned as a varm model object. EstMdl is a fully specified varm model.

Estimated, asymptotic standard errors of the estimated parameters, returned as a structure array containing the fields in this table.

FieldDescription
ConstantStandard errors of model constants corresponding to the estimates in EstMdl.Constant, a numseries-by-1 numeric vector
ARStandard errors of the autoregressive coefficients corresponding to estimates in EstMdl.AR, a cell vector with elements corresponding to EstMdl.AR
BetaStandard errors of regression coefficients corresponding to the estimates in EstMdl.Beta, a numseries-by-numpreds numeric matrix
TrendStandard errors of linear time trends corresponding to the estimates in EstMdl.Trend, a numseries-by-1 numeric vector

If estimate applies equality constraints during estimation by fixing any parameters to a value, then corresponding standard errors of those parameters are 0.

Optimized loglikelihood objective function value, returned as a numeric scalar.

Multivariate residuals from the fitted model, returned as a numeric matrix containing numseries columns.

• If you specify Y0, then E has numobs rows (see Y).

• Otherwise, E has numobsMdl.P rows to account for the presample removal.

 Hamilton, J. D. Time Series Analysis. Princeton, NJ: Princeton University Press, 1994.

 Johansen, S. Likelihood-Based Inference in Cointegrated Vector Autoregressive Models. Oxford: Oxford University Press, 1995.

 Juselius, K. The Cointegrated VAR Model. Oxford: Oxford University Press, 2006.

 Lütkepohl, H. New Introduction to Multiple Time Series Analysis. Berlin: Springer, 2005.